dsh-loop-engine 0.1.5-rc1

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

@@ -0,0 +1,29 @@
+/**
+ * Codex skill provider: exposes the codex CLI's instruction files as DSH
+ * skills.
+ *
+ * Codex has no per-skill catalog like the agents-skill standard; its
+ * instructions are `AGENTS.md` files read from the session cwd up to the git
+ * root, plus the global `~/.codex/AGENTS.md`. Each file set is surfaced as one
+ * user-invocable `agents-md` skill whose body is the concatenated file
+ * contents, so the dsh skill-injection seam (`/name` gestures) can carry it
+ * into the prompt.
+ *
+ * @module dsh-loop-engine/engine-codex/skills
+ */
+import type { SkillCandidate, SkillDefinition, SkillLookupOptions, SkillProvider, SkillProviderControl } from '../skills.ts';
+/**
+ * Skill provider that discovers `AGENTS.md` from every directory between the
+ * project cwd and the git root, plus the user home `~/.codex/AGENTS.md`.
+ */
+export declare class CodexSkillProvider implements SkillProvider {
+    private readonly control;
+    readonly name = "codex";
+    constructor(control: SkillProviderControl);
+    list(options: SkillLookupOptions): Promise<readonly SkillCandidate[]>;
+    get(candidate: SkillCandidate, _options: SkillLookupOptions): Promise<SkillDefinition | undefined>;
+    /** One merged `agents-md` candidate for a ranked file set. */
+    private agentsCandidate;
+}
+export default CodexSkillProvider;
+//# sourceMappingURL=skills.d.ts.map

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

@@ -0,0 +1,19 @@
+/**
+ * Public types of the Codex loop driver. Types only — no runtime code.
+ *
+ * @module dsh-loop-engine/engine-codex/types
+ */
+/** Codex CLI sandbox modes, as spoken by the app-server `sandbox` field. */
+export type CodexSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** Codex CLI approval policies, as spoken by the app-server `approvalPolicy` field. */
+export type CodexApprovalPolicy = 'never' | 'on-request' | 'on-failure' | 'untrusted';
+/** Driver configuration after defaults and load-time validation. */
+export interface ResolvedConfig {
+    /** Pinned sandbox mode; `undefined` follows the session's dsh permission knobs per query. */
+    readonly sandboxMode: CodexSandboxMode | undefined;
+    /** Pinned approval policy; `undefined` follows the session's dsh permission knobs per query. */
+    readonly approvalPolicy: CodexApprovalPolicy | undefined;
+    readonly env: Record<string, string>;
+    readonly model: string | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/engine-kimi/acp/client.d.ts

@@ -0,0 +1,76 @@
+/**
+ * JSON-RPC client for the `kimi acp` subprocess (Agent Client Protocol over
+ * stdio).
+ *
+ * The driver hands the client a process handle carrying its stdin/stdout/stderr
+ * (projected from the dsh subprocess seam). The client frames JSON-RPC 2.0
+ * records on a bare `\n` (via a byte decoder, tolerating a trailing `\r`),
+ * correlates request responses by `id`, dispatches every `session/update`
+ * notification to a buffered event stream, and answers the reverse-RPC
+ * `session/request_permission` requests the agent publishes. The child is
+ * long-lived (one per factory) and stepped over via `newSession` + `prompt`.
+ *
+ * @module dsh-loop-engine/engine-kimi/acp/client
+ */
+import type { KimiProcess, KimiSpawnCapability, KimiSpawnSpec } from '../process.ts';
+import { type AcpFrame, type AcpUpdate } from './types.ts';
+/** How the client answers one `session/request_permission`. */
+export type AcpPermissionHandler = (request: AcpFrame) => boolean | Promise<boolean>;
+/** Callback receiving every non-response event line. */
+export type AcpUpdateHandler = (update: AcpUpdate) => void;
+/**
+ * ACP client over one `kimi acp` child. Created once per driver scope and reused
+ * across steps, matching the Pi RPC client's lifecycle.
+ */
+export declare class AcpClient {
+    private readonly process;
+    private readonly pending;
+    private readonly updateBuffer;
+    private updateWake;
+    private updateHandler;
+    private permissionHandler;
+    private sealed;
+    private nextId;
+    private readonly decoder;
+    private buffer;
+    /** Whether this client was sealed or its process exited. */
+    get closed(): boolean;
+    /** Mount a client over an already-spawned `kimi acp` process. */
+    constructor(process: KimiProcess);
+    /**
+     * Create a client, spawning the `kimi acp` child through the supplied
+     * capability (or the default node spawn when none is given).
+     * @param spec - the `kimi acp` argv/cwd/env the child should run with.
+     * @param spawn - optional process-spawn capability (the subprocess seam).
+     * @returns the connected client.
+     */
+    static create(spec: KimiSpawnSpec, spawn?: KimiSpawnCapability): AcpClient;
+    /** Register the event dispatch handler. */
+    onUpdate(handler: AcpUpdateHandler): void;
+    /** Register the permission-approval handler (reverse-RPC answers). */
+    onPermission(handler: AcpPermissionHandler): void;
+    /** Send one request and await the correlated response. */
+    request(method: string, params: unknown): Promise<unknown>;
+    /** Send a notification (no correlated response awaited). */
+    notify(method: string, params: unknown): void;
+    /** Open the protocol handshake. */
+    initialize(): Promise<unknown>;
+    /** Start a fresh ACP session and resolve to its session id. */
+    newSession(cwd: string): Promise<string>;
+    /** Prompt the agent in a session and resolve when the turn completes. */
+    prompt(sessionId: string, text: string): Promise<unknown>;
+    /** Cancel the active turn in a session (fire-and-forget). */
+    cancel(sessionId: string): void;
+    /** Answer a pending `session/request_permission`. */
+    respondPermission(id: number, approved: boolean): void;
+    /** Consume every buffered update as an async generator. */
+    updates(): AsyncGenerator<AcpUpdate, void, void>;
+    /** Seal the client and request child termination. */
+    dispose(): void;
+    private feed;
+    /** Dispatch one parsed line: a response, an update notification, or a reverse-RPC request. */
+    private dispatch;
+    private settle;
+    private handlePermission;
+}
+//# sourceMappingURL=client.d.ts.map

package/lib/types/engine-kimi/acp/mapping.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Maps `kimi acp` `session/update` events to dsh session-log projections.
+ *
+ * Kimi streams incremental assistant text (`agent_message_chunk`), incremental
+ * thinking (`agent_thought_chunk`), a tool-call announcement (`tool_call`) and its
+ * progress/result stream (`tool_call_update`). This module is pure: it classifies
+ * an update, extracts chunk deltas, and projects the tool-call identity/result so
+ * the agent can fold them into the durable log. Content blocks use the observed
+ * kimi `{ type: 'content', content: { type: 'text', text } }` nesting; unknown
+ * block types are ignored.
+ *
+ * @module dsh-loop-engine/engine-kimi/acp/mapping
+ */
+import type { ToolResultMessage } from '@deepseek-ai/dsh-llm';
+import type { AcpContentBlock, AcpToolCallExt, AcpToolCallStreamExt, AcpUpdate } from './types.ts';
+/** Whether the update is an incremental assistant text chunk. */
+export declare function isTextChunk(update: AcpUpdate): update is AcpUpdate & {
+    readonly sessionUpdate: 'agent_message_chunk';
+    readonly content: AcpContentBlock;
+};
+/** Whether the update is an incremental thinking chunk. */
+export declare function isThoughtChunk(update: AcpUpdate): update is AcpUpdate & {
+    readonly sessionUpdate: 'agent_thought_chunk';
+    readonly content: AcpContentBlock;
+};
+/** Whether the update announces a tool call. */
+export declare function isToolCall(update: AcpUpdate): update is AcpToolCallExt;
+/** Whether the update streams a tool call's progress/result. */
+export declare function isToolCallUpdate(update: AcpUpdate): update is AcpToolCallStreamExt;
+/** The delta text of a text/thinking chunk. */
+export declare function chunkDelta(update: AcpUpdate): string;
+/** The raw tool-call id (+ content index) as the wire carries it. */
+export declare function toolCallIdOf(update: AcpUpdate): string;
+/** The tool display name (`title`). */
+export declare function toolCallName(update: AcpUpdate): string;
+/** Whether a tool stream status is settled (no longer streaming). */
+export declare function isToolSettledStatus(status: string): boolean;
+/** Whether a tool stream status denotes a failure. */
+export declare function isToolErrorStatus(status: string): boolean;
+/** Join the observed `{ type: 'content', content: { type: 'text', text } }` blocks. */
+export declare function toolContentText(update: AcpToolCallExt | AcpToolCallStreamExt): string;
+/** Project a completed tool call to a durable tool/result message. */
+export declare function toolResult(callId: string, text: string, isError: boolean): ToolResultMessage;
+//# sourceMappingURL=mapping.d.ts.map

package/lib/types/engine-kimi/acp/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Agent Client Protocol (ACP) wire types for the `kimi acp` driver.
+ *
+ * Kimi exposes the ACP adapter over stdio (JSON-RPC 2.0). The driver speaks a
+ * minimal, stable subset that a normal agent flow needs: initialize, session/new,
+ * session/prompt, session/cancel, plus the `session/update` notifications carrying
+ * incremental assistant text (`agent_message_chunk`), thinking
+ * (`agent_thought_chunk`), and tool calls (`tool_call` / `tool_call_update`).
+ * Tool-approval arrives as the reverse-RPC `session/request_permission`, which the
+ * client must answer. Shapes below are the live-record deltas observed against the
+ * 0.28.1 CLI; content blocks re-use a `{ type, text }` text shape (and tolerate
+ * other block types by ignoring them).
+ *
+ * @module dsh-loop-engine/engine-kimi/acp/types
+ */
+/** A text content block in an ACP update (the observed kimi shape). */
+export interface AcpTextContent {
+    readonly type: 'text';
+    readonly text: string;
+}
+/** One tool-call content block: the observed kimi `{ type: 'content', content }` nesting. */
+export interface AcpToolContentBlock {
+    readonly type: 'content';
+    readonly content: AcpTextContent;
+}
+/** A content block in a chunk/thought update; text is handled, others are ignored. */
+export type AcpContentBlock = AcpTextContent | {
+    readonly type: 'image' | 'resource_link' | 'audio' | string;
+    readonly [key: string]: unknown;
+};
+/** One `session/update` notification (partial; the discriminator is `sessionUpdate`). */
+export interface AcpUpdate {
+    readonly sessionUpdate: string;
+    readonly [key: string]: unknown;
+}
+/** A tool-call announcement (`sessionUpdate: 'tool_call'`). */
+export interface AcpToolCallExt extends AcpUpdate {
+    readonly sessionUpdate: 'tool_call';
+    readonly toolCallId: string;
+    readonly title: string;
+    readonly kind: string;
+    readonly status: string;
+    readonly content?: readonly AcpToolContentBlock[];
+}
+/** A tool-call progress/result stream (`sessionUpdate: 'tool_call_update'`). */
+export interface AcpToolCallStreamExt extends AcpUpdate {
+    readonly sessionUpdate: 'tool_call_update';
+    readonly toolCallId: string;
+    readonly status: string;
+    readonly content?: readonly AcpToolContentBlock[];
+}
+/** The `session/request_permission` reverse-RPC params. */
+export interface AcpPermissionRequest {
+    readonly sessionId?: string;
+    readonly request?: unknown;
+}
+/** Result of a completed `session/prompt` request (opaque; the turn ended). */
+export interface AcpPromptResult {
+    readonly [key: string]: unknown;
+}
+/** The id-scoped response to a request (result or error). */
+export interface AcpResponse {
+    readonly id: number;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: number;
+        readonly message: string;
+    };
+}
+/** A JSON-RPC request/notification frame on the wire. */
+export interface AcpFrame {
+    readonly jsonrpc: '2.0';
+    readonly id?: number;
+    readonly method?: string;
+    readonly params?: unknown;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: number;
+        readonly message: string;
+    };
+}
+/** Guards toolkit: is the frame a `session/update` notification carrying an update. */
+export declare function isUpdateFrame(frame: AcpFrame): frame is AcpFrame & {
+    readonly method: 'session/update';
+    readonly params: {
+        readonly sessionId: string;
+        readonly update: AcpUpdate;
+    };
+};
+/** Guards toolkit: is the frame a reverse-RPC request needing an approval answer. */
+export declare function isPermissionRequestFrame(frame: AcpFrame): frame is AcpFrame & {
+    readonly id: number;
+    readonly method: 'session/request_permission';
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,130 @@
+/**
+ * Kimi Code loop Agent: drives one session through turn and step boundaries over
+ * a persistent `kimi acp` child (Agent Client Protocol over stdio), speaking one
+ * stateless `session/new` + `session/prompt` per dsh step. The dsh session log is
+ * the sole source of model context and the prompt is a pure serialization of the
+ * durable history, so the transcript stays Model-visible ⟺ logged. Kimi owns its
+ * system prompt and tools natively; the ACP child is spawned through the dsh
+ * subprocess seam (the only available privilege boundary) and tool approvals are
+ * answered from the session's dsh approval knobs.
+ *
+ * @module dsh-loop-engine/engine-kimi/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 { KimiSpawnCapability } from './process.ts';
+/** Provider route label used for logged header snapshots and message provenance. */
+export declare const PROVIDER = "kimi";
+/** Drives one session through turn and step boundaries on Kimi Code. */
+export declare class KimiAgent implements Agent {
+    private loopCtx;
+    readonly id: SessionId;
+    readonly options: AgentOptions;
+    readonly session: Session;
+    private readonly config;
+    private readonly spawn;
+    private readonly bin;
+    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;
+    /** Lazily created ACP client, reused across steps and released on scope teardown. */
+    private acp;
+    /** The spawn spec the cached client was built from; a change forces a respawn. */
+    private lastSpec;
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig, spawn: KimiSpawnCapability, bin: string);
+    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;
+    /** 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;
+    /** Whether two spawn specs describe the same `kimi acp` child. */
+    private specsEqual;
+    /** Return the cached ACP client, respawning when the spec or process changed. */
+    private acpClient;
+    /** Build the `kimi acp` argv/cwd/env for the persistent child. */
+    private spawnSpec;
+    /** Run one `kimi acp` step for the current session history and map the streamed updates. */
+    private step;
+    /** Per-step accumulation state for streamed assistant blocks and tool calls. */
+    private blocks;
+    private emittedToolCalls;
+    private toolText;
+    private blockRef;
+    private ensureBlock;
+    /** Apply one streamed update to the current step's blocks and stream. */
+    private applyUpdate;
+    /**
+     * Flush the accumulated assistant blocks into one durable assistant/message
+     * carrying the exact stream the attempt published live.
+     * @param turn - durable turn owning the message.
+     * @param step - durable step owning the message.
+     * @param currentStream - the step's live attempt accessor; a step whose
+     *   blocks streamed always has one open, while a tool-only step has none.
+     */
+    private flushAssistant;
+}
+//# sourceMappingURL=agent.d.ts.map

package/lib/types/engine-kimi/commands.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Kimi Code slash-command bridge.
+ *
+ * The dsh `commands` runtime executes a registered command locally — the line is
+ * consumed and never reaches the model — so a command whose real processing
+ * lives inside the Kimi engine must forward the raw line back to the agent, which
+ * Kimi then expands (as far as the ACP prompt surface supports). Registering the
+ * built-ins keeps them visible in the dsh web slash menu; unregistered `/lines`
+ * pass through as user text, but the menu would hide the engine's command
+ * surface.
+ *
+ * Kimi's slash commands are chiefly TUI controls (`/login`, `/provider`,
+ * `/settings`, `/sessions`, `/tasks`, …) that the ACP prompt surface does not
+ * expand the way an interactive TUI does; this bridge therefore registers the
+ * subset that are meaningful to forward to the engine (session/mode/status and
+ * the goal form). `skill:` commands are already carried by the dsh skill
+ * injection seam and Kimi's own shorthand, so they are not duplicated here.
+ *
+ * `model` is deliberately absent even though the CLI has it: the dsh web
+ * client owns a `/model` contribution, and a same-named host command makes
+ * `ui-commands` throw the whole command menu source away, leaving only the
+ * skill group. `/goal` stays: the managed block disables dsh's `command-goal`
+ * row for hosted engines, so the slot is free and the CLI's own goal mode
+ * takes it over.
+ *
+ * @module dsh-loop-engine/engine-kimi/commands
+ */
+import type { CommandDefinition, CommandInvocation, CommandResult } from '../commands.ts';
+/**
+ * Build the forwarding handler for one Kimi slash command: it re-delivers the
+ * full `/<name> [args]` line to the receiving agent as a plain user message,
+ * where the engine expands it. `rawInput` already carries the separator
+ * whitespace and any arguments.
+ * @param name - the command name without the leading slash.
+ * @returns the command handler.
+ */
+export declare function forwardKimiCommand(name: string): (invocation: CommandInvocation) => CommandResult;
+/** Kimi Code's built-in slash commands that make sense to forward to the engine. */
+export declare const KIMI_COMMANDS: readonly CommandDefinition[];
+//# sourceMappingURL=commands.d.ts.map

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

@@ -0,0 +1,108 @@
+/**
+ * Kimi Code loop engine module: hosts the AgentFactory that drives every
+ * session through a persistent `kimi acp` child (Agent Client Protocol over
+ * stdio), speaking one stateless `session/new` + `session/prompt` per dsh step,
+ * with the durable session log as the sole source of model context.
+ * dsh-loop-engine constructs this factory when the Kimi engine is selected; this
+ * module is a library, not a Cordis plugin entry. Kimi has no host approval
+ * callback, so tool approvals surfaced by ACP (`session/request_permission`) are
+ * answered from the session's dsh approval knobs (an `ask` policy degrades to
+ * denial); the whole child is spawned through the dsh subprocess seam — the only
+ * available privilege boundary — and the sandbox stance follows the session's
+ * durable permission knobs as the subprocess provider resolves them (default
+ * read-only).
+ *
+ * @module dsh-loop-engine/engine-kimi
+ */
+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 { KimiSpawnCapability } from './process.ts';
+import type { ResolvedConfig } from './types.ts';
+/** Grace in milliseconds for Kimi process-tree termination. */
+export declare const KIMI_DISPOSE_GRACE_MS = 3000;
+/** Deployment-owned configuration for the Kimi loop plugin. */
+export interface Config {
+    /** Model alias for the `kimi` child (`-m`); Kimi native config owns the model when omitted. */
+    model?: string;
+    /** Explicit environment entries passed to the `kimi` child. */
+    env?: Record<string, string>;
+    /** Kimi CLI executable; `'kimi'` resolves through PATH when not pinned to an absolute path. */
+    bin?: string;
+}
+/** Schema of the Kimi loop plugin configuration. */
+export declare const Config: z<Config>;
+/** Host-face ctx key for the Kimi loop service. */
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoopKimi: KimiLoop;
+    }
+}
+/**
+ * Concrete AgentFactory and driver service of the Kimi 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 KimiLoop 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;
+    /** One-shot spawn capability handed to every agent, sandboxed by the subprocess seam. */
+    readonly spawn: KimiSpawnCapability;
+    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-kimi/mapping.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Mapping from Kimi Code `--output-format stream-json` records to dsh
+ * session-log events. Kimi emits one JSON object per stdout line, discriminated
+ * by a `role` field (verified against the 0.28.1 CLI):
+ *   - `{ "role": "assistant", "content": "<text>" }`
+ *   - `{ "role": "assistant", "tool_calls": [{ "type": "function",
+ *       "id": "call_…", "function": { "name": "Bash", "arguments": "<json>" } }] }`
+ *   - `{ "role": "tool", "tool_call_id": "call_…", "content": "<text>" }`
+ *   - `{ "role": "meta", "type": "session.resume_hint", … }` (discarded)
+ * Thinking and tool progress go to stderr, never the JSONL, so this module has no
+ * usage or reasoning projection. The module is pure: it parses a raw stdout
+ * buffer and returns plain record projections the agent folds into the log.
+ *
+ * @module dsh-loop-engine/engine-kimi/mapping
+ */
+import type { ToolResultMessage } from '@deepseek-ai/dsh-llm';
+/** One normalized Kimi tool-call record. */
+export interface KimiToolCall {
+    /** The tool invocation id (`call_…`), correlated with the later `tool` record. */
+    readonly id: string;
+    /** The tool name. */
+    readonly name: string;
+    /** The raw arguments JSON string, passed verbatim. */
+    readonly arguments: string;
+}
+/** One parsed Kimi stream-json record (partial, tolerant of unknown fields). */
+export interface KimiRecord {
+    readonly role?: unknown;
+    readonly type?: unknown;
+    readonly content?: unknown;
+    readonly tool_calls?: unknown;
+    readonly tool_call_id?: unknown;
+    readonly is_error?: unknown;
+    readonly isError?: unknown;
+    readonly error?: unknown;
+}
+/** Record role discriminant used by the step loop. */
+export type KimiRecordRole = 'assistant' | 'tool' | 'meta' | 'unknown';
+/**
+ * Parse a `kimi --output-format stream-json` stdout buffer into records.
+ * Lines are bare-`\n` delimited; blank lines and non-JSON lines are dropped.
+ * @param stdout - the child's full stdout text.
+ * @returns the parsed records, in order.
+ */
+export declare function parseKimiRecords(stdout: string): KimiRecord[];
+/** Classify one record's role. */
+export declare function roleOf(record: KimiRecord): KimiRecordRole;
+/**
+ * The joined text of one record's `content` field. Handles both the string
+ * form (`"content": "<text>"`) and an array form (`[{ "type": "text", "text": … }]`)
+ * defensively; any other shape renders empty.
+ * @param record - the parsed record.
+ * @returns the joined body text.
+ */
+export declare function recordContentText(record: KimiRecord): string;
+/**
+ * Normalize an assistant record's `tool_calls` array. Each entry keeps its id,
+ * name, and a verbatim argument string (the wire already serializes arguments
+ * as JSON text; absent args render `{}`).
+ * @param record - the parsed assistant record.
+ * @returns the normalized tool calls, in order.
+ */
+export declare function assistantToolCalls(record: KimiRecord): readonly KimiToolCall[];
+/**
+ * Surface a `tool` record as a durable tool-result message, or `undefined` when
+ * the record is not a correlatable tool result (missing `role: tool` or no id).
+ * @param record - the parsed record.
+ * @returns the dsh tool-result message, or `undefined`.
+ */
+export declare function toolResultMessage(record: KimiRecord): ToolResultMessage | undefined;
+//# sourceMappingURL=mapping.d.ts.map

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

@@ -0,0 +1,28 @@
+/**
+ * Tool-approval mapping for the `kimi acp` driver.
+ *
+ * Kimi's ACP adapter surfaces tool/permission decisions as the reverse-RPC
+ * `session/request_permission`, which the client must answer. The dsh harness
+ * has no interactive approval callback in the unattended runtime, so the fold
+ * mirrors the codex/Pi bridges: an `ask` approval policy degrades to a denial
+ * (the only safe answer when no human is present), and anything else
+ * (`never`, or knob-less) auto-approves the tool. A full-access sandbox mode
+ * also auto-approves; a `workspace-write` stance is still auto-approved here
+ * because Kimi's own permission gating (`--permission`/session policy) is what
+ * bounds the tool — the ACP approval is the host's gate, and the dsh
+ * `approval/policy` knob is its signal.
+ *
+ * @module dsh-loop-engine/engine-kimi/permission
+ */
+import type { PermissionEvent } from '../driver-core/permission-knobs.ts';
+/**
+ * Whether the driver should answer `session/request_permission` with approval for
+ * one query. An `ask` policy denies (fail-closed — no human is present in the
+ * unattended runtime); anything else (`never`, or knob-less) auto-approves. The
+ * sandbox stance is not consulted: Kimi's own tool policy bounds what a tool does,
+ * and the ACP approval is the host's gate, signalled by `approval/policy`.
+ * @param events - the durable session log.
+ * @returns whether tool requests are approved.
+ */
+export declare function resolveToolApproval(events: readonly PermissionEvent[]): boolean;
+//# sourceMappingURL=permission.d.ts.map