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

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

@@ -0,0 +1,173 @@
+/**
+ * Antigravity (`agy`) CLI process projection.
+ *
+ * `agy` is the Antigravity CLI. Its non-interactive surface is a `--print` mode
+ * with an explicit INPUT format and OUTPUT format; the combination this driver
+ * uses is the streaming-NDJSON one, because it is the only shape that carries a
+ * machine-readable verdict:
+ *
+ * ```
+ * agy --input-format stream-json --output-format stream-json --print=<prompt-arg>
+ * ```
+ *
+ * with the prompt itself written to stdin as one NDJSON line, and `--print=`
+ * given an EMPTY value. That last detail is not cosmetic — it is a real trap
+ * recorded in `docs/probes/agy.md`: `--print` takes an OPTIONAL value, so
+ * `agy --input-format stream-json --print` makes `--input-format` the prompt and
+ * the intended prompt is silently ignored (the CLI says so on stderr). Attaching
+ * an empty value (`--print=`) pins the flag's argument and leaves the rest of the
+ * command line alone.
+ *
+ * ## Verified against a signed-in host
+ *
+ * The first probe run could not get past
+ * `{"event":"result","result":{"status":"ERROR","error":"authentication failed or
+ * timed out"}}` — the host's Google credential had expired — so the streaming
+ * vocabulary was recorded as UNKNOWN rather than guessed. Re-probing after the
+ * host signed in produced the whole protocol (`docs/probes/agy.md`, raw captures
+ * with `scripts/probe/probe.mjs agy`), and this module and `./frames.ts` are written
+ * against it. The three findings that shape the code:
+ *
+ * 1. **`--print` takes an OPTIONAL value**, so a bare `--print` makes the NEXT
+ *    flag the prompt and silently ignores the real one (the CLI says so on
+ *    stderr after the fact). Attaching an empty value (`--print=`) pins it.
+ * 2. **The stdin message needs an `event` field**: one NDJSON line of
+ *    `{"event":"user","message":{"role":"user","content":[…blocks…]}}`. Without
+ *    it the CLI answers
+ *    `error: stream input message is missing the "event" field`; an event it does
+ *    not know is only a warning and is ignored.
+ * 3. **Headless mode cannot prompt, so a tool that needs permission is
+ *    AUTO-DENIED** (`permission_mode: "request-review"` at `init`), and the turn
+ *    ends with the CLI's own explanation. `--dangerously-skip-permissions` is
+ *    what switches it to `permission_mode: "always-proceed"`. `--mode` does NOT
+ *    affect this — `accept-edits` and `plan` both leave `request-review` — so the
+ *    dsh sandbox knob is mapped to exactly that one flag (see
+ *    {@link agyDangerouslySkipPermissions}).
+ *
+ * @module dsh-loop-engine-allinone/engine-agy/process
+ */
+import type { DshSandboxMode } from '../driver-core/permission-knobs.ts';
+import type { CliSpawnRequest } from '../driver-cli/transport.ts';
+/** Grace in milliseconds for Antigravity process-tree termination. */
+export declare const AGY_DISPOSE_GRACE_MS = 3000;
+/** The `--mode` values the CLI accepts for a session's execution mode. */
+export declare const AGY_MODES: readonly ["accept-edits", "auto", "plan"];
+/** One Antigravity execution mode. */
+export type AgyMode = (typeof AGY_MODES)[number];
+/** The `--effort` values the CLI accepts. */
+export declare const AGY_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max"];
+/** One Antigravity reasoning effort. */
+export type AgyEffort = (typeof AGY_EFFORTS)[number];
+/**
+ * Resolve the `agy` executable.
+ *
+ * Antigravity installs into the user's local application data under `agy/bin`.
+ * `LOCALAPPDATA` is consulted rather than a hardcoded home so the same code is
+ * right for a profile running under a different user; PATH is the last resort.
+ * @param configBin - an operator-pinned path, if any.
+ * @returns the executable to spawn as `argv[0]`.
+ */
+export declare function agyBinResolver(configBin?: string): string;
+/**
+ * Whether the host has an Antigravity credential file on disk.
+ *
+ * A HINT for the settings page, never a gate: Antigravity owns its credentials,
+ * the plugin only reports whether a login has happened at least once. A missing
+ * file means "never signed in here"; a PRESENT file can still be expired, which
+ * is exactly the state this machine was in when the probe ran, so the file's
+ * existence must not be read as "ready".
+ * @param home - the user's home directory.
+ * @returns whether the credential file exists.
+ */
+export declare function agyCredentialPresent(home: string): boolean;
+/** Everything one step's Antigravity child needs. */
+export interface AgySpawnSpec {
+    /** The resolved executable (`argv[0]`). */
+    readonly bin: string;
+    /** The prompt text; written to stdin as one NDJSON user message. */
+    readonly prompt: string;
+    /** The session's working directory. */
+    readonly cwd: string;
+    /** Explicit environment entries layered over the scrubbed parent environment. */
+    readonly env: Record<string, string>;
+    /** Pinned model (`--model`). */
+    readonly model: string | undefined;
+    /**
+     * Pinned execution mode (`--mode`), when the deployment named one.
+     *
+     * Optional with no default ON PURPOSE, and that is a finding rather than a
+     * shrug: `--mode auto` was observed to be refused for the probe host's account
+     * ("not available for this account; continuing in the default mode"), so the
+     * set of modes a given account accepts is not knowable ahead of time. Omitting
+     * the flag lets the CLI use its own default instead of warning on every step.
+     */
+    readonly mode: AgyMode | undefined;
+    /** Pinned reasoning effort (`--effort`). */
+    readonly effort: AgyEffort | undefined;
+    /** Whether to run the child with terminal restrictions (`--sandbox`). */
+    readonly sandbox: boolean;
+    /**
+     * Whether to auto-approve every tool (`--dangerously-skip-permissions`).
+     *
+     * The ONLY switch that makes tools run headless: without it the CLI reports
+     * `permission_mode: "request-review"` and denies anything that would have
+     * prompted. Mapped from the dsh sandbox knob by
+     * {@link agyDangerouslySkipPermissions}.
+     */
+    readonly dangerouslySkipPermissions: boolean;
+    /** Cancellation. */
+    readonly signal: AbortSignal;
+}
+/**
+ * Build the argv for one non-interactive Antigravity step.
+ *
+ * `--print=` carries an EMPTY value on purpose (see the module note): the flag
+ * takes an optional argument, so leaving it bare swallows the NEXT flag as the
+ * prompt.
+ * @param spec - the step's spawn spec.
+ * @returns the argv.
+ */
+export declare function agyArgv(spec: AgySpawnSpec): string[];
+/**
+ * Project one step's prompt onto the CLI's stdin wire shape.
+ *
+ * One NDJSON document per line, of which the driver writes exactly one. The
+ * `event` member is REQUIRED — it is the discriminator the CLI reads, and its
+ * absence is answered with
+ * `error: stream input message is missing the "event" field`. An event the CLI
+ * does not know is only a warning (`warning: ignoring unsupported stream input
+ * message event "message"`) and is ignored, so a future input kind cannot break
+ * a working driver. Verified shape:
+ * `{"event":"user","message":{"role":"user","content":[{"type":"text","text":"…"}]}}`.
+ * @param prompt - the prompt text.
+ * @returns the stdin payload, newline-terminated.
+ */
+export declare function agyStdinPrompt(prompt: string): string;
+/**
+ * Map the session's dsh sandbox knob onto Antigravity's permission switch.
+ *
+ * There is exactly one switch, and it is all-or-nothing. Headless Antigravity
+ * runs at `permission_mode: "request-review"` and AUTO-DENIES any tool that would
+ * have prompted — the CLI's own words being `a tool required the "command"
+ * permission that headless mode cannot prompt for, so it was auto-denied` —
+ * while `--dangerously-skip-permissions` moves it to `always-proceed`.
+ *
+ * So full access is the only knob that earns the flag. Everything else, including
+ * "no knobs at all", fails closed and leaves the subprocess sandbox as the
+ * boundary.
+ *
+ * `--mode` is deliberately NOT consulted here: it was verified to leave
+ * `permission_mode` at `request-review` for BOTH `accept-edits` and `plan`, so it
+ * is an execution mode rather than a permission switch, and using it as one would
+ * be a guess dressed up as a mapping.
+ * @param sandbox - the session's durable sandbox mode, if any.
+ * @returns whether to pass `--dangerously-skip-permissions`.
+ */
+export declare function agyDangerouslySkipPermissions(sandbox: DshSandboxMode | undefined): boolean;
+/**
+ * Project one step's spawn spec onto the transport request.
+ * @param spec - the step's spawn spec.
+ * @returns the transport's request shape.
+ */
+export declare function agySpawnRequest(spec: AgySpawnSpec): CliSpawnRequest;
+//# sourceMappingURL=process.d.ts.map

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

@@ -0,0 +1,186 @@
+/**
+ * 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-allinone/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';
+import { type SpawnCapability } from './sdk.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 Claude Code. */
+export declare class ClaudeCodeAgent implements Agent {
+    private loopCtx;
+    readonly id: SessionId;
+    readonly options: AgentOptions;
+    readonly session: Session;
+    private readonly config;
+    /**
+     * Process-spawn capability handed down from the engine, which resolves it
+     * from the host's subprocess service. Held as a capability rather than read
+     * off the context because a service PROPERTY read requires the reading
+     * fiber to have injected it, and this agent's context is the engine's.
+     */
+    private readonly spawn;
+    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.
+     *
+     * Two facts, both of them load-bearing for Session V4:
+     *
+     *  - a call must not be given a SECOND result in one step. The Claude Agent
+     *    SDK delivers the same tool result in two `user` messages ~57 ms apart,
+     *    and V4 keys its pending-tool map by call id alone — it deletes the call
+     *    on the first result, so a repeat is refused (`tool/result <id> has no
+     *    advertised tool lifecycle`) and the whole session log fails to load;
+     *  - a step must not END while a call it announced has no result at all
+     *    (`step/end leaves unresolved tool call <id>`). An engine that announces
+     *    several calls in one model turn and reports fewer outcomes leaves the
+     *    step unbalanced, so the closing pass writes the missing outcomes.
+     *
+     * 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;
+    /**
+     * Whether the current query has rotated into a second step. The query-total
+     * usage record is only meaningful while one step holds the whole query.
+     */
+    private rotated;
+    /**
+     * 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, 
+    /**
+     * Process-spawn capability handed down from the engine, which resolves it
+     * from the host's subprocess service. Held as a capability rather than read
+     * off the context because a service PROPERTY read requires the reading
+     * fiber to have injected it, and this agent's context is the engine's.
+     */
+    spawn: SpawnCapability);
+    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;
+    /**
+     * 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: an engine that announces
+     * several calls in one turn reports their outcomes one at a time, and rotating
+     * on the first one would strand the rest in a step that can never resolve them
+     * (`step/end leaves unresolved tool call …`). Those calls run one model turn
+     * later instead, which is what they belong 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;
+    /** 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.
+     * @param messages - the messages this step delivers; only their images ride
+     *   with the prompt as bytes, and only they.
+     */
+    private step;
+}
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +1,73 @@
+/**
+ * Claude Code loop engine module: drives every session it is handed through
+ * the official Claude Agent SDK, one stateless query 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 recorded agent
+ * preset; this module is a library, not a Cordis plugin entry.
+ *
+ * @module dsh-loop-engine-allinone/engine-claude
+ */
+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 { ClaudeCodeAgent } from './agent.ts';
+import { type SpawnCapability } from './sdk.ts';
+import type { ClaudeCodePermissionMode, ResolvedConfig } from './types.ts';
+import { HostedEngineRuntime } from '../driver-core/hosted-engine-runtime.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 passed to each query (`Options.model`, overridden by the session's own pick); also the request-header label. Claude Code native settings own the model when omitted. */
+    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;
+    /**
+     * An EXTERNAL Claude Code executable to run instead of the SDK's bundled one.
+     *
+     * Unbinding the SDK is a supported SDK option (`pathToClaudeCodeExecutable`),
+     * not a hack: it lets a deployment run its own signed-in `claude` install —
+     * including one whose credentials the bundled copy would not see. Omitted
+     * keeps the bundled binary and its own login directory, which is the
+     * behaviour every earlier release had.
+     */
+    bin?: string;
+}
+/** Schema of the Claude Code loop plugin configuration. */
+export declare const Config: z<Config>;
+/** Host-face ctx key this engine's runtime is registered under. */
+export declare const CLAUDE_CODE_ENGINE_LABEL = "agentLoopClaudeCode";
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoopClaudeCode: ClaudeCodeLoop;
+    }
+}
+/**
+ * Creation/resume machinery for the Claude Code 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 ClaudeCodeLoop extends HostedEngineRuntime<ResolvedConfig, ClaudeCodeAgent> {
+    /** Process-spawn capability handed to every agent, sandboxed by the subprocess seam. */
+    readonly spawn: SpawnCapability;
+    constructor(ctx: Context, config: Config);
+    /** Construct the Claude Code driver for one prepared session. */
+    protected buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): ClaudeCodeAgent;
+}
+//# sourceMappingURL=loop.d.ts.map

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

@@ -0,0 +1,108 @@
+/**
+ * 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-allinone/engine-claude/mapping
+ */
+import type { BetaMessage, BetaRawMessageStreamEvent } 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[];
+/**
+ * The counters {@link mapUsage} reads. The SDK reports these on an assistant
+ * message's `usage`, on a stream `message_delta`'s narrower usage, and on the
+ * query `result`'s totals, so the parameter is the common shape rather than any
+ * one of those types.
+ */
+export interface ReportedUsage {
+    readonly input_tokens: number | null;
+    readonly output_tokens: number | null;
+    readonly cache_read_input_tokens?: number | null;
+    readonly cache_creation_input_tokens?: number | null;
+}
+/**
+ * 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, stream delta, or query result.
+ * @returns dsh token accounting, omitting absent optional counters.
+ */
+export declare function mapUsage(usage: ReportedUsage): TokenUsage;
+/**
+ * Keep a usage sample only when it accounts for something.
+ *
+ * The SDK zero-fills `usage` on streamed assistant messages it cannot attribute
+ * (gateway-fronted models report the real counters on the stream's
+ * `message_delta` and the query's `result` instead). A sample with every bucket
+ * at zero is that placeholder, not a measurement: keeping it would both show an
+ * empty usage row and — because the token meter trusts a present sample over
+ * the stream — hide the real one.
+ * @param usage - a mapped usage sample, or undefined.
+ * @returns the sample when it is non-empty, otherwise undefined.
+ */
+export declare function meaningfulUsage(usage: TokenUsage | undefined): TokenUsage | undefined;
+/** 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-allinone/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-allinone/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