dsh-loop-engine 1.0.0-rc6 → 1.0.0-rc8

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, 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, 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

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

@@ -0,0 +1,61 @@
+/**
+ * Kimi CLI process projection. The driver locates the `kimi` executable, builds
+ * the `-p --output-format stream-json` argv for one step, and projects the dsh
+ * subprocess seam handle onto a minimal transport the agent can read to
+ * completion. Kimi has no host permission callback and no `--tools` pruning
+ * flag in `-p` mode, so the whole child is spawned through the seam — the only
+ * available privilege boundary (the seam's OS sandbox, default read-only) — and
+ * every step is a fresh one-shot child because `-p` is inherently stateless.
+ *
+ * @module dsh-loop-engine/engine-kimi/process
+ */
+import type { Readable, Writable } from 'node:stream';
+import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
+/** The exact argv/cwd/env the driver requests for one `kimi -p` child. */
+export interface KimiSpawnSpec {
+    /** The program plus its flags; `argv[0]` is the Kimi CLI executable. */
+    readonly argv: readonly string[];
+    readonly cwd: string;
+    readonly env: Record<string, string>;
+    /** Cancellation: the seam escalates process-tree termination when it fires. */
+    readonly signal?: AbortSignal;
+}
+/** A spawned Kimi process as the agent's transport needs it. */
+export interface KimiProcess {
+    /** Child stdin (JSON-RPC request frames). */
+    readonly stdin: Writable;
+    /** Child stdout (the `session/update` notification frames). */
+    readonly stdout: Readable;
+    /** Child stderr (diagnostics; drained and dropped). */
+    readonly stderr: Readable;
+    /** Resolves when the child closes. */
+    readonly done: Promise<unknown>;
+    /** Request process-tree termination. */
+    terminate(): void;
+}
+/** Spawns one Kimi child over the given spec (the driver's spawn capability). */
+export type KimiSpawnCapability = (spec: KimiSpawnSpec) => KimiProcess;
+/** Resolve the Kimi home directory from `KIMI_CODE_HOME` or the current user's home. */
+export declare function kimiHomeDir(): string;
+/**
+ * Resolve the Kimi CLI executable. An explicit config path wins; otherwise this
+ * probes the standard `<kimi home>/bin/kimi[.exe]` location and falls back to
+ * `'kimi'` (resolved through PATH by the spawner).
+ * @param configBin - an operator-pinned absolute path (or `'kimi'`), if any.
+ * @returns the executable to spawn as `argv[0]`.
+ */
+export declare function kimiBinResolver(configBin?: string): string;
+/**
+ * Build the persistent `kimi acp` argv. The ACP child stays alive across steps
+ * and is spoken to over JSON-RPC on stdio — the prompt is a request body, not an
+ * argv positional — so there is no command-line length ceiling and no model flag
+ * (Kimi owns model selection natively via its own config).
+ * @param bin - the Kimi executable.
+ * @returns the argv, `argv[0]` being the executable.
+ */
+export declare function kimiAcpArgv(bin: string): string[];
+/** Project the driver's spawn request onto the dsh subprocess seam. */
+export declare function kimiSubprocessSpec(spec: KimiSpawnSpec, graceMs: number): SubprocessSpawnSpec;
+/** Project a dsh subprocess handle onto the Kimi process transport. */
+export declare function fromSubprocess(handle: SubprocessHandle): KimiProcess;
+//# sourceMappingURL=process.d.ts.map

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

@@ -0,0 +1,57 @@
+/**
+ * Kimi Code skill provider: exposes the Kimi CLI's instruction files and skills
+ * as DSH skills.
+ *
+ * Kimi reads per-directory `AGENTS.md` files from the session cwd up to the git
+ * root, and installs skills from `skills/` directories — the user-level
+ * `$KIMI_CODE_HOME/skills/` (default `~/.kimi-code/skills/`) and the
+ * project-level `.kimi-code/skills/` (walking up to the git root). Each
+ * context-file set is surfaced as one user-invocable `agents-md` skill whose
+ * body is the concatenated file contents; every found `SKILL.md` catalog entry
+ * is surfaced under its own name, so the dsh skill-injection seam (`/name`
+ * gestures) can carry them into the prompt.
+ *
+ * The generic `~/.agents/skills/` and `.agents/skills/` roots are deliberately
+ * not scanned here: dsh's own `skill-filesystem` provider already exposes them
+ * through the same registry in the web profile. Kimi built-in Skills are
+ * shipped inside the CLI and cannot be read from a stable on-disk location, so
+ * the filesystem subset above is authoritative for the web menu. Note the
+ * shared {@link parseSkillFile} mirrors the agents-skill frontmatter
+ * (`name`/`description`/`whenToUse`/`disable-model-invocation`); Kimi's own
+ * `disableModelInvocation`/`type` fields are not translated, so a `type: flow`
+ * skill is surfaced as model-invocable.
+ *
+ * @module dsh-loop-engine/engine-kimi/skills
+ */
+import type { SkillCandidate, SkillDefinition, SkillLookupOptions, SkillProvider, SkillProviderControl } from '../skills.ts';
+/**
+ * Resolve the Kimi config directory, honoring the `KIMI_CODE_HOME` environment
+ * override and falling back to `~/.kimi-code`.
+ * @returns the absolute Kimi config directory.
+ */
+export declare function kimiAgentDir(): string;
+/**
+ * Skill provider that discovers context files and skills from Kimi's standard
+ * locations:
+ *   - project `AGENTS.md` files between the cwd and the git root — surfaced as
+ *     one `agents-md` skill;
+ *   - project `.kimi-code/skills/` and user `~/.kimi-code/skills/` — each
+ *     `SKILL.md` entry surfaced under its own name.
+ */
+export declare class KimiSkillProvider implements SkillProvider {
+    private readonly control;
+    readonly name = "kimi";
+    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;
+    /** Collect every skill in one skills directory, both kimi layouts. */
+    private collectSkillsDir;
+    /** One parsed skill as a ranked candidate. */
+    private skillCandidate;
+    /** Parse one SKILL.md file, or `undefined` when it is unreadable or invalid. */
+    private tryParse;
+}
+export default KimiSkillProvider;
+//# sourceMappingURL=skills.d.ts.map

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

@@ -0,0 +1,23 @@
+/**
+ * Public types of the Kimi Code loop driver. Types only — no runtime code.
+ *
+ * Kimi Code (`kimi`) has no host approval callback ("runs with the permissions
+ * of the user"), and its non-interactive `-p` surface already auto-approves tool
+ * calls. It also exposes no `--tools` pruning flag in `-p` mode, so there is no
+ * per-driver permission lever to pin. The driver therefore spawns the whole
+ * `kimi -p` child 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/types
+ */
+/** Driver configuration after defaults and load-time validation. */
+export interface ResolvedConfig {
+    /** Model alias the `kimi` child is launched with (`--model`); Kimi native config owns the model when omitted. */
+    readonly model: string | undefined;
+    /** Explicit environment entries layered over the credential-scrubbed parent environment. */
+    readonly env: Record<string, string>;
+    /** Kimi CLI executable; `'kimi'` resolves through PATH when not pinned to an absolute path. */
+    readonly bin: string;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -17,6 +17,8 @@ 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 PiSpawnCapability } from './rpc/client.ts';
+/** Provider route label used for logged header snapshots and message provenance. */
+export declare const PROVIDER = "pi";
 /** Drives one session through turn and step boundaries on Pi. */
 export declare class PiAgent implements Agent {
     private loopCtx;

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

@@ -77,12 +77,34 @@ export declare class PiLoop extends Service implements AgentFactory {
     private setupAndPublish;
     /**
      * Create an agent and session under one caller-supplied identity, owned by
-     * the accessing fiber.
+     * 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, 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.
@@ -90,7 +112,7 @@ export declare class PiLoop extends Service implements AgentFactory {
      * @returns the published handle.
      */
     resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>;
-    /** Resume through an explicit persistence handle. */
+    /** Resume through an explicit persistence service. */
     private resumeWith;
 }
 //# sourceMappingURL=loop.d.ts.map

package/lib/types/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * Web-switchable agent loop engine, node half.
  *
- * Hosts the non-default agent-loop engines (Claude Code, Codex) and
- * bridges them with the harness's single AgentFactory slot. The engine is
+ * Hosts the non-default agent-loop engines (Claude Code, Codex, Pi, Kimi Code)
+ * and bridges them with the harness's single AgentFactory slot. The engine is
  * selected by the `agent-loop-engine` settings section; the selection is
  * realized by a managed block in the profile's `cordis.patch.yml` that
  * disables the base bundle's `agent-loop` row — exactly one AgentFactory may
@@ -17,6 +17,22 @@
  * The settings section is seeded from the block so the UI mirrors the file,
  * and a committed settings change writes the block (only when it differs).
  *
+ * A hosted engine also takes over the session's command and skill surface:
+ * the block disables dsh's `command-goal` row, and the plugin authors a
+ * stripped copy of the `standard` agent preset into the user preset root
+ * (see `preset.ts`) and steers the `agent-presets` roster default to it, so
+ * new sessions get the engine's commands and skills instead of the dsh-native
+ * ones an external engine cannot honor. Switching back to `in-process`
+ * restores the previous default.
+ *
+ * While a hosted engine is mounted the plugin also serves its provider route
+ * label (`claude-code` / `codex` / `pi` / `kimi`) from the llm registry with
+ * a model-less placeholder adapter (see `provider-route.ts`): the engine logs
+ * that label into each session's request/header, and the web host refuses a
+ * turn whose session selection names a provider no adapter serves — without
+ * the placeholder the second prompt of every hosted session would fail with
+ * `model-unavailable`.
+ *
  * @module dsh-loop-engine
  */
 import { Context } from '@deepseek-ai/cordis';
@@ -50,6 +66,8 @@ export interface Config extends ClaudeCodeConfig {
     piProvider?: string;
     /** Thinking/reasoning level for the Pi RPC child, appended to its `--model`. */
     piThinking?: string;
+    /** Kimi CLI executable; `'kimi'` resolves through PATH when not pinned to an absolute path. */
+    kimiBin?: string;
 }
 /**
  * Schema of the loop engine composition entry.

package/lib/types/patch-manager.d.ts

@@ -12,8 +12,17 @@
  *   # -- dsh-loop-engine managed block: claude-code --
  *   - id: agent-loop
  *     disabled: true
+ *   - id: command-goal
+ *     disabled: true
  *   # -- /dsh-loop-engine managed block --
  *
+ * The `command-goal` row goes down with the loop: a hosted engine owns the
+ * session's command surface, and dsh's `/goal` would otherwise collide with
+ * an engine's own goal command (Kimi) or dangle over a goal service nothing
+ * drives (the other engines). The remaining dsh-native commands (`/export`,
+ * `/feedback`, `/permission`) are engine-agnostic session/settings controls
+ * that keep working under a hosted engine, so they stay.
+ *
  * `in-process` renders an absent block (the base bundle's `agent-loop` row
  * stays active and supplies the factory), so switching back removes the span
  * entirely. Any other engine renders the same disable block, and the begin

package/lib/types/preset.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Hosted-engine agent preset: a managed copy of the deployment's `standard`
+ * preset with the dsh-native command and skill rows stripped.
+ *
+ * A hosted engine (Claude Code, Codex, Pi, Kimi) owns its session's command
+ * and skill surface: the engine's own slash commands and skill providers are
+ * registered globally by the plugin, and the dsh-native equivalents would only
+ * duplicate or mislead — dsh `/plan` is advisory prompt text an external
+ * engine never assembles, dsh `/compact` cannot shrink a context the engine's
+ * child process holds, and dsh skills would sit next to the engine's own
+ * catalog. Those rows live inside the agent-preset composition, which a
+ * profile patch cannot reach, so the plugin authors a stripped preset into the
+ * user preset root (`$DSH_HOME/.agent-presets/<id>`) and steers the roster's
+ * default at runtime (see the plugin's apply).
+ *
+ * The preset is REGENERATED from the current `standard` composition on every
+ * boot that needs it: text on disk is never authoritative, so a harness
+ * upgrade that changes `standard` flows through. The file is plain YAML the
+ * loader already accepts — the strip is a line transform that preserves
+ * everything it does not drop byte for byte, comments included.
+ *
+ * @module dsh-loop-engine/preset
+ */
+/** Preset id the plugin authors into the user preset root. */
+export declare const HOSTED_PRESET_ID = "loop-engine";
+/** Harness-home-relative directory of locally authored presets (mirrors `USER_PRESET_DIR` in `dsh-agent-presets`). */
+export declare const USER_PRESET_DIR = ".agent-presets";
+/** The composition file that makes a directory a preset. */
+export declare const COMPOSITION_FILE = "agent.cordis.yml";
+/** The display-metadata file beside a preset's composition. */
+export declare const METADATA_FILE = "preset.yml";
+/** Source preset the hosted preset derives from. */
+export declare const SOURCE_PRESET_ID = "standard";
+/**
+ * Top-level rows stripped from the source preset for hosted engines:
+ * - `skill-filesystem` / `tool-skill`: the dsh skill surface — each engine
+ *   registers its own skill provider globally;
+ * - `tool-goal`: the model-facing goal tool — the managed block already
+ *   disables dsh's `/goal` command for hosted engines;
+ * - `planning`: dsh plan mode — its only model-visible effect is a system
+ *   prompt section an external engine never assembles;
+ * - `compaction`: dsh `/compact` and auto-compaction — a hosted engine owns
+ *   its context and its own `/compact` (Claude, Kimi).
+ */
+export declare const STRIPPED_ROWS: readonly ["skill-filesystem", "tool-skill", "tool-goal", "planning", "compaction"];
+/**
+ * Remove top-level entries by id from a preset composition, preserving every
+ * other byte. Each entry owns the comment/blank run directly above its opener
+ * — that run is the entry's section heading and drops with it — except the
+ * run above the FIRST entry, which is the file header and stays. Entries
+ * without an `id` opener are always kept: the transform touches only what it
+ * can name.
+ * @param text - the source composition.
+ * @param ids - top-level row ids to strip.
+ * @returns the stripped composition.
+ */
+export declare function stripPresetRows(text: string, ids?: readonly string[]): string;
+/** Minimal read seam over the host's preset roster (`AgentPresets.read`). */
+export interface PresetCompositionSource {
+    /** Read one preset's composition text; throws when the id is unknown. */
+    read(id: string): Promise<string>;
+}
+/**
+ * Regenerate the hosted-engine preset under the dsh home's user preset root
+ * from the roster's `standard` preset. Idempotent: an up-to-date directory is
+ * untouched, so no standing mount sees a spurious file-stamp change.
+ * @param dshHome - the resolved harness home.
+ * @param source - the roster's composition reader.
+ * @returns whether any file was written.
+ * @throws when the source preset cannot be read or the writes fail.
+ */
+export declare function ensureHostedPreset(dshHome: string, source: PresetCompositionSource): Promise<boolean>;
+//# sourceMappingURL=preset.d.ts.map

package/lib/types/provider-route.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Hosted-engine provider route placeholders.
+ *
+ * Every hosted engine logs its sessions' request/header with its own provider
+ * label (`claude-code`, `codex`, `pi`, `kimi`) rather than a model endpoint the
+ * harness llm registry serves — the engine owns its model natively. The web
+ * host derives a session's model selection from that header and refuses a turn
+ * whose provider no registered adapter serves, so without a placeholder route
+ * the SECOND prompt of every hosted session fails with `model-unavailable`.
+ * The placeholder serves the label while advertising no models; catalog groups
+ * that advertise nothing are dropped, so the model picker is unchanged.
+ *
+ * @module dsh-loop-engine/provider-route
+ */
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm';
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { LoopEngineId } from './settings.ts';
+/** Provider route label each hosted engine logs into its sessions' request/header. */
+export declare const HOSTED_PROVIDER_ROUTES: Readonly<Record<Exclude<LoopEngineId, 'in-process'>, string>>;
+/**
+ * Placeholder adapter serving one hosted engine's provider route label. It
+ * inherits the empty catalog and default metadata (the engine's model is not a
+ * harness-selectable endpoint), and {@link stream} fails loud: a call reaching
+ * it means a real model query was routed to an engine that owns its model
+ * natively — a wiring bug, not a request to serve.
+ */
+export declare class HostedEngineRouteAdapter extends LlmAdapter {
+    private readonly label;
+    /**
+     * @param label - the provider route label this placeholder serves.
+     */
+    constructor(label: string);
+    stream(_options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+//# sourceMappingURL=provider-route.d.ts.map

package/lib/types/settings.d.ts

@@ -2,10 +2,10 @@
  * Shared loop-engine identity, namespace, and schema.
  *
  * The namespace literal lives in the zero-import `./namespace.ts` so both
- * halves agree on the section name: the node half brands it through
- * `settingsNamespace()` (a runtime value), while the browser half imports the
- * same literal without pulling the host-side `dsh-settings` service into the
- * client bundle (cross-plugin value imports go through cordis services, and
+ * halves agree on the section name: the node half brands it as a
+ * `SettingsNamespace`, while the browser half imports the same literal
+ * without pulling the host-side `dsh-settings` service into the client
+ * bundle (cross-plugin value imports go through cordis services, and
  * `settings-scope.ts` follows the same discipline).
  *
  * @module dsh-loop-engine/settings
@@ -14,7 +14,7 @@ import z from '@deepseek-ai/schemastery';
 import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
 export { LOOP_ENGINE_SETTINGS_NAMESPACE_LITERAL } from './namespace.ts';
 /** The installed engine driving new Agent turns. */
-export declare const LOOP_ENGINE_IDS: readonly ["in-process", "claude-code", "codex", "pi"];
+export declare const LOOP_ENGINE_IDS: readonly ["in-process", "claude-code", "codex", "pi", "kimi"];
 /** Installed agent loop engine id. */
 export type LoopEngineId = (typeof LOOP_ENGINE_IDS)[number];
 /** Stored and composed loop engine selection. */
@@ -26,6 +26,6 @@ export interface LoopEngineSettings {
 }
 /** Schema of the loop engine settings section. */
 export declare const LOOP_ENGINE_SETTINGS_SCHEMA: z<LoopEngineSettings>;
-/** Brand the shared literal through the settings API on the node side. */
+/** The shared literal branded as a settings namespace on the node side. */
 export declare function loopEngineSettingsNamespace(): SettingsNamespace;
 //# sourceMappingURL=settings.d.ts.map