# Sources and Trust Notes
This file lists the primary references that define the intended behavior for OpenSymphony.
## Trust order
1. OpenAI Symphony `SPEC.md`
2. OpenHands SDK agent-server documentation
3. OpenHands SDK source for `RemoteConversation` when the docs do not state wire-level details clearly
4. FrankenTUI repository documentation
5. User-provided findings file for prior research and framing
## Primary references
### Symphony
- Repository: `https://github.com/openai/symphony`
- Spec: `https://github.com/openai/symphony/blob/main/SPEC.md`
Use these for:
- system goals and non-goals
- orchestration state machine
- workspace invariants
- `WORKFLOW.md` contract
- retry and reconciliation behavior
- optional status-surface boundary
### OpenHands SDK agent-server
Pinned for the current local-MVP implementation branch:
- SDK release: `v1.24.0`
- Release date: `2026-05-27`
- Release notes:
`https://github.com/OpenHands/software-agent-sdk/releases/tag/v1.24.0`
- Local tooling pin location:
`tools/openhands-server/`
Published `opensymphony` embeds this bundle for
`opensymphony install openhands`.
- Local server guide:
`https://docs.openhands.dev/sdk/guides/agent-server/local-server`
- Agent-server architecture:
`https://docs.openhands.dev/sdk/arch/agent-server`
- Agent-server overview:
`https://docs.openhands.dev/sdk/guides/agent-server/overview`
- Workspace architecture:
`https://docs.openhands.dev/sdk/arch/workspace`
- Start conversation:
`https://docs.openhands.dev/sdk/guides/agent-server/api-reference/conversations/start-conversation`
- Get conversation:
`https://docs.openhands.dev/sdk/guides/agent-server/api-reference/conversations/get-conversation`
- Run conversation:
`https://docs.openhands.dev/sdk/guides/agent-server/api-reference/conversations/run-conversation`
- Search conversation events:
`https://docs.openhands.dev/sdk/guides/agent-server/api-reference/events/search-conversation-events`
- Event API reference:
`https://docs.openhands.dev/sdk/api-reference/openhands.sdk.event`
Use these for:
- local no-Docker development pattern
- per-conversation `workspace.working_dir`
- REST endpoints and payload shapes
- event model
- `ConversationStateUpdateEvent`
- `LLMCompletionLogEvent`
- local vs remote workspace tradeoffs
### OpenHands source used for wire-level clarifications
- `remote_conversation.py`:
`https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py`
Use this source only for details that are underspecified or absent in the docs, such as:
- current WebSocket URL shape
- readiness barrier behavior
- reconciliation timing
- dedupe and ordering strategy
- reconnect backoff pattern
- current query-param auth fallback
- current `tool_module_qualnames` and `agent_definitions` forwarding in the start-conversation payload
Pinned implementation source:
- release: `v1.24.0`
- server entrypoint: `openhands-agent-server/openhands/agent_server/__main__.py`
- API router: `openhands-agent-server/openhands/agent_server/api.py`
- WebSocket router: `openhands-agent-server/openhands/agent_server/sockets.py`
- server readiness endpoints: `openhands-agent-server/openhands/agent_server/server_details_router.py`
Re-validate all wire-level assumptions against that pinned version before changing the adapter contract.
### OpenHands release notes
- SDK releases:
`https://github.com/OpenHands/software-agent-sdk/releases`
Use release notes to track:
- API changes
- WebSocket auth changes
- event-model additions
- compatibility risks across versions
### Pinned OpenHands version notes
As of 2026-06-02, this repository pins:
- `openhands-agent-server==1.24.0`
- `openhands-sdk==1.24.0`
- `openhands-tools==1.24.0`
- `openhands-workspace==1.24.0`
- release tag `v1.24.0`
- Python `3.13.12` for the repo-local server environment
Validation sources for this pin:
- PyPI project:
`https://pypi.org/project/openhands-agent-server/1.24.0/`
- GitHub release:
`https://github.com/OpenHands/software-agent-sdk/releases/tag/v1.24.0`
The current local supervisor assumptions validated against this pin are:
- the server still starts with `python -m openhands.agent_server`
- the CLI still accepts `--host` and `--port`
- the default bind host remains broader than loopback, so OpenSymphony keeps the
loopback-only wrapper
- REST auth uses the `X-Session-API-Key` header when session API keys are configured
- the SDK remote client still defaults WebSocket auth to the `session_api_key`
query parameter when an API key is present
- the server also accepts WebSocket header auth, with query-param auth taking
precedence when both are present
- `ConversationCreateRequest.agent.mcp_config` is sent on conversation creation
using the top-level `mcpServers` map, with each server carrying its `url` and
optional `headers`; the pinned REST surface has no MCP-config update
operation, so a changed worker grant requires a fresh conversation
- `openhands-sdk==1.24.0` exposes
`LLM.subscription_login(vendor, model, force_login, open_browser, auth_method,
**llm_kwargs)` for OpenAI ChatGPT/Codex subscription login. Its OpenAI path
constructs an `LLM` with `model="openai/<codex-model>"`,
`base_url="https://chatgpt.com/backend-api/codex"`, the OAuth access token as
the LLM API key, Codex headers, `litellm_extra_body.store=false`, and
streaming enabled.
- OpenSymphony accepts any non-empty bare model name or `openai/...` model name
in subscription mode so newer pinned SDK releases can add Codex-capable models
without a Rust whitelist change. Non-OpenAI provider prefixes remain rejected.
When bumping this version, re-validate the launch surface, readiness probe, HTTP
contract assumptions, and WebSocket notes before changing the repo pin.
### OpenHands skills and context loading
- Agent skills guide:
`https://docs.openhands.dev/sdk/guides/skill`
- General skills overview:
`https://docs.openhands.dev/overview/skills`
- Repository agent guidance:
`https://docs.openhands.dev/overview/skills/repo`
Use these for:
- repo-root `AGENTS.md`
- project skill loading
- `.agents/skills/` conventions
### OpenHands PR review workflow
- Workflow:
`.github/workflows/ai-pr-review.yml`
- Extensions repository:
`https://github.com/OpenHands/extensions`
- PR review action pin:
`75e39288f6c2366b75cf290441da06e187395f63`
Use this pin for the automated advisory AI PR review workflow. The review
action installs the current `openhands-sdk` package at runtime, so the action
pin must remain compatible with the SDK's current project-skill loading API.
Re-validate the action import path and repository skill loading behavior before
changing the pin.
### OpenHands sandboxing
- Process sandbox:
`https://docs.openhands.dev/openhands/usage/sandboxes/process`
- Sandbox overview:
`https://docs.openhands.dev/openhands/usage/sandboxes/overview`
Use these for:
- local trusted-mode safety posture
- later hardening discussions
- documentation of host-access risk
### FrankenTUI
- Repository:
`https://github.com/Dicklesworthstone/frankentui`
Use this for:
- inline mode assumptions
- diff-based rendering model
- pane workspace capabilities
- current dependency strategy
## Sources that are intentionally out of scope for the MVP runtime contract
These documents are useful for understanding the broader OpenHands product, but they are not the protocol contract for OpenSymphony's local MVP runtime adapter:
- OpenHands web-app Socket.IO WebSocket docs
- `openhands serve` GUI server docs
- ACP client protocols
- web-app REST docs that are not part of the SDK agent-server surface
## User-provided findings incorporated here
User file:
- `/mnt/data/symphony-design-opencode-analysis.md`
Key takeaways carried forward:
- Symphony should be treated as a harness-agnostic orchestration design.
- Workspace, retry, reconciliation, and tracker semantics stay Symphony-owned.
- Session-oriented harness integration is the right abstraction.
- Real-time runtime streaming is important enough to build in early rather than retrofit later.
## ACP executable client baseline
The client pins [`agent-client-protocol` 2.2.0](https://crates.io/crates/agent-client-protocol/2.2.0)
and [`agent-client-protocol-schema` 1.9.1](https://crates.io/crates/agent-client-protocol-schema/1.9.1).
The released SDK records source commit
[`2a78849d3eb3dcb140dade3b8fc938cf1e2b9ce5`](https://github.com/agentclientprotocol/rust-sdk/tree/2a78849d3eb3dcb140dade3b8fc938cf1e2b9ce5).
These package versions are distinct from negotiated ACP wire version 1.
The implementation uses the SDK's `Lines` transport, `Client` builder, typed v1
setup requests, raw SDK prompt response decoding for future stop reasons, and
ordered `Dispatch` handler. ACP v2 features are disabled.
Windows process ownership uses the safe Job Object API from
[`process-wrap` 10.0.0](https://docs.rs/process-wrap/10.0.0/process_wrap/):
`JobObject` assigns the suspended child before resuming it, and `KillOnDrop`
terminates descendants when ownership ends.
Wire authority: [v1 initialization](https://agentclientprotocol.com/protocol/v1/initialization),
[v1 prompt/cancel lifecycle](https://agentclientprotocol.com/protocol/v1/prompt-turn),
and [v1 transports](https://agentclientprotocol.com/protocol/v1/transports).
Client facilities follow the [v1 filesystem](https://agentclientprotocol.com/protocol/v1/file-system),
[v1 terminals](https://agentclientprotocol.com/protocol/v1/terminals),
[v1 session config options](https://agentclientprotocol.com/protocol/v1/session-config-options)
and [v1 MCP attachments](https://agentclientprotocol.com/protocol/v1/session-setup)
contracts. Optional callback fields use strict local deserialization so malformed
line, cwd, environment and output limits cannot silently become defaults.
Implementation and tests are in `crates/opensymphony-acp/src/` and `tests/acp.rs`.
Windows callback path ownership uses documented [CreateFile sharing and reparse
flags](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilew)
through [Rust OpenOptionsExt](https://doc.rust-lang.org/std/os/windows/fs/trait.OpenOptionsExt.html).
No-follow handles are checked before mutation, and ancestor handles exclude
write/delete sharing until file I/O or terminal spawn finishes.
## ACP vendor pins and observed contract
The [live qualification report](acp-live-qualification.md) pins Cursor CLI
`2026.09.08-6caf4ff` and Devin CLI `3000.10.21 (611c1cba)` as observed on
2026-09-25. Both negotiated ACP v1 over local stdio and advertised
`loadSession`; neither advertised `resumeSession`. Devin emitted configuration
updates before `session/new` replied. These are observed runtime contracts,
not assumptions about newer CLI releases. Re-run the ignored tests and revise
the pin before claiming another version. The supported Cursor extension shapes
and response observations are in [ACP extension
evidence](acp-extension-evidence.md).
## Current model
- COE-253 contributed: PR #19: COE-253: OpenHands Runtime Adapter (merge `911b0b4`)
- COE-255 contributed: PR #4: COE-255: add control plane and FrankenTUI slice
- COE-256 contributed: PR #1: COE-257: tighten hosted deployment guidance
- COE-261 contributed: PR #83: Add memory init and mapped docs sync
- COE-262 contributed: PR #34: COE-262: Harden OpenHands REST client contract (merge `0e2be26`)
- COE-265 contributed: PR #36: COE-265: WebSocket event stream, reconciliation, and recovery (merge `d78a8ce`)
## Important invariants
- Preserve the behavior described in the recent captured changes unless current code and tests show it has changed.
- Use capsule source refs to inspect the original PR or Linear issue when context is ambiguous.
## Operational flow
- No generated diagram requested for this sync.
## Known gotchas
- No area-specific gotchas were inferred from the selected memory.
## Recent changes
- COE-253: OpenHands Runtime Adapter
- COE-255: Observability and FrankenTUI
- COE-256: Validation and Local Operations
- COE-261: Local agent-server supervisor
- COE-262: REST client and conversation contract
- COE-265: WebSocket event stream, reconciliation, and recovery
- COE-266: Issue session runner
- COE-269: Control-plane API and snapshot store
- COE-271: FrankenTUI operator client
- COE-272: Fake OpenHands server and protocol contract suite
- COE-273: Live local end-to-end suite
- COE-274: CLI packaging, doctor, and local operations docs
- COE-275: Remote agent-server mode and auth hardening
- COE-280: Support workflow-owned OpenHands auth, provider, and launcher overrides at runtime
- COE-281: Support path-bearing OpenHands base URLs and MCP config at runtime
- COE-282: Support workflow-owned OpenHands conversation reuse policy at runtime
- COE-287: Add opensymphony debug command for conversational session debugging
- COE-294: Detect LLM config changes and rehydrate conversations with updated env vars
- COE-382: Add supply-chain and security audits to CI
- COE-383: Decompose oversized session and TUI modules into focused submodules
- COE-384: Expand error-path tests for Linear client and workspace hooks
- COE-385: Resolve runtime tracking TODO in OpenHands session runner
- COE-386: Wire cargo-llvm-cov coverage reporting and regression floor into CI
- COE-387: Audit tracing spans and diagnostics for secret leakage
- COE-389: Current Gateway Inventory And Vocabulary
- COE-390: Gateway Schemas And Stream Feasibility
- COE-391: Gateway Module, Capabilities, And Dashboard Snapshot
- COE-392: Task Graph, Run Detail, File, And Diff Read APIs
- COE-393: Event Journal And Stream Broker
- COE-395: Planning Artifact Schema And Session Service
- COE-396: Action Receipts And Initial Run Actions
- COE-401: Web App Entry And Deployment Modes
- COE-406: Repository, Linear, And Research Analysis
- COE-407: Browser Transport And Remote Stream Protocols
- COE-408: Harness Adapter And Capability Model
- COE-413: Implementation Plan Generator Stage
- COE-415: Milestone, Issue, And Sub-Issue Compiler
- COE-416: Dependency Graph And Plan Checks
- COE-417: Planning Workspace UI
- COE-419: Hosted Auth Placeholders And Web Parity
- COE-423: Model And Credential Settings
- COE-425: OpenHands Subscription Credential Adapter
- COE-426: Codex App-Server Prototype And Benchmarks
- COE-428: Model Configuration UI And Routing Metadata
- COE-429: Codex Approvals And Cross-Harness Routing
- COE-454: OKF Bundle Schema And Legacy Capsule Mapping
- COE-456: OKF Writer, Lint, And Migration Fixtures
- COE-458: Catalog Reindex And Query Compatibility From OKF
- COE-460: OKF Export, Import, And Visibility Boundaries
- COE-463: Docs Sync And MCP Admin Parity For OKF
- COE-473: Desktop task graph dependency and run detail parity
- COE-475: ChatGPT OAuth For Codex Harness
- COE-476: Codex Production Harness Enablement
- COE-478: Harden model profile storage and validation follow-ups
- COE-479: Codex Debug Session Resume
- COE-480: Run Detail Metrics And Density
- COE-481: Model Configuration Codex Subscription Follow-Up
- COE-482: TUI Codex Token Usage Accounting
- COE-483: Codex Event Content Summaries
- COE-484: Desktop Live Snapshot And Run Detail Refresh
- COE-498: Tree-sitter Provider Skeleton And Rust Parsing
- COE-499: Memory Context AST Provider Integration
- COE-500: Query Packs For Supported Agent Languages
- COE-501: Code Intelligence Persistence And Ingestion
- COE-502: Read-Only AST MCP And CLI Tools
- COE-503: Code Intelligence Performance Docs And Hardening
- COE-505: Add scheduler-side Codex stdio interrupt channel
- COE-506: Invert CodeIntelIndex trait ownership after AST memory integration
- COE-507: Deduplicate query-pack assets for grammar variants
- COE-508: Cache code-intel parsers and compiled query packs
- COE-540: Canonical Codex Thread Reuse And Workspace Retention
- COE-541: Durable Codex Thread Archive And Debug Recovery
- COE-547: Central Multi-Repository Config And Safe Migration
- COE-548: Canonical Repository Binding And Task Propagation
- COE-549: Verified Checkouts Instructions And Harness Envelopes
- COE-550: Per-Instance Memory Catalog And Source Migration
- COE-551: Scoped Cross-Repository Memory And Leaf Overlays
- COE-563: Implement task-packet admission and freeze tooling
- COE-608: ACP Profiles And Executable Protocol Client
- COE-609: ACP Session Ownership And Durable Recovery
- COE-610: ACP Client Callbacks And Session Configuration
- COE-611: ACP Execution Routing And Worker Integration
- COE-612: ACP Operator Requests And Response Routing
- COE-613: ACP Extensions And Harness Operations
- COE-615: ACP Runtime Conformance And Live Qualification
## Source refs
- COE-253
- COE-255
- COE-256
- COE-261
- COE-262
- COE-265
- COE-266
- COE-269
- COE-271
- COE-272
- COE-273
- COE-274
- COE-275
- COE-280
- COE-281
- COE-282
- COE-287
- COE-294
- COE-382
- COE-383
- COE-384
- COE-385
- COE-386
- COE-387
- COE-389
- COE-390
- COE-391
- COE-392
- COE-393
- COE-395
- COE-396
- COE-401
- COE-406
- COE-407
- COE-408
- COE-413
- COE-415
- COE-416
- COE-417
- COE-419
- COE-423
- COE-425
- COE-426
- COE-428
- COE-429
- COE-454
- COE-456
- COE-458
- COE-460
- COE-463
- COE-473
- COE-475
- COE-476
- COE-478
- COE-479
- COE-480
- COE-481
- COE-482
- COE-483
- COE-484
- COE-498
- COE-499
- COE-500
- COE-501
- COE-502
- COE-503
- COE-505
- COE-506
- COE-507
- COE-508
- COE-540
- COE-541
- COE-547
- COE-548
- COE-549
- COE-550
- COE-551
- COE-563
- COE-608
- COE-609
- COE-610
- COE-611
- COE-612
- COE-613
- COE-615