@meistrari/agent-core 0.0.0 → 0.1.1

package/README.md

@@ -7,12 +7,20 @@ Shared contracts and runtime modules for Tela coding-agent sandboxes.
 | `@meistrari/agent-core/protocol` | Provider-neutral agent commands, events, content, tools, usage, work items (Claude and Codex share it). |
 | `@meistrari/agent-core/supervisor-protocol/*` | Strict wire contracts between a worker runtime and the resident sandbox supervisor: bootstrap, commands, events, reverse RPC, control authority. |
 | `@meistrari/agent-core/errors`, `/logger`, `/provenance` | Shared primitives. |
-| `@meistrari/agent-core/supervisor` | Sandbox-resident supervisor runtime (Bun, SQLite). |
-| `@meistrari/agent-core/worker-runtime-client` | Control-plane WSS client: leases, generation fencing, command pump, durable event acking, reverse RPC dispatch. |
-| `@meistrari/agent-core/claude`, `/codex` | Harness adapters. |
+| `@meistrari/agent-core/supervisor` | Sandbox-resident supervisor runtime (Bun, WebSocket, SQLite), provider factory, and product-facing ports. |
+| `@meistrari/agent-core/worker-runtime-client` | Control-plane WSS client: leases, generation fencing, command pump, durable event ACKs, reverse RPC dispatch, ES256 authority, token crypto, and PG notifications. |
+| `@meistrari/agent-core/testing` | In-memory control-plane, scripted provider, loopback connection, and ES256 test fixtures. |
+| `@meistrari/agent-core/template-onboarding` | Validated service-owned E2B template registration and immutable provenance contract. |
+| `@meistrari/agent-core/agents` | Provider-neutral agent, run, tool, event-stream, and instruction-composer contracts. |
+| `@meistrari/agent-core/claude` | Claude Agent SDK provider with normalized lifecycle, message, tool, work, usage, and user-input events. |
+| `@meistrari/agent-core/codex` | Codex app-server provider, JSON-RPC transport, normalized event mapping, and pluggable authentication. |
+
+The supervisor accepts the Claude and Codex adapters through `createAgentSupervisorProviderFactory`, preserving the same durable wire protocol for either harness.
 
 The package ships TypeScript source and targets Bun `>=1.3.10`. There is no wire protocol version: a sandbox keeps the exact agent-core build it was created with for its lifetime (immutable sandbox invariant). Incompatible wire changes require reprovisioning sandboxes, never in-place upgrades.
 
+agent-core does not own a universal E2B template. Each consuming service builds and onboards its own template against the shared contracts and records that template's agent-core provenance. agent-api and Remy may therefore use different base images, harness versions, system packages, and startup hooks without forking the control protocol.
+
 ## Development
 
 ```bash
@@ -21,6 +29,31 @@ bun run lint
 bun run typecheck
 bun run test        # unit tests (src/**/*.test.ts)
 bun run test:e2e    # loopback worker <-> supervisor e2e
+bun run build:supervisor # cross-compile the Linux x64 resident executable
 ```
 
+## Resident supervisor entry
+
+`agent-core-supervisor` loads a product-owned extensions module so credentials, tools, workspace preparation, hooks, payload storage, and provider construction remain outside the shared runtime:
+
+```bash
+bunx agent-core-supervisor \
+  --extensions ./supervisor-extensions.ts \
+  --authority-jwks-path ./control-authority.json
+```
+
+Use `--loopback-tcp` for local and image-build probes. Production images default to the protected Unix socket. The extension module exports `default`, `extensions`, or `createSupervisorExtensions()` matching `SupervisorExtensions`.
+
 Publishing runs from `main` through `.github/workflows/publish.yml` (conventional commits decide the bump).
+
+## Durable command outcomes
+
+A supervisor `received` ACK advances the command delivery cursor only. Implementations of
+`DurableEventSink.record` must atomically store each durable event, project
+`supervisor.command.applied` or `supervisor.command.failed` into command state, and advance the
+ACK floor. Duplicate events must not repeat projections. This keeps outcomes consistent when
+the worker disconnects after persistence but before sending its event ACK.
+
+The former `ConnectionAuthorityStore.projectAppliedCommand` callback has been removed.
+Move that projection into the durable-event transaction; receiving a command does not prove
+that the provider executed it. See `InMemoryRuntimeControlPlane.record` for the test fixture.

package/bin/supervisor.ts

@@ -0,0 +1,116 @@
+#!/usr/bin/env bun
+import type { SupervisorExtensions } from '../src/supervisor/create-supervisor-runtime'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { createLogger } from '../src/logger'
+import {
+    createSupervisorRuntime,
+    residentSupervisorConfig,
+    TERMINAL_ERROR_CODE,
+} from '../src/supervisor'
+
+interface SupervisorExtensionsModule {
+    default?: SupervisorExtensions
+    extensions?: SupervisorExtensions
+    createSupervisorExtensions?: (input: {
+        developmentFaultDirectory?: string
+    }) => SupervisorExtensions | Promise<SupervisorExtensions>
+}
+
+const arguments_ = process.argv.slice(2)
+if (arguments_.includes('--help')) {
+    process.stdout.write(`agent-core-supervisor
+
+Required:
+  --extensions <path>                Supervisor extensions module (or AGENT_CORE_SUPERVISOR_EXTENSIONS)
+
+Options:
+  --loopback-tcp                     Listen on 127.0.0.1:8080 instead of the protected Unix socket
+  --port <number>                    Override the loopback TCP port
+  --authority-jwks-path <path>       Override the ES256 public JWKS configuration
+  --sandbox-id-path <path>           Override the local E2B sandbox identity file
+  --state-root <path>                Override the supervisor SQLite state root
+  --development-fault-directory <path>
+  --help
+`)
+    process.exit(0)
+}
+
+await main()
+
+async function main(): Promise<void> {
+    const logger = createLogger({ base: { runtime: 'agent-core-supervisor' } })
+    try {
+        const developmentFaultDirectory = option('--development-fault-directory')
+        const extensions = await loadExtensions({
+            path: option('--extensions') ?? process.env.AGENT_CORE_SUPERVISOR_EXTENSIONS,
+            developmentFaultDirectory,
+        })
+        const portValue = option('--port')
+        const port = portValue === undefined ? undefined : parsePort(portValue)
+        const runtime = await createSupervisorRuntime({
+            config: residentSupervisorConfig({
+                listen: arguments_.includes('--loopback-tcp') ? 'loopback-tcp' : 'protected-unix',
+                ...(port === undefined ? {} : { port }),
+                ...(option('--authority-jwks-path') ? { authorityJwksPath: option('--authority-jwks-path') } : {}),
+                ...(option('--sandbox-id-path') ? { sandboxIdPath: option('--sandbox-id-path') } : {}),
+                ...(option('--state-root') ? { stateRoot: option('--state-root') } : {}),
+            }),
+            extensions,
+            logger,
+        })
+        let stopping: Promise<void> | undefined
+        const stop = (reason: 'sigterm' | 'sigint') => {
+            stopping ??= runtime.stop({ reason }).then(() => {
+                process.exitCode = 0
+            })
+            return stopping
+        }
+        process.once('SIGTERM', () => void stop('sigterm'))
+        process.once('SIGINT', () => void stop('sigint'))
+        runtime.start()
+        logger.info({
+            transport: arguments_.includes('--loopback-tcp') ? 'loopback-tcp' : 'protected-unix',
+            port: runtime.port(),
+            developmentFaults: developmentFaultDirectory ? 'enabled' : 'disabled',
+        }, 'resident supervisor is listening')
+    }
+    catch (error) {
+        logger.error({ err: error }, 'resident supervisor failed to start')
+        process.exitCode = TERMINAL_ERROR_CODE
+    }
+}
+
+async function loadExtensions(input: {
+    path: string | undefined
+    developmentFaultDirectory: string | undefined
+}): Promise<SupervisorExtensions> {
+    if (!input.path)
+        throw new Error('--extensions or AGENT_CORE_SUPERVISOR_EXTENSIONS is required.')
+    const module = await import(pathToFileURL(resolve(input.path)).href) as SupervisorExtensionsModule
+    const extensions = module.createSupervisorExtensions
+        ? await module.createSupervisorExtensions({
+                ...(input.developmentFaultDirectory ? { developmentFaultDirectory: input.developmentFaultDirectory } : {}),
+            })
+        : module.default ?? module.extensions
+    if (!extensions)
+        throw new Error('Supervisor extensions module must export default, extensions, or createSupervisorExtensions().')
+    return extensions
+}
+
+function option(name: string): string | undefined {
+    const index = arguments_.indexOf(name)
+    if (index < 0)
+        return undefined
+    const value = arguments_[index + 1]
+    if (!value || value.startsWith('--'))
+        throw new Error(`${name} requires a value.`)
+    return value
+}
+
+function parsePort(value: string): number {
+    const port = Number(value)
+    if (!Number.isSafeInteger(port) || port < 0 || port > 65_535)
+        throw new Error('--port must be an integer between 0 and 65535.')
+    return port
+}

package/package.json

@@ -1,13 +1,13 @@
 {
     "name": "@meistrari/agent-core",
     "type": "module",
-    "version": "0.0.0",
+    "version": "0.1.1",
     "packageManager": "bun@1.3.12",
     "description": "Shared contracts and runtime modules for Tela coding-agent sandboxes: agent protocol, supervisor wire protocol, resident supervisor, worker runtime client, and Claude/Codex harness adapters.",
     "license": "UNLICENSED",
     "repository": {
         "type": "git",
-        "url": "https://github.com/meistrari/agent-core.git"
+        "url": "git+https://github.com/meistrari/agent-core.git"
     },
     "publishConfig": {
         "access": "public",
@@ -22,6 +22,9 @@
         "./protocol/agent-content": "./src/protocol/agent-content.ts",
         "./protocol/agent-tool-name": "./src/protocol/agent-tool-name.ts",
         "./protocol/agent-work": "./src/protocol/agent-work.ts",
+        "./agents": "./src/agents/index.ts",
+        "./claude": "./src/agents/claude/index.ts",
+        "./codex": "./src/agents/codex/index.ts",
         "./supervisor-protocol/agent-event-wrapper": "./src/supervisor-protocol/agent-event-wrapper.ts",
         "./supervisor-protocol/bootstrap": "./src/supervisor-protocol/bootstrap.ts",
         "./supervisor-protocol/bootstrap-rejection-receipt": "./src/supervisor-protocol/bootstrap-rejection-receipt.ts",
@@ -42,7 +45,15 @@
         "./supervisor-protocol/supervisor-agent-run-snapshot": "./src/supervisor-protocol/supervisor-agent-run-snapshot.ts",
         "./supervisor-protocol/supervisor-event": "./src/supervisor-protocol/supervisor-event.ts",
         "./supervisor-protocol/tela-page-content": "./src/supervisor-protocol/tela-page-content.ts",
-        "./supervisor-protocol/wire-codec": "./src/supervisor-protocol/wire-codec.ts"
+        "./supervisor-protocol/wire-codec": "./src/supervisor-protocol/wire-codec.ts",
+        "./template-onboarding": "./src/template-onboarding.ts",
+        "./supervisor": "./src/supervisor/index.ts",
+        "./supervisor/provider-factory": "./src/supervisor/provider-factory.ts",
+        "./testing": "./src/testing/index.ts",
+        "./worker-runtime-client": "./src/worker-runtime-client/index.ts"
+    },
+    "bin": {
+        "agent-core-supervisor": "bin/supervisor.ts"
     },
     "engines": {
         "bun": ">=1.3.10"
@@ -53,17 +64,45 @@
         "typecheck": "tsc --noEmit",
         "test": "bun test src/",
         "test:e2e": "bun test --pass-with-no-tests e2e/",
+        "build:supervisor": "bun scripts/build-supervisor-executable.ts",
         "provenance": "bun scripts/write-provenance.ts",
         "build": "bun scripts/write-provenance.ts"
     },
+    "peerDependencies": {
+        "@anthropic-ai/claude-agent-sdk": ">=0.3.207 <0.4.0",
+        "@anthropic-ai/sdk": "^0.93.0",
+        "@modelcontextprotocol/sdk": "^1.29.0",
+        "pg": "^8.16.3"
+    },
+    "peerDependenciesMeta": {
+        "@anthropic-ai/claude-agent-sdk": {
+            "optional": true
+        },
+        "@anthropic-ai/sdk": {
+            "optional": true
+        },
+        "@modelcontextprotocol/sdk": {
+            "optional": true
+        },
+        "pg": {
+            "optional": true
+        }
+    },
     "dependencies": {
+        "jose": "6.2.11",
         "pino": "^9.7.0",
+        "ulid": "3.0.2",
         "zod": "^4.1.12"
     },
     "devDependencies": {
         "@antfu/eslint-config": "4.16.2",
+        "@anthropic-ai/claude-agent-sdk": "0.3.224",
+        "@anthropic-ai/sdk": "0.93.0",
+        "@modelcontextprotocol/sdk": "1.29.0",
         "@types/bun": "1.3.12",
+        "@types/pg": "8.23.1",
         "eslint": "^9.30.0",
+        "pg": "8.23.0",
         "typescript": "5.9.3"
     }
 }

package/scripts/build-supervisor-executable.ts

@@ -0,0 +1,32 @@
+import { mkdir } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+
+const outputArgument = process.argv.indexOf('--outfile')
+const output = resolve(outputArgument >= 0
+    ? requiredArgument('--outfile', outputArgument)
+    : 'dist/agent-core-supervisor-linux-x64')
+const targetArgument = process.argv.indexOf('--target')
+const target = targetArgument >= 0
+    ? requiredArgument('--target', targetArgument) as Bun.Build.CompileTarget
+    : 'bun-linux-x64'
+
+await mkdir(dirname(output), { recursive: true })
+const result = await Bun.build({
+    entrypoints: [resolve('bin/supervisor.ts')],
+    compile: { target, outfile: output },
+    minify: true,
+    sourcemap: 'none',
+})
+if (!result.success) {
+    for (const log of result.logs)
+        console.error(log)
+    process.exit(1)
+}
+console.log(output)
+
+function requiredArgument(name: string, index: number): string {
+    const value = process.argv[index + 1]
+    if (!value || value.startsWith('--'))
+        throw new Error(`${name} requires a value.`)
+    return value
+}

package/src/agents/agent-error-serializer.ts

@@ -0,0 +1,23 @@
+import type { AgentError } from '../protocol'
+
+type ErrorWithCode = Error & { code?: unknown, cause?: unknown }
+
+const MAX_CAUSE_DEPTH = 3
+
+export function serializeAgentError(error: unknown, depth = 0): AgentError {
+    if (error instanceof Error) {
+        const withCode = error as ErrorWithCode
+        const serialized: AgentError = { message: error.message || error.name || 'Unknown error' }
+        if (typeof withCode.code === 'string' && withCode.code.trim())
+            serialized.code = withCode.code
+        if (error.name && error.name !== 'Error')
+            serialized.name = error.name
+        if (error.stack)
+            serialized.stack = error.stack
+        if (withCode.cause !== undefined && depth < MAX_CAUSE_DEPTH)
+            serialized.cause = serializeAgentError(withCode.cause, depth + 1)
+        return serialized
+    }
+
+    return { message: String(error) }
+}

package/src/agents/agent-event-stream.ts

@@ -0,0 +1,81 @@
+import type { AgentEvent, AgentProviderId } from '../protocol'
+import { agentEventSchema, InvalidAgentEventError } from '../protocol'
+import { createAgentEventId } from './agent-id'
+
+type AgentEventEnvelopeField = 'eventId' | 'provider' | 'sessionId' | 'providerSessionId' | 'timestamp' | 'sequence'
+export type AgentEventDraft = AgentEvent extends infer Event
+    ? Event extends AgentEvent
+        ? Omit<Event, AgentEventEnvelopeField>
+        : never
+    : never
+
+export class AgentEventStream implements AsyncIterable<AgentEvent> {
+    private readonly items: AgentEvent[] = []
+    private readonly resolvers: Array<(result: IteratorResult<AgentEvent>) => void> = []
+    private ended = false
+    private sequence = 0
+
+    constructor(
+        private readonly envelope: {
+            provider: AgentProviderId
+            sessionId: string
+            providerSessionId: string
+        },
+    ) {}
+
+    push(draft: AgentEventDraft): AgentEvent {
+        if (this.ended) {
+            throw new InvalidAgentEventError({ message: 'Cannot push an event after the stream has ended.' })
+        }
+
+        const parsed = agentEventSchema.safeParse({
+            ...draft,
+            eventId: createAgentEventId(),
+            provider: this.envelope.provider,
+            sessionId: this.envelope.sessionId,
+            providerSessionId: this.envelope.providerSessionId,
+            timestamp: new Date().toISOString(),
+            sequence: this.sequence,
+        })
+        if (!parsed.success) {
+            throw new InvalidAgentEventError({
+                message: 'Agent event draft is invalid.',
+                cause: parsed.error,
+            })
+        }
+        const event = parsed.data
+        this.sequence += 1
+
+        const resolver = this.resolvers.shift()
+        if (resolver) {
+            resolver({ value: event, done: false })
+        }
+        else {
+            this.items.push(event)
+        }
+
+        return event
+    }
+
+    end(): void {
+        if (this.ended)
+            return
+        this.ended = true
+        for (const resolver of this.resolvers.splice(0)) {
+            resolver({ value: undefined, done: true })
+        }
+    }
+
+    [Symbol.asyncIterator](): AsyncIterator<AgentEvent> {
+        return {
+            next: async () => {
+                const item = this.items.shift()
+                if (item)
+                    return await Promise.resolve({ value: item, done: false })
+                if (this.ended)
+                    return await Promise.resolve({ value: undefined, done: true })
+                return await new Promise<IteratorResult<AgentEvent>>(resolve => this.resolvers.push(resolve))
+            },
+        }
+    }
+}

package/src/agents/agent-id.ts

@@ -0,0 +1,17 @@
+import { ulid } from 'ulid'
+
+export function createAgentEventId(): string {
+    return `evt_${ulid()}`
+}
+
+export function createUserInputRequestId(): string {
+    return `req_${ulid()}`
+}
+
+export function createRuntimeTurnId(): string {
+    return `turn_${ulid()}`
+}
+
+export function createRuntimeWorkItemId(): string {
+    return `work_${ulid()}`
+}

package/src/agents/agent-operation.ts

@@ -0,0 +1,11 @@
+import type { AgentInputAttachmentPreparation } from './materialized-input-attachment'
+
+export type AgentSenderContext
+    = | { kind: 'application' }
+        | { kind: 'slack', mention: string }
+
+export interface AgentOperationOptions {
+    signal?: AbortSignal
+    inputAttachmentPreparation?: AgentInputAttachmentPreparation
+    senderContext?: AgentSenderContext
+}

package/src/agents/agent-provider.ts

@@ -0,0 +1,37 @@
+import type {
+    AgentModelId,
+    AgentProviderId,
+    AgentReasoningEffort,
+    AgentToolDefinition,
+} from '../protocol'
+import type { AgentOperationOptions } from './agent-operation'
+import type { AgentRun } from './agent-run'
+
+interface AgentSessionConfigInput {
+    sessionId: string
+    cwd: string
+    workspaceRepositoryRoots: readonly string[]
+    reasoningEffort?: AgentReasoningEffort
+    tools?: AgentToolDefinition[]
+}
+
+// Distributive over the provider so each arm keeps its provider correlated with its own model union:
+// the default `AgentProviderId` reproduces the `codex | claude` discriminated union, while a single
+// provider narrows to exactly that arm.
+export type AgentSessionOpenInput<Provider extends AgentProviderId = AgentProviderId>
+    = Provider extends AgentProviderId
+        ? AgentSessionConfigInput & { provider: Provider, model?: AgentModelId<Provider> }
+        : never
+
+export type AgentSessionResumeInput<Provider extends AgentProviderId = AgentProviderId>
+    = Provider extends AgentProviderId
+        ? AgentSessionConfigInput & { provider: Provider, providerSessionId: string, model?: AgentModelId<Provider> }
+        : never
+
+// Lifecycle only: openSession/resumeSession never apply user input. Callers submit the durable
+// command through the returned run afterwards, so the provider binding can be persisted first.
+export interface AgentProvider<Provider extends AgentProviderId = AgentProviderId> {
+    readonly id: Provider
+    openSession: (input: AgentSessionOpenInput<Provider>, options?: AgentOperationOptions) => Promise<AgentRun>
+    resumeSession: (input: AgentSessionResumeInput<Provider>, options?: AgentOperationOptions) => Promise<AgentRun>
+}

package/src/agents/agent-run.ts

@@ -0,0 +1,32 @@
+import type {
+    AgentEvent,
+    AgentRunMetadata,
+    InterruptAgentCommand,
+    RespondUserInputAgentCommand,
+    SendPromptCommand,
+    StopAgentCommand,
+} from '../protocol'
+import type { AgentOperationOptions } from './agent-operation'
+
+// Whether respond-user-input submitted provider input. `already_delivered` is the durable-store
+// idempotence fact for a redriven duplicate, not a provider prompt-acceptance receipt.
+export type AgentUserInputSubmission = 'submitted' | 'already_delivered'
+
+// Positive prompt-submission receipt. `turn` carries the provider's real turn identity (Codex: nested
+// `turn.id` from turn/start, flat `turnId` from turn/steer). `submitted` is the stream-submission arm
+// for providers whose input boundary carries no turn identity.
+export type AgentPromptAcceptance
+    = | { kind: 'turn', turnId: string, placement: 'started' | 'steered' }
+        | { kind: 'submitted' }
+
+export interface AgentRun {
+    readonly metadata: AgentRunMetadata
+    readonly events: AsyncIterable<AgentEvent>
+    prepareWorkspace: (options?: AgentOperationOptions) => Promise<void>
+    // Providers without root registration accept the root without provider I/O.
+    addWorkspaceRepositoryRoot: (root: string, options?: AgentOperationOptions) => Promise<void>
+    sendPrompt: (command: SendPromptCommand, options?: AgentOperationOptions) => Promise<AgentPromptAcceptance>
+    respondUserInput: (command: RespondUserInputAgentCommand, options?: AgentOperationOptions) => Promise<AgentUserInputSubmission>
+    interrupt: (command: InterruptAgentCommand, options?: AgentOperationOptions) => Promise<void>
+    stop: (command: StopAgentCommand, options?: AgentOperationOptions) => Promise<void>
+}

package/src/agents/agent-runtime-error.ts

@@ -0,0 +1,161 @@
+import type { InfrastructureErrorInput, ProviderErrorInput, ValidationErrorInput } from '../errors'
+import { InfrastructureError, ProviderError, ValidationError } from '../errors'
+
+type RuntimeProviderErrorInput = Omit<ProviderErrorInput, 'code'> & { code?: string }
+type RuntimeValidationErrorInput = Omit<ValidationErrorInput, 'code'> & { code?: string }
+type RuntimeInfrastructureErrorInput = Omit<InfrastructureErrorInput, 'code'> & { code?: string }
+
+export class AgentProviderRuntimeError extends ProviderError {
+    constructor(input: RuntimeProviderErrorInput) {
+        const { code = 'agents.provider-error', ...rest } = input
+        super({ code, ...rest })
+    }
+}
+
+// The one recovery consequence the supervisor loop performs for an input/operation the boundary
+// proved was not accepted by the provider or coordinator.
+export type KnownNotAcceptedRecovery
+    = | { kind: 'retry', reason: string, retryAfterMs?: number }
+        | { kind: 'external_action', reason: string }
+        | { kind: 'terminal', reason: string }
+
+export class AgentNotAcceptedError extends AgentProviderRuntimeError {
+    readonly recovery: KnownNotAcceptedRecovery
+
+    constructor(input: Omit<RuntimeProviderErrorInput, 'code' | 'retryable'> & { recovery: KnownNotAcceptedRecovery }) {
+        const { recovery, ...rest } = input
+        super({
+            code: 'agents.input-not-accepted',
+            publicMessage: 'Agent provider did not accept the operation.',
+            retryable: recovery.kind === 'retry',
+            ...rest,
+        })
+        this.recovery = recovery
+    }
+}
+
+// Turn-boundary race fact: the prompt was proven not accepted. Two producers exist — an adapter
+// pre-defers a `next` while its state shows an active turn (no request issued), and a `turn/steer`
+// answered -32600 is a post-write provider response proving the input was not accepted. Consumed
+// by the supervisor loop, which returns the durable command to pending, stops the drain pass, and
+// re-dispatches on the next work-relevant session-state change — no retry timer, no backoff.
+export class AgentPromptDeferredError extends AgentProviderRuntimeError {
+    constructor(input: Omit<RuntimeProviderErrorInput, 'code' | 'retryable'>) {
+        super({
+            code: 'agents.prompt-deferred',
+            publicMessage: 'Agent provider deferred the prompt at a turn boundary race.',
+            retryable: false,
+            ...input,
+        })
+    }
+}
+
+// Transport/response loss after the input may have been written: a delivery-unknown invalidates the
+// run's ownership but does not prove the run has closed (a Codex stdin write failure need not set
+// `stopped`). The supervisor explicitly relinquishes — stops the run and drains its consumer — then
+// durably waits before redriving the same command id; a duplicate is the accepted at-least-once cost.
+export class AgentDeliveryUnknownError extends AgentProviderRuntimeError {
+    constructor(input: Omit<RuntimeProviderErrorInput, 'code' | 'retryable'>) {
+        super({
+            code: 'agents.delivery-unknown',
+            publicMessage: 'Agent provider delivery outcome is unknown.',
+            retryable: false,
+            ...input,
+        })
+    }
+}
+
+export class AgentProviderLaunchError extends AgentProviderRuntimeError {
+    constructor(input: Omit<RuntimeProviderErrorInput, 'code'>) {
+        super({
+            code: 'agents.provider-launch-failed',
+            publicMessage: 'Agent provider failed to start.',
+            retryable: true,
+            ...input,
+        })
+    }
+}
+
+export class AgentProviderProtocolError extends AgentProviderRuntimeError {
+    constructor(input: Omit<RuntimeProviderErrorInput, 'code'>) {
+        super({
+            code: 'agents.provider-protocol-error',
+            publicMessage: 'Agent provider returned an invalid response.',
+            retryable: false,
+            ...input,
+        })
+    }
+}
+
+export class AgentProviderMetadataError extends AgentProviderRuntimeError {
+    constructor(input: Omit<RuntimeProviderErrorInput, 'code'>) {
+        super({
+            code: 'agents.provider-metadata-missing',
+            publicMessage: 'Agent provider did not return required session metadata.',
+            retryable: false,
+            ...input,
+        })
+    }
+}
+
+export class AgentRuntimeValidationError extends ValidationError {
+    constructor(input: RuntimeValidationErrorInput) {
+        const { code = 'agents.validation-failed', ...rest } = input
+        super({ code, ...rest })
+    }
+}
+
+export class AgentUnsupportedPromptBlockError extends AgentRuntimeValidationError {
+    constructor(input: { provider: string, blockType: string }) {
+        super({
+            code: 'agents.unsupported-prompt-block',
+            message: `Provider ${input.provider} does not support prompt block type ${input.blockType}.`,
+            publicMessage: 'Agent prompt contains unsupported content for the selected provider.',
+            details: input,
+        })
+    }
+}
+
+export class AgentToolValidationError extends AgentRuntimeValidationError {
+    constructor(input: Omit<RuntimeValidationErrorInput, 'code'>) {
+        super({
+            code: 'agents.tool-validation-failed',
+            publicMessage: 'Agent tool configuration is invalid.',
+            ...input,
+        })
+    }
+}
+
+export class AgentRunStateError extends AgentRuntimeValidationError {
+    constructor(input: Omit<RuntimeValidationErrorInput, 'code'>) {
+        super({
+            code: 'agents.invalid-run-state',
+            publicMessage: 'Agent run is not in the required state for this operation.',
+            ...input,
+        })
+    }
+}
+
+export class AgentUserInputRequestStoreError extends InfrastructureError {
+    constructor(input: Omit<RuntimeInfrastructureErrorInput, 'code'>) {
+        super({
+            code: 'agents.user-input-request-store-error',
+            publicMessage: 'Agent user-input request state is unavailable.',
+            retryable: false,
+            ...input,
+        })
+    }
+}
+
+export class AgentOperationAbortedError extends InfrastructureError {
+    constructor(input: Omit<RuntimeInfrastructureErrorInput, 'code' | 'message'> & { message?: string } = {}) {
+        super({
+            code: 'agents.operation-aborted',
+            message: input.message ?? 'Agent operation was aborted.',
+            publicMessage: 'Agent operation was aborted.',
+            retryable: false,
+            details: input.details,
+            cause: input.cause,
+        })
+    }
+}