dsh-loop-engine 0.1.5-rc1

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/assistant-stream.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Live assistant-stream framing for the hosted engines.
+ *
+ * Harness 0.1.5 made the model stream the durable record of an assistant
+ * attempt: `assistant/message` embeds its exact timed stream and may no longer
+ * cite `sourceEventSeqs`, and the transient per-chunk log events the plugin
+ * used to append (`assistant/chunk`) no longer exist. Live partials now travel
+ * through the process-local `agent/assistant-stream` notification instead, and
+ * the compact records are handed to the durable message.
+ *
+ * This is the driver-side equivalent of the loop's `AssistantStreamAttempt`,
+ * minus the block assembly: a hosted engine keeps assembling its own
+ * authoritative transcript from its own protocol, and this class only frames
+ * the attempt and compacts its stream for replay fidelity.
+ *
+ * @module dsh-loop-engine/driver-core/assistant-stream
+ */
+import type { AssistantStreamFrame } from '@deepseek-ai/dsh-agent';
+import { LlmAttemptId, type AssistantStreamRecord, type StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { SessionId, SessionSeq } from '@deepseek-ai/dsh-session';
+/**
+ * One model attempt on a hosted engine: ordered live frames plus the compact
+ * stream the durable `assistant/message` carries.
+ */
+export declare class DriverAssistantStream {
+    private readonly turn;
+    private readonly step;
+    private readonly emit;
+    private accumulator;
+    private index;
+    private revision;
+    private terminal;
+    /** Attempt identity unique within this agent lifecycle. */
+    readonly attemptId: LlmAttemptId;
+    /**
+     * @param sessionId - identity embedded only in the agent-lifecycle-local attempt id.
+     * @param attempt - agent-local attempt counter.
+     * @param turn - durable turn owning the request.
+     * @param step - durable step owning the request.
+     * @param emit - agent-scoped notification publisher.
+     */
+    constructor(sessionId: SessionId, attempt: number, turn: number, step: number, emit: (frame: AssistantStreamFrame) => void);
+    /** Whether this attempt has already published its terminal frame. */
+    get ended(): boolean;
+    /** Publish the opening marker before the first delivered chunk. */
+    start(): void;
+    /** Snapshot one chunk once, then feed durable compaction and live publication. */
+    push(chunk: StreamChunk): void;
+    /** Exact compact stream for the durable assistant message. */
+    get stream(): AssistantStreamRecord[];
+    /**
+     * Close the current record run and return it, leaving later chunks in a
+     * fresh run. An engine whose protocol reports content segments (rather than
+     * one stream per message) cuts at each segment boundary, so every durable
+     * message embeds exactly the chunks its own content produced even though the
+     * live frames keep flowing through one attempt.
+     * @returns the compact records accumulated since the previous cut.
+     */
+    takeStream(): AssistantStreamRecord[];
+    /**
+     * Publish terminal settlement after the matching durable event commits.
+     * @param append - synchronous durable append returning its committed seq.
+     */
+    settle(append: () => SessionSeq): void;
+    /** Publish abandonment when no durable settlement can be committed. */
+    abandon(): void;
+}
+//# sourceMappingURL=assistant-stream.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/inbox.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Driver-owned durable inbox for the hosted engines.
+ *
+ * Harness 0.1.5 turned `Inbox` from a concrete class into an interface the
+ * driver owns, so this module carries the projection the plugin used to
+ * construct from `dsh-agent`: pending input is folded from the session's own
+ * `agent/inbox/spliced` events and every mutation commits a normalized splice
+ * back into that log before the live lists change. The durable event stream is
+ * what the web client's conversation reducer and session resume both read, so
+ * the semantics match the removed class exactly.
+ *
+ * @module dsh-loop-engine/driver-core/inbox
+ */
+import type { Inbox, InboxTarget } from '@deepseek-ai/dsh-agent';
+import type { MessageId } from '@deepseek-ai/dsh-llm';
+import type { Session, UserMessage } from '@deepseek-ai/dsh-session';
+/** Live notifications committed by inbox mutations. */
+export interface InboxNotifications {
+    /** Publish one inserted message. */
+    inserted(message: UserMessage): void;
+    /** Publish one discarded message. */
+    discarded(message: UserMessage): void;
+    /** Publish one claimed message inside its owning turn. */
+    claimed(message: UserMessage, turn: number): void;
+}
+/**
+ * A replay-once projection of the session's durable inbox splices. Unlike the
+ * harness's driver inbox, this one keeps its own fold instead of registering a
+ * session projection, because the hosted engines drive sessions whose preset
+ * context is not the agent-loop's.
+ */
+export declare class DriverInbox implements Inbox {
+    private readonly session;
+    private readonly notifications;
+    private readonly state;
+    constructor(session: Session, notifications: InboxNotifications);
+    /** Prompts awaiting individual turns. */
+    get nextTurn(): readonly UserMessage[];
+    /** Input awaiting the next step boundary. */
+    get nextStep(): readonly UserMessage[];
+    /** Whether either pending-message list contains work. */
+    get hasPending(): boolean;
+    /** Durably cancel all pending input, clearing next-step before next-turn. */
+    clear(): void;
+    /**
+     * Remove and return the complete batch proposed for one step, publishing
+     * each claimed message. The durable splices are pure deletions.
+     * @param target - whether this boundary also consumes one queued turn.
+     * @param turn - turn that will own the claimed batch.
+     * @returns next-step input followed by the queued turn, when requested.
+     */
+    claim(target: InboxTarget, turn: number): UserMessage[];
+    /**
+     * Append one message to a pending list and durably record the insertion.
+     * @param target - pending list to extend.
+     * @param message - message to append.
+     * @throws if the message identity is already pending.
+     */
+    append(target: InboxTarget, message: UserMessage): void;
+    /**
+     * Prepend one message to a pending list and durably record the insertion.
+     * @param target - pending list to extend.
+     * @param message - message to prepend.
+     * @throws if the message identity is already pending.
+     */
+    prepend(target: InboxTarget, message: UserMessage): void;
+    /**
+     * Replace one pending message in place, possibly changing its identity. A
+     * successful replacement publishes the old message as discarded and the new
+     * message as inserted.
+     * @param messageId - identity of the pending message to replace.
+     * @param newMessage - replacement message.
+     * @returns whether the message was still pending.
+     * @throws if the replacement duplicates another pending message identity.
+     */
+    replace(messageId: MessageId, newMessage: UserMessage): boolean;
+    /**
+     * Remove one pending message and durably record its cancellation.
+     * @param messageId - identity of the pending message to remove.
+     * @returns whether the message was still pending.
+     */
+    remove(messageId: MessageId): boolean;
+    /**
+     * Apply standard splice semantics and durably record the normalized result.
+     * The durable event commits before the live projection mutates, so
+     * synchronous `session/event` observers see the pre-splice lists and can
+     * reconstruct the removed messages from the normalized coordinates.
+     * @param target - pending list to mutate.
+     * @param start - splice position.
+     * @param deleteCount - maximum number of messages to remove.
+     * @param inserted - messages to insert at the resolved position.
+     * @returns messages removed by the splice.
+     */
+    splice(target: InboxTarget, start: number, deleteCount: number, inserted: UserMessage[]): UserMessage[];
+    /** Locate one pending identity across both owned lists. */
+    private locate;
+    /** Commit one normalized mutation and publish its live notifications. */
+    private mutate;
+    /** Apply one normalized durable splice to the projection. */
+    private apply;
+    /** Validate one normalized splice against the current projection. */
+    private validate;
+}
+//# sourceMappingURL=inbox.d.ts.map