dsh-loop-engine-allinone 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,67 @@
+/**
+ * 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-allinone/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;
+    /**
+     * An external Claude Code executable for the SDK to launch instead of its own
+     * bundled copy (`Options.pathToClaudeCodeExecutable`).
+     *
+     * A public SDK option rather than a workaround: the SDK spawns whatever path
+     * this names, so a deployment can run an install it signed in itself — with
+     * credentials the bundled copy's own login directory would not have. Absent
+     * keeps the bundled binary, which is what every earlier release did.
+     */
+    readonly bin?: string;
+    /**
+     * 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,28 @@
+/**
+ * Public types of the Claude Code loop driver. Types only — no runtime code.
+ *
+ * @module dsh-loop-engine-allinone/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;
+    /**
+     * An EXTERNAL Claude Code executable to run instead of the SDK's own bundled
+     * one, or `undefined` to keep the bundled binary.
+     *
+     * Handed to the SDK's own `pathToClaudeCodeExecutable` option, which is a
+     * public SDK surface — the SDK then launches this binary rather than the copy
+     * it ships. The bundled copy keeps its own credential semantics, so a
+     * deployment that pins a path must have signed that install in itself.
+     */
+    readonly bin: string | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,216 @@
+/**
+ * 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 projection of it — the
+ * serialized history, plus one `localImage` path item per image the step
+ * delivers (codex opens those files itself, so no bytes cross the wire).
+ * 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. Native
+ * approval requests (the `item/…/requestApproval` family) are server-initiated
+ * requests, not notifications: the client answers them through the dsh approval
+ * seam (`agent/requestPermission` → `ctx.approval`), while the thread still
+ * starts with a declarative `sandboxMode`/`approvalPolicy` stance.
+ *
+ * @module dsh-loop-engine-allinone/engine-codex/agent
+ */
+import type { Agent, AgentCancelCause, AgentOptions, AgentStatus, CancelOptions, InboxTarget } 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';
+import { DriverInbox } from '../driver-core/inbox.ts';
+/**
+ * Provider route label this driver logs into request/header snapshots and
+ * message provenance — the ONE route every hosted engine shares
+ * ({@link HOSTED_ROUTE_LABEL}), so all four engines select `external/default`
+ * and the model menu carries a single group instead of one per engine.
+ */
+export declare const PROVIDER = "external";
+/** 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: DriverInbox;
+    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;
+    /** Agent-lifecycle-local counter naming each streamed attempt. */
+    private streamAttempts;
+    /**
+     * Tool results logged into the currently open step. A result means the
+     * segment that requested the call is finished, so the next assistant content
+     * opens the next step (see {@link beginSegment}).
+     */
+    private stepSettledTools;
+    /**
+     * The current step's calls, and which of them already carry a result.
+     *
+     * Codex reports a call and its outcome as one item, so this pairing settles as
+     * it is written and the closing pass is normally a net — it is wired anyway,
+     * because the Session V4 rule it enforces is the step's, not the item's: a
+     * call may not be given a second result in one step, and a step may not end
+     * while a call it announced has no result at all ({@link closeStep} writes the
+     * missing outcome).
+     *
+     * Reset per step (see {@link step}), never on an internal segment rotation:
+     * call ids are unique for the life of the session, so retaining the marks only
+     * widens duplicate suppression and can never hide a legitimate result.
+     */
+    private readonly stepTools;
+    /**
+     * Rotate to the next step when the segment that ran a tool has finished, so
+     * each assistant segment lands in its own step.
+     *
+     * Called as new assistant content begins. A step holding a settled tool
+     * result means the previous segment is complete, and the content about to be
+     * written belongs to the next one. Rotating here (rather than when a call is
+     * announced) keeps calls announced together — one model turn — in one step.
+     *
+     * A step that still OWES a result does not rotate: a call whose outcome Codex
+     * has not reported yet would be stranded in a step that can never resolve it
+     * (`step/end leaves unresolved tool call …`). Such a call runs one model turn
+     * later instead, which is what it belongs to, and a call the engine never
+     * answers is closed by {@link closeStep} rather than by moving on.
+     * @param phase - the running phase carrying the open step's position.
+     */
+    private beginSegment;
+    /** Lazily created app-server client, reused across steps and released on scope teardown. */
+    private appServer;
+    /**
+     * The spawn configuration (`argv` + `env`) the cached client was built from.
+     * Codex's endpoint lives in the child's own command line, so a handover change
+     * must respawn the child rather than reuse one configured for another endpoint.
+     */
+    private appServerConfig;
+    /**
+     * Countdown that shuts the child down once this agent has been idle past the
+     * configured window, so an idle session stops paying for a process nothing
+     * is driving. Armed and cancelled by {@link setPhase}.
+     */
+    private readonly idleChild;
+    /**
+     * Resolves the read-only path behind each image block of the prompt. The
+     * attachment service is read lazily on every call, so a host that composes it
+     * after this agent still reaches the transcript.
+     */
+    private readonly imageAccess;
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig);
+    /** Shut the cached child down; the next step's {@link appServerClient} spawns a fresh one. */
+    private closeChild;
+    /**
+     * Return the cached app-server client, spawning one on first use, after a dead
+     * process, or when the resolved dsh endpoint changed since the last spawn.
+     *
+     * A handover is codex's own `-c` configuration for a dsh provider, so a
+     * different endpoint (different provider, base URL, protocol, or credential)
+     * needs a different child — the config is fixed when the process starts.
+     * @param handover - the session's resolved dsh endpoint, or undefined to leave codex to its own configuration.
+     */
+    private appServerClient;
+    /**
+     * Answer one server-initiated interaction. Approvals go through the dsh
+     * approval seam; a `request_user_input` question goes to the user-questions
+     * seam (both fail closed when their seam is absent), and an MCP elicitation is
+     * declined outright. Anything else is a protocol error.
+     * @param method - the server request method.
+     * @param params - the server request params.
+     * @returns the JSON-RPC outcome to send back.
+     */
+    private answerRequest;
+    /** Resolve one native Codex approval request through the dsh approval seam. */
+    private answerApproval;
+    /**
+     * Put one `request_user_input` question to the human through the dsh
+     * user-questions seam. The seam itself fails closed (`NO_PROVIDER`) when no
+     * answerer is composed, so a refusal degrades to "no answers given" and the
+     * turn continues; asking is never silently skipped, and the degradation is
+     * logged rather than swallowed.
+     * @param params - the request params carrying the questions.
+     * @returns the response payload (or the empty answer when nobody answered).
+     */
+    private answerUserInput;
+    /** Ask the dsh approval seam; fail closed to a denial when it is absent. */
+    private requestApproval;
+    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.
+     * @param messages - the messages this step delivers; each of its images rides
+     *   along as a `localImage` path item, and only they.
+     */
+    private step;
+}
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +1,80 @@
+/**
+ * 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-allinone/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;
+/** A JSON-RPC reply the client writes back for one inbound server request. */
+export type RequestOutcome = {
+    readonly result: unknown;
+} | {
+    readonly error: {
+        readonly code: number;
+        readonly message: string;
+    };
+};
+/** Callback answering one server-initiated JSON-RPC request. */
+export type RequestHandler = (method: string, params: unknown, id: number | string) => RequestOutcome | Promise<RequestOutcome>;
+/** 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 requestHandler;
+    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.
+     *
+     * `argv` appends the driver's own overrides to the bare `app-server`
+     * subcommand (codex's `-c key=value` configuration), and `env` layers the
+     * driver's explicit entries over the ambient environment — the child still
+     * needs `PATH` and, under a user's own codex setup, the ambient auth facts its
+     * configuration reads, so this is an overlay, not a replacement. Both default
+     * to nothing, which is the bare `codex app-server` the driver used before a
+     * dsh endpoint was ever handed over.
+     * @param argv - extra arguments after the `app-server` subcommand.
+     * @param env - explicit environment entries layered over the ambient one.
+     * @param bin - an external codex executable to launch instead of the bundled
+     *   dependency; absent runs the bundled copy, byte-for-byte the old argv.
+     * @returns the initialized client.
+     */
+    static create(argv?: readonly string[], env?: NodeJS.ProcessEnv, bin?: string): Promise<AppServerClient>;
+    /** Set the notification handler for streaming events. */
+    onNotification(handler: NotificationHandler): void;
+    /** Set the handler for server-initiated requests (e.g. approvals). */
+    onRequest(handler: RequestHandler): 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;
+    /** Resolve one inbound server request and write the JSON-RPC reply to stdin. */
+    private answerRequest;
+}
+//# 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-loop-engine-allinone/engine-codex/appserver/mapping
+ */
+import type { TokenUsage, ToolResultMessage } from '@deepseek-ai/dsh-llm';
+import { ToolCallId } from '@deepseek-ai/dsh-llm';
+/** 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: ToolCallId;
+        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: ToolCallId;
+        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: ToolCallId;
+        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-loop-engine-allinone/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