Executor Protocol — V1

Executors implement this interface to receive a task from the control plane, stream run events, and report completion. Source file: spec/v1/executors/PROTOCOL.md.

Phase 2 executor interface

Every executor is a package under packages/executors/<name>/ that exports an Executor TypeScript interface:

interface Executor {
  /** Unique name, e.g. "claude-code", "mock", "http" */
  name: string;

  /** Launch a run for the given task. Returns when the run is complete. */
  run(input: ExecutorInput): Promise<ExecutorResult>;
}

interface ExecutorInput {
  runId: string;       // UUID
  tenantId: string;    // UUID
  projectSlug: string;
  taskType: string;    // e.g. "dev-task"
  skillName: string;   // e.g. "core:dev-task"
  worktreePath: string;
  iterationCap: number;
  emit: (event: RunEvent) => Promise<void>;
}

interface ExecutorResult {
  status: 'success' | 'failed' | 'cancelled';
  cost?: { llmTokens?: number; durationMs?: number };
}

Built-in executors

Name	Description	Phase
claude-code	Runs Claude Code (flat-rate Max subscription) against a git worktree. Primary executor for all active projects.	P0
mock	Deterministic mock for unit/integration testing. Emits fake events and returns a configurable status after a fixed delay.	P0
http	BYO-key escape hatch. Forwards the task to any HTTP endpoint that implements the executor protocol. Enables external or custom executors.	P2

Raw source (spec/v1/executors/PROTOCOL.md)

# Executor Protocol (placeholder — fleshed out in Phase 2)

The interface every executor implements. See [`../../../docs/EXECUTORS.md`](../../../docs/EXECUTORS.md) for the full design.

## Phase 0 status

In P0 we only have one executor (`claude-code`) and it lives inside the worker. The protocol is defined informally by the `Executor` TypeScript interface in `packages/executors/claude-code/`.

In Phase 2 this document gets fleshed out with:
- Formal request/response shapes (with JSON Schema)
- The HTTP executor protocol (for external executors)
- Completion-signal patterns
- Iteration semantics
- Sandbox / isolation requirements