@vidge/dsh-agent-hub 0.1.0-rc1

package/lib/invariant.js

@@ -0,0 +1,96 @@
+// 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() {
+  return [
+    `${MANAGED_BLOCK_BEGIN} --`,
+    "- id: agent-loop",
+    "  disabled: true",
+    END_MARKER_LINE
+  ].join("\n");
+}
+function hasManagedBlock(text) {
+  return text.includes(MANAGED_BLOCK_BEGIN);
+}
+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}
+`;
+}
+var EMPTY_FLOW_SEQ_RE = /^[ \t]*\[\][ \t]*$/;
+function isEmptyFlowSeqDocument(text) {
+  let sawEmptySeq = false;
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    if (!sawEmptySeq && EMPTY_FLOW_SEQ_RE.test(line)) {
+      sawEmptySeq = true;
+      continue;
+    }
+    return false;
+  }
+  return sawEmptySeq;
+}
+function stripEmptyFlowSeq(text) {
+  const lines = text.split("\n");
+  const at = lines.findIndex((line) => EMPTY_FLOW_SEQ_RE.test(line));
+  lines.splice(at, 1);
+  return lines.join("\n");
+}
+function applyManagedBlock(text) {
+  const block = renderManagedBlock();
+  const span = managedSpan(text);
+  if (!span.present) {
+    const base = ensureTrailingNewline(
+      isEmptyFlowSeqDocument(text) ? stripEmptyFlowSeq(text).trimEnd() : text
+    );
+    return `${base}
+${block}`;
+  }
+  return `${span.head}${span.blankBefore ? "\n" : ""}${block}${span.tail}`;
+}
+
+// src/invariant.ts
+var PACKAGE_NAME = "dsh-agent-hub";
+var name = "loop-engine-invariant";
+var inject = ["invariants"];
+var install = (ctx, fail) => {
+  void ctx;
+  const seed = "# dsh profile patch layer\n";
+  const applied = applyManagedBlock(seed);
+  if (applyManagedBlock(applied) !== applied) fail("managed-block application is not a fixed point");
+  if (!hasManagedBlock(applied)) fail("managed block must be present after application");
+  if (!renderManagedBlock().includes("- id: agent-loop")) fail("managed block must disable the base agent-loop row");
+  if (!renderManagedBlock().includes("disabled: true")) fail("managed block must disable, not merely target, the base row");
+  const legacy = `${seed}
+${MANAGED_BLOCK_BEGIN}: codex --
+- id: agent-loop
+  disabled: true
+${MANAGED_BLOCK_END}
+`;
+  const upgraded = applyManagedBlock(legacy);
+  if (upgraded !== applied) fail("a legacy engine-tagged block must upgrade to the permanent block");
+};
+var apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+export {
+  apply,
+  inject,
+  name
+};
+//# sourceMappingURL=invariant.js.map

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

@@ -0,0 +1,73 @@
+/**
+ * Composer loop-engine control, registered at the `conversation.input.right`
+ * seat so it sits immediately left of the model select in the composer's tool
+ * row.
+ *
+ * It shows **this session's actual engine**, read from the node half over the
+ * plugin's own RPC channel. That distinction is the whole point of this
+ * component. A session's engine is chosen inside `createAgent`, which the
+ * harness fires eagerly when a session is *opened* — before a user can click
+ * anything — so a control backed by the settings value would name "the last
+ * thing picked anywhere" while the session ran something else. That was a real,
+ * reported defect: the composer read "In-process engine" while Claude Code
+ * answered.
+ *
+ * The seat never hides itself over a failed read. When the engine cannot be
+ * resolved it says so and stays clickable: the picker is the only route to
+ * another engine, so removing it would strand the user with no control and no
+ * explanation — which is precisely how this looked when the channel silently
+ * failed to register.
+ *
+ * Because the engine is fixed before the control is reachable, picking a
+ * different one cannot change this session. It instead **creates a new one**:
+ * the seat mints a session id, reserves the engine for it over the channel, and
+ * asks the host to create exactly that id — bypassing `connectWorkspace`, which
+ * would hand back the current blank session and defeat the purpose. The
+ * abandoned blank session is left alone; discarding a session is the user's
+ * call, not the picker's.
+ *
+ * Styling is token-driven inline styles like the section (the client-module
+ * bundle is esbuild-built without a CSS loader).
+ * @module dsh-agent-hub/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 { EngineRpc } from './engine-rpc.ts';
+import type { LoopEngineId } from '../settings.ts';
+import type { en } from './locales.ts';
+/** Creates a session on a caller-chosen id and brings it to the foreground. */
+export interface SessionSwitcher {
+    /**
+     * Create a session carrying a specific engine, and open it.
+     * @param engine - engine the new session must run on.
+     * @returns whether a new session was created and opened.
+     */
+    startSessionOn(engine: LoopEngineId): Promise<boolean>;
+}
+/** Injected dependencies of {@link LoopEngineComposerSelect} (slot `inject`). */
+export interface LoopEngineComposerSelectInjected {
+    /** The settings store, for the composer-visibility toggle and the default engine. */
+    controller: LoopEngineStore;
+    /** Reads a session's true engine from the node half. */
+    rpc: EngineRpc;
+    /** Creates and opens a session bound to a chosen engine. */
+    switcher: SessionSwitcher;
+    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 seat.
+ * @param props - composed slot props.
+ * @returns the control naming this session's engine, or null when the settings
+ *   toggle hides it.
+ */
+export declare function LoopEngineComposerSelect(props: LoopEngineComposerSelectProps): JSX.Element | null;
+//# sourceMappingURL=LoopEngineComposerSelect.d.ts.map

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

@@ -0,0 +1,43 @@
+/**
+ * Loop engine settings section component: one dropdown choosing the **default**
+ * agent loop engine, backed by the duplicated settings scope through the inject
+ * face.
+ *
+ * This is deliberately not a switch for "the current engine". A session's
+ * engine is fixed inside `createAgent`, which the harness fires eagerly when a
+ * session is opened, so nothing set here can reach a session that already
+ * exists. It applies to sessions created later that do not reserve an engine of
+ * their own — the composer seat is where a session's engine is chosen. That
+ * split mirrors the harness's own `agentPreset`: a per-session control, plus a
+ * settings entry that only sets the default.
+ *
+ * Picking commits immediately; there is no confirmation dialog and no
+ * `location.reload()`, because every engine is resident behind one router.
+ *
+ * Styling is token-driven like the rest of the settings shell (`--dsw-*`
+ * aliases), with the picker rendered through the shared `Menu` primitive. 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-agent-hub/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 binding notice and the composer toggle. */
+export declare function LoopEngineSection(props: LoopEngineSectionProps): JSX.Element;
+//# sourceMappingURL=LoopEngineSection.d.ts.map

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

@@ -0,0 +1,74 @@
+/**
+ * Browser half of the `/loop-engine` Connection RPC channel.
+ *
+ * The composer needs two things the rest of the client cannot give it: the
+ * engine a session is *actually* running (it lives in a node-side sidecar, not
+ * in the log, header, or settings), and a way to claim an engine for a session
+ * *before* that session is created (agent creation is eager, so there is no
+ * later moment). Both are one `connection.rpc.call` away.
+ *
+ * The Connection is provided conditionally, so every method degrades to
+ * `undefined` rather than throwing when it is absent — the composer then falls
+ * back to a read-only label.
+ *
+ * @module dsh-agent-hub/client/engine-rpc
+ */
+import { type LoopEngineId } from '../namespace.ts';
+/** Carrier-neutral result the Connection RPC transport returns. */
+type RpcResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+/**
+ * The browser Connection surface this module borrows, declared structurally so
+ * the client bundle needs no value import from the connection package.
+ */
+export interface ConnectionLike {
+    readonly rpc: {
+        call(channel: string, endpoint: string, payload: unknown, signal?: AbortSignal): Promise<RpcResult<unknown>>;
+    };
+}
+/** Calls the plugin's own channel, tolerating a profile that has no Connection. */
+export declare class EngineRpc {
+    private readonly connection;
+    /**
+     * @param connection - the browser connection, or undefined when the profile has none.
+     */
+    constructor(connection: ConnectionLike | undefined);
+    /** Whether the channel is reachable; false makes the composer read-only. */
+    get available(): boolean;
+    /**
+     * Claim an engine for a session id the caller is about to create.
+     *
+     * Must be awaited before the session is created: the host resolves the
+     * reservation inside `createAgent`, which the harness fires eagerly at
+     * session-open.
+     *
+     * @param sessionId - id the caller will pass to `sessions.create`.
+     * @param engine - engine that session must run on.
+     * @returns whether the reservation landed.
+     */
+    bind(sessionId: string, engine: LoopEngineId): Promise<boolean>;
+    /**
+     * Read the engine a session is actually bound to.
+     * @param sessionId - the session to look up.
+     * @param signal - abort when the seat unmounts or the session changes.
+     * @returns the engine, or undefined when unknown or unreachable.
+     */
+    resolve(sessionId: string, signal?: AbortSignal): Promise<LoopEngineId | undefined>;
+    /**
+     * Issue one call, folding transport and endpoint failures into `undefined`.
+     *
+     * A failure here is never worth breaking the composer over: the engine is a
+     * label and a convenience, and the session works regardless.
+     */
+    private call;
+}
+export {};
+//# sourceMappingURL=engine-rpc.d.ts.map

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

@@ -0,0 +1,28 @@
+/**
+ * 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-agent-hub/client
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type LoopEngineKey } from './locales.ts';
+export type { LoopEngineSectionInjected, LoopEngineSectionProps } from './LoopEngineSection.tsx';
+export type { LoopEngineComposerSelectInjected, LoopEngineComposerSelectProps, SessionSwitcher } 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,44 @@
+/**
+ * Loop engine settings page copy (Chinese product copy; comments in English).
+ * @module dsh-agent-hub/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;
+    /** Settings toggle: show the engine picker in the chat page composer. */
+    showInComposerLabel: string;
+    /** Unavailable-state message. */
+    unavailable: string;
+    /** Notice explaining that the choice binds at session creation. */
+    switchNotice: string;
+    /** Composer tooltip: picking a different engine starts a new session. */
+    switchCreatesSession: string;
+    /** Tooltip of the read-only composer seat: this session's engine is already fixed. */
+    boundNotice: string;
+    /** Composer label while this session's engine is still being read. */
+    engineResolving: string;
+    /** Composer label when this session's engine could not be read. */
+    engineUnknown: string;
+    /** Composer tooltip when the engine could not be read: picking still starts a session. */
+    engineUnknownNotice: string;
+    /** Saving state label. */
+    saving: 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/session-location.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Where a newly created session should be placed.
+ *
+ * Split out of the client entry because the entry cannot be imported under
+ * vitest — it pulls the composer components, which expect the browser module
+ * loader — while this decision is pure and worth a regression test of its own.
+ * It has no imports so the browser bundle can take it as-is.
+ *
+ * @module dsh-agent-hub/client/session-location
+ */
+/** The subset of a session summary this decision reads. */
+export interface SessionSummaryLike {
+    readonly cwd?: string;
+}
+/** The subset of a workspace view this decision reads. */
+export interface WorkspaceViewLike {
+    readonly workspaceId: string;
+    readonly sessionIds: readonly string[];
+}
+/** The `sessions.list` snapshot fields this decision reads. */
+export interface SessionListLike {
+    readonly current?: string;
+    readonly byId: Record<string, SessionSummaryLike | undefined>;
+}
+/**
+ * Location argument for `sessions.create`.
+ *
+ * The two fields are mutually exclusive by host contract, not by style: the
+ * create command rejects a request carrying both with `gateway/bad-request`
+ * (`api/session-controller/src/commands.ts:72-74`). Hence a union of two
+ * one-field shapes rather than an object with both optional.
+ */
+export type SessionLocation = {
+    readonly workspaceId: string;
+} | {
+    readonly cwd: string;
+} | Record<string, never>;
+/**
+ * Decide where the engine switcher's new session goes.
+ *
+ * Workspace membership is what the user actually chose, and it is *not*
+ * implied by the directory: `create` attaches a session to a workspace only on
+ * the `workspaceId` branch (`commands.ts:96-106`). Passing the current
+ * session's `cwd` instead therefore produces a session in the right directory
+ * that belongs to no workspace, and the UI asks the user to pick a workspace
+ * all over again — which is exactly the bug this function exists to prevent.
+ *
+ * Membership is held by the workspace rather than the session, so finding it
+ * means scanning `items` for one listing the current session. That is the same
+ * lookup `uiWorkspace.startSession` does
+ * (`client/ui-workspace/src/client/navigation.ts:117-120`).
+ *
+ * `cwd` is the fallback for a session that genuinely has no workspace — a
+ * default-workspace profile, or a session created outside the workspace UI —
+ * not a companion to `workspaceId`.
+ *
+ * @param sessions - the current `sessions.list` snapshot.
+ * @param workspaces - the current workspace views, or undefined when the
+ *   profile mounts no workspace controller.
+ * @returns the location argument to spread into `sessions.create`.
+ */
+export declare function sessionLocation(sessions: SessionListLike, workspaces: readonly WorkspaceViewLike[] | undefined): SessionLocation;
+//# sourceMappingURL=session-location.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-agent-hub/client/store
+ */
+import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/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-agent-hub/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-agent-hub/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-agent-hub/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