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

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

@@ -0,0 +1,225 @@
+/**
+ * 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-loop-engine-allinone/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;
+}
+/**
+ * One item of a `turn/start` input array. Codex's `UserInput` is a union of
+ * text, image, local-image, audio, skill, and mention items; this driver sends
+ * the step's serialized prompt as a text item and then one `localImage` item
+ * per image the step carries. `localImage` names a host file rather than
+ * carrying bytes, so codex's app-server opens the image itself.
+ */
+export type TurnInput = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'localImage';
+    readonly path: 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,75 @@
+/**
+ * Codex loop engine module: drives every session it is handed through the
+ * OpenAI Codex SDK, one stateless thread per dsh step, with the durable
+ * session log as the sole source of model context. The router routes a session
+ * here on the plugin's own engine record, else its agent preset; 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-loop-engine-allinone/engine-codex
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import { CodexAgent } from './agent.ts';
+import type { CodexApprovalPolicy, CodexSandboxMode, ResolvedConfig } from './types.ts';
+import { HostedEngineRuntime } from '../driver-core/hosted-engine-runtime.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>;
+    /** Fallback model for the app-server thread, used when the session selects none; Codex native settings own the model when omitted. */
+    model?: string;
+    /**
+     * Idle window in milliseconds before a session's `codex app-server` child is
+     * shut down, spawned again by the next step. Omitted or non-positive keeps
+     * the child for the session's whole life.
+     */
+    childIdleMs?: number;
+    /**
+     * An EXTERNAL `codex` executable, replacing this package's bundled
+     * `@openai/codex` dependency. Omitted keeps the bundled copy, which is what
+     * every earlier release ran.
+     */
+    bin?: string;
+}
+/** Schema of the Codex loop plugin configuration. */
+export declare const Config: z<Config>;
+/** Host-face ctx key this engine's runtime is registered under. */
+export declare const CODEX_ENGINE_LABEL = "agentLoopCodex";
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoopCodex: CodexLoop;
+    }
+}
+/**
+ * Creation/resume machinery for the Codex engine. The process-wide
+ * AgentFactory slot belongs to the router, which delegates each session to the
+ * engine its preset names; this class is that engine's driver, not a plugin.
+ */
+export declare class CodexLoop extends HostedEngineRuntime<ResolvedConfig, CodexAgent> {
+    constructor(ctx: Context, config: Config);
+    /** Construct the Codex driver for one prepared session. */
+    protected buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): CodexAgent;
+}
+//# sourceMappingURL=loop.d.ts.map

package/lib/types/engine-codex/model-handover.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Codex's dialect for a dsh endpoint: the `codex app-server` configuration
+ * overrides and environment that point it at dsh's model.
+ *
+ * Codex resolves a custom endpoint through `model_providers.<id>` in its own
+ * `config.toml` (`name`, `base_url`, `wire_api`, and an `env_key` naming the
+ * variable the credential is read from), and `codex app-server` accepts those as
+ * `-c key=value` overrides — so the handover needs no edit of `~/.codex`. The
+ * credential travels in the child's environment under {@link CODEX_DSH_API_KEY_ENV},
+ * which the `env_key` names.
+ *
+ * `name` is not optional in practice even though the CLI's own docs describe it
+ * as display metadata: codex 0.149.1 (the version this plugin pins) refuses to
+ * load a provider whose `name` is empty — "provider name must not be empty in
+ * `model_providers`" — and that config error kills `app-server` on startup, which
+ * the driver can only report as "process exited unexpectedly". Omitting it looked
+ * correct and failed before any request was ever sent, so every override this
+ * module builds carries it (verified against the pinned binary).
+ *
+ * Codex speaks only OpenAI's `responses` wire as of the version this plugin pins
+ * (0.149.1 dropped `chat`). A dsh protocol with no codex equivalent (Anthropic
+ * Messages, and now OpenAI Chat Completions) is NOT guessed: `wire_api` is
+ * omitted, so codex falls back to its own default wire and fails loud on the
+ * request — the honest outcome, since the plugin cannot make codex speak a
+ * protocol it does not implement. That default is `responses` as of 0.149.1: the
+ * request lands on `<baseURL>/responses`, which an Anthropic Messages or Chat
+ * Completions endpoint does not serve.
+ *
+ * @module dsh-loop-engine-allinone/engine-codex/model-handover
+ */
+import type { DshModelHandover } from '../driver-core/model-handover.ts';
+/** Provider id codex is configured with when dsh's endpoint is handed over. */
+export declare const CODEX_DSH_PROVIDER = "dsh";
+/** Environment variable codex reads the handed-over credential from. */
+export declare const CODEX_DSH_API_KEY_ENV = "DSH_LOOP_ENGINE_API_KEY";
+/** The `codex app-server` argv/env that hand one dsh endpoint over. */
+export interface CodexModelConfig {
+    /** `-c` overrides to append to the `app-server` subcommand. */
+    readonly argv: string[];
+    /** Environment the child needs to read the endpoint's credential. */
+    readonly env: Record<string, string>;
+}
+/**
+ * Translate one dsh endpoint handover into codex's `-c` overrides and the
+ * environment carrying the credential.
+ *
+ * The provider id ({@link CODEX_DSH_PROVIDER}) is a plugin-owned name: it exists
+ * only in this child's command line, so it cannot collide with a provider the
+ * user configured, and the model itself is still handed over as the thread's own
+ * `model` param. The provider's `name` repeats that id because codex rejects an
+ * empty one at config load, before any request is made.
+ * @param handover - the resolved dsh endpoint for the session's selection.
+ * @returns the argv entries and environment to spawn the app-server with.
+ */
+export declare function codexModelConfig(handover: DshModelHandover): CodexModelConfig;
+//# sourceMappingURL=model-handover.d.ts.map

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

@@ -0,0 +1,126 @@
+/**
+ * Mapping from the dsh session's durable permission knobs to one Codex query's
+ * declarative permission stance, plus the replies to every server-initiated
+ * interaction Codex can raise. Codex surfaces interactive approval as
+ * server-initiated JSON-RPC requests answered through the dsh approval seam
+ * (see `approvalReason` / `resolveApprovalRequest` below), while the thread
+ * still starts with the `sandboxMode` + `approvalPolicy` pair chosen at
+ * creation. 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` (approvals are then
+ *     routed to the dsh approval seam, failing closed when it is absent),
+ *   - anything else fails closed → `read-only` + `never`.
+ *
+ * The other two interactions (`item/tool/requestUserInput` and
+ * `mcpServer/elicitation/request`) have no approval to grant: one asks the human
+ * a question, the other asks for MCP input. Both are mapped here so the driver
+ * answers them in-vocabulary instead of failing them with a protocol error that
+ * the model reads as a broken tool.
+ *
+ * @module dsh-loop-engine-allinone/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;
+/**
+ * One question to put to the human, in the shape the dsh user-questions seam
+ * accepts. Declared inline (a structural subset) to avoid a peer dep on
+ * `@deepseek-ai/dsh-user-questions`, matching the approval seam's treatment.
+ */
+export interface UserQuestionItem {
+    /** Stable question id, echoed back by the answer and by our reply. */
+    readonly id: string;
+    /** The question to display. */
+    readonly question: string;
+    /** Optional short heading/group label. */
+    readonly header?: string;
+    /** Optional choices a UI renders as a menu. */
+    readonly options?: readonly {
+        readonly label: string;
+        readonly description?: string;
+    }[];
+}
+/** The human's answer, in the shape the dsh user-questions seam returns. */
+export interface UserQuestionAnswer {
+    /** One entry per answered question; unanswered questions are simply absent. */
+    readonly answers: readonly {
+        readonly id: string;
+        readonly selected: readonly string[];
+        /** Optional free-text answer, carried alongside `selected`. */
+        readonly custom?: string;
+    }[];
+}
+/** The `item/tool/requestUserInput` result Codex expects. */
+export interface CodexUserInputResponse {
+    /** Answer lists keyed by question id; an empty map means "no answers given". */
+    readonly answers: Record<string, {
+        readonly answers: string[];
+    }>;
+}
+/**
+ * Read the answerable questions of one `item/tool/requestUserInput` request. The
+ * wire is untrusted, so an entry with no usable id or wording is dropped: the
+ * reply is keyed by question id, and a synthesized key would answer a question
+ * Codex never asked.
+ * @param params - the request params.
+ * @returns the questions to put to the human, possibly none.
+ */
+export declare function userInputQuestions(params: unknown): UserQuestionItem[];
+/**
+ * Project one human answer onto Codex's response shape. A free-text answer rides
+ * along as a further entry of the question's answer list, and no answer at all
+ * (no seam, or the human dismissed it) becomes an empty map — the honest "asked,
+ * answered nothing", never an invented answer.
+ * @param answer - the seam's answer, or undefined when none was obtained.
+ * @returns the response payload.
+ */
+export declare function userInputResponse(answer: UserQuestionAnswer | undefined): CodexUserInputResponse;
+/**
+ * The reply to one `mcpServer/elicitation/request`. An unattended driver cannot
+ * render an elicitation form, so it declines — the same stance the Claude Code
+ * driver takes for the equivalent callback, and the one answer that never
+ * fabricates input the user did not give.
+ * @returns the response payload.
+ */
+export declare function elicitationResponse(): {
+    action: 'decline';
+};
+/**
+ * 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;
+/** The closed outcome of one dsh approval request (mirrors the dsh-user-approval seam). */
+export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
+/** Short tool identity for the dsh approval request carrying one native Codex approval. */
+export declare function approvalToolName(method: string): string;
+/** Human-readable reason for one native Codex approval request. */
+export declare function approvalReason(method: string, params: unknown): string;
+/** The native decision a command/file-change approval resolves to. */
+export declare function approvalDecision(outcome: ApprovalOutcome): 'accept' | 'decline';
+/** The native permissions-request response for one approval outcome. */
+export declare function permissionsGrant(outcome: ApprovalOutcome, requested: unknown): {
+    permissions: unknown;
+    scope: 'turn';
+};
+/** Build the JSON-RPC reply payload for one inbound Codex approval request. */
+export declare function resolveApprovalRequest(method: string, params: unknown, outcome: ApprovalOutcome): {
+    result: unknown;
+} | {
+    error: {
+        code: number;
+        message: string;
+    };
+};
+//# sourceMappingURL=permission.d.ts.map

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

@@ -0,0 +1,28 @@
+/**
+ * Codex skill provider: exposes the codex CLI's instruction files as DSH
+ * skills.
+ *
+ * Codex has no per-skill catalog like the agents-skill standard; its
+ * instructions are `AGENTS.md` files read from the session cwd up to the git
+ * root, plus the global `~/.codex/AGENTS.md`. Each file set is surfaced as one
+ * user-invocable `agents-md` skill whose body is the concatenated file
+ * contents, so the dsh skill-injection seam (`/name` gestures) can carry it
+ * into the prompt.
+ *
+ * The discovery algorithm itself lives in {@link AgentsMdSkillProvider}; this
+ * module supplies only Codex's locations and ranks — and, having no skills
+ * catalog, no `skills` entry.
+ *
+ * @module dsh-loop-engine-allinone/engine-codex/skills
+ */
+import { AgentsMdSkillProvider } from '../driver-core/agents-md-skill-provider.ts';
+import type { SkillProviderControl } from '../skills.ts';
+/**
+ * Skill provider that discovers `AGENTS.md` from every directory between the
+ * project cwd and the git root, plus the user home `~/.codex/AGENTS.md`.
+ */
+export declare class CodexSkillProvider extends AgentsMdSkillProvider {
+    constructor(control: SkillProviderControl);
+}
+export default CodexSkillProvider;
+//# sourceMappingURL=skills.d.ts.map

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

@@ -0,0 +1,36 @@
+/**
+ * Public types of the Codex loop driver. Types only — no runtime code.
+ *
+ * @module dsh-loop-engine-allinone/engine-codex/types
+ */
+/** Codex CLI sandbox modes, as spoken by the app-server `sandbox` field. */
+export type CodexSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** Codex CLI approval policies, as spoken by the app-server `approvalPolicy` field. */
+export type CodexApprovalPolicy = 'never' | 'on-request' | 'on-failure' | 'untrusted';
+/** Driver configuration after defaults and load-time validation. */
+export interface ResolvedConfig {
+    /** Pinned sandbox mode; `undefined` follows the session's dsh permission knobs per query. */
+    readonly sandboxMode: CodexSandboxMode | undefined;
+    /** Pinned approval policy; `undefined` follows the session's dsh permission knobs per query. */
+    readonly approvalPolicy: CodexApprovalPolicy | undefined;
+    readonly env: Record<string, string>;
+    readonly model: string | undefined;
+    /**
+     * How long an idle session keeps its `codex app-server` child, in
+     * milliseconds; zero or less keeps it for the session's whole life. See
+     * `driver-core/idle-child.ts` for why the child, and not the agent, is what
+     * gets released.
+     */
+    readonly childIdleMs: number;
+    /**
+     * An EXTERNAL `codex` executable to launch instead of this package's bundled
+     * `@openai/codex`, or `undefined` to keep the bundled copy.
+     *
+     * The bundled dependency is a Node script, so the driver runs it under the
+     * current node; an external path may be either — a `.js` entrypoint is run
+     * under node, anything else is spawned directly. That distinction is why the
+     * resolver returns a whole argv prefix rather than a single path.
+     */
+    readonly bin: string | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,132 @@
+/**
+ * The node-side half of the engine registry: which class drives which engine.
+ *
+ * {@link ENGINE_REGISTRY} (`./engine-registry.ts`) declares what every engine
+ * IS, in data the browser bundle can also read. This module is the one place
+ * that has to import the driver classes themselves, and it is deliberately
+ * node-only: `./client/**` must never reach it, or the browser artifact would
+ * pull `node:fs`, the SDKs and every engine driver with it.
+ *
+ * The two are kept in step by the type system rather than by discipline:
+ * {@link ENGINE_DRIVER_FACTORIES} is a total `Record` over
+ * {@link HostedEngineId}, so adding an id to the registry without adding its
+ * driver fails the build. The reverse (a driver with no id) cannot happen —
+ * the record's keys are the ids.
+ *
+ * ## What a driver factory receives
+ *
+ * Every engine is constructed from the SAME composition-entry config object
+ * (`Config` in `./index.ts`), because the entry is an engine-agnostic superset:
+ * any session may select any engine at any moment, so the entry carries every
+ * engine's knobs at once. Each factory picks the fields its engine owns and
+ * drops the rest — which is why the per-engine config projections live here
+ * rather than in the entry's schema.
+ *
+ * @module dsh-loop-engine-allinone/engine-drivers
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ClaudeCodePermissionMode } from './engine-claude/types.ts';
+import type { CodexApprovalPolicy, CodexSandboxMode } from './engine-codex/types.ts';
+import type { PiSandboxMode } from './engine-pi/types.ts';
+import type { AgyEffort, AgyMode } from './engine-agy/process.ts';
+import type { HostedEngineId } from './engine-registry.ts';
+import type { RouterEngine } from './router-loop.ts';
+/**
+ * The engine knobs one composition entry carries, as this module reads them.
+ *
+ * Declared structurally rather than imported from `./index.ts` so the
+ * dependency runs one way: `index.ts` imports the dispatch table, and the table
+ * does not import the entry's schema. Every field is optional, matching the
+ * entry's permissive schema — a deployment configures only the engines it uses.
+ */
+export interface EngineDriverConfig {
+    /** Claude Code: pinned permission mode (overrides the session's own knobs). */
+    permissionMode?: ClaudeCodePermissionMode;
+    /** Explicit environment entries layered over the credential-scrubbed parent environment. */
+    env?: Record<string, string>;
+    /** Fallback model, used when the session selects none. */
+    model?: string;
+    /** Claude Code: grace for process-tree termination. */
+    disposeGraceMs?: number;
+    /** Claude Code: cap on agent turns per query. */
+    maxTurns?: number;
+    /** Codex / Pi: pinned sandbox mode. */
+    sandboxMode?: CodexSandboxMode | PiSandboxMode;
+    /** Codex: pinned approval policy. */
+    approvalPolicy?: CodexApprovalPolicy;
+    /** Pi: pinned LLM provider. */
+    piProvider?: string;
+    /** Pi: thinking/reasoning level. */
+    piThinking?: string;
+    /** Idle window before a persistent child is shut down (Kimi, Codex). */
+    childIdleMs?: number;
+    /** Antigravity: pinned execution mode (`--mode`). */
+    agyMode?: AgyMode;
+    /** Antigravity: pinned reasoning effort (`--effort`). */
+    agyEffort?: AgyEffort;
+    /** Antigravity: pinned terminal-restriction flag. */
+    agySandbox?: boolean;
+    /** Antigravity: pinned auto-approve flag, overriding the session's sandbox knob. */
+    agyDangerouslySkipPermissions?: boolean;
+    /** Qoder CN: pinned permission mode, overriding the session's dsh knobs. */
+    qoderPermissionMode?: string;
+    /** Hermes: pinned reasoning level (`--reasoning`). */
+    hermesReasoning?: string;
+    /**
+     * The Kimi engine's executable, as every release before the registry exposed
+     * it.
+     *
+     * Kept as a working alias rather than removed: it is a published composition
+     * field, so a deployment that set it must keep working unchanged, and silently
+     * ignoring a configured path would point the engine at a different binary than
+     * the operator chose. {@link EngineDriverConfig.bins} WINS when both are set —
+     * the newer, engine-agnostic form is the one to prefer.
+     *
+     * @deprecated use `bins.kimiBin`.
+     */
+    kimiBin?: string;
+    /**
+     * Per-engine executable overrides, keyed by each descriptor's
+     * {@link EngineDescriptor.binConfigKey}.
+     *
+     * One open map rather than a field per engine: the registry already names the
+     * key each engine reads, so a new engine adds no schema field and no
+     * projection branch — it reads `config.bins?.[descriptor.binConfigKey]`.
+     */
+    bins?: Readonly<Record<string, string>>;
+    /**
+     * Per-engine account REGION overrides, keyed by each descriptor's own
+     * {@link EngineRegion.configKey}.
+     *
+     * The same open-map shape as {@link EngineDriverConfig.bins}, for the same
+     * reason: an engine whose CLI scopes accounts by region declares the knob in the
+     * registry, and a deployment overrides it here without a per-engine schema
+     * field. Today only MiniMax Code declares one (`regions.mcodeRegion`, default
+     * `cn`).
+     */
+    regions?: Readonly<Record<string, string>>;
+}
+/** Builds one engine's driver runtime. */
+export type EngineDriverFactory = (ctx: Context, config: EngineDriverConfig) => RouterEngine;
+/**
+ * One factory per hosted engine.
+ *
+ * Total over {@link HostedEngineId} by type: the compiler refuses a missing row,
+ * which is what makes "add an id to the registry" an incomplete change until the
+ * driver is wired too.
+ */
+export declare const ENGINE_DRIVER_FACTORIES: Readonly<Record<HostedEngineId, EngineDriverFactory>>;
+/**
+ * Build one hosted engine's driver runtime.
+ *
+ * The one dispatch point the router calls, replacing the per-engine `switch`
+ * that used to live in `./index.ts`: adding an engine is now a registry row plus
+ * a factory row, and the `switch` that would have needed a new `case` — and a
+ * new `default` to keep TypeScript quiet — is gone.
+ * @param engine - the engine to build.
+ * @param ctx - the context the runtime's effects belong to.
+ * @param config - the composition entry's engine knobs.
+ * @returns the engine's driver runtime.
+ */
+export declare function buildEngineDriver(engine: HostedEngineId, ctx: Context, config: EngineDriverConfig): RouterEngine;
+//# sourceMappingURL=engine-drivers.d.ts.map