Temporary Agent Execution Structured Interaction Spec

Current authority: AgentExecution is the canonical in-memory Entity instance and owner of the Agent execution process. MCP, stdout, and provider output are input channels. Terminal is optional transport. AgentExecutionRegistry is daemon-internal lookup and process-handle plumbing.

This is the umbrella working implementation spec for the Agent execution structured interaction architecture described by ADR-0006.05 and extended by ADR-0006.06.

It is temporary on purpose. It exists so future implementation sessions can continue from the same clean-sheet model. When the implementation converges, fold the durable parts into CONTEXT.md, accepted ADRs, and permanent architecture pages, then delete this file.

Reflection

The task is to implement a clear architecture for how an Agent execution communicates with Mission through the Entity that owns its scope. The current @mission:: marker path is useful source material for parser behavior, validation, and tests.

The current code is useful evidence. It has parsers, policy checks, terminal observation, AgentExecution messages, AgentExecution state, and workflow integration. The target ownership model keeps scoped Task, Mission, Repository, and Artifact meaning in the owning Entity path, with narrow private capabilities behind AgentExecution for launch and IO mechanics.

The desired architecture is an Entity-addressed runtime conversation:

AgentExecutionScope
  -> owning Entity
      -> Agent execution protocol descriptor
      -> owner-addressed Agent signals
      -> owner-owned observation handling
      -> AgentExecution state changes and Entity events

The implementation must make the available structured interaction inspectable before launch, materialize the declared signal transports from that inspected contract, parse or receive Agent signals against that same contract, and route accepted observations through the owning Entity path.

Authoritative Inputs

  • CONTEXT.md: canonical Mission language.
  • ADR-0001.03: Entity classes own behavior.
  • ADR-0001.05: Entity commands are the canonical operator mutation surface.
  • ADR-0006.04: prompt-scoped Agent execution signals are the current transport baseline.
  • ADR-0006.01: Agent, AgentAdapter, AgentExecution, AgentExecutionRegistry, and Terminal vocabulary.
  • ADR-0006.05: structured Agent execution interaction vocabulary and owner-addressed signal model.
  • ADR-0006.06: open-mission-mcp is the daemon-owned MCP signal transport for Agent signals.
  • Mission MCP Server Spec: subordinate realization blueprint for the MCP transport. Descriptor, observation, owner-routing, and idempotency semantics come from this spec.

Vocabulary To Implement

Agent Execution Protocol Descriptor

The Agent execution protocol descriptor is the source of truth for one execution’s structured interaction contract.

It combines:

  • Agent execution message descriptors: daemon/operator-to-AgentExecution input.
  • Agent signal descriptors: Agent-to-owner structured signal payloads and their declared delivery transports.
  • Owner addressing metadata: marker prefix, owning Entity name, owning Entity id, and scope identifiers.
  • Policy metadata: which outcomes each accepted signal may produce.
  • Transport metadata: whether this execution exposes stdout-marker delivery, open-mission-mcp delivery, or both.

Agent Execution Message

An Agent execution message is structured input sent by the daemon or operator to an AgentExecution. It may be delivered to a terminal-backed adapter as prompt text, but the message itself is structured daemon intent.

Message examples:

  • prompt the Agent execution
  • interrupt or resume the Agent execution
  • request a checkpoint
  • attach, remove, or reorder Agent execution context
  • answer an Agent needs_input observation

Agent Signal

An Agent signal is structured Agent-authored input to the owning Entity path. It may arrive as a stdout marker or as a open-mission-mcp tool call. The signal payload shape is the same regardless of transport.

For stdout-marker delivery, the marker prefix is derived from the owning Entity, not from the transport or adapter.

Target marker prefixes:

  • @task:: for task-scoped Agent executions
  • @mission:: for mission-scoped Agent executions
  • @repository:: for repository-scoped Agent executions
  • @artifact:: for artifact-scoped Agent executions
  • @system:: for system-scoped Agent executions

The stdout marker payload is strict JSON. The MCP tool payload is schema-validated structured input. The descriptor defines the accepted payload shapes and delivery transports for that execution.

Mission MCP Server

The Mission MCP server is the daemon-owned local MCP service named open-mission-mcp. It materializes session-scoped tools from the Agent execution protocol descriptor and converts accepted MCP tool calls into Agent execution observations. It is a transport adapter into the same observation path as stdout markers.

Agent Execution Observation

An Agent execution observation is the daemon-normalized form of process output or structured Agent-authored transport input. Observations come from parsed Agent signal stdout markers, open-mission-mcp tool calls, provider-structured output, terminal diagnostics, or daemon-observed semantic operation records.

Observation handling belongs to AgentExecution and the owning Entity path. The owning Entity decides scoped meaning. AgentExecutionRegistry only resolves the active AgentExecution and process handle.

Agent execution observations are append-only and idempotent. An Agent signal event id may produce policy effects at most once for one AgentExecution, regardless of whether it arrived through stdout-marker delivery, open-mission-mcp, adapter replay, or a transport retry.

Agent Execution Claim

An Agent execution claim is an accepted observation where the Agent declares a state assertion such as ready-for-verification, completed, failed, blocked, or needing input. Claims update AgentExecution audit/progress state and may publish Entity events. Mission task completion follows owner workflow rules.

Entity Event

An Entity event is an accepted daemon-published fact. Agent stdout becomes an Entity event only after parsing, policy evaluation, owner handling, and event publication.

Target Ownership

Scan Findings From The First Implementation Pass

The first implementation pass exposed three architecture smells to resolve during convergence:

  • Marker prefixes were duplicated in daemon runtime code even though AgentExecutionOwnerMarkerPrefixSchema already owns the enum.
  • Runtime signal modules introduced terms such as protocol-marker, parser defaults, and signal decisions that were not part of ADR-0006.05 vocabulary.
  • The daemon signals folder mixed transport observation, payload parsing, policy evaluation, prompt rendering, and semantic state mutation in a way that obscured which behavior belongs to AgentExecution and which belongs to the owning Entity.

Correction rule: the daemon may normalize output into observations. Owner prefixes come from the AgentExecution descriptor, and scoped Mission, Task, Repository, or Artifact meaning stays with the owning Entity path.

Current consolidation outcome:

  • Agent signal marker payload schemas and limits live in the AgentExecution Entity schema boundary.
  • AgentExecution signal, observation, and decision types live in the AgentExecution protocol boundary, not in daemon runtime.
  • AgentExecution owns generic observation policy for session-safe promotion, duplicate rejection, lifecycle boundaries, and route/address validation.
  • Daemon runtime signal files are limited to launch instruction rendering and observation routing/normalization.
  • Standalone parser/normalizer files that only restated runtime details were removed.

Runtime-local helper terms are allowed only when they describe daemon mechanics. Keep them small:

  • observation: daemon-normalized runtime output.
  • origin: the runtime boundary that produced the observation.
  • diagnostic: non-authoritative runtime evidence.

Avoid promoting helper words such as candidate, decision, marker, or policy into architecture vocabulary unless an ADR defines them. If they remain in implementation code, they are implementation details and should stay close to the code that uses them.

AgentExecution Entity

AgentExecution owns:

  • execution identity
  • explicit AgentExecutionScope
  • durable Agent execution context
  • protocol descriptor snapshot
  • message descriptors
  • signal descriptors
  • signal delivery declarations
  • observation identity and idempotency
  • generic observation promotion policy for AgentExecution state
  • progress and attention state
  • terminal handle references
  • audit-facing AgentExecution events

Owning Entity

The owning Entity is resolved from AgentExecutionScope:

Scope kind Owning Entity
system System-level daemon owner, later formalized as an Entity if needed
repository Repository
mission Mission
task Task, with Running Mission aggregate as workflow delegate
artifact Artifact, with optional Mission or Task context from scope data

The owning Entity owns:

  • descriptor contribution for scope-specific signals
  • owner-addressed marker prefix
  • observation handling policy for scoped meaning
  • mapping accepted observations to Entity events, AgentExecution updates, and workflow events
  • context operations that require owner knowledge of artifacts, tasks, repositories, or missions

AgentExecution And Registry Boundary

AgentExecution owns launch intent, process state, selected signal delivery, terminal attachment state, message delivery attempts, provider output intake, stdout/stderr observation capture, MCP access registration state, and routing accepted observations to the owner path.

AgentExecutionRegistry owns only active lookup and live process-handle registration for AgentExecution instances. It may route an inbound transport observation to the active AgentExecution by id; runtime data shape, session control, lifecycle ownership, and owner-specific command behavior stay outside the registry.

Private launch and IO helpers are named for their mechanical responsibility and stay behind AgentExecution. AgentExecution remains the public owner of execution lifecycle.

AgentAdapter

AgentAdapter owns provider translation only:

  • adapter metadata validation
  • provider transport capability declaration
  • launch command, args, env, and optional preparation
  • provider-structured output parsing into observations
  • provider-specific delivery mechanics when the adapter supports structured delivery
  • provider-specific MCP client configuration when the selected delivery is mcp-tool

AgentAdapter capability, selected AgentExecution delivery, and provisioning result are separate values. The adapter can support MCP while an execution selects stdout markers because of launch mode, Mission policy, detached runtime, remote execution, or loopback constraints. If the selected delivery is mcp-tool and provisioning fails, the launch fails; stdout-marker delivery is selected only before launch through policy and operator intent.

Terminal And TerminalRegistry

Terminal and TerminalRegistry remain the PTY authority:

  • process lease
  • screen state
  • input and resize
  • exit state
  • terminal snapshots and recording updates

Terminal output is runtime material. Structured Agent communication starts when owner-addressed signal parsing accepts a line as a signal candidate.

Protocol Descriptor Shape

The implementation should introduce a schema-backed descriptor close to the AgentExecution Entity module.

Suggested shape:

type AgentExecutionProtocolDescriptor = {
  version: 1;
  owner: {
    entity: 'Task' | 'Mission' | 'Repository' | 'Artifact' | 'System';
    entityId: string;
    markerPrefix: '@task::' | '@mission::' | '@repository::' | '@artifact::' | '@system::';
  };
  scope: AgentExecutionScope;
  messages: AgentExecutionMessageDescriptor[];
  signals: AgentSignalDescriptor[];
  mcp?: {
    serverName: 'open-mission-mcp';
    exposure: 'session-scoped';
    publicApi: false;
  };
};

Suggested signal descriptor shape:

type AgentSignalDescriptor = {
  type: string;
  label: string;
  payloadSchemaKey: string;
  deliveries: Array<'stdout-marker' | 'mcp-tool'>;
  policy: 'progress' | 'claim' | 'input-request' | 'audit-message' | 'diagnostic';
  outcomes: Array<'agent-execution-event' | 'agent-execution-state' | 'owner-entity-event' | 'workflow-event'>;
};

The exact TypeScript names can change during implementation. The source of truth is Zod schemas with inferred types. The descriptor field is deliveries.

mcp descriptor metadata is not a place to store secrets, local endpoint data, or live session tokens. Those belong to daemon runtime access records and adapter launch preparation.

Baseline Signals

Every owner can contribute a different signal set, but the first clean implementation should support these shared Agent signals:

  • progress: update AgentExecution progress after owner policy acceptance.
  • needs_input: keep AgentExecution lifecycle running, set attention to awaiting-operator, attach the current input-request id, and publish an owner-visible event when useful. Payload must include question and choices, where each choice is either a fixed label/value choice or a manual freeform-input choice with label and optional placeholder.
  • blocked: update AgentExecution progress/attention and publish an owner-visible event when useful.
  • ready_for_verification: create a verification claim for owner/operator handling.
  • completed_claim: create a completion claim for owner/operator handling.
  • failed_claim: create a failure claim for owner/operator handling.
  • message: append an audit-facing AgentExecution message event.

Task scope can map ready_for_verification to verification workflow affordances. Task scope can map daemon-authoritative lifecycle events to Task completion through the Running Mission aggregate. Agent-authored completion claims remain claims until owner workflow behavior accepts a transition.

Implementation Sequence

1. Stabilize Descriptors

Create schema-backed protocol descriptor types in the AgentExecution Entity module.

Add signal descriptor schemas beside or near existing message descriptors. Prefer one AgentExecution-owned protocol schema module if AgentExecutionSchema.ts becomes too broad.

Replace singular delivery with deliveries: Array<'stdout-marker' | 'mcp-tool'>. Remove all singular field usage in the same change. This is greenfield cleanup, not a compatibility migration.

Expose the protocol descriptor in AgentExecution data or a protocol snapshot query so launch code, Open Mission, tests, and prompt rendering read the same descriptor.

2. Resolve Owning Entity From Scope

Introduce owner-Entity resolution from AgentExecutionScope in daemon/core code.

Resolution returns owner metadata and owner behavior used by daemon internals:

  • owner Entity name
  • owner Entity id
  • marker prefix
  • descriptor contribution
  • observation handling method

This can be implemented with TypeScript interfaces internally, but the architecture vocabulary remains owner-Entity resolution and Entity behavior.

3. Render Instructions From Descriptor

Replace hand-written signal payload lists in launch prompt construction with descriptor-rendered instructions for executions that declare stdout-marker delivery.

The rendered instructions include:

  • marker prefix
  • owner Entity kind resolved from AgentExecutionScope
  • execution id
  • required AgentExecution identity field
  • supported signal payloads from descriptors
  • examples generated from descriptors

For executions that declare mcp-tool delivery, open-mission-mcp materializes tools from the same signal descriptors. MCP tool names are execution-scoped transport affordances, not stable public APIs.

4. Parse Owner-Addressed Signals

Replace the single Mission protocol parser with owner-addressed Agent signal parsing.

Parsing accepts the prefix from the descriptor for the active execution. It parses strict JSON, validates payload shape through the signal descriptor, preserves event id / observation id data, and returns Agent execution observations.

A missing descriptor prefix is a launch/routing error. Runtime parsing uses the active execution descriptor.

The current parser and tests are useful source material, but the new parsing path should be descriptor-driven and should not duplicate marker-prefix literals owned by the AgentExecution schema.

4a. Materialize Mission MCP Tools

Use the Mission MCP Server Spec for concrete MCP realization. Architecturally, open-mission-mcp must:

  • start and stop with the daemon
  • register access for active Agent executions that declare mcp-tool delivery
  • materialize tools dynamically from the AgentExecution protocol descriptor
  • validate tool payloads with canonical AgentExecution signal schemas
  • route accepted calls into the same transport-neutral observation path as stdout markers
  • return acknowledgement status without claiming workflow completion

It uses canonical signal schemas, routes workflow effects through owner behavior, and shares the AgentExecution model.

5. Route Observations Through Owner Entity

Change AgentExecution observation application so it routes observations from every declared transport to the owning Entity path.

The owner path evaluates observation policy, updates AgentExecution state through accepted owner behavior, publishes Entity events, and emits workflow events through the Running Mission aggregate when scope rules require it.

Apply AgentExecution-owned idempotency before policy effects. Duplicate Agent signal event ids must not repeat AgentExecution state changes, owner Entity events, or workflow effects.

6. Update Runtime Messages

Clarify Agent execution messages as daemon/operator-to-AgentExecution input.

Move context-changing messages behind daemon-accepted AgentExecution context operations. Adapter delivery remains best effort and audit material.

7. Remove Conflicting Runtime Paths

After the owner-routed descriptor path works, remove or rewrite current code that keeps these responsibilities outside the target owners:

  • hard-coded @mission:: launch instruction generation as the universal signal source
  • signal payload lists duplicated outside descriptors
  • direct semantic application of scoped observations outside AgentExecution and the owning Entity path
  • Mission/task assumptions baked into AgentExecution identity where AgentExecutionScope should carry the owner context
  • runtime message descriptors stored as data without a matching signal descriptor source of truth
  • standalone runtime files that only restate schema, prefix, or descriptor facts already owned by AgentExecution
  • singular delivery descriptor fields
  • MCP-local signal payload schemas
  • MCP provisioning branches that silently degrade an MCP-declared launch into stdout markers

Tests And Validation

Minimum test coverage:

  • descriptor schema validation for message and signal descriptors
  • descriptor schema rejects singular delivery and accepts deliveries
  • owner prefix derivation for task, mission, repository, and artifact scopes
  • prompt instructions generated from descriptors
  • open-mission-mcp tools generated from the same descriptors
  • parser accepts only the active execution’s owner prefix and descriptor payloads
  • parser rejects malformed, oversized, wrong-execution, duplicate, and unsupported markers
  • MCP tool calls reject malformed, oversized, wrong-execution, duplicate, unauthorized, and unsupported inputs
  • AgentExecution routes stdout-marker and MCP observations to owner handling rather than applying scoped meaning directly in transport code
  • Task-owned ready/completion/failure claims remain claims until owner workflow behavior accepts lifecycle changes
  • Open Mission reads message and signal descriptors from the same protocol source used for launch instructions

Run at minimum:

pnpm --filter @flying-pillow/open-mission-core check
pnpm --filter @flying-pillow/open-mission-core test
pnpm --filter @flying-pillow/open-mission-core build
pnpm --filter @flying-pillow/open-mission-web check
pnpm --filter @flying-pillow/open-mission-web build

Open Design Questions

  1. Should artifact-scoped execution always use @artifact::, or should task-owned artifact work use @task:: when taskId is present?
  2. Should owner observation handling be a daemon-internal Entity method first, then promoted to Entity contract only when a client-facing need appears?
  3. Should AgentExecution publish separate events for progress.changed, claim.created, and input.requested, or keep only data.changed until Open Mission needs more specific event channels?
  4. Should @system:: be implemented now, or postponed until a System Entity contract exists?

Working Implementation Rule

Prefer deleting conflicting old paths over wrapping them. If the current implementation duplicates descriptor truth, owner routing, or signal payload definitions, converge it into the new owner-addressed protocol model in the same bounded change.