@titan-design/agent 0.1.0 → 0.2.0

package/README.md

@@ -120,8 +120,112 @@ says. Prefer `allowedTools` wildcards over a permissive mode.
 This package runs one session. It does not pool, schedule, or retry; that
 belongs to the workflow tier.
 
+## Explicit multi-harness contracts
+
+`dispatchHarnessRun(request, adapter)` is the new, explicit contract for Claude
+Code and Codex adapters. It does not replace or reroute `runAgent()`. Every request
+has a discriminating `harness`, a fresh or resume target, and a required positive
+finite `wallTimeMs`. Claude's Anthropic SDK fields live only under the
+`claude-code` branch; Codex model, reasoning, sandbox, approval, and native JSON
+Schema fields live only under the `codex` branch.
+
+Optional limits name their unit (`usd`, `model_requests`, `agent_iterations`, or
+`tokens`), scope (`execution` or `conversation`), and enforcement (`hard` or
+`advisory`). These are not interchangeable: an agent iteration is not a model
+request, and an estimated SDK dollar stop is not a hard financial cap.
+
+Adapters supply a `HarnessCapabilityDescriptor` that marks every operation and
+declared limit `supported`, `unsupported`, or `unverified`, with evidence or a
+reason. Core declares no adapter capabilities itself. Before invoking an adapter,
+the dispatcher checks the operation, resume identity, structured-output and
+cancellation needs, caller requirements, mandatory hard execution deadline, and
+all optional limits. Unsupported and unverified requirements return an
+`unsupported_requirement` result with no adapter call.
+
+Support for the hard `milliseconds` execution limit means the adapter can stop
+the local execution at its deadline. It does not claim that a remote model request
+has stopped unless the adapter separately reports verified cancellation support.
+Normalized progress, results, usage measurements, execution identity, conversation
+identity, and transcript source hints contain no harness-native event types.
+
+## Supervised Codex exec adapter
+
+`createCodexExecAdapter({ auth: "cached-cli" })` runs the pinned ChatGPT desktop
+Codex binary through `codex exec --json`. The caller must select a model and an
+absolute working directory. Fresh runs persist a native thread; resumes always use
+the supplied native thread ID and never `--last`. The adapter ignores user config,
+strips API-key credentials from the child environment, accepts only the
+noninteractive `never` approval policy, and leaves persistence enabled so
+`@titan-design/session-read` can discover the rollout by thread ID and namespace.
+
+The adapter checks `codex --version` before every launch. The mandatory wall deadline
+covers that check, temporary output-schema setup, and the run itself. Timeout or
+caller abort terminates the owned process group, then sends `SIGKILL` after the
+configured grace period. JSONL output becomes normalized progress, conversation
+identity, final text or locally validated structured output, and token usage with
+Codex event provenance. Hard dollar, request, iteration, and token caps remain
+unsupported and fail preflight before either version probing or process spawn.
+
+A zero exit is successful only after Codex emits `turn.completed`. Its usage is a
+turn snapshot: the adapter uses Codex's native turn ID when one is present and an
+execution-correlated synthetic turn ID otherwise. It is never labeled as a
+conversation total. If an abort or wall deadline stops the OS process without a
+native terminal turn event, the result is `cancelled_unknown` and retains the
+requested cause and process exit evidence. Temporary schema cleanup completes
+before the terminal progress event, so cleanup failure cannot follow a reported
+successful finish.
+
 ## Ending a run
 
 Every run ends cleanly. The inactivity watchdog resets on each streamed message
 and, like the caller's `AbortSignal`, ends the run through the SDK's
 `abortController` and then `query.close()`, so no CLI subprocess is left behind.
+
+## Bounded Claude adapter
+
+`createClaudeCodeAdapter({ maxTurns, maxBudgetUsd, inactivityTimeoutMs?, deps? })`
+wraps the existing `runAgent` in the common `HarnessAdapter<"claude-code">`
+contract. Both native circuit breakers remain required. Every request also supplies
+`wallTimeMs`; expiration aborts and closes the owned SDK query. A local stop cannot
+prove that native execution was cancelled, so the durable dispatcher records an
+unknown cancellation unless terminal evidence is available.
+
+Fresh and resumed requests keep invocation identity separate from native session
+identity. Native options, permission settings, MCP servers, schema validation, and
+cached-auth handling flow through `runAgent`. Structured output remains validated
+by the caller's Zod schema. SDK query usage is aggregated across its main, subagent, and internal model calls
+into one turn-scoped snapshot with estimated cost. Multiple models yield a null
+model label so their totals do not overwrite each other. Total input includes cache
+reads and cache creation; those subset counters must not be added again.
+
+The adapter does not translate SDK `maxTurns` into a generic model-request or
+agent-iteration limit, or treat the SDK budget estimate as an exact monetary cap.
+Generic optional limits remain unsupported until their semantics are verified.
+No process reattachment, visible terminal, or semantic-interrupt capability is
+claimed by this wrapper. Legacy `runAgent` callers retain their existing API.
+
+## Durable harness dispatch
+
+`createDurableHarnessDispatcher(adapter, { ledger, supervisorId, leaseMs })`
+wraps either harness adapter with an early durable acknowledgment and a completion
+promise. Apply `executionLedgerMigration(version)` from
+`@titan-design/agent-lifecycle` to the authoritative database before constructing
+the ledger. Each dispatch requires caller-generated `executionId` and `requestKey`
+values. The dispatcher commits `prepare` and `begin_dispatch` before calling the
+adapter, renews its captured owner lease while the call is live, and commits the
+terminal result before resolving completion.
+
+`reconcile(executionId)` returns a live handle only in the same dispatcher instance
+while its exact owner generation and lease remain valid. After restart it can read
+back a durable terminal result. An expired record that never committed
+`begin_dispatch` is closed as a retryable failure because the ledger proves the
+adapter was not called. A missing record or any post-dispatch record without an
+attachment handle returns unknown or recovery-required evidence and never
+authorizes resubmission. The dispatcher does not infer liveness from a PID or a
+transcript.
+
+Cancellation intent is stored before the local abort signal fires. Without a
+native terminal acknowledgment after a deadline or abort, the ledger records
+`cancellation_unknown`. Lease-renewal, stale-owner, and local persistence failures
+settle completion promptly even when the adapter ignores abort; they cannot write a
+terminal result through a newer owner's fence. Durable results must be JSON-safe.

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { PermissionMode, AgentDefinition, McpServerConfig, HookEvent, HookCallbackMatcher, SettingSource, SDKMessage, ModelUsage, query, SDKResultMessage } from '@anthropic-ai/claude-agent-sdk';
 import { ZodError, ZodType } from 'zod';
+import { ConversationIdentity, ExecutionIdentity, UsageMeasurement, ExecutionRecord, ExecutionTerminal, AgentIdentity, ExecutionReconcileOutcome } from '@titan-design/agent-protocol';
+import { ExecutionLedger } from '@titan-design/agent-lifecycle';
 
 /** Why a run ended without a usable answer. One kind per recovery strategy. */
 type AgentFailure = {
@@ -115,6 +117,259 @@ interface AgentRunDeps {
  */
 declare function runAgent<T = string>(config: AgentRunConfig<T>, deps?: AgentRunDeps): Promise<AgentRunResult<T>>;
 
+type Harness = "claude-code" | "codex";
+declare const CODEX_SANDBOXES: readonly ["read-only", "workspace-write", "danger-full-access"];
+declare const CODEX_APPROVAL_POLICIES: readonly ["untrusted", "on-failure", "on-request", "never"];
+type CodexSandbox = (typeof CODEX_SANDBOXES)[number];
+type CodexApprovalPolicy = (typeof CODEX_APPROVAL_POLICIES)[number];
+declare const EXECUTION_CAPABILITIES: readonly ["fresh_run", "resume", "fork", "structured_output", "interactive_approvals", "external_cancellation", "semantic_interrupt", "active_turn_steering", "idle_turn_submission", "persisted_transcript", "process_reattachment", "token_reporting"];
+type ExecutionCapability = (typeof EXECUTION_CAPABILITIES)[number];
+type CapabilityAssessment = {
+    status: "supported";
+    evidence: string;
+} | {
+    status: "unsupported" | "unverified";
+    reason: string;
+};
+type LimitUnit = "milliseconds" | "usd" | "model_requests" | "agent_iterations" | "tokens";
+type OptionalLimitUnit = Exclude<LimitUnit, "milliseconds">;
+type LimitScope = "execution" | "conversation";
+type LimitEnforcement = "hard" | "advisory";
+interface ExecutionLimit {
+    unit: OptionalLimitUnit;
+    value: number;
+    scope: LimitScope;
+    enforcement: LimitEnforcement;
+}
+interface LimitCapability {
+    unit: LimitUnit;
+    scope: LimitScope;
+    enforcement: LimitEnforcement;
+    assessment: CapabilityAssessment;
+}
+/** A factual report supplied by an adapter implementation, not a promise made by the core. */
+interface HarnessCapabilityDescriptor<H extends Harness = Harness> {
+    harness: H;
+    adapter: {
+        name: string;
+        version: string;
+    };
+    capabilities: Record<ExecutionCapability, CapabilityAssessment>;
+    limits: readonly LimitCapability[];
+}
+type RunTarget = {
+    kind: "fresh";
+    namespace: string;
+} | {
+    kind: "resume";
+    conversation: ConversationIdentity;
+};
+interface BoundedRunBase {
+    prompt: string;
+    cwd: string;
+    target: RunTarget;
+    /** Required hard deadline for this execution. Must be positive and finite. */
+    wallTimeMs: number;
+    limits?: readonly ExecutionLimit[];
+    requires?: readonly ExecutionCapability[];
+    signal?: AbortSignal;
+    onProgress?: (progress: HarnessRunProgress) => void;
+}
+/** Anthropic SDK configuration remains confined to the Claude Code branch. */
+interface ClaudeCodeNativeOptions<T> {
+    model?: string;
+    outputSchema?: ZodType<T>;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    permissionMode?: PermissionMode;
+    agents?: Record<string, AgentDefinition>;
+    mcpServers?: Record<string, McpServerConfig>;
+    hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+    settingSources?: SettingSource[];
+    allowApiKeyBilling?: boolean;
+}
+interface CodexOutputSchema<T> {
+    jsonSchema: Record<string, unknown>;
+    /** Second validation boundary after Codex applies the native JSON Schema. */
+    parse(value: unknown): T;
+}
+interface CodexNativeOptions<T> {
+    model?: string;
+    /** Adapter validates model/version-specific values; core only requires a nonempty string. */
+    reasoningEffort?: string;
+    sandbox?: CodexSandbox;
+    approvalPolicy?: CodexApprovalPolicy;
+    outputSchema?: CodexOutputSchema<T>;
+}
+interface ClaudeCodeRunRequest<T = string> extends BoundedRunBase {
+    harness: "claude-code";
+    native?: ClaudeCodeNativeOptions<T>;
+}
+interface CodexRunRequest<T = string> extends BoundedRunBase {
+    harness: "codex";
+    native?: CodexNativeOptions<T>;
+}
+type HarnessRunRequest<T = string> = ClaudeCodeRunRequest<T> | CodexRunRequest<T>;
+type HarnessRunRequestFor<H extends Harness, T = string> = H extends "claude-code" ? ClaudeCodeRunRequest<T> : CodexRunRequest<T>;
+type HarnessRunProgress = {
+    harness: Harness;
+    atMs: number;
+} & ({
+    kind: "execution_started";
+    execution: ExecutionIdentity;
+} | {
+    kind: "conversation_identified";
+    executionId: string;
+    conversation: ConversationIdentity;
+} | {
+    kind: "assistant_output";
+    executionId: string;
+    text: string;
+} | {
+    kind: "usage";
+    executionId: string;
+    measurement: UsageMeasurement;
+} | {
+    kind: "execution_finished";
+    executionId: string;
+    outcome: "succeeded" | "failed" | "cancelled";
+});
+type HarnessRunOutput<T> = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "structured";
+    value: T;
+};
+interface TranscriptSourceHint {
+    format: string;
+    namespace: string;
+    path?: string;
+}
+type HarnessRunFailure = {
+    kind: "invalid_request";
+    reason: string;
+} | {
+    kind: "harness_mismatch";
+    reason: string;
+} | {
+    kind: "unsupported_requirement";
+    reason: string;
+    requirement: {
+        kind: "capability";
+        capability: ExecutionCapability;
+    } | {
+        kind: "limit";
+        limit: LimitCapability;
+    };
+    status: "unsupported" | "unverified";
+} | {
+    kind: "rate_limited";
+    reason: string;
+    retryAtMs?: number;
+    native?: unknown;
+} | {
+    kind: "limit_exceeded";
+    reason: string;
+    unit: LimitUnit;
+    native?: unknown;
+} | {
+    kind: "output_invalid";
+    reason: string;
+    native?: unknown;
+} | {
+    kind: "auth_misconfigured";
+    reason: string;
+    native?: unknown;
+} | {
+    kind: "aborted";
+    reason: string;
+} | {
+    kind: "wall_time_exceeded";
+    reason: string;
+    wallTimeMs: number;
+} | {
+    kind: "cancelled_unknown";
+    reason: string;
+    native?: unknown;
+} | {
+    kind: "runtime_error";
+    reason: string;
+    native?: unknown;
+};
+type HarnessRunResult<T = string, H extends Harness = Harness> = {
+    ok: true;
+    harness: H;
+    execution: ExecutionIdentity;
+    conversation: ConversationIdentity;
+    output: HarnessRunOutput<T>;
+    usage: readonly UsageMeasurement[];
+    transcript?: TranscriptSourceHint;
+} | {
+    ok: false;
+    harness: H;
+    execution?: ExecutionIdentity;
+    conversation?: ConversationIdentity;
+    failure: HarnessRunFailure;
+    usage: readonly UsageMeasurement[];
+};
+interface HarnessAdapter<H extends Harness> {
+    descriptor: HarnessCapabilityDescriptor<H>;
+    run<T>(request: HarnessRunRequestFor<H, T>): Promise<HarnessRunResult<T, H>>;
+}
+
+declare function preflightHarnessRun<H extends Harness, T>(request: HarnessRunRequestFor<H, T>, descriptor: HarnessCapabilityDescriptor<H>): HarnessRunFailure | undefined;
+declare function dispatchHarnessRun<H extends Harness, T>(request: HarnessRunRequestFor<H, T>, adapter: HarnessAdapter<H>): Promise<HarnessRunResult<T, H>>;
+
+interface CodexProcessExit {
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+}
+interface SupervisedCodexProcess {
+    stdout: AsyncIterable<string>;
+    stderr: AsyncIterable<string>;
+    completed: Promise<CodexProcessExit>;
+    terminate(signal: "SIGTERM" | "SIGKILL"): void;
+}
+interface CodexSchemaFile {
+    path: string;
+    dispose(): Promise<void>;
+}
+interface CodexProcessInput {
+    executablePath: string;
+    args: readonly string[];
+    cwd: string;
+    env: Record<string, string>;
+}
+interface CodexVersionInspectionOptions {
+    signal?: AbortSignal;
+    timeoutMs: number;
+}
+
+declare const DEFAULT_CODEX_EXECUTABLE = "/Applications/ChatGPT.app/Contents/Resources/codex";
+declare const SUPPORTED_CODEX_EXEC_VERSION = "0.154.0-alpha.6.1";
+declare const STRIPPED_CODEX_AUTH_VARS: readonly ["CODEX_API_KEY", "OPENAI_API_KEY", "OPENAI_ACCESS_TOKEN"];
+interface CodexExecAdapterOptions {
+    auth: "cached-cli";
+    executablePath?: string;
+    env?: NodeJS.ProcessEnv;
+    killGraceMs?: number;
+}
+interface CodexExecDeps {
+    inspectVersion?: (executablePath: string, env: Record<string, string>, options: CodexVersionInspectionOptions) => Promise<string>;
+    start?: (input: CodexProcessInput) => SupervisedCodexProcess;
+    createSchemaFile?: (schema: Record<string, unknown>) => Promise<CodexSchemaFile>;
+    executionId?: () => string;
+    now?: () => number;
+    deadlineNow?: () => number;
+}
+declare function createCodexExecAdapter(options: CodexExecAdapterOptions, deps?: CodexExecDeps): HarnessAdapter<"codex">;
+declare function prepareCodexEnv(env: NodeJS.ProcessEnv): Record<string, string>;
+declare function codexExecCapabilities(): HarnessCapabilityDescriptor<"codex">;
+declare function buildCodexExecArgs<T>(request: CodexRunRequest<T>, schemaPath?: string): string[];
+
+declare const DEFAULT_CODEX_KILL_GRACE_MS = 2000;
+
 interface ClassifyOptions {
     /** Epoch millis used to turn a relative "retry after Ns" hint into an absolute date. */
     now?: number;
@@ -185,4 +440,85 @@ declare const FORBIDDEN_API_KEY_SOURCES: ReadonlySet<string>;
 /** Post-flight on the first `system/init`, the earliest point the real auth route is observable. */
 declare function assertApiKeySourceAllowed(observed: string | undefined): void;
 
-export { ANTI_NESTING_VARS, type AgentFailure, type AgentFailureKind, type AgentInit, type AgentRunConfig, type AgentRunDeps, type AgentRunResult, type AgentUsage, AuthMisconfiguredError, CLAUDE_CODE_PASSTHROUGH_VARS, type ClassifyOptions, DEFAULT_INACTIVITY_MS, DEFAULT_MAX_RETRIES, FORBIDDEN_API_KEY_SOURCES, type PrepareEnvOptions, STRIPPED_AUTH_VARS, STRIPPED_PROXY_VARS, assertApiKeySourceAllowed, assertAuthEnvOk, classifyResult, prepareEnv, runAgent, sumModelCost, usageFromResult };
+interface DurableHarnessSuccess<T = unknown, H extends Harness = Harness> {
+    harness: H;
+    adapterExecution: ExecutionIdentity;
+    conversation: ConversationIdentity;
+    output: HarnessRunOutput<T>;
+    usage: readonly UsageMeasurement[];
+    transcript?: TranscriptSourceHint;
+}
+type DurableHarnessRecord<H extends Harness = Harness> = ExecutionRecord<DurableHarnessSuccess<unknown, H>>;
+type DurableSettlement<T = unknown, H extends Harness = Harness> = {
+    kind: "terminal";
+    record: ExecutionRecord<DurableHarnessSuccess<T, H>>;
+    terminal: ExecutionTerminal<DurableHarnessSuccess<T, H>>;
+} | {
+    kind: "recovery_required";
+    record: DurableHarnessRecord<H>;
+    evidence: string;
+} | {
+    kind: "ownership_lost";
+    record?: DurableHarnessRecord<H>;
+    evidence: string;
+};
+interface DurableDispatchInput<H extends Harness, T = string> {
+    executionId: string;
+    requestKey: string;
+    agent?: AgentIdentity;
+    request: HarnessRunRequestFor<H, T>;
+}
+interface DurableDispatchAck<T = unknown, H extends Harness = Harness> {
+    executionId: string;
+    requestKey: string;
+    runnerRef: string;
+    completion: Promise<DurableSettlement<T, H>>;
+}
+interface DurableLiveHandle<T = unknown, H extends Harness = Harness> {
+    runnerRef: string;
+    completion: Promise<DurableSettlement<T, H>>;
+}
+type DurableReconcileOutcome<H extends Harness = Harness> = ExecutionReconcileOutcome<DurableHarnessSuccess<unknown, H>, DurableLiveHandle<unknown, H>>;
+type DurableCancelResult<H extends Harness = Harness> = {
+    kind: "requested";
+    record: DurableHarnessRecord<H>;
+} | {
+    kind: "not_live";
+    evidence: string;
+} | {
+    kind: "ownership_lost";
+    record?: DurableHarnessRecord<H>;
+    evidence: string;
+};
+interface DurableHarnessDispatcher<H extends Harness> {
+    readonly adapter: HarnessAdapter<H>;
+    dispatch<T>(input: DurableDispatchInput<H, T>): Promise<DurableDispatchAck<T, H>>;
+    reconcile(executionId: string): Promise<DurableReconcileOutcome<H>>;
+    cancel(executionId: string, reason: string): DurableCancelResult<H>;
+}
+interface DurableHarnessDispatcherOptions<H extends Harness> {
+    ledger: ExecutionLedger<DurableHarnessSuccess<unknown, H>>;
+    supervisorId: string;
+    leaseMs: number;
+    renewEveryMs?: number;
+}
+interface DurableHarnessDispatcherDeps {
+    eventId?: () => string;
+    now?: () => number;
+    setInterval?: typeof globalThis.setInterval;
+    clearInterval?: typeof globalThis.clearInterval;
+}
+
+declare function createDurableHarnessDispatcher<H extends Harness>(adapter: DurableHarnessDispatcher<H>["adapter"], options: DurableHarnessDispatcherOptions<H>, deps?: DurableHarnessDispatcherDeps): DurableHarnessDispatcher<H>;
+
+interface ClaudeCodeAdapterOptions {
+    maxTurns: number;
+    maxBudgetUsd: number;
+    inactivityTimeoutMs?: number;
+    deps?: AgentRunDeps;
+}
+/** Existing Claude query circuit breakers remain mandatory; their native units stay explicit. */
+declare function createClaudeCodeAdapter(options: ClaudeCodeAdapterOptions): HarnessAdapter<"claude-code">;
+declare function claudeCodeCapabilities(): HarnessCapabilityDescriptor<"claude-code">;
+
+export { ANTI_NESTING_VARS, type AgentFailure, type AgentFailureKind, type AgentInit, type AgentRunConfig, type AgentRunDeps, type AgentRunResult, type AgentUsage, AuthMisconfiguredError, type BoundedRunBase, CLAUDE_CODE_PASSTHROUGH_VARS, CODEX_APPROVAL_POLICIES, CODEX_SANDBOXES, type CapabilityAssessment, type ClassifyOptions, type ClaudeCodeAdapterOptions, type ClaudeCodeNativeOptions, type ClaudeCodeRunRequest, type CodexApprovalPolicy, type CodexExecAdapterOptions, type CodexExecDeps, type CodexNativeOptions, type CodexOutputSchema, type CodexProcessExit, type CodexProcessInput, type CodexRunRequest, type CodexSandbox, type CodexSchemaFile, type CodexVersionInspectionOptions, DEFAULT_CODEX_EXECUTABLE, DEFAULT_CODEX_KILL_GRACE_MS, DEFAULT_INACTIVITY_MS, DEFAULT_MAX_RETRIES, type DurableCancelResult, type DurableDispatchAck, type DurableDispatchInput, type DurableHarnessDispatcher, type DurableHarnessDispatcherDeps, type DurableHarnessDispatcherOptions, type DurableHarnessRecord, type DurableHarnessSuccess, type DurableLiveHandle, type DurableReconcileOutcome, type DurableSettlement, EXECUTION_CAPABILITIES, type ExecutionCapability, type ExecutionLimit, FORBIDDEN_API_KEY_SOURCES, type Harness, type HarnessAdapter, type HarnessCapabilityDescriptor, type HarnessRunFailure, type HarnessRunOutput, type HarnessRunProgress, type HarnessRunRequest, type HarnessRunRequestFor, type HarnessRunResult, type LimitCapability, type LimitEnforcement, type LimitScope, type LimitUnit, type OptionalLimitUnit, type PrepareEnvOptions, type RunTarget, STRIPPED_AUTH_VARS, STRIPPED_CODEX_AUTH_VARS, STRIPPED_PROXY_VARS, SUPPORTED_CODEX_EXEC_VERSION, type SupervisedCodexProcess, type TranscriptSourceHint, assertApiKeySourceAllowed, assertAuthEnvOk, buildCodexExecArgs, classifyResult, claudeCodeCapabilities, codexExecCapabilities, createClaudeCodeAdapter, createCodexExecAdapter, createDurableHarnessDispatcher, dispatchHarnessRun, preflightHarnessRun, prepareCodexEnv, prepareEnv, runAgent, sumModelCost, usageFromResult };