runtime-contract.md

Runtime Contract

Thesis

The proposed runtime contract is a narrow layer that sits above model and tool SDKs and below heavier orchestration or product-specific shells. Its purpose is to standardize execution semantics for coding agents without dictating product UX or business-domain logic.

Core Entities

1. Task
2. Turn
3. ToolCall
4. ToolResult
5. CompletionAttempt
6. RecoveryAttempt
7. AgentState
8. RequiredAction
9. ContextCompaction
10. SubagentRun
11. PolicyDecision
12. JournalEvent

Core Invariants

1. A task is not complete merely because the model says so.
2. Completion must be explicit and guarded.
3. Tool failures remain part of task state unless classified as terminal by runtime or policy.
4. Runtime state must be inspectable independently of the transcript.
5. Context management is part of the runtime contract.
6. Delegation must be bounded and observable.
7. Policy interception should exist at tool and stop boundaries.
8. Domain-specific rules belong above or beside the runtime core.

Lifecycle

1. Create task.
2. Build initial runtime context.
3. Enter turn loop.
4. Execute tools or handle required actions.
5. Reinject results.
6. Evaluate completion attempts.
7. Compact or checkpoint when needed.
8. Stop only when completion is accepted or an explicit blocker is raised.

Interface Sketch

type AgentState =
  | 'idle'
  | 'running'
  | 'streaming'
  | 'waiting_for_permission'
  | 'waiting_for_input'
  | 'compacting'
  | 'resumable'
  | 'completed'
  | 'failed_terminal';

interface RuntimeTask {
  id: string;
  goal: string;
  state: AgentState;
  openRequirements: RequiredAction[];
  journal: JournalEvent[];
}

interface ToolResult {
  callId: string;
  status: 'success' | 'failure';
  output?: string;
  errorType?: string;
  retryable?: boolean;
}

interface CompletionDecision {
  accepted: boolean;
  reasons: string[];
}

Boundaries

What Belongs In This Layer

• task lifecycle,
• execution loop,
• completion gating,
• failure reinjection,
• state transitions,
• compaction hooks,
• subagent contracts,
• journals and telemetry events.

What Does Not Belong In This Layer

• repository-specific coding rules,
• product UI styling,
• Git-specific workflow policies,
• business-domain approval semantics,
• vendor-specific instruction file conventions.

Current Confidence

The existence of a narrow runtime layer is a speculative proposal, but many of the entities and invariants inside it are supported by stronger convergence signals.