dsh-loop-engine 1.0.0-rc10

package/lib/types/engine-claude/agent.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Claude Code loop Agent: drives one session through turn and step boundaries
+ * with one Claude Agent SDK query per step. Claude Code owns its prompt,
+ * tools, and permissions; the durable session log remains the source of truth
+ * and the query prompt is a pure serialization of it.
+ *
+ * @module dsh-loop-engine/engine-claude/agent
+ */
+import type { Agent, AgentCancelCause, AgentOptions, AgentStatus, CancelOptions, InboxTarget } from '@deepseek-ai/dsh-agent';
+import { Inbox } from '@deepseek-ai/dsh-agent';
+import type { Scope } from '@deepseek-ai/dsh-scope';
+import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session';
+import type { Context } from '@deepseek-ai/cordis';
+import type { ResolvedConfig } from './types.ts';
+/** Provider route label used for logged header snapshots and message provenance. */
+export declare const PROVIDER = "claude-code";
+/** Drives one session through turn and step boundaries on Claude Code. */
+export declare class ClaudeCodeAgent implements Agent {
+    private loopCtx;
+    readonly id: SessionId;
+    readonly options: AgentOptions;
+    readonly session: Session;
+    private readonly config;
+    readonly inbox: Inbox;
+    private phase;
+    private activityDone;
+    /** The agent-scoped registration boundary; the lifecycle owner unwinds it after the driver exits. */
+    readonly scope: Scope;
+    readonly ctx: Context;
+    /** Fused dispatcher, built once in the constructor so hot-path dispatches never allocate. */
+    private readonly dispatch;
+    /** Whether this loop instance has appended its initial/resume request anchor. */
+    private requestHeaderLogged;
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig);
+    get status(): AgentStatus;
+    /** Commit a phase and publish its externally visible status transition. */
+    private setPhase;
+    send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;
+    /**
+     * Queue a message for the next turn and wake the driver.
+     * @param input - the user message to deliver.
+     */
+    followup(input: UserMessage): void;
+    /**
+     * Queue a message for the running step and wake the driver.
+     * @param input - the user message to deliver.
+     */
+    steer(input: UserMessage): void;
+    /**
+     * Queue a message for the running step without waking the driver.
+     * @param input - the user message to deliver.
+     */
+    inject(input: UserMessage): void;
+    cancel(cause: AgentCancelCause, options?: CancelOptions): void;
+    /**
+     * Run a maintenance job while the agent is idle.
+     * @param job - the maintenance operation, receiving the phase abort signal.
+     * @returns the maintenance result.
+     */
+    runMaintenance<T>(job: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    /**
+     * Start one driver, or latch its wake behind maintenance or an aborted
+     * activity. A wake sent while idle always opens its turn boundary, even
+     * when its message was cleared; only a latched replay is suppressed when
+     * the queue no longer holds the wake.
+     * @param wakeAfterAbort - the {@link send} classification, captured before
+     *   the inbox insertion so a reentrant cancel cannot reclassify it.
+     */
+    private wakeDriver;
+    whenIdle(): Promise<void>;
+    /** Report one failure at its live boundary, then preserve it for driver containment. */
+    private throwError;
+    private kick;
+    private preStep;
+    /**
+     * Scan the step's user messages for `/name` skill gestures, load each
+     * matching skill, and inject the rendered skill content into the message
+     * batch.  This mirrors what dsh-tool-skill does for the in-process engine.
+     * @param messages - the current step's message batch.
+     * @param signal - cancellation signal (aborted loads are silently dropped).
+     * @returns the original batch when no skill was invoked, or an extended
+     *   batch with injected skill-content messages appended.
+     */
+    private injectSkills;
+    /**
+     * Resolve the native permission handling for one query. A deployment-pinned
+     * mode wins outright; otherwise the session's durable dsh permission knobs
+     * decide per query (mid-session preset switches included): full access
+     * bypasses native checks, an `ask` policy forwards each native permission
+     * request to the dsh approval seam, and anything else fails closed with the
+     * unattended deny-all stance.
+     * @returns the permission fields of the query spec.
+     */
+    private queryPermission;
+    /** Open one turn before claiming its first proposed step. */
+    private turn;
+    /** Model label recorded in the request header for one lifecycle. */
+    private modelLabel;
+    /** Append the request header snapshot once per loop instance. */
+    private assertRequestHeader;
+    /** Run one Claude Code query for the current step and map its transcript into the session log. */
+    private step;
+}
+//# sourceMappingURL=agent.d.ts.map

package/lib/types/engine-claude/loop.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Claude Code loop engine module: hosts the AgentFactory that drives every
+ * session through the official Claude Agent SDK, one stateless query per dsh
+ * step, with the durable session log as the sole source of model context.
+ * dsh-loop-engine constructs this factory when the Claude Code engine is
+ * selected; this module is a library, not a Cordis plugin entry.
+ *
+ * @module dsh-loop-engine/engine-claude
+ */
+import { Service } from '@deepseek-ai/cordis';
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { AgentFactory, AgentHandle, CreateAgentOptions, ResumeAgentOptions } from '@deepseek-ai/dsh-agent';
+import type { ClaudeCodePermissionMode, ResolvedConfig } from './types.ts';
+/** Deployment-selectable non-interactive Claude Code permission modes. */
+export declare const CLAUDE_CODE_PERMISSION_MODES: readonly ClaudeCodePermissionMode[];
+/** Deployment-owned configuration for the Claude Code loop plugin. */
+export interface Config {
+    /**
+     * Native non-interactive permission handling for every query. When omitted,
+     * each query follows the session's dsh permission knobs (`sandbox/mode` and
+     * `approval/policy`): full access bypasses native checks, an `ask` policy
+     * forwards requests to the dsh approval seam, and anything else auto-denies.
+     * A pinned mode overrides the session for every query: `dontAsk` auto-denies,
+     * `acceptEdits` accepts edits, `auto` uses the native classifier, `plan`
+     * returns a plan without approving execution, and `bypassPermissions`
+     * explicitly skips permission checks.
+     */
+    permissionMode?: ClaudeCodePermissionMode;
+    /** Explicit environment entries layered over the credential-scrubbed parent environment. */
+    env?: Record<string, string>;
+    /** Model label for the logged request header; Claude Code native settings own the actual model. */
+    model?: string;
+    /** Grace in milliseconds for Claude Code process-tree termination. */
+    disposeGraceMs?: number;
+    /** Cap on the number of conversation turns before each query stops. */
+    maxTurns?: number;
+}
+/** Schema of the Claude Code loop plugin configuration. */
+export declare const Config: z<Config>;
+/** Host-face ctx key for the Claude Code loop service. */
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoopClaudeCode: ClaudeCodeLoop;
+    }
+}
+/**
+ * Concrete AgentFactory and driver service of the Claude Code loop. Creation
+ * and resume follow the registry factory contract and the shared publication
+ * transaction: prepare, run setup, then publish through both registries,
+ * announce, and emit `agent/session-start`.
+ */
+export declare class ClaudeCodeLoop extends Service implements AgentFactory {
+    /** Services the loop resolves through its own fiber; blessed identically to the package-level entry inject. */
+    static inject: string[];
+    /** Validated configuration owned by the loop plugin. */
+    readonly config: ResolvedConfig;
+    private readonly ownership;
+    /** Plain holder prevents Cordis from re-tracing the factory's dependency context through a caller shadow. */
+    private readonly runtime;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Construct the driver, scope, and one memoized reverse teardown for a new
+     * agent. The teardown is registered with the factory and the owner fiber
+     * BEFORE publication, so a mid-setup unload rolls everything back; `signal`
+     * fuses caller cancellation with lifecycle teardown for setup awaits.
+     */
+    private prepare;
+    /** Prepare one Agent around an acquired Session, run setup, and publish it. */
+    private setupAndPublish;
+    /**
+     * Create an agent and session under one caller-supplied identity, owned by
+     * the accessing fiber. When a persistence backend is mounted, the session's
+     * durable identity is stored before publication.
+     * @param ownerCtx - caller context that structurally owns the lifecycle.
+     * @param options - identities, session seed/metadata, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>;
+    /**
+     * Take a fresh session's write ownership when persistence is mounted.
+     * Nothing is appended here: the constructor seed (which never re-emits
+     * through `session/event`) is stored by {@link appendUnstoredSuffix} at the
+     * publication commit point, so a failed or cancelled setup closes an
+     * unmaterialized handle and leaves no stored residue — the same id can be
+     * created again.
+     * @param session - the unpublished session to store.
+     * @param signal - optional cancellation forwarded to the backend create.
+     * @returns the owned handle and stored cursor, or `undefined` without a backend.
+     */
+    private createStoredSession;
+    /**
+     * Durably store the session events appended since the last stored cursor.
+     * Pre-publication appends (constructor seed markers, setup-window events)
+     * never re-emit through `session/event`, so publication must flush them
+     * through the handle before live events start routing into it.
+     * @param stored - the session's owned handle and stored cursor, if any.
+     * @param session - the unpublished session whose suffix is stored.
+     */
+    private appendUnstoredSuffix;
+    /**
+     * Resume an owned agent from the configured persistence service.
+     * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
+     * @param options - persisted identity, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>;
+    /** Resume through an explicit persistence service. */
+    private resumeWith;
+}
+//# sourceMappingURL=loop.d.ts.map

package/lib/types/engine-claude/mapping.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Pure translation from the Claude Agent SDK's message vocabulary to the dsh
+ * session-log vocabulary. Each function maps one SDK message to the durable
+ * event payloads the driver appends inside its current step, so the mapping
+ * stays unit-testable without any SDK process.
+ *
+ * @module dsh-loop-engine/engine-claude/mapping
+ */
+import type { BetaMessage, BetaRawMessageStreamEvent, BetaUsage } from '@anthropic-ai/sdk/resources/beta/messages/messages.mjs';
+import type { MessageParam } from '@anthropic-ai/sdk/resources';
+import { ToolCallId, type ContentBlock, type StreamChunk, type TokenUsage, type ToolResultMessage } from '@deepseek-ai/dsh-llm';
+/** One tool invocation surfaced from a Claude Code assistant message. */
+export interface MappedToolCall {
+    /** SDK tool_use id, reused as the dsh call-id so results pair. */
+    readonly callId: ToolCallId;
+    /** Tool name exactly as the SDK reported it. */
+    readonly name: string;
+    /** Raw JSON arguments string as the SDK produced them. */
+    readonly arguments: string;
+}
+/** Result of translating one SDK assistant message. */
+export interface MappedAssistantMessage {
+    /** dsh content blocks: text verbatim, tool calls as tool-call blocks. */
+    readonly content: ContentBlock[];
+    /** Tool invocations surfaced as dsh tool/call events. */
+    readonly toolCalls: readonly MappedToolCall[];
+    /** Provider-reported token accounting, when present. */
+    readonly usage: TokenUsage | undefined;
+    /** Model id reported by the SDK message. */
+    readonly model: string;
+}
+/**
+ * Render an SDK tool input as the raw JSON string carried by a dsh tool-call
+ * block. Values that cannot be stringified (undefined, functions, cyclic
+ * graphs) fall back to a stable placeholder instead of failing the mapping.
+ * @param input - the SDK tool input value.
+ * @returns the JSON string, or a placeholder when the input is not JSON-serializable.
+ */
+export declare function stringifyToolInput(input: unknown): string;
+/**
+ * Translate one SDK assistant message into dsh content blocks and tool calls.
+ * Text blocks map verbatim; tool_use blocks map to tool-call blocks and
+ * surfaced calls; thinking blocks map to reasoning blocks; redacted-thinking
+ * and unknown blocks are dropped.
+ * @param message - the SDK assistant message.
+ * @returns the mapped content, calls, usage, and model.
+ */
+export declare function mapAssistantMessage(message: BetaMessage): MappedAssistantMessage;
+/**
+ * Translate the tool_result blocks of one SDK user message into dsh
+ * tool-result messages. Non-tool_result blocks are ignored: Claude Code user
+ * messages inside a query carry only tool outcomes.
+ * @param message - the SDK user message.
+ * @returns the mapped tool-result messages, in block order.
+ */
+export declare function mapToolResults(message: MessageParam): ToolResultMessage[];
+/**
+ * Translate SDK token accounting into the dsh token-usage shape. Cache
+ * breakpoints are optional; absent or null SDK counters stay absent.
+ * @param usage - SDK-reported usage for one assistant message.
+ * @returns dsh token accounting, omitting absent optional counters.
+ */
+export declare function mapUsage(usage: BetaUsage): TokenUsage;
+/** Per-block-index tool-call identity captured at `content_block_start`, reused by `input_json_delta`. */
+export interface StreamToolCall {
+    readonly callId: ToolCallId;
+    readonly name: string;
+}
+/**
+ * Translate one SDK raw stream event into the dsh assistant chunks that drive
+ * the live partial projection. Text blocks yield `block-start`/`text-delta`;
+ * thinking blocks yield `block-start`/`reasoning-delta`; tool_use blocks yield
+ * `block-start`/`tool-call-delta`. Redacted thinking, signature deltas,
+ * `content_block_stop`, and transport events yield nothing — the durable
+ * `assistant/message` is appended separately from the SDK's complete message,
+ * so the streamed chunks never have to carry the whole block.
+ * @param event - one raw stream event from an `includePartialMessages` query.
+ * @param toolCalls - per-block-index tool identity, mutated here at a tool
+ *   `content_block_start` so later `input_json_delta` can name the call.
+ * @returns the chunks that change the visible partial (empty for non-visual events).
+ */
+export declare function mapStreamEvent(event: BetaRawMessageStreamEvent, toolCalls: Map<number, StreamToolCall>): StreamChunk[];
+//# sourceMappingURL=mapping.d.ts.map

package/lib/types/engine-claude/permission.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Mapping from the dsh session's durable permission knobs to one Claude Code
+ * query's native permission handling. The session log pins `sandbox/mode`
+ * and `approval/policy` events at creation and records every later switch;
+ * folding them per query keeps the Claude Code driver consistent with the
+ * permission preset the web surface shows, including mid-session switches.
+ *
+ * @module dsh-loop-engine/engine-claude/permission
+ */
+import type { PermissionEvent } from '../driver-core/permission-knobs.ts';
+/**
+ * The effective native permission stance for one query:
+ *   - `bypass` — full access: skip every native permission check.
+ *   - `ask` — forward each native permission request to the dsh approval seam.
+ *   - `deny` — auto-deny every native permission request (unattended default).
+ */
+export type SessionPermission = {
+    readonly kind: 'bypass';
+} | {
+    readonly kind: 'ask';
+} | {
+    readonly kind: 'deny';
+};
+/**
+ * Resolve the session's effective native permission stance. Full access wins
+ * outright (the web "full" preset pins it together with `never`); otherwise
+ * an `ask` policy forwards permission requests to the dsh approval seam and
+ * anything else — including a session with no recorded knobs — fails closed.
+ * @param events - the durable session log.
+ * @returns the stance one query should run under.
+ */
+export declare function resolveSessionPermission(events: readonly PermissionEvent[]): SessionPermission;
+/**
+ * Human-readable explanation of WHY a native permission request is asked,
+ * carrying a bounded excerpt of the exact tool input.
+ * @param toolName - the native tool being decided.
+ * @param input - the exact tool input.
+ * @returns the approval request's reason text.
+ */
+export declare function approvalReason(toolName: string, input: Record<string, unknown>): string;
+//# sourceMappingURL=permission.d.ts.map

package/lib/types/engine-claude/process.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Projection from the shared managed-process handle to the official Claude
+ * Agent SDK's custom-spawn process interface.
+ *
+ * @module dsh-loop-engine/engine-claude/process
+ */
+import type { SpawnedProcess, SpawnOptions } from '@anthropic-ai/claude-agent-sdk';
+import { type SubprocessHandle, type SubprocessOutcome, type SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/**
+ * Encode the SDK's complete child environment as a subprocess overlay.
+ * @param env - SDK-composed child environment after its removals and replacements.
+ * @returns explicit values plus tombstones for surviving ambient names the SDK removed.
+ */
+export declare function sdkEnvironmentOverlay(env: SpawnOptions['env']): NodeJS.ProcessEnv;
+/**
+ * Translate one official SDK spawn request to the shared process owner.
+ * @param options - command, arguments, workspace, environment, and forwarded signal from the SDK.
+ * @param graceMs - process-tree termination grace.
+ * @returns the fully explicit shared subprocess request.
+ */
+export declare function claudeSpawnSpec(options: SpawnOptions, graceMs: number): SubprocessSpawnSpec;
+/**
+ * SDK-facing view of one shared managed process. Protocol transport remains
+ * in the official SDK; this adapter only projects streams and exit events.
+ */
+export declare class ManagedClaudeCodeProcess implements SpawnedProcess {
+    private readonly child;
+    readonly stdin: import("stream").Writable;
+    readonly stdout: import("stream").Readable;
+    private readonly events;
+    private outcomeValue;
+    private killRequested;
+    /**
+     * Project a managed process with piped stdin and stdout.
+     * @param child - shared handle that remains the process-tree authority.
+     */
+    constructor(child: SubprocessHandle);
+    /** Whether the SDK has requested managed tree termination. */
+    get killed(): boolean;
+    /** Direct-child exit code, or null while running or after signal exit. */
+    get exitCode(): number | null;
+    /** Direct-child terminating signal, if any. */
+    get signalCode(): NodeJS.Signals | null;
+    /** Exact managed-process outcome after exit, or undefined while running. */
+    get outcome(): SubprocessOutcome | undefined;
+    /**
+     * Route the SDK's termination request to the tree-scoped process owner.
+     * @param _signal - SDK-selected signal; the shared seam owns its escalation ladder.
+     * @returns false only after exit or a previous termination request.
+     */
+    kill(_signal: NodeJS.Signals): boolean;
+    /** Register a persistent process lifecycle listener. */
+    on(event: 'exit' | 'error', listener: ((code: number | null, signal: NodeJS.Signals | null) => void) | ((error: Error) => void)): void;
+    /** Register a one-shot process lifecycle listener. */
+    once(event: 'exit' | 'error', listener: ((code: number | null, signal: NodeJS.Signals | null) => void) | ((error: Error) => void)): void;
+    /** Remove a process lifecycle listener. */
+    off(event: 'exit' | 'error', listener: ((code: number | null, signal: NodeJS.Signals | null) => void) | ((error: Error) => void)): void;
+}
+//# sourceMappingURL=process.d.ts.map

package/lib/types/engine-claude/sdk.d.ts

@@ -0,0 +1,57 @@
+/**
+ * One Claude Agent SDK query: options assembly, process seam projection, and
+ * the headless interaction policy. The driver runs exactly one query per dsh
+ * step; this module owns no session state.
+ *
+ * @module dsh-loop-engine/engine-claude/sdk
+ */
+import type { Options, PermissionMode } from '@anthropic-ai/claude-agent-sdk';
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/** Native lock-down mode fixed for every query unless deployment overrides it. */
+export declare const DEFAULT_PERMISSION_MODE: "dontAsk";
+/** Grace in milliseconds for Claude Code process-tree termination. */
+export declare const DEFAULT_DISPOSE_GRACE_MS = 3000;
+export type { PermissionMode };
+/** Deployment-owned process-spawn capability handed over from the plugin. */
+export type SpawnCapability = (spec: SubprocessSpawnSpec) => SubprocessHandle;
+/** Everything one SDK query needs, resolved at step time. */
+export interface ClaudeCodeQuerySpec {
+    /** Absolute workspace the Claude Code process runs in. */
+    readonly cwd: string;
+    /** Native permission handling for this query. */
+    readonly permissionMode: PermissionMode;
+    /** Explicit environment entries layered over the scrubbed parent environment. */
+    readonly env?: Record<string, string>;
+    /** Grace in milliseconds for process-tree termination. */
+    readonly disposeGraceMs: number;
+    /** Model override for the SDK, when the deployment pins one. */
+    readonly model?: string;
+    /** Cap on the number of conversation turns before the query stops. */
+    readonly maxTurns?: number;
+    /**
+     * Decide one native permission request through the dsh approval seam.
+     * When present, `canUseTool` forwards to it instead of auto-denying.
+     */
+    readonly onToolPermission?: (toolName: string, input: Record<string, unknown>, signal: AbortSignal) => Promise<'allow' | 'deny'>;
+    /** Spawn the Claude Code child under the shared process owner. */
+    readonly spawn: SpawnCapability;
+    /** Receive a human-readable denial or decline for one unattended interaction. */
+    readonly onUnattended?: (description: string) => void;
+}
+/**
+ * Diagnose one auto-answered interaction in headless mode.
+ * @param mode - permission mode in force.
+ * @param kind - what the interaction was.
+ * @param answer - what the driver did.
+ * @param why - reason the driver cannot forward the interaction.
+ * @returns a stable one-line diagnostic.
+ */
+export declare function unattendedDiagnostic(mode: PermissionMode, kind: string, answer: string, why: string): string;
+/**
+ * Build the fixed official SDK options for one step's query.
+ * @param spec - workspace, environment, process seam, and disposal policy.
+ * @param controller - per-query cancellation owner.
+ * @returns the options for one stateless query.
+ */
+export declare function claudeQueryOptions(spec: ClaudeCodeQuerySpec, controller: AbortController): Options;
+//# sourceMappingURL=sdk.d.ts.map

package/lib/types/engine-claude/types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Public types of the Claude Code loop driver. Types only — no runtime code.
+ *
+ * @module dsh-loop-engine/engine-claude/types
+ */
+import type { PermissionMode } from '@anthropic-ai/claude-agent-sdk';
+/** Claude Code permission modes that never wait for a human response. */
+export type ClaudeCodePermissionMode = Extract<PermissionMode, 'dontAsk' | 'acceptEdits' | 'auto' | 'plan' | 'bypassPermissions'>;
+/** Driver configuration after defaults and load-time validation. */
+export interface ResolvedConfig {
+    /** Pinned native mode; `undefined` follows the session's dsh permission knobs per query. */
+    readonly permissionMode: ClaudeCodePermissionMode | undefined;
+    readonly env: Record<string, string>;
+    readonly model: string | undefined;
+    readonly disposeGraceMs: number;
+    readonly maxTurns: number | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/engine-codex/agent.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Codex loop Agent: drives one session through turn and step boundaries by
+ * spawning a `codex app-server` child process and speaking JSON-RPC over stdio.
+ * Codex owns its prompt, tools, and sandbox; the durable session log remains
+ * the source of truth and the thread input is a pure serialization of it.
+ * The app-server streams token-level deltas via `item/agentMessage/delta` and
+ * `item/reasoning/summaryTextDelta`, so the visible partial paints
+ * progressively as the model generates — not all at once at the end. It offers
+ * no interactive approval callback, so permissions are folded declaratively
+ * into each thread's `sandboxMode`/`approvalPolicy`.
+ *
+ * @module dsh-loop-engine/engine-codex/agent
+ */
+import type { Agent, AgentCancelCause, AgentOptions, AgentStatus, CancelOptions, InboxTarget } from '@deepseek-ai/dsh-agent';
+import { Inbox } from '@deepseek-ai/dsh-agent';
+import type { Scope } from '@deepseek-ai/dsh-scope';
+import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session';
+import type { Context } from '@deepseek-ai/cordis';
+import type { ResolvedConfig } from './types.ts';
+/** Provider route label used for logged header snapshots and message provenance. */
+export declare const PROVIDER = "codex";
+/** Drives one session through turn and step boundaries on Codex. */
+export declare class CodexAgent implements Agent {
+    private loopCtx;
+    readonly id: SessionId;
+    readonly options: AgentOptions;
+    readonly session: Session;
+    private readonly config;
+    readonly inbox: Inbox;
+    private phase;
+    private activityDone;
+    /** The agent-scoped registration boundary; the lifecycle owner unwinds it after the driver exits. */
+    readonly scope: Scope;
+    readonly ctx: Context;
+    /** Fused dispatcher, built once in the constructor so hot-path dispatches never allocate. */
+    private readonly dispatch;
+    /** Whether this loop instance has appended its initial/resume request anchor. */
+    private requestHeaderLogged;
+    /** Lazily created app-server client, reused across steps and released on scope teardown. */
+    private appServer;
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig);
+    /** Return the cached app-server client, spawning one on first use or after a dead process. */
+    private appServerClient;
+    get status(): AgentStatus;
+    /** Commit a phase and publish its externally visible status transition. */
+    private setPhase;
+    send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;
+    /**
+     * Queue a message for the next turn and wake the driver.
+     * @param input - the user message to deliver.
+     */
+    followup(input: UserMessage): void;
+    /**
+     * Queue a message for the running step and wake the driver.
+     * @param input - the user message to deliver.
+     */
+    steer(input: UserMessage): void;
+    /**
+     * Queue a message for the running step without waking the driver.
+     * @param input - the user message to deliver.
+     */
+    inject(input: UserMessage): void;
+    cancel(cause: AgentCancelCause, options?: CancelOptions): void;
+    /**
+     * Run a maintenance job while the agent is idle.
+     * @param job - the maintenance operation, receiving the phase abort signal.
+     * @returns the maintenance result.
+     */
+    runMaintenance<T>(job: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    /**
+     * Start one driver, or latch its wake behind maintenance or an aborted
+     * activity. A wake sent while idle always opens its turn boundary, even
+     * when its message was cleared; only a latched replay is suppressed when
+     * the queue no longer holds the wake.
+     * @param wakeAfterAbort - the {@link send} classification, captured before
+     *   the inbox insertion so a reentrant cancel cannot reclassify it.
+     */
+    private wakeDriver;
+    whenIdle(): Promise<void>;
+    /** Report one failure at its live boundary, then preserve it for driver containment. */
+    private throwError;
+    private kick;
+    private preStep;
+    /**
+     * Scan the step's user messages for `/name` skill gestures, load each
+     * matching skill, and inject the rendered skill content into the message
+     * batch.  This mirrors what dsh-tool-skill does for the in-process engine.
+     * @param messages - the current step's message batch.
+     * @param signal - cancellation signal (aborted loads are silently dropped).
+     * @returns the original batch when no skill was invoked, or an extended
+     *   batch with injected skill-content messages appended.
+     */
+    private injectSkills;
+    /**
+     * Resolve the declarative permission stance for one query. Deployment-pinned
+     * fields win per field; anything unpinned follows the session's durable dsh
+     * permission knobs, re-folded per query so mid-session preset switches take
+     * effect on the next step.
+     * @returns the permission fields of the query spec.
+     */
+    private queryPermission;
+    /** Open one turn before claiming its first proposed step. */
+    private turn;
+    /** Model label recorded in the request header for one lifecycle. */
+    private modelLabel;
+    /** Append the request header snapshot once per loop instance. */
+    private assertRequestHeader;
+    /** Run one Codex thread for the current step and map its transcript into the session log. */
+    private step;
+}
+//# sourceMappingURL=agent.d.ts.map

package/lib/types/engine-codex/appserver/client.d.ts

@@ -0,0 +1,49 @@
+/**
+ * JSON-RPC client over stdio for the codex app-server. Spawns
+ * `codex app-server` as a child process, sends JSON-RPC 2.0 requests over
+ * stdin, and reads newline-delimited JSON responses/notifications from stdout.
+ *
+ * @module dsh-loop-engine/engine-codex/appserver/client
+ */
+import type { InitializeResult, ThreadResumeParams, ThreadStartParams, ThreadStartResult, TurnInterruptParams, TurnStartParams, TurnStartResult } from './types.ts';
+/** Callback for receiving server notifications. */
+export type NotificationHandler = (method: string, params: unknown) => void;
+/** Callback for receiving raw stderr lines from the server process. */
+export type StderrHandler = (line: string) => void;
+/** JSON-RPC client for the codex app-server. */
+export declare class AppServerClient {
+    private process;
+    private rl;
+    private reqId;
+    private pending;
+    private notificationHandler;
+    private stderrHandler;
+    private disposed;
+    /** Whether this client was disposed or its server process exited. */
+    get closed(): boolean;
+    /** Create a client by spawning `codex app-server`. */
+    private constructor();
+    /** Spawn the pinned app-server dependency and initialize the client. */
+    static create(): Promise<AppServerClient>;
+    /** Set the notification handler for streaming events. */
+    onNotification(handler: NotificationHandler): void;
+    /** Set the stderr handler for server log lines. */
+    onStderr(handler: StderrHandler): void;
+    /** Send the initialize handshake. */
+    initialize(): Promise<InitializeResult>;
+    /** Create a new thread. */
+    threadStart(params: ThreadStartParams): Promise<ThreadStartResult>;
+    /** Resume an existing thread. */
+    threadResume(params: ThreadResumeParams): Promise<ThreadStartResult>;
+    /** Start a turn with the given input. */
+    turnStart(params: TurnStartParams): Promise<TurnStartResult>;
+    /** Interrupt an active turn. */
+    turnInterrupt(params: TurnInterruptParams): Promise<unknown>;
+    /** Dispose the client and kill the server process. */
+    dispose(): void;
+    /** Send a JSON-RPC request and wait for the response. */
+    private request;
+    /** Handle one line of stdout from the server. */
+    private handleLine;
+}
+//# sourceMappingURL=client.d.ts.map