dsh-loop-engine 1.0.0-rc10

package/lib/invariant.js

@@ -0,0 +1,108 @@
+// src/settings.ts
+import z from "@deepseek-ai/schemastery";
+var LOOP_ENGINE_IDS = ["in-process", "claude-code", "codex", "pi", "kimi"];
+var LOOP_ENGINE_SETTINGS_SCHEMA = z.object({
+  engine: z.union([z.const("in-process"), z.const("claude-code"), z.const("codex"), z.const("pi"), z.const("kimi")]).default("in-process"),
+  showInComposer: z.boolean().default(true)
+});
+
+// src/patch-manager.ts
+var MANAGED_BLOCK_BEGIN = "# -- dsh-loop-engine managed block: ";
+var MANAGED_BLOCK_END = "# -- /dsh-loop-engine managed block --";
+var END_MARKER_LINE = `${MANAGED_BLOCK_END}
+`;
+function renderManagedBlock(engine) {
+  if (engine === "in-process") return "";
+  return [
+    `${MANAGED_BLOCK_BEGIN}${engine} --`,
+    "- id: agent-loop",
+    "  disabled: true",
+    "- id: command-goal",
+    "  disabled: true",
+    END_MARKER_LINE
+  ].join("\n");
+}
+var BEGIN_MARKER_RE = /^# -- dsh-loop-engine managed block: (\S+) --$/m;
+function currentEngineOf(text) {
+  const engine = BEGIN_MARKER_RE.exec(text)?.[1];
+  return LOOP_ENGINE_IDS.includes(engine ?? "") ? engine : "in-process";
+}
+function managedSpan(text) {
+  const begin = text.indexOf(MANAGED_BLOCK_BEGIN);
+  if (begin === -1) return { head: text, tail: "", present: false, blankBefore: false };
+  const afterBegin = begin + MANAGED_BLOCK_BEGIN.length;
+  const endAt = text.indexOf(MANAGED_BLOCK_END, afterBegin);
+  const spanEnd = endAt === -1 ? text.length : endAt + END_MARKER_LINE.length;
+  const before = text.slice(0, begin);
+  const blankBefore = before.endsWith("\n\n");
+  return {
+    head: blankBefore ? before.slice(0, -1) : before,
+    tail: text.slice(spanEnd),
+    present: true,
+    blankBefore
+  };
+}
+function ensureTrailingNewline(text) {
+  return text.endsWith("\n") ? text : `${text}
+`;
+}
+function hasRootEntry(text) {
+  return /^(?:- |\[)/m.test(text);
+}
+function dropSeedPlaceholder(text) {
+  return text.replace(/^\[\]\n/m, "");
+}
+function seedEmptyArray(text) {
+  const head = text.replace(/\n+$/, "");
+  return head === "" ? "[]\n" : `${head}
+[]
+`;
+}
+function applyManagedBlock(text, engine) {
+  const block = renderManagedBlock(engine);
+  const span = managedSpan(text);
+  let result;
+  if (!span.present) {
+    if (block === "") {
+      result = text;
+    } else {
+      const base = ensureTrailingNewline(text);
+      result = `${base}
+${block}`;
+    }
+  } else if (block === "") {
+    result = span.tail.startsWith("\n") ? `${span.head}${span.tail.slice(1)}` : `${span.head}${span.tail}`;
+  } else {
+    result = `${span.head}${span.blankBefore ? "\n" : ""}${block}${span.tail}`;
+  }
+  if (block !== "") return dropSeedPlaceholder(result);
+  if (text.trim() === "") return result;
+  return hasRootEntry(result) ? result : seedEmptyArray(result);
+}
+
+// src/invariant.ts
+var PACKAGE_NAME = "dsh-loop-engine";
+var name = "loop-engine-invariant";
+var inject = ["invariants"];
+var install = (ctx, fail) => {
+  void ctx;
+  const seed = "";
+  const commentOnly = "# dsh profile patch layer\n";
+  for (const engine of LOOP_ENGINE_IDS) {
+    const applied = applyManagedBlock(seed, engine);
+    const reborn = applyManagedBlock(applied, currentEngineOf(applied));
+    if (reborn !== applied) fail(`bare round trip for ${engine} is not a fixed point`);
+    if (engine === "in-process" && applied !== seed) fail("in-process engine must leave a bare layer unchanged");
+    if (engine !== "in-process" && currentEngineOf(renderManagedBlock(engine)) !== engine) fail(`${engine} block must read back as the ${engine} engine`);
+    if (engine === "in-process" && applyManagedBlock(commentOnly, engine) === commentOnly) {
+      fail("in-process engine must re-seed a comment-only file to a loadable top-level array");
+    }
+  }
+};
+var apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+export {
+  apply,
+  inject,
+  name
+};
+//# sourceMappingURL=invariant.js.map

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

@@ -0,0 +1,34 @@
+/**
+ * Session header engine badge: a read-only chip naming the loop engine that
+ * drives this session. The engine is a deployment-level choice, so the chip
+ * reports the same value for every session — naming what sessions run is the
+ * honest affordance; the switch itself lives in the settings section.
+ *
+ * Styling is token-driven inline styles like the settings section (the
+ * client-module bundle is esbuild-built without a CSS loader).
+ * @module dsh-loop-engine/client/badge
+ */
+import type { JSX } from 'react';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { InjectFace } from '@deepseek-ai/dsh-client-ui-slots';
+import type { LoopEngineState } from './store.ts';
+import type { en } from './locales.ts';
+/** Registration-side business face for the header badge. */
+export interface LoopEngineBadgeInjected {
+    hooks: {
+        /** Engine snapshot bound by the renderer as useSnapshot. */
+        snapshot: SnapshotStore<LoopEngineState>;
+    };
+    /** Section copy bound to the engine dictionaries. */
+    t: (key: keyof typeof en) => string;
+}
+/** Props delivered by the slot outlet (the renderer erases the share boundary). */
+export type LoopEngineBadgeProps = Partial<InjectFace<LoopEngineBadgeInjected>>;
+/**
+ * Render the session header's loop-engine chip. Hides until the settings
+ * scope settles, so the header never flashes a provisional engine.
+ * @param props - composed slot props.
+ * @returns the chip, or null while the engine is unknown.
+ */
+export declare function LoopEngineBadge(props: LoopEngineBadgeProps): JSX.Element | null;
+//# sourceMappingURL=LoopEngineBadge.d.ts.map

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

@@ -0,0 +1,40 @@
+/**
+ * Composer loop-engine picker: a compact dropdown registered at the
+ * `conversation.input.right` seat, so it sits immediately left of the model
+ * select in the composer's tool row. The engine is a deployment-level choice,
+ * so this surface shares the same settings-backed {@link LoopEngineStore} as
+ * the settings section and the header badge — a change in any one is what the
+ * others show next. Switching still asks for confirmation first (it interrupts
+ * sessions still running on the previous engine) and reloads the page once the
+ * commit lands, matching the settings section's semantics.
+ *
+ * Styling is token-driven inline styles like the badge and section (the
+ * client-module bundle is esbuild-built without a CSS loader).
+ * @module dsh-loop-engine/client/composer
+ */
+import { type JSX } from 'react';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { InjectFace } from '@deepseek-ai/dsh-client-ui-slots';
+import type { LoopEngineStore, LoopEngineState } from './store.ts';
+import type { en } from './locales.ts';
+/** Injected dependencies of {@link LoopEngineComposerSelect} (slot `inject`). */
+export interface LoopEngineComposerSelectInjected {
+    /** The selection store (loaded on mount, refreshed by scope pushes). */
+    controller: LoopEngineStore;
+    hooks: {
+        /** Engine snapshot bound by the UI renderer as useSnapshot. */
+        snapshot: SnapshotStore<LoopEngineState>;
+    };
+    /** Composer copy bound to the loop engine dictionaries. */
+    t: (key: keyof typeof en) => string;
+}
+/** Props delivered by the slot outlet (the renderer erases the share boundary). */
+export type LoopEngineComposerSelectProps = Partial<InjectFace<LoopEngineComposerSelectInjected>>;
+/**
+ * Render the composer's loop-engine dropdown. Hides until the settings scope
+ * settles, so the composer never flashes a provisional engine.
+ * @param props - composed slot props.
+ * @returns the picker, or null while the engine is unknown.
+ */
+export declare function LoopEngineComposerSelect(props: LoopEngineComposerSelectProps): JSX.Element | null;
+//# sourceMappingURL=LoopEngineComposerSelect.d.ts.map

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

@@ -0,0 +1,34 @@
+/**
+ * Loop engine settings section component: one dropdown choosing the agent
+ * loop engine, backed by the duplicated settings scope through the inject face.
+ * Changing the engine asks for confirmation first, because the switch
+ * interrupts sessions still running on the previous engine.
+ *
+ * Styling is token-driven like the rest of the settings shell (`--dsw-*`
+ * aliases), with the picker rendered through the shared `Menu` primitive and
+ * the confirmation through `Modal`. The client-module bundle is esbuild-built
+ * without a CSS loader, so the section shell uses token-based inline styles
+ * instead of a CSS module.
+ * @module dsh-loop-engine/client
+ */
+import { type JSX } from 'react';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { InjectFace } from '@deepseek-ai/dsh-client-ui-slots';
+import type { LoopEngineStore, LoopEngineState } from './store.ts';
+import type { en } from './locales.ts';
+/** Injected dependencies of {@link LoopEngineSection} (slot `inject`). */
+export interface LoopEngineSectionInjected {
+    /** The selection store (loaded on mount, refreshed by scope pushes). */
+    controller: LoopEngineStore;
+    hooks: {
+        /** Section snapshot bound by the UI renderer as useSnapshot. */
+        snapshot: SnapshotStore<LoopEngineState>;
+    };
+    /** Section copy. */
+    t: (key: keyof typeof en) => string;
+}
+/** Props delivered by the slot outlet (the renderer erases the share boundary). */
+export type LoopEngineSectionProps = Partial<InjectFace<LoopEngineSectionInjected>>;
+/** Render the engine dropdown plus the interrupt notice and the switch confirmation. */
+export declare function LoopEngineSection(props: LoopEngineSectionProps): JSX.Element;
+//# sourceMappingURL=LoopEngineSection.d.ts.map

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

@@ -0,0 +1,29 @@
+/**
+ * Loop engine settings plugin, browser half. Registers the "Loop engine"
+ * page under the settings section slot once the settings shell declares it,
+ * binding one store to the duplicated `agent-loop-engine` settings scope.
+ * Export discipline: packages/client/AGENTS.md.
+ * @module dsh-loop-engine/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { type LoopEngineKey } from './locales.ts';
+export type { LoopEngineSectionInjected, LoopEngineSectionProps } from './LoopEngineSection.tsx';
+export type { LoopEngineBadgeInjected, LoopEngineBadgeProps } from './LoopEngineBadge.tsx';
+export type { LoopEngineComposerSelectInjected, LoopEngineComposerSelectProps } from './LoopEngineComposerSelect.tsx';
+export type { LoopEngineState } from './store.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The Loop engine settings page copy. */
+        'settings.loop-engine': LoopEngineKey;
+    }
+}
+/** Required services (cordis fiber inject). The target slot is declared by
+ * ui-settings' apply; registration depends on it through `slots.inject()`. */
+export declare const inject: string[];
+/**
+ * Register the Loop engine section once the `settings.section` declaration is
+ * on the ledger and bind its store to the duplicated settings scope.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,46 @@
+/**
+ * Loop engine settings page copy (Chinese product copy; comments in English).
+ * @module dsh-loop-engine/client/locales
+ */
+/** Copy keys of the loop engine settings page. */
+export interface LoopEngineKey {
+    /** Settings navigation label. */
+    nav: string;
+    /** Panel description under the title. */
+    description: string;
+    /** Option label: the default in-process loop driver. */
+    engineInProcess: string;
+    /** Option label: the Claude Code CLI driver. */
+    engineClaudeCode: string;
+    /** Option label: the Codex CLI driver. */
+    engineCodex: string;
+    /** Option label: the Pi CLI driver. */
+    enginePi: string;
+    /** Option label: the Kimi Code CLI driver. */
+    engineKimi: string;
+    /** Settings toggle: show the engine picker in the chat page composer. */
+    showInComposerLabel: string;
+    /** Unavailable-state message. */
+    unavailable: string;
+    /** Notice shown when the selection would interrupt running agents. */
+    switchNotice: string;
+    /** Saving state label. */
+    saving: string;
+    /** Confirmation dialog title. */
+    confirmTitle: string;
+    /** Confirmation dialog body. */
+    confirmBody: string;
+    /** Confirmation action label. */
+    confirmAction: string;
+    /** Cancel action label. */
+    cancelAction: string;
+    /** Accessible close-button label of the confirmation dialog. */
+    closeLabel: string;
+    /** Notice shown while the Claude Code engine owns the slot: model selection is native. */
+    claudeModelNotice: string;
+}
+/** Simplified Chinese copy. */
+export declare const zh: Record<keyof LoopEngineKey, string>;
+/** English copy. */
+export declare const en: Record<keyof LoopEngineKey, string>;
+//# sourceMappingURL=locales.d.ts.map

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

@@ -0,0 +1,58 @@
+/**
+ * Loop engine selection store: the durable settings scope is the transport,
+ * and the store publishes a render-safe snapshot plus the write path.
+ * @module dsh-loop-engine/client/store
+ */
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { LoopEngineId } from '../settings.ts';
+/** State rendered by the loop engine section. */
+export interface LoopEngineState {
+    status: 'loading' | 'ready' | 'unavailable' | 'saving';
+    engine: LoopEngineId;
+    showInComposer: boolean;
+    writable: boolean;
+    error: string | null;
+}
+/** Narrow a wire section to the stored engine id and display toggle; an invalid one reads default. */
+export declare function decodeLoopEngine(section: unknown): {
+    engine: LoopEngineId;
+    showInComposer: boolean;
+} | undefined;
+/** Coordinates the settings-backed loop engine selection. */
+export declare class LoopEngineStore {
+    private readonly scope;
+    /** uSES-safe state source shared by the registered settings section. */
+    readonly store: SnapshotStore<LoopEngineState>;
+    private following;
+    private saving;
+    /**
+     * @param scope - the loop engine settings namespace scope.
+     */
+    constructor(scope: SettingsScope<{
+        engine: LoopEngineId;
+        showInComposer: boolean;
+    }>);
+    /** Begin following the bound scope and publish its current answer. */
+    load(): void;
+    /**
+     * Persist the selected engine. Success is judged against the snapshot the
+     * write left behind, so a refused write reports error after its recovery.
+     * @param engine - the engine to select for future Agent turns.
+     * @returns whether the write landed.
+     */
+    setEngine(engine: LoopEngineId): Promise<boolean>;
+    /**
+     * Persist whether the composer shows the engine picker. Success is judged
+     * against the snapshot the write left behind, so a refused write reports
+     * error after its recovery. Unlike {@link setEngine}, landing does not reload
+     * the page — the toggle only changes composer visibility.
+     * @param show - whether the chat page composer reveals the engine picker.
+     * @returns whether the write landed.
+     */
+    setShowInComposer(show: boolean): Promise<boolean>;
+    /** Stop following the scope. */
+    dispose(): void;
+    private derive;
+}
+//# sourceMappingURL=store.d.ts.map

package/lib/types/commands.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Claude Code slash-command bridge.
+ *
+ * The dsh `commands` runtime executes a registered command locally — the line
+ * is consumed and never reaches the model — so a command whose real processing
+ * lives inside the Claude Code CLI must forward the raw line back to the
+ * engine. The definitions here do exactly that: the handler delivers
+ * `/<name> [args]` to the receiving agent as a plain user message, and the CLI
+ * then expands it natively (built-ins and custom `.claude/commands/*.md`).
+ * Registering the built-ins keeps them visible in the dsh web slash menu;
+ * unregistered `/lines` pass through as user text, but the menu would hide the
+ * engine's command surface.
+ *
+ * User-level custom slash commands (`~/.claude/commands/*.md`) are discovered
+ * and registered the same way, so they appear in the menu AND reach the CLI.
+ * Project-level `.claude/commands/` files are left to the CLI entirely: they
+ * are cwd-dependent, and a global dsh registration would collide across
+ * projects.
+ *
+ * @module dsh-loop-engine/commands
+ */
+import type { UserMessage } from '@deepseek-ai/dsh-session';
+/** Minimal shape of a DSH command definition (avoiding a direct peer dep on @deepseek-ai/dsh-commands). */
+export interface CommandDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly input?: {
+        readonly hint: string;
+        readonly images?: boolean;
+    };
+    readonly handler: (invocation: CommandInvocation) => CommandResult | Promise<CommandResult>;
+}
+/** Invocation delivered to one registered command handler. */
+export interface CommandInvocation {
+    readonly commandId: string;
+    /** The receiving agent; forwarding handlers deliver the raw line back to it. */
+    readonly agent: {
+        readonly followup: (input: UserMessage) => void;
+    };
+    /** Exact text following the command name, including separator whitespace. */
+    readonly rawInput: string;
+    readonly signal: AbortSignal;
+}
+/** Settled result of one command handler. */
+export interface CommandResult {
+    readonly kind: 'success' | 'error';
+    readonly text?: string;
+}
+/**
+ * Build the forwarding handler for one Claude Code slash command: it
+ * re-delivers the full `/<name> [args]` line to the receiving agent as a
+ * plain user message, where the CLI expands it. `rawInput` already carries the
+ * separator whitespace and any arguments.
+ * @param name - the command name without the leading slash.
+ * @returns the command handler.
+ */
+export declare function forwardClaudeCodeCommand(name: string): (invocation: CommandInvocation) => CommandResult;
+/** Claude Code's built-in slash commands. */
+export declare const CLAUDE_CODE_COMMANDS: readonly CommandDefinition[];
+/**
+ * Discover the user-level custom slash commands from `~/.claude/commands/*.md`
+ * and build forwarding definitions for them. The scan is synchronous so the
+ * mount path can register the commands before the engine-selection commit
+ * returns; files without a usable name or description, and names already taken
+ * by the built-ins, are skipped.
+ * @returns forwarding definitions, sorted by file name.
+ */
+export declare function discoverUserSlashCommands(): CommandDefinition[];
+//# sourceMappingURL=commands.d.ts.map

package/lib/types/driver-core/context-files.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Context-file collection and body loading shared by the hosted engine
+ * drivers.
+ *
+ * Codex and Pi read per-directory instruction files (`AGENTS.md`; pi also
+ * accepts `CLAUDE.md` and prefers `AGENTS.override.md` inside any directory
+ * that has one) while walking from the session cwd up to the git root. The
+ * skill providers surface each collected set as one merged skill candidate so
+ * the dsh skill-injection seam (`/name` gestures) can carry it into the
+ * prompt; the body-loading helpers below feed both providers' list/get paths.
+ *
+ * @module dsh-loop-engine/driver-core/context-files
+ */
+/** Per-directory context-file resolution policy for one engine. */
+export interface ContextFilePolicy {
+    /** Per-directory override file that replaces the primary files when present. */
+    readonly override?: string;
+    /** Per-directory primary files, tried in order until one exists. */
+    readonly primary: readonly string[];
+}
+/**
+ * The directory chain from `cwd` up to the git root, nearest first. Without a
+ * repository the chain is just the resolved `cwd` itself, matching
+ * {@link findProjectRoot}'s fallback so the walk stays bounded.
+ * @param cwd - the session working directory.
+ * @returns the chain of directories to inspect.
+ */
+export declare function projectAncestors(cwd: string): Promise<string[]>;
+/**
+ * Collect every directory's context file per the policy, from the session cwd
+ * up to the git root.
+ * @param cwd - the session working directory.
+ * @param policy - per-directory resolution policy.
+ * @returns existing context files, nearest directory first.
+ */
+export declare function collectProjectContextFiles(cwd: string, policy: ContextFilePolicy): Promise<string[]>;
+/**
+ * Read one file, or `undefined` when it is unreadable.
+ * @param path - the file to read.
+ * @returns the file body, or `undefined` on any failure.
+ */
+export declare function readOptionalFile(path: string): Promise<string | undefined>;
+/**
+ * Whether any of the given sources carries non-whitespace content.
+ * @param paths - candidate file paths.
+ * @returns whether at least one readable source is non-empty.
+ */
+export declare function anySourceNonEmpty(paths: readonly string[]): Promise<boolean>;
+/**
+ * Whether one file exists and carries non-whitespace content.
+ * @param path - the file to inspect.
+ * @returns whether the file is readable and non-empty.
+ */
+export declare function fileNonEmpty(path: string): Promise<boolean>;
+/**
+ * Concatenate every non-empty readable source body in order, or `undefined`
+ * when none are readable.
+ * @param paths - candidate file paths, nearest directory first.
+ * @returns the joined bodies, or `undefined` when nothing could be read.
+ */
+export declare function readSources(paths: readonly string[]): Promise<string | undefined>;
+//# sourceMappingURL=context-files.d.ts.map

package/lib/types/driver-core/ownership.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared factory ownership and abort-race machinery for the hosted engines.
+ * Both the Claude Code and Codex loop drivers run the same lifecycle: exactly
+ * one factory owns the AgentFactory slot, every live agent's teardown is
+ * tracked until it settles, and setup awaits are raced against a fused abort
+ * signal. These helpers are engine-free — they only touch the fiber state,
+ * the session id type, and an AbortController — so the two loop modules share
+ * them verbatim.
+ *
+ * @module dsh-loop-engine/driver-core/ownership
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+/** Fiber states that cannot own or serve a new lifecycle. */
+export declare const INACTIVE_STATES: ReadonlySet<number>;
+/** Factory-level ownership: live agent teardowns plus load-time tracking. */
+export declare class FactoryOwnership {
+    private readonly fiber;
+    private accepting;
+    private readonly teardown;
+    private readonly inactive;
+    private readonly liveAgents;
+    private startupTasks;
+    constructor(fiber: Context['fiber']);
+    /** Aborts (reason: `agent loop is not active` error) when factory teardown begins. */
+    get signal(): AbortSignal;
+    isActive(): boolean;
+    /** Track one live agent's shared teardown until it has run. */
+    track(dispose: () => Promise<void>): () => void;
+    /** Join config startup work that begins before an agent exists. */
+    trackStartup(job: Promise<void>): void;
+    /** Join one public create/resume continuation; factory dispose awaits its settlement. */
+    trackWrapper(job: Promise<unknown>): void;
+    dispose(): Promise<void>;
+}
+/** Await `operation`, or throw the signal's reason as soon as it aborts. */
+export declare function raceAbort<T>(operation: PromiseLike<T> | T, signal: AbortSignal, id: SessionId): Promise<T>;
+/** Start an abortable operation and release a value that arrives after cancellation. */
+export declare function raceAbortCall<T>(operation: () => PromiseLike<T> | T, signal: AbortSignal, id: SessionId, releaseAbandoned?: (value: T) => void): Promise<T>;
+//# sourceMappingURL=ownership.d.ts.map

package/lib/types/driver-core/permission-knobs.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Reading the dsh session's durable permission knobs from the session log.
+ * Both the Claude Code and Codex drivers fold the same `sandbox/mode` and
+ * `approval/policy` events (pinned at creation, re-recorded on every switch)
+ * into per-query permission decisions; the knob readers are engine-free.
+ *
+ * @module dsh-loop-engine/driver-core/permission-knobs
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/**
+ * Minimal structural shape of one session log event. The base `SessionEvent`
+ * union in this compilation does not carry the sandbox/approval packages'
+ * augmentation keys, so the fold reads the wire shape directly.
+ */
+export type PermissionEvent = Pick<SessionEvent, 'data'> & {
+    readonly type: string;
+};
+/** dsh sandbox modes, mirrored inline to avoid a peer dep on @deepseek-ai/dsh-sandbox-policy. */
+export type DshSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** dsh approval policies, mirrored inline to avoid a peer dep on @deepseek-ai/dsh-user-approval. */
+export type DshApprovalPolicy = 'ask' | 'never';
+/** The session's sandbox-mode override: the last `sandbox/mode` event, if any. */
+export declare function sessionSandboxMode(events: readonly PermissionEvent[]): DshSandboxMode | undefined;
+/** The session's approval-policy override: the last `approval/policy` event, if any. */
+export declare function sessionApprovalPolicy(events: readonly PermissionEvent[]): DshApprovalPolicy | undefined;
+//# sourceMappingURL=permission-knobs.d.ts.map

package/lib/types/driver-core/prompt.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Serialization of the durable session history into the prompt text of one
+ * hosted-engine query. Both the Claude Code and Codex drivers build their
+ * per-step input from the durable session log: the transcript is the log's
+ * exact projection, so a later replay of the same log derives the identical
+ * prompt (Model-visible ⟺ logged bridge).
+ *
+ * @module dsh-loop-engine/driver-core/prompt
+ */
+import type { Message } from '@deepseek-ai/dsh-llm';
+/** Model-facing stand-in for an image block that the hosted engines cannot consume as bytes. */
+export declare const OMITTED_IMAGE_TEXT = "[image omitted: the driver does not transcribe images; read the file when a path is available]";
+/**
+ * Serialize a derived conversation history into the prompt text of one hosted
+ * query. The last message is the live user request that triggered the step;
+ * every earlier message is durable replay context. The output is a pure
+ * function of the log prefix.
+ * @param messages - derived history, oldest first, as returned by
+ *   `Session.deriveMessages()` at step time.
+ * @returns the prompt text to pass to the engine.
+ */
+export declare function serializeHistory(messages: readonly Message[]): string;
+//# sourceMappingURL=prompt.d.ts.map

package/lib/types/driver-core/skill-inject.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Skill-injection helpers shared by the hosted engine drivers. Both the Claude
+ * Code and Codex agents replicate the dsh `/name` skill gesture scan and the
+ * XML `<skill_content>` rendering that the in-process engine's dsh-tool-skill
+ * handler would otherwise provide — their agent contexts do not descend from
+ * the agent-preset chain. These helpers are pure: they take user messages or a
+ * loaded skill and return the injected text, with no session or loop access.
+ *
+ * @module dsh-loop-engine/driver-core/skill-inject
+ */
+import type { UserMessage } from '@deepseek-ai/dsh-session';
+export declare function isSkillName(name: string): boolean;
+/** Minimal shape of a loaded skill definition. */
+export interface SkillDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly whenToUse?: string;
+    readonly invocation: {
+        readonly modelInvocable: boolean;
+        readonly userInvocable: boolean;
+    };
+    readonly source: string;
+    readonly provider: string;
+    readonly content: string;
+    readonly path?: string;
+    readonly resourceBase?: {
+        readonly kind: string;
+        readonly path: string;
+    };
+}
+/** Durable source for an injected user-explicit skill invocation (mirrors dsh-skill's). */
+export interface SkillInvocationSource {
+    readonly kind: 'skill-invocation';
+    readonly name: string;
+    readonly form: 'instructions';
+}
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** A user-explicit skill invocation injected by this driver. */
+        'skill-invocation': SkillInvocationSource;
+    }
+}
+/** Minimal shape of the SkillRegistry service. */
+export interface SkillsService {
+    get(name: string, options: {
+        cwd?: string;
+        signal?: AbortSignal;
+        scope?: unknown;
+    }): Promise<SkillDefinition | undefined>;
+}
+/** Escape text for inclusion in XML-like skill markup. */
+export declare function escapeText(value: string): string;
+/** Escape an XML-like attribute value. */
+export declare function escapeAttr(value: string): string;
+/** Render the `<skill_content>` block for a loaded skill. */
+export declare function renderSkillContent(skill: SkillDefinition): string;
+/** Collect `/name` gesture tokens from direct user messages, in first-seen order. */
+export declare function invokedSkillNames(messages: readonly UserMessage[]): string[];
+//# sourceMappingURL=skill-inject.d.ts.map