@vidge/dsh-agent-hub 0.1.0-rc1

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-agent-hub/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-agent-hub/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-agent-hub/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,116 @@
+/**
+ * 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-agent-hub/engine-claude/agent
+ */
+import type { Agent, AgentCancelCause, AgentOptions, AgentStatus, CancelOptions, InboxTarget } from '@deepseek-ai/dsh-agent';
+import { Inbox } from '@deepseek-ai/dsh-agent';
+import type { Scope } from '@deepseek-ai/dsh-scope';
+import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session';
+import type { Context } from '@deepseek-ai/cordis';
+import type { ResolvedConfig } from './types.ts';
+/** Drives one session through turn and step boundaries on Claude Code. */
+export declare class ClaudeCodeAgent implements Agent {
+    private loopCtx;
+    readonly id: SessionId;
+    readonly options: AgentOptions;
+    readonly session: Session;
+    private readonly config;
+    readonly inbox: Inbox;
+    private phase;
+    private activityDone;
+    /** The agent-scoped registration boundary; the lifecycle owner unwinds it after the driver exits. */
+    readonly scope: Scope;
+    readonly ctx: Context;
+    /** Fused dispatcher, built once in the constructor so hot-path dispatches never allocate. */
+    private readonly dispatch;
+    /** Whether this loop instance has appended its initial/resume request anchor. */
+    private requestHeaderLogged;
+    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;
+    /**
+     * Resolve the model one query runs on, session choice first.
+     *
+     * The web surface sets `AgentOptions.model` when a session picks a model, and
+     * `agentDefaultModel` holds the global default; reading both is what makes
+     * the dsh model picker mean something for this engine. The service is
+     * optional — a minimal profile may not mount it — so it is resolved through
+     * `ctx.get` rather than `inject`, and a faulting provider degrades to the
+     * next layer instead of failing the turn.
+     *
+     * @returns the chosen id (undefined leaves the CLI on its own default),
+     * its provider route, and the layer that chose it.
+     */
+    private resolveModel;
+    /** 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,99 @@
+/**
+ * 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-agent-hub constructs this factory when the Claude Code engine is
+ * selected; this module is a library, not a Cordis plugin entry.
+ *
+ * @module dsh-agent-hub/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 { ClaudeCodeBackend, ClaudeCodePermissionMode, ResolvedConfig } from './types.ts';
+/** Deployment-selectable non-interactive Claude Code permission modes. */
+export declare const CLAUDE_CODE_PERMISSION_MODES: readonly ClaudeCodePermissionMode[];
+/** Provider backends the deployment can pin for the CLI child. */
+export declare const CLAUDE_CODE_BACKENDS: readonly ClaudeCodeBackend[];
+/** 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;
+    /**
+     * Provider backend for the CLI child. The CLI resolves backends by
+     * precedence, so a host holding credentials for two of them silently runs on
+     * the wrong one — pin this when the host is not single-homed. `auto` (the
+     * default) takes the first configured, preferring a relay over ambient cloud
+     * credentials.
+     */
+    backend?: ClaudeCodeBackend;
+    /** 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.
+     * @param ownerCtx - caller context that structurally owns the lifecycle.
+     * @param options - identities, session seed/metadata, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>;
+    /**
+     * Resume an owned agent from the configured persistence service.
+     * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
+     * @param options - persisted identity, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>;
+    /** Resume through an explicit persistence handle. */
+    private resumeWith;
+}
+//# sourceMappingURL=loop.d.ts.map

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

@@ -0,0 +1,84 @@
+/**
+ * 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-agent-hub/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 { type ContentBlock, type StreamChunk, type TokenUsage, type ToolResultMessage } from '@deepseek-ai/dsh-llm';
+import { CallId } from '../llm-compat.ts';
+/** 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: CallId;
+    /** 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: CallId;
+    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-agent-hub/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-agent-hub/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/provider-env.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Derive the Claude Code child's provider environment from dsh's own LLM
+ * configuration, so a session reaches the same endpoint dsh itself would use.
+ *
+ * The alternative — re-inheriting `process.env` — only works when the host was
+ * launched from a shell that already exported provider credentials. A dsh
+ * started from a desktop launcher inherits none, the child falls back to the
+ * CLI's own login state, and the turn dies as a 403 far from its cause. dsh
+ * already knows the answer: `llm-pi-ai` holds the route's `baseURL` and the
+ * name of its credential, and `credentials` resolves that name to a secret.
+ * This module reads both and states the result as environment variables the
+ * Agent SDK understands.
+ *
+ * Only the route's *transport* is derived. Which model runs is settled earlier
+ * by the agent's own resolution (session choice, then `agentDefaultModel`), and
+ * is passed in rather than re-read here.
+ *
+ * Everything is resolved per call. `credentials.resolve` is contractually a
+ * per-call read — the store layers process env over `~/.dsh/.credentials.yaml`
+ * over `.env` files, any of which may change under a long-lived host — so a
+ * cached secret would outlive its source.
+ *
+ * @module dsh-agent-hub/engine-claude/provider-env
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** How a resolved route is carried to the child. */
+export interface ProviderEnv {
+    /** Environment entries to lay over the child's environment. */
+    readonly env: Record<string, string>;
+    /** One line naming the route, for the session log. */
+    readonly diagnostic: string;
+}
+/**
+ * Build the child's provider environment from the route the selected model
+ * belongs to.
+ *
+ * Returns undefined — leaving the caller's existing behavior intact — whenever
+ * the route cannot be derived: no provider named, settings or credentials
+ * absent, the route unconfigured, its credential unset, or its protocol one the
+ * CLI cannot speak. Each of those is a profile that legitimately routes some
+ * other way, so none is an error here; the caller still falls back to inherited
+ * environment, and `backendDiagnostic` still reports when that leaves the child
+ * with nothing.
+ *
+ * @param ctx - context to resolve `settings` and `credentials` through.
+ * @param provider - route id from the resolved model selection.
+ * @returns the environment overlay and a diagnostic, or undefined.
+ */
+export declare function deriveProviderEnv(ctx: Context, provider: string | undefined): Promise<ProviderEnv | undefined>;
+//# sourceMappingURL=provider-env.d.ts.map

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

@@ -0,0 +1,101 @@
+/**
+ * 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-agent-hub/engine-claude/sdk
+ */
+import type { Options, PermissionMode } from '@anthropic-ai/claude-agent-sdk';
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+import type { ClaudeCodeBackend } from './types.ts';
+/** 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>;
+    /**
+     * Provider routing derived from dsh's own LLM configuration, when the model
+     * selection named a route this plugin could resolve.
+     *
+     * Kept separate from {@link env} because it does not merely add entries: a
+     * derived route is authoritative about which backend the child speaks, so
+     * every *other* backend's keys are removed rather than left to out-rank it.
+     * The deployment's `env` still layers on top, so an explicit override wins.
+     */
+    readonly providerEnv?: Record<string, string>;
+    /** Grace in milliseconds for process-tree termination. */
+    readonly disposeGraceMs: number;
+    /** Model override for the SDK, when a selection or the deployment pins one. */
+    readonly model?: string;
+    /** Provider route the model id belongs to, used to diagnose a backend mismatch. */
+    readonly provider?: string;
+    /** Provider backend the child is pointed at; defaults to `auto`. */
+    readonly backend?: ClaudeCodeBackend;
+    /** 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;
+/**
+ * Describe the backend the child will actually run on.
+ *
+ * A misrouted child fails far from its cause: with nothing configured the CLI
+ * falls back to its own login state and reports "Not logged in", and with the
+ * wrong backend it reports a model that is "not available". Neither names the
+ * environment, so state the resolved routing up front.
+ *
+ * @param env - the composed child environment.
+ * @param backend - the deployment's choice.
+ * @returns a one-line diagnostic, or undefined when routing is unambiguous.
+ */
+export declare function backendDiagnostic(env: Record<string, string>, backend: ClaudeCodeBackend): string | undefined;
+/**
+ * Flag a model the active backend is unlikely to serve.
+ *
+ * The dsh selection names a provider route, and only a relay's endpoint is
+ * deployment-chosen — so a selection routed at some other provider reaching a
+ * cloud backend is a mismatch the child will discover as an opaque
+ * model-not-found. The id is still sent as-is: the caller asked for it, the
+ * provider lists it, and refusing here would substitute a model the user did
+ * not pick.
+ *
+ * @param model - the resolved model id.
+ * @param provider - the provider route the selection named, when it named one.
+ * @param env - the composed child environment.
+ * @returns a one-line diagnostic, or undefined when nothing looks wrong.
+ */
+export declare function modelDiagnostic(model: string | undefined, provider: string | undefined, env: Record<string, string>): string | undefined;
+/**
+ * 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