@vidge/dsh-agent-hub 0.1.0-rc1

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

@@ -0,0 +1,28 @@
+/**
+ * Public types of the Claude Code loop driver. Types only — no runtime code.
+ *
+ * @module dsh-agent-hub/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'>;
+/**
+ * Which provider backend the CLI child is pointed at.
+ *
+ * The CLI resolves backends by precedence rather than by merging, so a host
+ * environment carrying two of them silently runs on the wrong one. `auto`
+ * picks the first configured backend in the order relay, Bedrock, Vertex,
+ * direct; the explicit values pin one and drop the others.
+ */
+export type ClaudeCodeBackend = 'auto' | 'relay' | 'bedrock' | 'vertex' | 'anthropic';
+/** 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 backend: ClaudeCodeBackend;
+    readonly disposeGraceMs: number;
+    readonly maxTurns: number | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,109 @@
+/**
+ * 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-agent-hub/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';
+/** 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-agent-hub/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

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

@@ -0,0 +1,67 @@
+/**
+ * Maps completed app-server items and turn usage to dsh session-log events.
+ * Only these end-state projections live here: token-level streaming deltas are
+ * folded inline by the driver's step loop; this module turns the item that
+ * finished a stream into the durable tool/call + tool/result events and folds
+ * a finished turn's usage into a TokenUsage.
+ *
+ * @module dsh-agent-hub/engine-codex/appserver/mapping
+ */
+import type { TokenUsage, ToolResultMessage } from '@deepseek-ai/dsh-llm';
+import { CallId } from '../../llm-compat.ts';
+/** Map app-server turn usage to dsh TokenUsage. */
+export declare function mapUsage(usage: {
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens?: number;
+    reasoningOutputTokens?: number;
+}): TokenUsage;
+/** Map a completed commandExecution item to tool call and result message. */
+export declare function mapCommandExecution(item: {
+    id: string;
+    command?: string;
+    aggregatedOutput?: string | null;
+    exitCode?: number | null;
+    status?: string;
+}): {
+    call: {
+        callId: CallId;
+        name: string;
+        arguments: string;
+    };
+    result: ToolResultMessage;
+};
+/** Map a completed fileChange item to tool call and result message. */
+export declare function mapFileChange(item: {
+    id: string;
+    changes?: unknown[];
+    status?: string;
+}): {
+    call: {
+        callId: CallId;
+        name: string;
+        arguments: string;
+    };
+    result: ToolResultMessage;
+};
+/** Map a completed mcpToolCall item to tool call and result message. */
+export declare function mapMcpToolCall(item: {
+    id: string;
+    server?: string;
+    tool?: string;
+    arguments?: unknown;
+    result?: {
+        content?: unknown[];
+    };
+    error?: {
+        message?: string;
+    };
+}): {
+    call: {
+        callId: CallId;
+        name: string;
+        arguments: string;
+    };
+    result: ToolResultMessage;
+};
+//# sourceMappingURL=mapping.d.ts.map

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

@@ -0,0 +1,66 @@
+/**
+ * Thread lifecycle management for the codex app-server. Wraps a codex thread
+ * and its turn-level streaming, producing dsh-native events from the
+ * app-server's JSON-RPC notifications.
+ *
+ * @module dsh-agent-hub/engine-codex/appserver/thread
+ */
+import type { AppServerClient } from './client.ts';
+import type { ErrorNotification, ItemCompletedNotification, ThreadStartParams, ThreadTokenUsageUpdatedNotification, TurnCompletedNotification, TurnInput } from './types.ts';
+/** An event yielded during a turn's streaming. */
+export type AppServerEvent = {
+    readonly kind: 'turn-started';
+    readonly turnId: string;
+} | {
+    readonly kind: 'item-started';
+    readonly itemType: string;
+    readonly itemId: string;
+} | {
+    readonly kind: 'agent-delta';
+    readonly itemId: string;
+    readonly delta: string;
+} | {
+    readonly kind: 'reasoning-summary-delta';
+    readonly itemId: string;
+    readonly delta: string;
+    readonly summaryIndex: number;
+} | {
+    readonly kind: 'reasoning-text-delta';
+    readonly itemId: string;
+    readonly delta: string;
+    readonly contentIndex: number;
+} | {
+    readonly kind: 'plan-delta';
+    readonly itemId: string;
+    readonly delta: string;
+} | {
+    readonly kind: 'item-completed';
+    readonly item: ItemCompletedNotification['item'];
+} | {
+    readonly kind: 'turn-completed';
+    readonly turn: TurnCompletedNotification['turn'];
+} | {
+    readonly kind: 'token-usage';
+    readonly usage: ThreadTokenUsageUpdatedNotification['tokenUsage'];
+} | {
+    readonly kind: 'error';
+    readonly error: ErrorNotification['error'];
+    readonly willRetry: boolean;
+};
+/** Wraps one codex thread and its streaming turns. */
+export declare class AppServerThread {
+    private readonly client;
+    readonly threadId: string;
+    constructor(client: AppServerClient, threadId: string);
+    /** Create a new thread on the app-server. */
+    static create(client: AppServerClient, params: ThreadStartParams): Promise<AppServerThread>;
+    /**
+     * Start a turn and stream its events as an async generator.
+     * The generator ends when the turn completes or an error occurs.
+     */
+    turn(input: readonly TurnInput[], options: {
+        signal?: AbortSignal;
+        params?: Partial<Omit<import('./types.ts').TurnStartParams, 'threadId' | 'input'>>;
+    }): AsyncGenerator<AppServerEvent, void, void>;
+}
+//# sourceMappingURL=thread.d.ts.map

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

@@ -0,0 +1,215 @@
+/**
+ * App-server protocol type definitions. A minimal subset of the types generated
+ * by `codex app-server generate-ts`, covering only what the driver needs for
+ * streaming (initialize, thread/start, turn/start, notifications).
+ *
+ * @module dsh-agent-hub/engine-codex/appserver/types
+ */
+/** A JSON-RPC 2.0 request sent to the app-server. */
+export interface JsonRpcRequest {
+    readonly jsonrpc: '2.0';
+    readonly id: number;
+    readonly method: string;
+    readonly params?: unknown;
+}
+/** A JSON-RPC 2.0 response (success or error). */
+export interface JsonRpcResponse {
+    readonly id: number;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: number;
+        readonly message: string;
+    };
+}
+/** A JSON-RPC 2.0 notification (no id). */
+export interface JsonRpcNotification {
+    readonly method: string;
+    readonly params: unknown;
+}
+export interface InitializeParams {
+    readonly clientInfo: {
+        readonly name: string;
+        readonly title: string | null;
+        readonly version: string;
+    };
+    readonly capabilities: {
+        readonly experimentalApi: boolean;
+        readonly requestAttestation: boolean;
+    } | null;
+}
+export interface InitializeResult {
+    readonly userAgent: string;
+    readonly codexHome: string;
+    readonly platformFamily: string;
+    readonly platformOs: string;
+}
+/** Sandbox mode accepted by `thread/start`; unlike turn policies, this is a string enum. */
+export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** Internally tagged sandbox override accepted by `turn/start`. */
+export type SandboxPolicy = {
+    readonly type: 'dangerFullAccess';
+} | {
+    readonly type: 'readOnly';
+    readonly networkAccess: boolean;
+} | {
+    readonly type: 'externalSandbox';
+    readonly networkAccess: 'restricted' | 'enabled';
+} | {
+    readonly type: 'workspaceWrite';
+    readonly writableRoots: readonly string[];
+    readonly networkAccess: boolean;
+    readonly excludeTmpdirEnvVar: boolean;
+    readonly excludeSlashTmp: boolean;
+};
+export interface ThreadStartParams {
+    readonly model?: string | null;
+    readonly modelProvider?: string | null;
+    readonly cwd?: string | null;
+    readonly approvalPolicy?: string | null;
+    readonly sandbox?: SandboxMode | null;
+    readonly ephemeral?: boolean | null;
+    readonly [key: string]: unknown;
+}
+export interface ThreadInfo {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly modelProvider: string;
+    readonly [key: string]: unknown;
+}
+export interface ThreadStartResult {
+    readonly thread: ThreadInfo;
+}
+export interface ThreadResumeParams {
+    readonly threadId: string;
+    readonly cwd?: string | null;
+    readonly approvalPolicy?: string | null;
+    readonly sandbox?: string | null;
+    readonly [key: string]: unknown;
+}
+export interface TurnStartParams {
+    readonly threadId: string;
+    readonly input: readonly TurnInput[];
+    readonly cwd?: string | null;
+    readonly approvalPolicy?: string | null;
+    readonly sandboxPolicy?: SandboxPolicy | null;
+    readonly model?: string | null;
+    readonly [key: string]: unknown;
+}
+export interface TurnInput {
+    readonly type: 'text';
+    readonly text: string;
+}
+export interface TurnInfo {
+    readonly id: string;
+    readonly status: string;
+    readonly error: {
+        readonly message: string;
+    } | null;
+    readonly items: readonly unknown[];
+    readonly [key: string]: unknown;
+}
+export interface TurnStartResult {
+    readonly turn: TurnInfo;
+}
+export interface TurnInterruptParams {
+    readonly threadId: string;
+    readonly turnId: string;
+}
+/** item/agentMessage/delta — agent message token delta. */
+export interface AgentMessageDeltaNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly itemId: string;
+    readonly delta: string;
+}
+/** item/reasoning/summaryTextDelta — reasoning summary token delta. */
+export interface ReasoningSummaryTextDeltaNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly itemId: string;
+    readonly delta: string;
+    readonly summaryIndex: number;
+}
+/** item/reasoning/textDelta — reasoning content token delta. */
+export interface ReasoningTextDeltaNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly itemId: string;
+    readonly delta: string;
+    readonly contentIndex: number;
+}
+/** item/plan/delta — plan delta. */
+export interface PlanDeltaNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly itemId: string;
+    readonly delta: string;
+}
+/** item/started — item lifecycle start. */
+export interface ItemStartedNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly item: {
+        readonly type: string;
+        readonly id: string;
+        readonly [key: string]: unknown;
+    };
+    readonly startedAtMs: number;
+}
+/** item/completed — item lifecycle end. */
+export interface ItemCompletedNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly item: {
+        readonly type: string;
+        readonly id: string;
+        readonly text?: string;
+        readonly [key: string]: unknown;
+    };
+    readonly completedAtMs: number;
+}
+/** turn/completed — turn end with usage. */
+export interface TurnCompletedNotification {
+    readonly threadId: string;
+    readonly turn: TurnInfo & {
+        readonly usage?: {
+            readonly inputTokens: number;
+            readonly cachedInputTokens?: number;
+            readonly outputTokens: number;
+            readonly reasoningOutputTokens?: number;
+        };
+    };
+}
+/** thread/tokenUsage/updated — token usage update. */
+export interface ThreadTokenUsageUpdatedNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly tokenUsage: {
+        readonly total: {
+            readonly totalTokens: number;
+            readonly inputTokens: number;
+            readonly cachedInputTokens: number;
+            readonly outputTokens: number;
+            readonly reasoningOutputTokens: number;
+        };
+        readonly last: {
+            readonly totalTokens: number;
+            readonly inputTokens: number;
+            readonly cachedInputTokens: number;
+            readonly outputTokens: number;
+            readonly reasoningOutputTokens: number;
+        };
+    };
+}
+/** error notification. */
+export interface ErrorNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly error: {
+        readonly message: string;
+        readonly codexErrorInfo?: string | null;
+        readonly additionalDetails?: string | null;
+    };
+    readonly willRetry: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,92 @@
+/**
+ * Codex loop engine module: hosts the AgentFactory that drives every session
+ * through the OpenAI Codex SDK, one stateless thread per dsh step, with the
+ * durable session log as the sole source of model context. dsh-agent-hub
+ * constructs this factory when the Codex engine is selected; this module is a
+ * library, not a Cordis plugin entry. The Codex SDK spawns its own CLI binary
+ * (no spawn injection seam), so this loop deliberately does not inject the dsh
+ * subprocess service.
+ *
+ * @module dsh-agent-hub/engine-codex
+ */
+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 { CodexApprovalPolicy, CodexSandboxMode, ResolvedConfig } from './types.ts';
+/** Codex CLI sandbox modes a deployment may pin. */
+export declare const CODEX_SANDBOX_MODES: readonly CodexSandboxMode[];
+/** Codex CLI approval policies a deployment may pin. */
+export declare const CODEX_APPROVAL_POLICIES: readonly CodexApprovalPolicy[];
+/** Deployment-owned configuration for the Codex loop plugin. */
+export interface Config {
+    /**
+     * Pinned sandbox mode for every thread. When omitted, each query follows the
+     * session's dsh permission knobs (`sandbox/mode` and `approval/policy`):
+     * full access maps to `danger-full-access`, an `ask` policy maps to
+     * `workspace-write`, and anything else fails closed with `read-only`.
+     */
+    sandboxMode?: CodexSandboxMode;
+    /**
+     * Pinned approval policy for every thread. When omitted, each query follows
+     * the session's dsh permission knobs: an `ask` policy maps to `on-request`
+     * (the CLI's own interactive prompt degrades to a denial in the unattended
+     * dsh runtime) and anything else maps to `never`.
+     */
+    approvalPolicy?: CodexApprovalPolicy;
+    /** Explicit environment entries layered over the credential-scrubbed parent environment. */
+    env?: Record<string, string>;
+    /** Model override for the SDK; Codex native settings own the model when omitted. */
+    model?: string;
+}
+/** Schema of the Codex loop plugin configuration. */
+export declare const Config: z<Config>;
+/** Host-face ctx key for the Codex loop service. */
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoopCodex: CodexLoop;
+    }
+}
+/**
+ * Concrete AgentFactory and driver service of the Codex 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 CodexLoop 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.
+     * @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>;
+    /**
+     * 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 handle. */
+    private resumeWith;
+}
+//# sourceMappingURL=loop.d.ts.map

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

@@ -0,0 +1,32 @@
+/**
+ * Mapping from the dsh session's durable permission knobs to one Codex query's
+ * declarative permission stance. Codex has no interactive approval callback:
+ * permissions are the `sandboxMode` + `approvalPolicy` pair chosen when the
+ * thread starts, so the fold maps the session's `sandbox/mode` and
+ * `approval/policy` events directly, mirroring the web surface's presets:
+ *   - full access → `danger-full-access` + `never` (no native checks at all),
+ *   - an `ask` policy → `workspace-write` + `on-request` (the CLI's own
+ *     interactive prompt degrades to a denial in the unattended dsh runtime),
+ *   - anything else fails closed → `read-only` + `never`.
+ *
+ * @module dsh-agent-hub/engine-codex/permission
+ */
+import type { PermissionEvent } from '../driver-core/permission-knobs.ts';
+import type { CodexApprovalPolicy, CodexSandboxMode } from './types.ts';
+/** The declarative permission stance one Codex thread runs under. */
+export interface CodexPermission {
+    readonly sandboxMode: CodexSandboxMode;
+    readonly approvalPolicy: CodexApprovalPolicy;
+}
+/** Conservative unattended default: read-only sandbox, never ask. */
+export declare const DEFAULT_CODEX_PERMISSION: CodexPermission;
+/**
+ * Resolve the session's effective Codex permission stance. Full access wins
+ * outright; otherwise an `ask` policy maps to the CLI's on-request approval
+ * inside a workspace-write sandbox; 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[]): CodexPermission;
+//# sourceMappingURL=permission.d.ts.map