Symphony Go

Note: This project was one-shot by Codex and is pending human review.

Go implementation of the Symphony service specified by openai/symphony.

What It Does

symphony is a long-running service that:

• Loads a repository-owned WORKFLOW.md.
• Resolves typed runtime config from YAML front matter.
• Polls Linear for active issues.
• Creates per-issue workspaces under the configured workspace root.
• Runs Codex app-server sessions inside those workspaces.
• Reconciles running sessions against tracker state and retries failed work with backoff.

Current Architecture

• internal/workflow: WORKFLOW.md loading, parsing, reload management.
• internal/config: typed config resolution and dispatch validation.
• internal/tracker/linear: Linear GraphQL adapter and normalization.
• internal/workspace: workspace creation, hooks, cleanup, and path safety.
• internal/codex: Codex app-server protocol client over stdio.
• internal/httpserver: optional loopback HTTP listener wrapper.
• internal/httpapi: dashboard and JSON API handlers.
• internal/tools/lineargraphql: optional linear_graphql Codex tool implementation.
• internal/worker: one worker attempt with continuation turns on a shared thread.
• internal/orchestrator: polling, dispatch, retries, reconciliation, and runtime accounting.
• internal/service: host wiring for dynamic reload, startup cleanup, and tick scheduling.

Running

Create a WORKFLOW.md in the repository root, then run:

go run ./cmd/symphony

Or provide an explicit workflow path:

go run ./cmd/symphony path/to/WORKFLOW.md

Enable the optional HTTP surface from the CLI:

go run ./cmd/symphony --port 8080

Or from WORKFLOW.md:

server:
  port: 8080

Required workflow values for real dispatch:

• tracker.kind: linear
• tracker.project_slug
• tracker.api_key or LINEAR_API_KEY
• codex.command if you do not want the default codex app-server

HTTP port precedence:

• CLI --port overrides server.port.
• The HTTP server binds loopback only (127.0.0.1).
• Listener changes are restart-bound; workflow reload does not hot-rebind the HTTP port.

Safety Posture

This implementation currently targets a trusted-host model.

• Codex runs inside per-issue workspace directories only.
• Workspace paths are sanitized and validated to stay under the configured workspace root.
• Workspace hooks are treated as trusted shell configuration.
• Approval requests are auto-approved in the Codex client.
• User-input-required turns fail immediately instead of stalling.

If you need a stricter deployment, add host/container isolation and tighten Codex approval/sandbox settings in WORKFLOW.md.

Observability

• Structured logs are emitted through Go slog.
• Runtime state is available through the in-process orchestrator snapshot API used by the host layer.
• Aggregate token usage, live session state, retry queue state, and runtime totals are tracked live in memory and persisted to .symphony/state.json.
• Optional HTTP endpoints:
  • GET /
  • GET /api/v1/state
  • GET /api/v1/<issue_identifier>
  • POST /api/v1/refresh

Restart Persistence

• Retry entries, aggregate token/runtime totals, rate-limit snapshots, and per-issue debug/session metadata are persisted to .symphony/state.json.
• On startup, persisted retries are re-armed from their saved due times.
• Running workers are not resumed after a restart. Symphony recovers by re-polling Linear and dispatching fresh work if the issue is still active.
• Persisted state is operational metadata, not a durable job ledger.

Agent Tooling

The Codex client now advertises and handles the optional linear_graphql tool when the active tracker is Linear.

• Tool calls reuse the active workflow's Linear endpoint and auth.
• Supported calls must contain exactly one GraphQL operation.
• Unknown tool names still return unsupported_tool_call without stalling the session.
• User-input-required turns still fail immediately.

Real Integration Profile

The repository includes opt-in smoke tests for real Linear and real Codex app-server validation.

• They are skipped by default and only run when explicit SYMPHONY_RUN_*_INTEGRATION=1 flags are set.
• Required env vars and example commands are documented in docs/integration-testing.md.
• These tests are intended for operator validation, not routine offline CI.

Current Non-Goals / Remaining Optional Extensions

• No tracker adapters beyond Linear.
• No SSH worker extension from Appendix A.

Verification

Run the full test suite with:

GOCACHE=/tmp/go-build-cache GOMODCACHE=/tmp/go-mod-cache go test ./...