dsh-loop-engine 0.1.5-rc1

package/lib/types/driver-core/ownership.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared factory ownership and abort-race machinery for the hosted engines.
+ * Both the Claude Code and Codex loop drivers run the same lifecycle: exactly
+ * one factory owns the AgentFactory slot, every live agent's teardown is
+ * tracked until it settles, and setup awaits are raced against a fused abort
+ * signal. These helpers are engine-free — they only touch the fiber state,
+ * the session id type, and an AbortController — so the two loop modules share
+ * them verbatim.
+ *
+ * @module dsh-loop-engine/driver-core/ownership
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+/** Fiber states that cannot own or serve a new lifecycle. */
+export declare const INACTIVE_STATES: ReadonlySet<number>;
+/** Factory-level ownership: live agent teardowns plus load-time tracking. */
+export declare class FactoryOwnership {
+    private readonly fiber;
+    private accepting;
+    private readonly teardown;
+    private readonly inactive;
+    private readonly liveAgents;
+    private startupTasks;
+    constructor(fiber: Context['fiber']);
+    /** Aborts (reason: `agent loop is not active` error) when factory teardown begins. */
+    get signal(): AbortSignal;
+    isActive(): boolean;
+    /** Track one live agent's shared teardown until it has run. */
+    track(dispose: () => Promise<void>): () => void;
+    /** Join config startup work that begins before an agent exists. */
+    trackStartup(job: Promise<void>): void;
+    /** Join one public create/resume continuation; factory dispose awaits its settlement. */
+    trackWrapper(job: Promise<unknown>): void;
+    dispose(): Promise<void>;
+}
+/** Await `operation`, or throw the signal's reason as soon as it aborts. */
+export declare function raceAbort<T>(operation: PromiseLike<T> | T, signal: AbortSignal, id: SessionId): Promise<T>;
+/** Start an abortable operation and release a value that arrives after cancellation. */
+export declare function raceAbortCall<T>(operation: () => PromiseLike<T> | T, signal: AbortSignal, id: SessionId, releaseAbandoned?: (value: T) => void): Promise<T>;
+//# sourceMappingURL=ownership.d.ts.map

package/lib/types/driver-core/permission-knobs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Reading the dsh session's durable permission knobs from the session log.
+ * Both the Claude Code and Codex drivers fold the same `sandbox/mode` and
+ * `approval/policy` events (pinned at creation, re-recorded on every switch)
+ * into per-query permission decisions; the knob readers are engine-free.
+ *
+ * @module dsh-loop-engine/driver-core/permission-knobs
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/**
+ * Minimal structural shape of one session log event. The base `SessionEvent`
+ * union in this compilation does not carry the sandbox/approval packages'
+ * augmentation keys, so the fold reads the wire shape directly.
+ */
+export type PermissionEvent = Pick<SessionEvent, 'data'> & {
+    readonly type: string;
+};
+/** dsh sandbox modes, mirrored inline to avoid a peer dep on @deepseek-ai/dsh-sandbox-policy. */
+export type DshSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** dsh approval policies, mirrored inline to avoid a peer dep on @deepseek-ai/dsh-user-approval. */
+export type DshApprovalPolicy = 'ask' | 'never';
+/** The session's sandbox-mode override: the last `sandbox/mode` event, if any. */
+export declare function sessionSandboxMode(events: readonly PermissionEvent[]): DshSandboxMode | undefined;
+/** The session's approval-policy override: the last `approval/policy` event, if any. */
+export declare function sessionApprovalPolicy(events: readonly PermissionEvent[]): DshApprovalPolicy | undefined;
+//# sourceMappingURL=permission-knobs.d.ts.map

package/lib/types/driver-core/prompt.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Serialization of the durable session history into the prompt text of one
+ * hosted-engine query. Both the Claude Code and Codex drivers build their
+ * per-step input from the durable session log: the transcript is the log's
+ * exact projection, so a later replay of the same log derives the identical
+ * prompt (Model-visible ⟺ logged bridge).
+ *
+ * @module dsh-loop-engine/driver-core/prompt
+ */
+import type { Message } from '@deepseek-ai/dsh-llm';
+/** Model-facing stand-in for an image block that the hosted engines cannot consume as bytes. */
+export declare const OMITTED_IMAGE_TEXT = "[image omitted: the driver does not transcribe images; read the file when a path is available]";
+/**
+ * Serialize a derived conversation history into the prompt text of one hosted
+ * query. The last message is the live user request that triggered the step;
+ * every earlier message is durable replay context. The output is a pure
+ * function of the log prefix.
+ * @param messages - derived history, oldest first, as returned by
+ *   `Session.deriveMessages()` at step time.
+ * @returns the prompt text to pass to the engine.
+ */
+export declare function serializeHistory(messages: readonly Message[]): string;
+//# sourceMappingURL=prompt.d.ts.map

package/lib/types/driver-core/skill-inject.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Skill-injection helpers shared by the hosted engine drivers. Both the Claude
+ * Code and Codex agents replicate the dsh `/name` skill gesture scan and the
+ * XML `<skill_content>` rendering that the in-process engine's dsh-tool-skill
+ * handler would otherwise provide — their agent contexts do not descend from
+ * the agent-preset chain. These helpers are pure: they take user messages or a
+ * loaded skill and return the injected text, with no session or loop access.
+ *
+ * @module dsh-loop-engine/driver-core/skill-inject
+ */
+import type { UserMessage } from '@deepseek-ai/dsh-session';
+export declare function isSkillName(name: string): boolean;
+/** Minimal shape of a loaded skill definition. */
+export interface SkillDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse?: string;
+    readonly invocation: {
+        readonly modelInvocable: boolean;
+        readonly userInvocable: boolean;
+    };
+    readonly source: string;
+    readonly provider: string;
+    readonly content: string;
+    readonly path?: string;
+    readonly resourceBase?: {
+        readonly kind: string;
+        readonly path: string;
+    };
+}
+/** Durable source for an injected user-explicit skill invocation (mirrors dsh-skill's). */
+export interface SkillInvocationSource {
+    readonly kind: 'skill-invocation';
+    readonly name: string;
+    readonly form: 'instructions';
+}
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** A user-explicit skill invocation injected by this driver. */
+        'skill-invocation': SkillInvocationSource;
+    }
+}
+/** Minimal shape of the SkillRegistry service. */
+export interface SkillsService {
+    get(name: string, options: {
+        cwd?: string;
+        signal?: AbortSignal;
+        scope?: unknown;
+    }): Promise<SkillDefinition | undefined>;
+}
+/** Escape text for inclusion in XML-like skill markup. */
+export declare function escapeText(value: string): string;
+/** Escape an XML-like attribute value. */
+export declare function escapeAttr(value: string): string;
+/** Render the `<skill_content>` block for a loaded skill. */
+export declare function renderSkillContent(skill: SkillDefinition): string;
+/** Collect `/name` gesture tokens from direct user messages, in first-seen order. */
+export declare function invokedSkillNames(messages: readonly UserMessage[]): string[];
+//# sourceMappingURL=skill-inject.d.ts.map

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

@@ -0,0 +1,106 @@
+/**
+ * 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 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 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: 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;
+    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, optional live parent, 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, optional live parent, 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