dsh-loop-engine 1.0.0-rc10

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

@@ -0,0 +1,235 @@
+/**
+ * Pi RPC protocol type definitions. A minimal subset of the upstream
+ * `pi --mode rpc` protocol, covering only what the driver needs: the commands
+ * it sends (`new_session`, `prompt`, `abort`, `get_session_stats`), the
+ * response envelope, and the streaming events it maps into the durable dsh
+ * session log. Types only — no runtime code.
+ *
+ * The protocol is strict LF (`\n`) JSONL: records are delimited only by a bare
+ * `\n` (a trailing `\r` is tolerated), and Unicode separators such as U+2028 /
+ * U+2029 are ordinary characters inside JSON strings — so a generic line reader
+ * that treats them as newlines is not compliant.
+ *
+ * @module dsh-loop-engine/engine-pi/rpc/types
+ */
+/** Optional per-command correlation id; echoed back on the response. */
+export interface PiCommandCorrelation {
+    readonly id?: number;
+}
+/** Start a fresh Pi session (the driver issues one per dsh step). */
+export interface PiNewSessionCommand extends PiCommandCorrelation {
+    readonly type: 'new_session';
+    readonly parentSession?: string;
+}
+/** Send a user prompt to the agent and begin streaming events. */
+export interface PiPromptCommand extends PiCommandCorrelation {
+    readonly type: 'prompt';
+    readonly message: string;
+    readonly images?: readonly PiImage[];
+    readonly streamingBehavior?: 'steer' | 'followUp';
+}
+/** Abort the current agent operation. */
+export interface PiAbortCommand extends PiCommandCorrelation {
+    readonly type: 'abort';
+}
+/** Query session stats (usage/cost fallback when a message carries none). */
+export interface PiGetSessionStatsCommand extends PiCommandCorrelation {
+    readonly type: 'get_session_stats';
+}
+/** Every command the client can send. */
+export type PiCommand = PiNewSessionCommand | PiPromptCommand | PiAbortCommand | PiGetSessionStatsCommand;
+/** Message attachment (images) accepted by `prompt`. */
+export interface PiImage {
+    readonly type: 'image';
+    readonly data: string;
+    readonly mimeType: string;
+}
+/** Successful or failed command response. */
+export interface PiResponse {
+    readonly type: 'response';
+    readonly command?: string;
+    readonly success: boolean;
+    readonly error?: string;
+    readonly id?: number;
+    readonly data?: unknown;
+}
+/** Session statistics returned by `get_session_stats`. */
+export interface PiSessionStats {
+    readonly tokens?: {
+        readonly input?: number;
+        readonly output?: number;
+        readonly cacheRead?: number;
+        readonly cacheWrite?: number;
+        readonly total?: number;
+    };
+    readonly contextUsage?: {
+        readonly tokens?: number | null;
+        readonly contextWindow?: number;
+        readonly percent?: number | null;
+    };
+}
+/** Provider-reported token usage attached to messages and updates. */
+export interface PiUsage {
+    readonly input?: number;
+    readonly output?: number;
+    readonly cacheRead?: number;
+    readonly cacheWrite?: number;
+    readonly totalTokens?: number;
+}
+/** A content block of a Pi message. */
+export type PiContent = {
+    readonly type: 'text';
+    readonly text: string;
+} | {
+    readonly type: 'thinking';
+    readonly thinking: string;
+} | {
+    readonly type: 'toolCall';
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: unknown;
+};
+/** One role-tagged Pi message. */
+export interface PiMessage {
+    readonly role: 'user' | 'assistant' | 'toolResult' | 'system';
+    readonly content: string | readonly PiContent[];
+    readonly usage?: PiUsage;
+    readonly isError?: boolean;
+    readonly toolCallId?: string;
+    readonly toolName?: string;
+    readonly timestamp?: number;
+    readonly id?: string;
+}
+/** A tool result as carried by `turn_end.toolResults`. */
+export interface PiToolResult {
+    readonly role: 'toolResult';
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly content: readonly PiContent[];
+    readonly isError?: boolean;
+    readonly usage?: PiUsage;
+}
+/** The `assistantMessageEvent` delta union of `message_update`. */
+export type PiAssistantMessageEvent = {
+    readonly type: 'text_start';
+    readonly contentIndex: number;
+} | {
+    readonly type: 'text_delta';
+    readonly contentIndex: number;
+    readonly delta: string;
+} | {
+    readonly type: 'text_end';
+    readonly contentIndex: number;
+    readonly content?: string;
+} | {
+    readonly type: 'thinking_start';
+    readonly contentIndex: number;
+} | {
+    readonly type: 'thinking_delta';
+    readonly contentIndex: number;
+    readonly delta: string;
+} | {
+    readonly type: 'thinking_end';
+    readonly contentIndex: number;
+    readonly thinking?: string;
+} | {
+    readonly type: 'toolcall_start';
+    readonly contentIndex: number;
+    readonly id: string;
+    readonly toolName: string;
+} | {
+    readonly type: 'toolcall_delta';
+    readonly contentIndex: number;
+    readonly delta: string;
+} | {
+    readonly type: 'toolcall_end';
+    readonly contentIndex: number;
+    readonly toolCall: {
+        readonly id: string;
+        readonly name: string;
+        readonly arguments: unknown;
+    };
+};
+/** An `extension_ui_request` (dialog or fire-and-forget). */
+export interface PiExtensionUiRequest {
+    readonly type: 'extension_ui_request';
+    readonly id: string;
+    readonly method: 'select' | 'confirm' | 'input' | 'editor' | 'notify' | 'setStatus' | 'setWidget' | 'setTitle' | 'set_editor_text';
+    readonly title?: string;
+    readonly options?: readonly string[];
+    readonly message?: string;
+    readonly [key: string]: unknown;
+}
+/** A tool-execution event (start / update / end). */
+export type PiToolExecutionEvent = {
+    readonly type: 'tool_execution_start';
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly args: unknown;
+} | {
+    readonly type: 'tool_execution_update';
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly args: unknown;
+    readonly partialResult: unknown;
+} | {
+    readonly type: 'tool_execution_end';
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly result: unknown;
+    readonly isError: boolean;
+};
+/** Every agent event the driver consumes or ignores. */
+export type PiEvent = {
+    readonly type: 'response';
+} & PiResponse | {
+    readonly type: 'agent_start';
+} | {
+    readonly type: 'agent_end';
+    readonly messages?: readonly PiMessage[];
+    readonly willRetry?: boolean;
+} | {
+    readonly type: 'agent_settled';
+} | {
+    readonly type: 'turn_start';
+} | {
+    readonly type: 'turn_end';
+    readonly message?: PiMessage;
+    readonly toolResults?: readonly PiToolResult[];
+} | {
+    readonly type: 'message_start';
+    readonly message: PiMessage;
+} | {
+    readonly type: 'message_update';
+    readonly usage?: PiUsage;
+    readonly assistantMessageEvent: PiAssistantMessageEvent;
+} | {
+    readonly type: 'message_end';
+    readonly message: PiMessage;
+} | PiToolExecutionEvent | {
+    readonly type: 'compaction_start';
+    readonly reason?: string;
+} | {
+    readonly type: 'compaction_end';
+    readonly reason?: string;
+    readonly aborted?: boolean;
+    readonly willRetry?: boolean;
+    readonly result?: unknown;
+} | {
+    readonly type: 'auto_retry_start';
+    readonly attempt?: number;
+} | {
+    readonly type: 'auto_retry_end';
+    readonly success?: boolean;
+    readonly attempt?: number;
+    readonly finalError?: string;
+} | {
+    readonly type: 'queue_update';
+    readonly steering?: readonly string[];
+    readonly followUp?: readonly string[];
+} | {
+    readonly type: 'bash_execution_update';
+    readonly id?: string;
+    readonly delta?: string;
+} | PiExtensionUiRequest;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,55 @@
+/**
+ * Pi skill provider: exposes the Pi CLI's instruction files and skills as DSH
+ * skills.
+ *
+ * Pi reads per-directory context files (`AGENTS.md`, or `CLAUDE.md`,
+ * preferring `AGENTS.override.md` where one exists) from the session cwd up to
+ * the git root, plus a global `AGENTS.md` under the pi config directory
+ * (`PI_CODING_AGENT_DIR` or `~/.pi/agent`), and installs skills from
+ * `skills/` directories (`~/.pi/agent/skills/` and project `.pi/skills/`
+ * walking up). 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.
+ *
+ * `.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. Pi settings/CLI/package skills are only discoverable
+ * through a running `pi --mode rpc` probe, which the engine does not perform
+ * at composition time — the filesystem subset above is authoritative for the
+ * web menu.
+ *
+ * @module dsh-loop-engine/engine-pi/skills
+ */
+import type { SkillCandidate, SkillDefinition, SkillLookupOptions, SkillProvider, SkillProviderControl } from '../skills.ts';
+/**
+ * Resolve the pi config directory, honoring the `PI_CODING_AGENT_DIR`
+ * environment override and falling back to `~/.pi/agent`.
+ * @returns the absolute pi config directory.
+ */
+export declare function piAgentDir(): string;
+/**
+ * Skill provider that discovers context files and skills from pi's standard
+ * locations:
+ *   - project context files between the cwd and the git root (plus
+ *     `~/.pi/agent/AGENTS.md`) — surfaced as one `agents-md` skill;
+ *   - project `.pi/skills/` and user `~/.pi/agent/skills/` — each `SKILL.md`
+ *     entry surfaced under its own name.
+ */
+export declare class PiSkillProvider implements SkillProvider {
+    private readonly control;
+    readonly name = "pi";
+    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 pi 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 PiSkillProvider;
+//# sourceMappingURL=skills.d.ts.map

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

@@ -0,0 +1,27 @@
+/**
+ * Public types of the Pi loop driver. Types only — no runtime code.
+ *
+ * Pi carries no native permission system ("runs with the permissions of the
+ * user"), so the declarative stance this driver resolves is a sandbox mode plus
+ * the tool set the process is allowed to use; the rest of the driver then
+ * either wraps the whole `pi --mode rpc` child in the dsh subprocess sandbox or
+ * prunes its `--tools` accordingly.
+ *
+ * @module dsh-loop-engine/engine-pi/types
+ */
+/** Pi sandbox stances the driver can resolve, mapped from the dsh session knobs. */
+export type PiSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** 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: PiSandboxMode | undefined;
+    /** LLM provider the `pi` RPC process is launched with (`--provider`). */
+    readonly provider: string | undefined;
+    /** Model pattern the `pi` RPC process is launched with (`--model`). */
+    readonly model: string | undefined;
+    /** Thinking/reasoning level for the model (`--model <id>:<level>` or set at runtime). */
+    readonly thinkingLevel: string | undefined;
+    /** Explicit environment entries layered over the credential-scrubbed parent environment. */
+    readonly env: Record<string, string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Web-switchable agent loop engine, node half.
+ *
+ * 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
+ * register, so a non-default engine owns the slot by disabling the base loop
+ * first, and `in-process` leaves the base row active (this plugin does NOT
+ * register its own factory then).
+ *
+ * The managed block is the ground truth the factory decision reads at boot:
+ * apply() reads the file synchronously, so a committed engine change takes
+ * effect on the next recomposition (restart); the config-only HMR watcher
+ * re-applies the patch file but cannot re-register an AgentFactory mid-run.
+ * 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';
+import z from '@deepseek-ai/schemastery';
+import { type Config as ClaudeCodeConfig } from './engine-claude/loop.ts';
+import type { CodexApprovalPolicy, CodexSandboxMode } from './engine-codex/types.ts';
+import { type LoopEngineId } from './settings.ts';
+export declare const name = "loop-engine";
+/**
+ * Services the plugin's own fiber requires. The plugin declares none of its
+ * own: the optional host services it reads (`commands`, `skills`) are resolved
+ * lazily via `ctx.get` and may be absent, and the hosted engine factories
+ * (Claude Code / Codex) declare their own `inject` when the plugin mounts them
+ * as children. Empty keeps the plugin from demanding a service that a minimal
+ * profile does not provide.
+ */
+export declare const inject: never[];
+/** Composition entry for the loop engine selection and the hosted engine drivers. */
+export interface Config extends ClaudeCodeConfig {
+    /** Profile whose `cordis.patch.yml` carries the managed block; defaults to `web`. */
+    profile?: string;
+    /** Patch file name inside the profile; defaults to `cordis.patch.yml`. */
+    patchFilename?: string;
+    /** Explicit absolute path to the patch file, overriding profile + filename. */
+    patchPath?: string;
+    /** Pinned Codex sandbox mode; falls back to the session's dsh permission knobs. */
+    sandboxMode?: CodexSandboxMode;
+    /** Pinned Codex approval policy; falls back to the session's dsh permission knobs. */
+    approvalPolicy?: CodexApprovalPolicy;
+    /** LLM provider for the Pi RPC child (`--provider`). */
+    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.
+ *
+ * A schemastery object validates each field only when it is present and lets
+ * an absent key fall through as `undefined`, so omitted knobs are accepted —
+ * matching the permissive interface and read path (`resolvePatchPath` defaults
+ * the patch path; each engine driver resolves only the knobs it owns and
+ * omitted deployment tunables fall back to the session). The composition entry
+ * is an engine-agnostic superset: the selectable knobs belong to whichever
+ * engine the settings pick at runtime, so both engines' knobs may coexist and
+ * only the selected one is consumed.
+ */
+export declare const Config: z<Config>;
+/** Resolve the managed patch file from configuration, defaulting to the web profile. */
+export declare function resolvePatchPath(config: Config): string;
+/** Atomically replace the patch file (same-directory temp + rename). */
+export declare function writePatchFile(path: string, text: string): Promise<void>;
+/**
+ * Synchronously atomically replace the patch file. The engine-selection
+ * onChange is a synchronous hook with no await, and the write MUST land before
+ * the caller is told the switch committed — otherwise a user who restarts
+ * `dsh web` immediately reads the stale file and the previous engine boots.
+ * @param path - the profile's patch file.
+ * @param text - the next file content.
+ */
+export declare function writePatchFileSync(path: string, text: string): void;
+/**
+ * Rewrite the managed block for a target engine, preserving the rest of the
+ * file byte for byte. Only writes when the file actually differs.
+ * @param path - the profile's patch file.
+ * @param engine - the target engine.
+ * @returns whether a write occurred.
+ */
+export declare function syncManagedBlock(path: string, engine: LoopEngineId): Promise<boolean>;
+/**
+ * Apply the plugin: seed the settings section from the managed block, host
+ * the non-default engine factory when the block says so, and translate
+ * committed engine changes into managed-block writes.
+ * @param ctx - the composing context.
+ * @param config - composition entry for the managed patch file.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Package-owned invariant companion for the loop engine selection.
+ *
+ * The plugin's owned relationship is the patch-manager round trip: rendering
+ * a managed block for an engine and reading it back must produce the same
+ * engine, and the `in-process` engine must render an absent block (so the base
+ * bundle's `agent-loop` row stays mounted). The companion asserts both against
+ * the pure transform, binding the writer's inverse to the reader directly.
+ *
+ * @module dsh-loop-engine/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "loop-engine-invariant";
+/** Services required before the companion can register. */
+export declare const inject: string[];
+/**
+ * Register the loop-engine invariant contribution.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/namespace.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Loop engine namespace literal: the one string both halves agree on, in a
+ * module with no runtime imports so the browser bundle can import it without
+ * dragging `dsh-settings` (a host-side service) into the client artifact.
+ * @module dsh-loop-engine/namespace
+ */
+/** Settings namespace carrying the deployment's selected agent loop engine. */
+export declare const LOOP_ENGINE_SETTINGS_NAMESPACE_LITERAL = "agent-loop-engine";
+//# sourceMappingURL=namespace.d.ts.map

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

@@ -0,0 +1,59 @@
+/**
+ * Managed-block editing for a profile's `cordis.patch.yml`.
+ *
+ * The plugin owns one contiguous block inside the user's patch file, delimited
+ * by a begin/end marker pair, and rewrites only that span on engine switches
+ * — everything else the user wrote (other patches, their comments) survives
+ * byte for byte. The block's content is the loader patch that takes the loop
+ * engine over: it disables the base bundle's `agent-loop` row so this plugin's
+ * factory (hosted by dsh-loop-engine) can register without colliding, because
+ * the harness admits exactly one AgentFactory:
+ *
+ *   # -- 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
+ * marker carries the specific engine id (`# -- dsh-loop-engine managed block:
+ * claude-code --`) so `currentEngineOf` can read which non-default engine owns
+ * the slot from the file alone. All functions here are pure string transforms —
+ * file I/O and durability live in the plugin's apply.
+ *
+ * @module dsh-loop-engine/patch-manager
+ */
+import type { LoopEngineId } from './settings.ts';
+/** Begin marker of the plugin-managed span inside a profile patch file. */
+export declare const MANAGED_BLOCK_BEGIN = "# -- dsh-loop-engine managed block: ";
+/** End marker of the plugin-managed span inside a profile patch file. */
+export declare const MANAGED_BLOCK_END = "# -- /dsh-loop-engine managed block --";
+/** Render the managed block for one engine; `in-process` returns the empty span. */
+export declare function renderManagedBlock(engine: LoopEngineId): string;
+/** Whether a patch-file text contains the managed block span. */
+export declare function hasManagedBlock(text: string): boolean;
+/** Derive the current engine from a patch-file text by the managed block's begin marker. */
+export declare function currentEngineOf(text: string): LoopEngineId;
+/**
+ * Produce the next patch-file text for a target engine, preserving every byte
+ * outside the managed span. Appends the span when absent; replaces or removes
+ * it when present. The managed block is a root-level collection, so a leftover
+ * seed `[]` is dropped when adding it, and a removal that leaves no entries is
+ * re-seeded back to `[]` — either way the file stays a single valid top-level
+ * array the harness can boot.
+ * @param text - current patch-file text.
+ * @param engine - target engine.
+ * @returns the rewritten patch-file text.
+ */
+export declare function applyManagedBlock(text: string, engine: LoopEngineId): string;
+//# sourceMappingURL=patch-manager.d.ts.map

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,49 @@
+/**
+ * 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, LlmModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { LoopEngineId } from './settings.ts';
+import type { PiModelEntry } from './engine-pi/probe.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>>;
+/** Injectable catalog source a hosted engine route can advertise over the placeholder. */
+export interface HostedEngineRouteAdapterOptions {
+    /**
+     * Optional model catalog generator. When present, `listModels` advertises
+     * these entries under this route's provider label; when absent, the catalog
+     * stays empty (the default, "engine owns its models" behavior).
+     */
+    readonly listModels?: () => readonly PiModelEntry[];
+}
+/**
+ * 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;
+    private readonly options;
+    /**
+     * @param label - the provider route label this placeholder serves.
+     * @param options - optional catalog source; omit for an empty catalog.
+     */
+    constructor(label: string, options?: HostedEngineRouteAdapterOptions);
+    /** Advertise the injected Pi models (if any) under this route's provider label. */
+    listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+    stream(_options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+//# sourceMappingURL=provider-route.d.ts.map