dsh-loop-engine 1.0.0-rc2

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

@@ -0,0 +1,105 @@
+/**
+ * Strict-LF JSONL client for the Pi RPC subprocess (`pi --mode rpc`).
+ *
+ * The driver hands the client a process handle carrying its stdin/stdout/stderr
+ * (projected from the dsh subprocess seam, so the whole `pi` child is sandboxed
+ * by the harness). The client frames records on a bare `\n` only — not on
+ * Unicode separators — using a byte decoder, tolerates a trailing `\r`, and
+ * correlates command responses by the optional `id` field while dispatching
+ * every non-response line to a buffered event stream.
+ *
+ * @module dsh-loop-engine/engine-pi/rpc/client
+ */
+import type { ChildProcess } from 'node:child_process';
+import type { Readable, Writable } from 'node:stream';
+import type { PiCommand, PiEvent, PiResponse } from './types.ts';
+/** A spawned Pi RPC process as the protocol transport needs it. */
+export interface PiProcess {
+    /** Child stdin (command JSON lines). */
+    readonly stdin: Writable;
+    /** Child stdout (response + event JSON lines). */
+    readonly stdout: Readable;
+    /** Child stderr (diagnostics; buffered and dropped). */
+    readonly stderr: Readable;
+    /** Register a single human-readable termination callback. */
+    onExit(handler: () => void): void;
+    /** Request process-tree termination. */
+    terminate(): void;
+}
+/** The exact argv/cwd/env the driver requests for one `pi --mode rpc` child. */
+export interface PiSpawnSpec {
+    /** The program plus its flags; `argv[0]` is the Pi CLI entrypoint. */
+    readonly argv: readonly string[];
+    readonly cwd: string;
+    readonly env: Record<string, string>;
+}
+/** Spawns one Pi RPC process over the given spec (the driver's spawn capability). */
+export type PiSpawnCapability = (spec: PiSpawnSpec) => PiProcess;
+/** Callback receiving every non-response event line. */
+export type PiEventHandler = (event: PiEvent) => void;
+/** Options for one `prompt` command. */
+export interface PiPromptOptions {
+    readonly streamingBehavior?: 'steer' | 'followUp';
+}
+/** Project a `node:child_process` child onto the Pi protocol transport. */
+export declare function fromChildProcess(child: ChildProcess): PiProcess;
+/** Prompt the agent and stream its events. */
+export declare class PiRpcClient {
+    private readonly process;
+    private reqId;
+    private pending;
+    private readonly eventBuffer;
+    private eventWake;
+    private eventHandler;
+    private disposed;
+    private readonly decoder;
+    private buffer;
+    private readonly onStderr;
+    /** Whether this client was disposed or its process exited. */
+    get closed(): boolean;
+    /** Mount a client over an already-spawned Pi RPC process. */
+    constructor(process: PiProcess);
+    /**
+     * Create a client, spawning the Pi RPC child through the supplied capability
+     * (or the default node-runtime spawn when none is given).
+     * @param spec - the Pi CLI argv/cwd/env the child should run with.
+     * @param spawn - optional process-spawn capability (the subprocess seam);
+     *   absent falls back to the plain node child spawn.
+     * @returns the connected client.
+     */
+    static create(spec: PiSpawnSpec, spawn?: PiSpawnCapability): PiRpcClient;
+    /** Register the event dispatch handler. */
+    onEvent(handler: PiEventHandler): void;
+    /** Drop any events still buffered from a previous step (stateless per-step sessions). */
+    clearEvents(): void;
+    /** Start a fresh Pi session. */
+    newSession(): Promise<PiResponse>;
+    /** Prompt the agent and await the acceptance response. */
+    prompt(message: string, options?: PiPromptOptions): Promise<PiResponse>;
+    /** Abort the current agent operation. */
+    abort(): Promise<PiResponse>;
+    /** Query session stats. */
+    getSessionStats(): Promise<PiResponse>;
+    /** Send a command without awaiting its response (fire-and-forget). */
+    send(command: PiCommand): void;
+    /**
+     * Send a command and await the correlated response. Assigns a fresh `id`
+     * when the command carries none, so responses always round-trip.
+     */
+    request(command: PiCommand): Promise<PiResponse>;
+    /**
+     * Consume every buffered event as an async generator, waking as fresh lines
+     * arrive. The caller bounds the iteration by a terminal event; unmatched
+     * lines stay buffered for a later iteration.
+     */
+    events(): AsyncGenerator<PiEvent, void, void>;
+    /** Dispose the client and request child termination. */
+    dispose(): void;
+    /** Feed one chunk of stdout into the framing state machine. */
+    private feed;
+    /** Dispatch one parsed line to the pending map or the event queue. */
+    private dispatch;
+    /** Drain decoded stderr bytes (no-op consumer keeps the pipe flowing). */
+    private consumeStderr;
+}
+//# sourceMappingURL=client.d.ts.map

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

@@ -0,0 +1,37 @@
+/**
+ * Maps Pi RPC messages and end-of-execution events to dsh session-log events.
+ * Token-level streaming deltas are folded inline by the driver's step loop
+ * (they carry live progress); this module projects the end-state items — a
+ * completed tool call, a completed tool execution, and a finished turn's usage
+ * — into the durable `tool/call`, `tool/result`, and usage events.
+ *
+ * @module dsh-loop-engine/engine-pi/rpc/mapping
+ */
+import type { TokenUsage, ToolResultMessage } from '@deepseek-ai/dsh-llm';
+import type { PiUsage } from './types.ts';
+/** Map one Pi usage snapshot to dsh TokenUsage. */
+export declare function mapUsage(usage: PiUsage): TokenUsage;
+/**
+ * Derive the compact transcript text of a Pi content block, joining nested
+ * text segments so the durable tool-result block carries the read model text.
+ * @param content - the result payload (e.g. `{ content: [{ type, text }, ...] }`).
+ * @returns the joined text.
+ */
+export declare function resultText(content: unknown): string;
+/** Map a completed Pi tool-execution end event to the durable tool/result message. */
+export declare function mapToolResult(ev: {
+    toolCallId: string;
+    result: unknown;
+    isError: boolean;
+}): ToolResultMessage;
+/** Map the identity of a Pi message tool call or execution start to a durable tool/call. */
+export declare function mapToolCall(ev: {
+    callId: string;
+    name: string;
+    arguments: unknown;
+}): {
+    callId: string;
+    name: string;
+    arguments: string;
+};
+//# sourceMappingURL=mapping.d.ts.map

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,26 @@
+/**
+ * Pi skill provider: exposes the Pi CLI's instruction files as DSH skills.
+ * Pi reads project and user instruction files named `AGENTS.md` (like codex),
+ * and its own tool rules live under `.pi/`. Each found `AGENTS.md` is surfaced
+ * as a single user-invocable skill whose content is the file body, so the dsh
+ * skill-injection seam (`/name` gestures) can carry it into the prompt — the
+ * same bridge the codex driver exposes.
+ *
+ * @module dsh-loop-engine/engine-pi/skills
+ */
+import { type SkillCandidate, type SkillDefinition, type SkillLookupOptions, type SkillProvider, type SkillProviderControl } from '../skills.ts';
+/**
+ * Skill provider that discovers `AGENTS.md` from the project root (git root
+ * when one exists) and the user home `~/.pi/AGENTS.md`.
+ */
+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>;
+    /** Read one AGENTS.md file and push a candidate when it exists. */
+    private collectAgentsMd;
+}
+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,96 @@
+/**
+ * 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
+ * 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).
+ *
+ * @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;
+}
+/**
+ * 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,47 @@
+/**
+ * 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
+ *   # -- /dsh-loop-engine managed block --
+ *
+ * `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.
+ * @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/settings.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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
+ * `settings-scope.ts` follows the same discipline).
+ *
+ * @module dsh-loop-engine/settings
+ */
+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"];
+/** Installed agent loop engine id. */
+export type LoopEngineId = (typeof LOOP_ENGINE_IDS)[number];
+/** Stored and composed loop engine selection. */
+export interface LoopEngineSettings {
+    /** The engine future Agents are created on. */
+    engine: LoopEngineId;
+}
+/** 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. */
+export declare function loopEngineSettingsNamespace(): SettingsNamespace;
+//# sourceMappingURL=settings.d.ts.map