@vidge/dsh-agent-hub 0.1.0-rc1

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-agent-hub/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-agent-hub/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-agent-hub/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/engine-record.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Durable per-session engine records.
+ *
+ * A session's engine must survive the process, because resuming a session on
+ * a different engine replays history that engine cannot act on. The harness
+ * offers no writable durable slot for this:
+ *
+ *  - `SessionHeader.agentPreset` is owned by the agent-presets subsystem — the
+ *    web controller writes it through `composeAgent()` and asserts it unchanged
+ *    on resume — and `SessionHeader` has no free-form dict (its fields are
+ *    closed at two `meta` literals and the SQLite column list).
+ *  - A custom session event is worse than unavailable: the persistence
+ *    coordinator refuses to load any log carrying a type outside the generated
+ *    `KNOWN_SESSION_EVENT_TYPES` unless the envelope sets `ignorable`, which
+ *    `Session.append()` provides no way to do. An out-of-repo event would make
+ *    every session this plugin wrote permanently unloadable.
+ *
+ * So the record lives in a plugin-owned sidecar keyed by session id, written
+ * with the same atomic temp+rename discipline as the managed patch file.
+ *
+ * @module dsh-agent-hub/engine-record
+ */
+import { type LoopEngineId } from './settings.ts';
+/** Backend-owned artifact location, as returned by `sessionPersistence.locate`. */
+export interface SessionLocation {
+    readonly kind: string;
+    readonly path: string;
+}
+/**
+ * The session metadata `locate` reads to derive an artifact path.
+ *
+ * `cwd` is NOT optional decoration: the JSONL backend groups sessions into a
+ * per-project directory keyed by it (`projectDir(root, cwd)`), and an
+ * `undefined` cwd selects the literal `_no-cwd` bucket. Passing only `id`
+ * therefore returns a path in a directory the session does not live in — the
+ * sidecar is written where nothing will ever read it, and every resume falls
+ * through to the `in-process` default.
+ */
+export interface SessionMetaLike {
+    readonly id: string;
+    readonly cwd?: string;
+}
+/**
+ * The persistence surface the record store borrows. Declared structurally so
+ * this module needs no peer dependency on the persistence package, and so a
+ * profile without persistence degrades to the shared fallback directory.
+ */
+export interface RecordPersistence {
+    locate(meta: SessionMetaLike): SessionLocation | undefined;
+    inspect(id: string, signal?: AbortSignal): Promise<{
+        meta: SessionMetaLike;
+    }>;
+}
+/** Fallback directory for backends with no per-session artifact (e.g. SQLite). */
+export declare function fallbackDir(): string;
+/** The fallback record path for one session id. */
+export declare function fallbackPathFor(sessionId: string): string;
+/**
+ * Reads and writes the per-session engine record.
+ *
+ * The store prefers a sidecar beside the backend's own per-session artifact so
+ * the record travels with the session; backends that own no such artifact fall
+ * back to a shared directory under the dsh home.
+ */
+export declare class EngineRecordStore {
+    private readonly persistence;
+    constructor(persistence: () => RecordPersistence | undefined);
+    /**
+     * Resolve the record path for a session, preferring the backend's artifact
+     * directory. Uses `locate`, which explicitly does not read, create, or
+     * materialize the artifact.
+     *
+     * `cwd` must be supplied whenever it is known: it selects the backend's
+     * per-project directory, so omitting it silently addresses a different
+     * directory than the one holding the session.
+     */
+    private pathFor;
+    /**
+     * Record a session's engine. Called before the engine creates the session,
+     * so the record is never missing for a session that exists.
+     * @param meta - the session being created, including the `cwd` that keys its artifact directory.
+     * @param engine - the engine that will own it.
+     */
+    remember(meta: SessionMetaLike, engine: LoopEngineId): Promise<void>;
+    /**
+     * Recover a session's engine.
+     *
+     * The session's `cwd` is not known to the caller on the resume path — only
+     * its id — so the backend's own header is consulted first to rebuild the
+     * artifact path. A backend that cannot inspect (or a session it does not
+     * know) degrades to the shared fallback directory rather than failing the
+     * resume: a lost record costs the default engine, an exception costs the
+     * session.
+     *
+     * Sessions written before this plugin gained per-session routing carry no
+     * record; they ran on whichever engine was globally selected, and the base
+     * in-process loop is the only safe default — it is what an unpatched profile
+     * boots with.
+     * @param sessionId - the session being resumed.
+     * @returns the recorded engine, or `in-process` when no record exists.
+     */
+    recall(sessionId: string): Promise<LoopEngineId>;
+    /**
+     * Rebuild a session's sidecar path from the backend's stored header.
+     *
+     * `inspect` is the correct probe here rather than `prepare`: it is a
+     * non-exclusive borrow that returns a validated header and leaves the
+     * coordinator's reusable cold session in place for the real engine's
+     * subsequent `prepare`, whereas `prepare` would take the exclusive
+     * reservation out from under it.
+     *
+     * @param sessionId - the session whose artifact directory is wanted.
+     * @returns the sidecar path, or `undefined` when it cannot be derived.
+     */
+    private locateByInspect;
+    /**
+     * Drop fallback records whose session no longer resolves, bounded per run so
+     * a large history cannot stall startup. Sidecars beside a backend artifact
+     * need no sweep: the backend removes the directory with the session.
+     * @param limit - maximum number of records to examine.
+     */
+    collectOrphans(limit?: number): Promise<number>;
+}
+//# sourceMappingURL=engine-record.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Web-switchable agent loop engine, node half.
+ *
+ * Hosts every agent-loop engine (the base in-process loop, Claude Code, Codex,
+ * and Pi) and gives each session its own. The harness admits exactly one
+ * AgentFactory, so this plugin registers a {@link LoopEngineRouter} in that slot
+ * for the life of the process and mounts the four engines behind it through
+ * shadowed contexts that redirect their `setFactory` calls into router
+ * registration. The engine classes themselves are unmodified.
+ *
+ * A session's engine is fixed when it is created and recorded durably
+ * ({@link EngineRecordStore}), because resuming a session on a different engine
+ * would replay history that engine cannot act on — each engine writes its own
+ * provenance. The `agent-loop-engine` settings section therefore selects the
+ * engine for the *next new* session only; switching it never disturbs a running
+ * session and needs no restart.
+ *
+ * The managed block in the profile's `cordis.patch.yml` is now permanent and
+ * engine-independent: it disables the base bundle's `agent-loop` row so this
+ * plugin owns the slot in every configuration.
+ *
+ * @module dsh-agent-hub
+ */
+import { Context, type Fiber } 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.
+ *
+ * `agents` and `systemPrompt` are read directly by {@link apply}: the router
+ * claims the single AgentFactory slot on `ctx.agents`, and each engine mounts
+ * through a context that shadows both members. Cordis refuses a bare property
+ * read on an undeclared service ("cannot get property \"agents\" without
+ * inject"), so both must be listed — and listing them also makes the fiber wait
+ * for them rather than racing their providers.
+ *
+ * The optional host services (`commands`, `skills`) stay out: they are resolved
+ * lazily via `ctx.get` and may legitimately be absent from a minimal profile.
+ * The hosted engine factories declare their own `inject` when mounted as
+ * children.
+ */
+export declare const inject: string[];
+/** 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;
+}
+/**
+ * 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;
+/**
+ * Ensure the permanent managed block is present, preserving the rest of the
+ * file byte for byte. Only writes when the file actually differs.
+ * @param path - the profile's patch file.
+ * @returns whether a write occurred.
+ */
+export declare function syncManagedBlock(path: string): Promise<boolean>;
+/**
+ * Mount the base in-process loop behind the router.
+ *
+ * The plugin now owns the AgentFactory slot in every configuration, so the base
+ * loop can no longer register itself through the bundle — the managed block
+ * disables its row. It is instead hosted here, through the same shadowed
+ * context as the other engines, which keeps `in-process` a first-class
+ * per-session choice.
+ *
+ * The import is dynamic and failure-tolerant: the package is a peer, and a
+ * deployment that omits it should lose only the in-process engine rather than
+ * failing the whole plugin tree.
+ *
+ * @param ctx - the plugin context, used for diagnostics.
+ * @param loopCtx - the shadowed context that redirects `setFactory` to the router.
+ * @param mount - the shared fiber-start helper.
+ */
+export declare function mountBaseLoop(ctx: Context, loopCtx: Context, mount: (engine: LoopEngineId, plugin: () => (Fiber & PromiseLike<Fiber>)) => void): void;
+/**
+ * Register an engine's skill provider into ONE agent's own scope layer.
+ *
+ * The harness's skill registry is layered by `scopeOf(ctx)`, and every engine
+ * mints its agent as its own scope key then hands that scope-tagged context to
+ * `setup`. Registering through that context therefore makes the provider
+ * visible to exactly one session — a codex session never sees
+ * `~/.claude/skills/` — with no per-provider engine predicate, and the
+ * registration unwinds with the agent's scope.
+ *
+ * `in-process` contributes nothing: the base loop brings the harness's own
+ * skills, and this plugin adds no engine-specific ones for it.
+ *
+ * @param engine - the engine that owns the session being set up.
+ * @param agentCtx - the scope-tagged agent context the engine passes to `setup`.
+ */
+export declare function registerEngineSkills(engine: LoopEngineId, agentCtx: Context): void;
+/**
+ * Apply the plugin: own the AgentFactory slot with the router, mount every
+ * engine behind it, and track the selection for new sessions.
+ * @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 managed patch block.
+ *
+ * The plugin's owned relationship is that the managed block is a permanent
+ * fixed point: applying it is idempotent, it always yields the row that frees
+ * the AgentFactory slot for this plugin's router, and it upgrades a legacy
+ * engine-tagged block from the era when the block encoded the selection. The
+ * companion asserts these against the pure transform.
+ *
+ * @module dsh-agent-hub/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/llm-compat.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cross-version shim for the one dsh-llm export that was renamed mid-line.
+ *
+ * `dsh-llm` renamed its tool-call brand between the two published lines:
+ *
+ *   - `0.1.1-rc.2` (dist-tag `latest`, what plain `dsh` installs) exports `CallId`
+ *   - `0.1.2-alpha.2` (dist-tag `alpha`, the harness monorepo source) exports `ToolCallId`
+ *
+ * A named import of either one is a hard ESM link error against the other line
+ * ("does not provide an export named ..."), which fails the whole plugin tree at
+ * boot before any of our code runs. A namespace import is not checked per-member
+ * at link time, so it loads under both and we can pick the survivor at runtime.
+ *
+ * The brand type is deliberately derived from `ToolResultMessageInput['callId']`
+ * rather than hard-coded to either `Branded<'CallId'>` or `Branded<'ToolCallId'>`:
+ * the two lines brand with different literals, so only the installed package's
+ * own view of the type is assignable to the APIs we hand these values to.
+ *
+ * @module dsh-agent-hub/llm-compat
+ */
+import type { ToolResultMessageInput } from '@deepseek-ai/dsh-llm';
+/**
+ * The tool-call id brand, as the *installed* dsh-llm defines it. Aliased off a
+ * consuming API so it stays correct on both the `CallId` and `ToolCallId` lines.
+ */
+export type CallId = ToolResultMessageInput['callId'];
+/**
+ * Brand a raw string as a tool-call id, resolving to whichever name the
+ * installed dsh-llm publishes.
+ */
+export declare const CallId: (id: string) => CallId;
+//# sourceMappingURL=llm-compat.d.ts.map

package/lib/types/namespace.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Loop engine constants shared by both halves, in a module with no runtime
+ * imports so the browser bundle can import them without dragging
+ * `dsh-settings` (a host-side service) into the client artifact.
+ *
+ * That constraint is load-bearing, not stylistic: the browser bundle inlines
+ * non-seed specifiers (see `build.mjs`), so a value imported from
+ * `./settings.ts` — which imports `dsh-settings` — pulls the whole host-side
+ * settings module into the client build. Anything both halves need as a
+ * *value* belongs here; `./settings.ts` re-exports it for the node half.
+ * @module dsh-agent-hub/namespace
+ */
+/** Settings namespace carrying the deployment's selected agent loop engine. */
+export declare const LOOP_ENGINE_SETTINGS_NAMESPACE_LITERAL = "agent-loop-engine";
+/** The installed engines driving new Agent turns. */
+export declare const LOOP_ENGINE_IDS: readonly ["in-process", "claude-code", "codex", "pi"];
+/** Installed agent loop engine id. */
+export type LoopEngineId = (typeof LOOP_ENGINE_IDS)[number];
+//# sourceMappingURL=namespace.d.ts.map