dsh-loop-engine 1.0.0-rc5 → 1.0.0-rc7

package/lib/invariant.js

@@ -1,9 +1,9 @@
 // src/settings.ts
 import z from "@deepseek-ai/schemastery";
 import { settingsNamespace } from "@deepseek-ai/dsh-settings";
-var LOOP_ENGINE_IDS = ["in-process", "claude-code", "codex", "pi"];
+var LOOP_ENGINE_IDS = ["in-process", "claude-code", "codex", "pi", "kimi"];
 var LOOP_ENGINE_SETTINGS_SCHEMA = z.object({
-  engine: z.union([z.const("in-process"), z.const("claude-code"), z.const("codex"), z.const("pi")]).default("in-process"),
+  engine: z.union([z.const("in-process"), z.const("claude-code"), z.const("codex"), z.const("pi"), z.const("kimi")]).default("in-process"),
   showInComposer: z.boolean().default(true)
 });
 
@@ -62,16 +62,20 @@ function applyManagedBlock(text, engine) {
   const span = managedSpan(text);
   let result;
   if (!span.present) {
-    if (block === "") return text;
-    const base = ensureTrailingNewline(text);
-    result = `${base}
+    if (block === "") {
+      result = text;
+    } else {
+      const base = ensureTrailingNewline(text);
+      result = `${base}
 ${block}`;
+    }
   } else if (block === "") {
     result = span.tail.startsWith("\n") ? `${span.head}${span.tail.slice(1)}` : `${span.head}${span.tail}`;
   } else {
     result = `${span.head}${span.blankBefore ? "\n" : ""}${block}${span.tail}`;
   }
   if (block !== "") return dropSeedPlaceholder(result);
+  if (text.trim() === "") return result;
   return hasRootEntry(result) ? result : seedEmptyArray(result);
 }
 
@@ -81,13 +85,17 @@ var name = "loop-engine-invariant";
 var inject = ["invariants"];
 var install = (ctx, fail) => {
   void ctx;
-  const seed = "# dsh profile patch layer\n";
+  const seed = "";
+  const commentOnly = "# dsh profile patch layer\n";
   for (const engine of LOOP_ENGINE_IDS) {
     const applied = applyManagedBlock(seed, engine);
     const reborn = applyManagedBlock(applied, currentEngineOf(applied));
-    if (reborn !== applied) fail(`managed-block round trip for ${engine} is not a fixed point`);
-    if (engine === "in-process" && applied !== seed) fail("in-process engine must leave the file text unchanged");
+    if (reborn !== applied) fail(`bare round trip for ${engine} is not a fixed point`);
+    if (engine === "in-process" && applied !== seed) fail("in-process engine must leave a bare layer unchanged");
     if (engine !== "in-process" && currentEngineOf(renderManagedBlock(engine)) !== engine) fail(`${engine} block must read back as the ${engine} engine`);
+    if (engine === "in-process" && applyManagedBlock(commentOnly, engine) === commentOnly) {
+      fail("in-process engine must re-seed a comment-only file to a loadable top-level array");
+    }
   }
 };
 var apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));

package/lib/types/client/locales.d.ts

@@ -16,6 +16,8 @@ export interface LoopEngineKey {
     engineCodex: string;
     /** Option label: the Pi CLI driver. */
     enginePi: string;
+    /** Option label: the Kimi Code CLI driver. */
+    engineKimi: string;
     /** Settings toggle: show the engine picker in the chat page composer. */
     showInComposerLabel: string;
     /** Unavailable-state message. */

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,121 @@
+/**
+ * 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 { 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';
+import type { KimiSpawnCapability } from './process.ts';
+/** 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: 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;
+    /** 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;
+    /** Append one streamed update's durable effect for the current step. */
+    private applyUpdate;
+    /** Append one live chunk and return its durable seq. */
+    private appendChunk;
+    /** Flush the accumulated assistant blocks into one durable assistant/message. */
+    private flushAssistant;
+}
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ *
+ * @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,86 @@
+/**
+ * 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.
+     * @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-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