# 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
- `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.
## Current model
- COE-401 contributed: PR #92: COE-401: Web app entry and deployment modes (merge `73b9067`)
- COE-407 contributed: PR #125: feat(api-client): browser transport streaming, replay, and remote protocols (COE-407) (merge `4d70347`)
- COE-408 contributed: PR #129: Add harness adapter capability discovery (merge `96345e3`)
- COE-419 contributed: PR #126: Load desktop task graph dependencies from Linear (merge `64242a6`)
- COE-423 contributed: PR #130: feat(gateway): add model credential settings seam (merge `07274f4`)
- COE-425 contributed: PR #132: feat(openhands): add subscription credential adapter (merge `93cea67`)
## 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-401: Web App Entry And Deployment Modes
- COE-407: Browser Transport And Remote Stream Protocols
- COE-408: Harness Adapter And Capability Model
- 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
## Source refs
- COE-401
- COE-407
- COE-408
- 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