AgentExecution is the authoritative Entity for one daemon-owned execution of one Agent under an explicit owner reference. It owns canonical execution identity, owner routing, selected Agent identity, lifecycle posture, structured message acceptance, daemon-normalized observation intake, durable journal state, and optional Terminal linkage for execution transport.

The Entity now uses canonical id as its only self-identity. agentExecutionId remains only where it is a foreign reference to an AgentExecution Entity, such as the embedded journal reference and the durable agent_execution_journal rows.

Authority

Definition

AgentExecution represents the current recoverable state of one Agent run plus the semantic ledger that explains how that run accepted messages, recorded daemon-normalized observations, decided state changes, and linked itself to an execution transport. The hydrated boundary is AgentExecutionSchema; the durable row is AgentExecutionStorageSchema; the durable ordered ledger is AgentExecutionJournalRecordStorageSchema.

The class owns direct execution behavior. It can create canonical ids, start and stop a subprocess, accept structured messages, intake daemon-normalized observations, append journal records, attach or open a Terminal lane, and emit runtime lifecycle or message events to listeners. Terminal remains separate: AgentExecution stores only an optional terminalId link and derives AgentExecution-facing terminal snapshots from TerminalRegistry updates.

The public interaction vocabulary remains message-first. recordObservation exists because daemon runtime collaborators and adapters need one canonical seam for accepting normalized evidence into the semantic journal, not because observation is intended to become a second operator-facing command vocabulary alongside messages.

Current Doctrine Audit

Check Status Notes
ADR 0001.01 canonical self-identity Aligned Top-level AgentExecution self identity is canonical id.
ADR 0001.01 duplicate self-id removal Aligned Top-level agentExecutionId is gone from hydrated and storage state and remains only as a foreign reference outside the Entity itself.
ADR 0001.02 class/schema/contract split Aligned AgentExecution.ts, AgentExecutionSchema.ts, and AgentExecutionContract.ts are the owning files.
ADR 0001.08 narrow storage versus hydrated read Aligned Storage holds canonical recoverable state; hydrated state adds runtime-facing fields like terminalId, adapterLabel, currentTurnTitle, and awaitingInput.
ADR 0001.08 instance targeting by transport id Aligned Public Entity methods are addressed by top-level AgentExecution id.
ADR 0006.01 AgentExecution versus Terminal ownership Aligned AgentExecution owns lifecycle and structured interaction; Terminal owns PTY transport mechanics and live terminal state.
ADR 0006.10 journal ownership Aligned Semantic interaction facts are durable AgentExecution journal records keyed by journal id and AgentExecution foreign reference.
Contract/event cross-control Partially aligned Contract declares data.changed, lifecycle, message, and terminal events; runtime class listeners emit lifecycle and message events directly, while terminal publication is bridged from DaemonIpcServer.ts.

Responsibilities

Area AgentExecution owns
Identity Canonical AgentExecution Entity id and deterministic id creation from owner entity, owner id, and seed.
Ownership ownerEntity and ownerId place the execution under System, Repository, Mission, Task, or Artifact.
Agent selection agentId records the chosen Agent or adapter identity for the execution.
Lifecycle posture lifecycle, attention, activity, awaitingInput, currentTurnTitle, and adapterLabel describe the current execution state.
Structured messages messageRegistry, sendMessage, and message acknowledgements define which structured messages can be accepted and how accepted messages affect state.
Observation intake recordObservation validates daemon-normalized observations, deduplicates them, decides whether to reject, record only, or update state, and returns a structured acknowledgement.
Durable journal journal reference, ordered journal append behavior, and journal payload shaping for message, observation, decision, state, activity, owner-effect, and projection records.
Process control Optional subprocess launch, output capture, termination, and process snapshot ownership inside the class runtime.
Terminal linkage Optional terminalId linkage plus AgentExecution-facing terminal snapshots and transport state derived from TerminalRegistry.
Runtime event stream Lifecycle and message runtime events emitted through onDidEvent.

Non-Responsibilities

Neighbor AgentExecution does not own
Terminal PTY lifecycle, screen state, input transport, resize, exit observation, and terminal persistence.
TerminalRegistry Shared live registry mechanics for terminal creation, attachment, snapshots, key input, and resize.
Agent Catalogue identity, adapter availability, and provider-specific launch translation.
Owner Entities Repository, Mission, Task, Artifact, or System meaning for downstream owner effects and workflow changes.
Journal projections Owner-specific timeline or workflow projections derived from journal facts.
SSE and IPC publication Transporting entity events to clients; this is handled by daemon publication surfaces.

Major Seams And Boundaries

Boundary What crosses the AgentExecution boundary What stays outside
Entity transport Canonical AgentExecution id plus method-specific payloads. Surface routing, IPC, and UI command rendering.
Journal durability Ordered AgentExecutionJournalRecordStorageSchema records appended through an injected journal writer. Storage implementation and owner-specific projection building.
Terminal transport terminalId link, AgentExecution terminal snapshots, and transport availability state. PTY ownership, persistence, and raw terminal event storage.
Agent runtime launch Launch config, adapter label, prompt context, and lifecycle state changes from the adapter seam. Provider-specific protocol translation inside the adapter.
Owner embedding Owner Entities may embed hydrated AgentExecution data, as Mission does through agentExecutions. AgentExecution does not become owner-specific to fit those projections.
Replay and recovery Journal replay can rebuild state transitions from ordered journal rows. Replay does not recreate subprocesses or TerminalRegistry handles by itself.

Usage And Operating Model

AgentExecution is created from owner-scoped launch intent. Owner surfaces such as Repository and Mission choose the owner reference and selected Agent, while adapter-facing launch code turns that intent into an AgentExecution instance with canonical id, durable journal reference, and initial lifecycle posture.

During live execution, AgentExecution owns the semantic state machine. Structured messages accepted through sendMessage become durable journal facts and may move the execution into awaiting-agent-response. Daemon-normalized observations accepted through recordObservation are the reverse path: runtime evidence is normalized by daemon collaborators or adapters, then AgentExecution decides whether to reject it, record it, or mutate attention and activity state.

Terminal interaction is explicitly split. AgentExecution can open or attach a Terminal lane and can expose an execution-facing terminal snapshot, but TerminalRegistry remains the live authority for PTY state and raw I/O. Publication to clients is also split: lifecycle and message events come from the live AgentExecution instance through onDidEvent, while terminal events are bridged from daemon terminal-owner publication.

Recovery is journal-first, not process-first. replayAgentExecutionJournalRecords can rebuild accepted-message and state-change effects from durable journal rows, but it does not recreate subprocesses, reattach PTYs, or infer transport health. Those remain runtime concerns owned by the live AgentExecution instance and terminal infrastructure.

Contract Methods

Method Attribute Detail
read Kind query
read Input EntityIdSchema
read Result AgentExecutionSchema
read Behavior Resolves current hydrated AgentExecution data by canonical id.
read Likely callers Daemon entity dispatcher, owner Entity reads, Mission channel projections.
read Side effects None beyond Entity read and hydration.
sendMessage Kind mutation
sendMessage Input AgentExecutionSendMessageInputSchema
sendMessage Result AgentExecutionSendMessageAcknowledgementSchema
sendMessage Behavior Accepts a structured AgentExecution message, assigns or preserves messageId, appends journal facts, and updates activity when the message starts a turn.
sendMessage Likely callers Operator surfaces, daemon follow-up flows, tests, owner command surfaces.
sendMessage Side effects Journal append and in-memory state mutation.
recordObservation Kind mutation
recordObservation Input AgentExecutionObservationIntakeInputSchema
recordObservation Result AgentExecutionObservationAcknowledgementSchema
recordObservation Behavior Accepts one semantic observation, deduplicates it, records durable facts, may update attention or activity, and returns a structured decision acknowledgement.
recordObservation Likely callers Adapter and runtime observation intake, daemon observation routing, tests.
recordObservation Side effects Journal append and possible in-memory state mutation.
openTerminal Kind mutation
openTerminal Input AgentExecutionOpenTerminalInputSchema
openTerminal Result AgentExecutionTerminalSchema
openTerminal Behavior Opens a new Terminal lane through TerminalRegistry, stores the returned terminal id, updates transport availability, and returns an execution-facing terminal snapshot.
openTerminal Likely callers AgentAdapter.ts for terminal-backed launches.
openTerminal Side effects Creates live terminal transport and mutates AgentExecution terminal and lifecycle state.
attachTerminal Kind mutation
attachTerminal Input AgentExecutionTerminalAttachmentInputSchema
attachTerminal Result AgentExecutionTerminalSchema
attachTerminal Behavior Attaches an existing terminal id to the execution and returns the current execution-facing terminal snapshot.
attachTerminal Likely callers Recovery and reattach flows, tests, execution transport controllers.
attachTerminal Side effects Mutates AgentExecution terminal linkage and transport state.
readTerminal Kind query
readTerminal Input AgentExecutionInstanceInputSchema
readTerminal Result AgentExecutionTerminalSchema
readTerminal Behavior Reads the current terminal snapshot for the linked terminal id, marking transport unavailable if the live terminal is absent.
readTerminal Likely callers Operator console panes, Mission terminal surfaces, and System terminal forwarding surfaces.
readTerminal Side effects May mutate transport availability in memory.
sendTerminalInput Kind mutation
sendTerminalInput Input AgentExecutionTerminalInputSchema
sendTerminalInput Result AgentExecutionTerminalSchema
sendTerminalInput Behavior Sends text input or resize commands to the linked terminal id and returns the refreshed execution-facing terminal snapshot.
sendTerminalInput Likely callers Operator console input surfaces and terminal forwarding methods on owners.
sendTerminalInput Side effects Writes to TerminalRegistry and then re-reads terminal state.

Events

Event Attribute Detail
data.changed Payload schema AgentExecutionDataChangedEventSchema
data.changed Current publisher path Contract helper createAgentExecutionDataChangedEvent.
data.changed Known consumers Entity publication surfaces and tests.
data.changed Meaning Full AgentExecution data snapshot changed.
execution.started Payload schema AgentExecutionStartedEventSchema
execution.started Current publisher path Runtime listeners on the AgentExecution class, often set by AgentAdapter.ts.
execution.started Known consumers Mission runtime ingestion, workflow request execution flows, operator clients.
execution.started Meaning Execution became active.
execution.attached Payload schema AgentExecutionAttachedEventSchema
execution.attached Current publisher path Runtime listeners on the AgentExecution class.
execution.attached Known consumers Mission and runtime listeners that reattach to an existing execution.
execution.attached Meaning Runtime reattachment occurred.
execution.updated Payload schema AgentExecutionUpdatedEventSchema
execution.updated Current publisher path Runtime listeners on the AgentExecution class, especially after observation or live-context changes.
execution.updated Known consumers Mission console state refresh and runtime projections.
execution.updated Meaning Execution state changed without finalization.
execution.completed Payload schema AgentExecutionCompletedEventSchema
execution.completed Current publisher path Runtime listeners on the AgentExecution class.
execution.completed Known consumers Mission runtime ingestion and workflow lifecycle handling.
execution.completed Meaning Execution ended successfully.
execution.failed Payload schema AgentExecutionFailedEventSchema
execution.failed Current publisher path Runtime listeners on the AgentExecution class.
execution.failed Known consumers Mission runtime ingestion and workflow lifecycle handling.
execution.failed Meaning Execution ended unsuccessfully.
execution.cancelled Payload schema AgentExecutionCancelledEventSchema
execution.cancelled Current publisher path Runtime listeners on the AgentExecution class.
execution.cancelled Known consumers Mission runtime ingestion and workflow lifecycle handling.
execution.cancelled Meaning Execution was cancelled.
execution.terminated Payload schema AgentExecutionTerminatedEventSchema
execution.terminated Current publisher path Runtime listeners on the AgentExecution class.
execution.terminated Known consumers Mission runtime ingestion and workflow lifecycle handling.
execution.terminated Meaning Execution was forcibly terminated.
execution.message Payload schema AgentExecutionMessageEventSchema
execution.message Current publisher path Runtime listeners on the AgentExecution class.
execution.message Known consumers Mission console line ingestion and runtime message surfaces.
execution.message Meaning AgentExecution emitted operator-visible text on stdout, stderr, or system.
terminal Payload schema AgentExecutionTerminalSchema in the contract; createAgentExecutionTerminalEvent wraps it for publication.
terminal Current publisher path DaemonIpcServer.ts bridges Terminal owner updates addressed to AgentExecution.
terminal Known consumers Operator terminal panes and AgentExecution-addressed terminal subscribers.
terminal Meaning The execution-facing terminal lane changed.

Event Notes

  • data.changed: declared in the contract and helper-backed, but the current class runtime shown here does not emit it directly. Treat it as an envelope-level publication shape rather than the primary live listener surface.
  • Lifecycle events: the live AgentExecution instance emits these through onDidEvent, and runtime coordinators such as workflow execution and Mission ingestion subscribe to them to update Mission-facing state.
  • execution.message: carries operator-visible text only. It is not the same thing as a structured AgentExecution message accepted through sendMessage.
  • terminal: reflects execution-facing lane state derived from Terminal ownership and publication, not a transfer of Terminal authority into AgentExecution.

Property Groups

Property group Entry Detail
Identity id EntityIdSchema. Canonical AgentExecution Entity identity.
Ownership ownerEntity AgentExecutionOwnerEntitySchema. Owning Entity type.
Ownership ownerId IdSchema. Owning Entity id.
Agent agentId IdSchema. Selected Agent or adapter identity.
Lifecycle posture lifecycle AgentExecutionLifecycleStateSchema. Daemon-owned execution lifecycle state.
Lifecycle posture attention AgentExecutionAttentionStateSchema. Collaboration attention posture.
Lifecycle posture activity AgentExecutionActivityStateSchema. Current semantic work posture.
Messages messageRegistry AgentExecutionMessageRegistrySchema. Structured message descriptors supported by the execution.
Transport transportState AgentExecutionTransportStateSchema. Current structured transport availability.
Transport mcpAvailability AgentExecutionMcpAvailabilitySchema. Current MCP-backed semantic operation availability.
Journal journal AgentExecutionJournalReferenceSchema. Durable journal identity plus counters and owner link.
Lineage lineage Optional AgentExecutionRetryLineageSchema. Retry relationship to an earlier AgentExecution.
Hydrated runtime view terminalId Optional EntityIdSchema. Linked terminal id for the execution-facing lane.
Hydrated runtime view adapterLabel Optional string. Operator-facing adapter display label.
Hydrated runtime view currentTurnTitle Optional string. Operator-facing title for the current turn.
Hydrated runtime view awaitingInput Optional boolean. Whether the execution is awaiting operator input.
Timestamps createdAt, updatedAt string. Entity creation and last update timestamps.

The class also owns private runtime-only process fields: processHandle, processSnapshot, processExitPromise, recordedObservationIds, and runtime event listeners. Those are class runtime mechanics, not schema fields.

Relations And Collaborators

Collaborator Attribute Detail
AgentAdapter Role Shapes launch intent into provider-specific command, args, env, and optional terminal-backed launch behavior.
AgentAdapter Direction of authority Adapter translates; AgentExecution remains lifecycle and semantic-state owner.
TerminalRegistry Role Live terminal creation, attachment, snapshot, input, resize, and update publication.
TerminalRegistry Direction of authority TerminalRegistry owns PTY state; AgentExecution owns only the execution-facing link and derived transport state.
AgentExecutionJournalWriter Role Persists ordered semantic journal rows when AgentExecution appends records.
AgentExecutionJournalWriter Direction of authority AgentExecution owns record shape and sequencing; the writer owns storage side effects only.
AgentExecutionJournalReplayer Role Rebuilds current semantic state from ordered durable journal rows.
AgentExecutionJournalReplayer Direction of authority Replay consumes AgentExecution-owned journal truth; it does not redefine the Entity boundary.
AgentExecutionTerminalRecordingWriter Role Persists raw terminal recording files keyed by AgentExecution id from TerminalRegistry updates.
AgentExecutionTerminalRecordingWriter Direction of authority Writer owns raw recording append behavior; AgentExecution remains separate from raw terminal truth.
DaemonIpcServer Role Bridges Terminal owner updates into the agentExecution.terminal publication path.
DaemonIpcServer Direction of authority Daemon publication transports AgentExecution-facing events but does not own AgentExecution truth.
Mission Role Embeds AgentExecution snapshots, ingests runtime lifecycle and message events, updates Mission console state, and feeds terminal recording reconciliation.
Mission Direction of authority Mission is a consumer and owner of Mission projections, not AgentExecution semantics.
requestExecutor Role Subscribes to live AgentExecution events during workflow execution.
requestExecutor Direction of authority Workflow orchestration consumes AgentExecution events but does not redefine their meaning.

Schema And Subschema Map

Schema Purpose
AgentExecutionInputSchema Creation input for a new AgentExecution; may accept a caller-supplied canonical id.
AgentExecutionStorageSchema Persisted agent_execution row containing canonical recoverable execution state.
AgentExecutionSchema Hydrated Entity boundary returned by read and carried in lifecycle/message events.
AgentExecutionJournalReferenceSchema Embedded durable journal reference stored on AgentExecution.
AgentExecutionJournalRecordStorageSchema Persisted agent_execution_journal row for one ordered semantic record.
AgentExecutionJournalRecordInputSchema Discriminated journal append input used by the class before storage shaping.
AgentExecutionMessageRegistrySchema Structured message descriptors advertised by the execution.
AgentExecutionSendMessageInputSchema Structured message acceptance payload.
AgentExecutionSendMessageAcknowledgementSchema Result of sendMessage.
AgentExecutionObservationIntakeInputSchema Observation intake payload for recordObservation.
AgentExecutionObservationAcknowledgementSchema Result of recordObservation.
AgentExecutionInstanceInputSchema Empty payload for instance methods addressed only by top-level AgentExecution id.
AgentExecutionOpenTerminalInputSchema New terminal launch payload.
AgentExecutionTerminalAttachmentInputSchema Existing terminal-id linkage payload.
AgentExecutionTerminalInputSchema Terminal data or resize payload.
AgentExecutionTerminalSchema AgentExecution-facing terminal state snapshot.
AgentExecutionDataChangedEventSchema Declared payload for a full data snapshot change.
AgentExecutionEventSchema Union of lifecycle and message runtime events.
AgentExecutionTerminalEventSchema Wrapper schema for a terminal event carrying AgentExecutionTerminalSchema.
AgentExecutionTerminalRecordingEntrySchema Header, output, input, resize, and exit entries for AgentExecution terminal recording files.

ERD 

erDiagram
    AGENT_EXECUTION {
        string id PK
        string ownerEntity
        string ownerId
        string agentId
        string lifecycle
        string attention
        string activity
        string journalId
    }

    AGENT_EXECUTION_JOURNAL_RECORD {
        string id PK
        string journalId
        string agentExecutionId FK
        int sequence
        string type
        string occurredAt
    }

    TERMINAL {
        string id PK
        string ownerEntity
        string ownerEntityId
    }

    MISSION {
        string id PK
    }

    REPOSITORY {
        string id PK
    }

    TASK {
        string id PK
    }

    ARTIFACT {
        string id PK
    }

    SYSTEM_SCOPE {
        string id PK
    }

    AGENT_EXECUTION ||--o{ AGENT_EXECUTION_JOURNAL_RECORD : records
    AGENT_EXECUTION }o--o| TERMINAL : links
    MISSION ||--o{ AGENT_EXECUTION : may_own
    REPOSITORY ||--o{ AGENT_EXECUTION : may_own
    TASK ||--o{ AGENT_EXECUTION : may_own
    ARTIFACT ||--o{ AGENT_EXECUTION : may_own
    SYSTEM_SCOPE ||--o{ AGENT_EXECUTION : may_own

journal.agentExecutionId and journal-record agentExecutionId are foreign references back to the canonical AgentExecution Entity id. They are not duplicate top-level self-identity fields on AgentExecution itself.

Main Runtime Flows

Creation And Launch 

flowchart TD
    A[Owner or adapter requests launch] --> B[AgentExecution.createData or createDataFromLaunch]
    B --> C[Create canonical AgentExecution id]
    C --> D[Create durable journal reference]
    D --> E[Hydrate AgentExecution instance]
    E --> F{Terminal-backed launch?}
    F -- yes --> G[openTerminal through TerminalRegistry]
    F -- no --> H[Attach live context only]
    G --> I[setLifecycleState execution.started]
    H --> I

Structured Message Intake 

flowchart TD
    A[Caller] --> B[sendMessage]
    B --> C[Parse AgentExecutionSendMessageInputSchema]
    C --> D[Assign or preserve messageId]
    D --> E[Append message.accepted journal record]
    E --> F{startsTurn?}
    F -- yes --> G[Append state.changed and set activity awaiting-agent-response]
    F -- no --> H[Preserve current activity]
    G --> I[Return acknowledgement]
    H --> I

Observation Intake And Replay 

flowchart TD
    A[Daemon-normalized observation] --> B[recordObservation]
    B --> C[Deduplicate observationId]
    C --> D[Append observation.recorded]
    D --> E[Decide record-only or update-state]
    E --> F[Append decision.recorded]
    F --> G{state change?}
    G -- yes --> H[Append state.changed and mutate in-memory state]
    G -- no --> I[Persist records only]
    H --> J[Journal rows]
    I --> J
    J --> K[replayAgentExecutionJournalRecords can rebuild state later]

Terminal Publication And Recording 

flowchart TD
    A[TerminalRegistry update] --> B[DaemonIpcServer owner bridge]
    B --> C[createAgentExecutionTerminalEvent]
    C --> D[Publish agentExecution.terminal]
    A --> E[AgentExecutionTerminalRecordingWriter]
    E --> F[Append header or output/input/resize/exit entry]
    F --> G[Terminal recording file rooted by AgentExecution id]

Cross-Control Checklist

Surface Status Notes
Class vs schema Aligned Class mutates fields defined by AgentExecutionSchema and uses journal input schemas before storage shaping.
Class vs contract Aligned Public contract methods are implemented on the class and addressed by canonical AgentExecution id.
Schema vs ADR 0001.01 Aligned Self identity is canonical id; remaining agentExecutionId occurrences are foreign references in journal-related shapes.
Schema vs ADR 0001.08 Aligned Storage and hydrated boundaries are distinct, with runtime-facing fields only on the hydrated schema.
Contract events vs runtime emission Partially aligned Runtime class listeners emit lifecycle/message events; terminal events are published by daemon bridge; data.changed is declared and helper-backed but not emitted directly by the class runtime path documented here.
Journal replay vs storage Aligned Replay validates both journalId and agentExecutionId === data.id before applying records.
Terminal recording vs Terminal ownership Aligned Recording files are keyed by AgentExecution id, but the recorded stream still originates from TerminalRegistry updates.
Docs vs implementation Aligned This page now documents the post-collapse canonical id model, the runtime listener/publication split, and the current method/event surface without fallback naming.

Implementation Findings To Carry Forward

  • Keep AgentExecution self identity canonical and top-level id-only.
  • Keep agentExecutionId restricted to foreign-reference roles in the journal reference and journal record shapes.
  • Keep AgentExecution methods addressed by transport id; do not reintroduce locator payloads that repeat self identity.
  • Keep Terminal linkage documented as linkage only, not as Terminal ownership.
  • Keep journal replay and terminal recording documentation tied to their actual owning files rather than paraphrasing them into a new abstraction surface.