Skip to main content

​
Core Entities

The Symphony service operates on the following domain entities:

​
Issue

Normalized issue record used by orchestration, prompt rendering, and observability output.
​
id
string
required
Stable tracker-internal ID
​
identifier
string
required
Human-readable ticket key (example: ABC-123)
​
title
string
required
Issue title
​
description
string | null
Issue description text
​
priority
integer | null
Lower numbers are higher priority in dispatch sorting
​
state
string
required
Current tracker state name
​
branch_name
string | null
Tracker-provided branch metadata if available
​
url
string | null
URL to the issue in the tracker
​
labels
string[]
Normalized to lowercase
​
blocked_by
object[]
List of blocker references, each containing:
  • id (string | null)
  • identifier (string | null)
  • state (string | null)
​
created_at
timestamp | null
Issue creation timestamp
​
updated_at
timestamp | null
Last update timestamp

​
Workflow Definition

Parsed WORKFLOW.md payload.
​
config
object
required
YAML front matter root object
​
prompt_template
string
required
Markdown body after front matter, trimmed

​
Service Config (Typed View)

Typed runtime values derived from WorkflowDefinition.config plus environment resolution.

​
Workspace

Filesystem workspace assigned to one issue identifier.
​
path
string
required
Workspace path (current runtime typically uses absolute paths, but relative roots are possible if configured without path separators)
​
workspace_key
string
required
Sanitized issue identifier
​
created_now
boolean
required
Used to gate after_create hook execution

​
Run Attempt

One execution attempt for one issue.
​
issue_id
string
required
Issue tracker-internal ID
​
issue_identifier
string
required
Human-readable issue identifier
​
attempt
integer | null
null for first run, >=1 for retries/continuation
​
workspace_path
string
required
Absolute path to workspace directory
​
started_at
timestamp
required
Run start timestamp
​
status
string
required
Current run status
​
error
string
Optional error message

​
Live Session (Agent Session Metadata)

State tracked while a coding-agent subprocess is running.
​
session_id
string
required
Format: <thread_id>-<turn_id>
​
thread_id
string
required
Coding agent thread identifier
​
turn_id
string
required
Current turn identifier
​
codex_app_server_pid
string | null
Process ID of the running Codex app-server
​
last_codex_event
string | null
Most recent event type from Codex
​
last_codex_timestamp
timestamp | null
Timestamp of last Codex event
​
last_codex_message
object
Summarized payload of last message
​
codex_input_tokens
integer
default:0
Input tokens consumed
​
codex_output_tokens
integer
default:0
Output tokens generated
​
codex_total_tokens
integer
default:0
Total tokens (input + output)
​
last_reported_input_tokens
integer
default:0
Last reported input token count
​
last_reported_output_tokens
integer
default:0
Last reported output token count
​
last_reported_total_tokens
integer
default:0
Last reported total token count
​
turn_count
integer
required
Number of coding-agent turns started within the current worker lifetime

​
Retry Entry

Scheduled retry state for an issue.
​
issue_id
string
required
Issue tracker-internal ID
​
identifier
string
required
Best-effort human ID for status surfaces/logs
​
attempt
integer
required
1-based retry attempt number
​
due_at_ms
number
required
Monotonic clock timestamp for retry execution
​
timer_handle
any
required
Runtime-specific timer reference
​
error
string | null
Error message from previous attempt

​
Orchestrator Runtime State

Single authoritative in-memory state owned by the orchestrator.
​
poll_interval_ms
integer
required
Current effective poll interval
​
max_concurrent_agents
integer
required
Current effective global concurrency limit
​
running
object
required
Map of issue_id -> running entry
​
claimed
Set<string>
required
Set of issue IDs reserved/running/retrying
​
retry_attempts
object
required
Map of issue_id -> RetryEntry
​
completed
Set<string>
required
Set of issue IDs (bookkeeping only, not dispatch gating)
​
codex_totals
object
required
Aggregate tokens + runtime seconds
​
codex_rate_limits
object | null
Latest rate-limit snapshot from agent events

​
Stable Identifiers and Normalization Rules

Issue ID

Use for tracker lookups and internal map keys

Issue Identifier

Use for human-readable logs and workspace naming

Workspace Key

Derive from issue.identifier by replacing any character not in [A-Za-z0-9._-] with _. Use the sanitized value for the workspace directory name.

Normalized Issue State

Compare states after trim + lowercase

Session ID

Compose from coding-agent thread_id and turn_id as <thread_id>-<turn_id>
All identifier normalization rules must be applied consistently across the system to ensure workspace path determinism and correct state lookups.

Build docs developers (and LLMs) love

Get started for freeTalk to us