dsh-loop-engine 1.0.0-rc2

package/lib/invariant.js

@@ -0,0 +1,83 @@
+// src/settings.ts
+import z from "@deepseek-ai/schemastery";
+import { settingsNamespace } from "@deepseek-ai/dsh-settings";
+var LOOP_ENGINE_IDS = ["in-process", "claude-code", "codex", "pi"];
+var LOOP_ENGINE_SETTINGS_SCHEMA = z.object({
+  engine: z.union([z.const("in-process"), z.const("claude-code"), z.const("codex"), z.const("pi")]).default("in-process")
+});
+
+// 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",
+    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 applyManagedBlock(text, engine) {
+  const block = renderManagedBlock(engine);
+  const span = managedSpan(text);
+  if (!span.present) {
+    if (block === "") return text;
+    const base = ensureTrailingNewline(text);
+    return `${base}
+${block}`;
+  }
+  if (block === "") {
+    return span.tail.startsWith("\n") ? `${span.head}${span.tail.slice(1)}` : `${span.head}${span.tail}`;
+  }
+  return `${span.head}${span.blankBefore ? "\n" : ""}${block}${span.tail}`;
+}
+
+// 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 = "# 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(`managed-block round trip for ${engine} is not a fixed point`);
+    if (engine === "in-process" && applied !== seed) fail("in-process engine must leave the file text unchanged");
+    if (engine !== "in-process" && currentEngineOf(renderManagedBlock(engine)) !== engine) fail(`${engine} block must read back as the ${engine} engine`);
+  }
+};
+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-runtime/client';
+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/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-runtime/client';
+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,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-loop-engine/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 { LoopEngineBadgeInjected, LoopEngineBadgeProps } from './LoopEngineBadge.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,40 @@
+/**
+ * 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;
+    /** 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;
+    /** 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,45 @@
+/**
+ * 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, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
+import type { LoopEngineId } from '../settings.ts';
+/** State rendered by the loop engine section. */
+export interface LoopEngineState {
+    status: 'loading' | 'ready' | 'unavailable' | 'saving';
+    engine: LoopEngineId;
+    writable: boolean;
+    error: string | null;
+}
+/** Narrow a wire section to the stored engine id; an invalid one reads default. */
+export declare function decodeLoopEngine(section: unknown): {
+    engine: LoopEngineId;
+} | 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;
+    }>);
+    /** 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>;
+    /** Stop following the scope. */
+    dispose(): void;
+    private derive;
+}
+//# sourceMappingURL=store.d.ts.map

package/lib/types/commands.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Claude Code built-in slash command definitions.
+ *
+ * These commands are registered into the DSH CommandRuntime when the
+ * claude-code engine is active.  The handlers are stubs — the real command
+ * processing happens inside the Claude Agent SDK — so the UI shows the
+ * commands in the slash menu and the handler returns success immediately.
+ *
+ * @module dsh-loop-engine/commands
+ */
+/** 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>;
+}
+export interface CommandInvocation {
+    readonly commandId: string;
+    readonly rawInput: string;
+    readonly signal: AbortSignal;
+}
+export interface CommandResult {
+    readonly kind: 'success' | 'error';
+    readonly text?: string;
+}
+/** Claude Code's built-in slash commands. */
+export declare const CLAUDE_CODE_COMMANDS: CommandDefinition[];
+//# sourceMappingURL=commands.d.ts.map

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

@@ -0,0 +1,41 @@
+/**
+ * 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 { FiberState } from '@deepseek-ai/cordis';
+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<FiberState>;
+/** 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

package/lib/types/engine-claude/agent.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Claude Code loop Agent: drives one session through turn and step boundaries
+ * with one Claude Agent SDK query per step. Claude Code owns its prompt,
+ * tools, and permissions; the durable session log remains the source of truth
+ * and the query prompt is a pure serialization of it.
+ *
+ * @module dsh-loop-engine/engine-claude/agent
+ */
+import type { Agent, AgentCancelCause, AgentOptions, AgentStatus, CancelOptions, InboxTarget } from '@deepseek-ai/dsh-agent';
+import { Inbox } from '@deepseek-ai/dsh-agent';
+import type { Scope } from '@deepseek-ai/dsh-scope';
+import type { Session, SessionId, UserMessage } from '@deepseek-ai/dsh-session';
+import type { Context } from '@deepseek-ai/cordis';
+import type { ResolvedConfig } from './types.ts';
+/** Drives one session through turn and step boundaries on Claude Code. */
+export declare class ClaudeCodeAgent implements Agent {
+    private loopCtx;
+    readonly id: SessionId;
+    readonly options: AgentOptions;
+    readonly session: Session;
+    private readonly config;
+    readonly inbox: Inbox;
+    private phase;
+    private activityDone;
+    /** The agent-scoped registration boundary; the lifecycle owner unwinds it after the driver exits. */
+    readonly scope: Scope;
+    readonly ctx: Context;
+    /** Fused dispatcher, built once in the constructor so hot-path dispatches never allocate. */
+    private readonly dispatch;
+    /** Whether this loop instance has appended its initial/resume request anchor. */
+    private requestHeaderLogged;
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig);
+    get status(): AgentStatus;
+    /** Commit a phase and publish its externally visible status transition. */
+    private setPhase;
+    send(message: UserMessage, target: InboxTarget, wakeup: boolean): void;
+    /**
+     * Queue a message for the next turn and wake the driver.
+     * @param input - the user message to deliver.
+     */
+    followup(input: UserMessage): void;
+    /**
+     * Queue a message for the running step and wake the driver.
+     * @param input - the user message to deliver.
+     */
+    steer(input: UserMessage): void;
+    /**
+     * Queue a message for the running step without waking the driver.
+     * @param input - the user message to deliver.
+     */
+    inject(input: UserMessage): void;
+    cancel(cause: AgentCancelCause, options?: CancelOptions): void;
+    /**
+     * Run a maintenance job while the agent is idle.
+     * @param job - the maintenance operation, receiving the phase abort signal.
+     * @returns the maintenance result.
+     */
+    runMaintenance<T>(job: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    /**
+     * Start one driver, or latch its wake behind maintenance or an aborted
+     * activity. A wake sent while idle always opens its turn boundary, even
+     * when its message was cleared; only a latched replay is suppressed when
+     * the queue no longer holds the wake.
+     * @param wakeAfterAbort - the {@link send} classification, captured before
+     *   the inbox insertion so a reentrant cancel cannot reclassify it.
+     */
+    private wakeDriver;
+    whenIdle(): Promise<void>;
+    /** Report one failure at its live boundary, then preserve it for driver containment. */
+    private throwError;
+    private kick;
+    private preStep;
+    /**
+     * Scan the step's user messages for `/name` skill gestures, load each
+     * matching skill, and inject the rendered skill content into the message
+     * batch.  This mirrors what dsh-tool-skill does for the in-process engine.
+     * @param messages - the current step's message batch.
+     * @param signal - cancellation signal (aborted loads are silently dropped).
+     * @returns the original batch when no skill was invoked, or an extended
+     *   batch with injected skill-content messages appended.
+     */
+    private injectSkills;
+    /**
+     * Resolve the native permission handling for one query. A deployment-pinned
+     * mode wins outright; otherwise the session's durable dsh permission knobs
+     * decide per query (mid-session preset switches included): full access
+     * bypasses native checks, an `ask` policy forwards each native permission
+     * request to the dsh approval seam, and anything else fails closed with the
+     * unattended deny-all stance.
+     * @returns the permission fields of the query spec.
+     */
+    private queryPermission;
+    /** Open one turn before claiming its first proposed step. */
+    private turn;
+    /** Model label recorded in the request header for one lifecycle. */
+    private modelLabel;
+    /** Append the request header snapshot once per loop instance. */
+    private assertRequestHeader;
+    /** Run one Claude Code query for the current step and map its transcript into the session log. */
+    private step;
+}
+//# sourceMappingURL=agent.d.ts.map

package/lib/types/engine-claude/loop.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Claude Code loop engine module: hosts the AgentFactory that drives every
+ * session through the official Claude Agent SDK, one stateless query per dsh
+ * step, with the durable session log as the sole source of model context.
+ * dsh-loop-engine constructs this factory when the Claude Code engine is
+ * selected; this module is a library, not a Cordis plugin entry.
+ *
+ * @module dsh-loop-engine/engine-claude
+ */
+import { Service } from '@deepseek-ai/cordis';
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { AgentFactory, AgentHandle, CreateAgentOptions, ResumeAgentOptions } from '@deepseek-ai/dsh-agent';
+import type { ClaudeCodePermissionMode, ResolvedConfig } from './types.ts';
+/** Deployment-selectable non-interactive Claude Code permission modes. */
+export declare const CLAUDE_CODE_PERMISSION_MODES: readonly ClaudeCodePermissionMode[];
+/** Deployment-owned configuration for the Claude Code loop plugin. */
+export interface Config {
+    /**
+     * Native non-interactive permission handling for every query. When omitted,
+     * each query follows the session's dsh permission knobs (`sandbox/mode` and
+     * `approval/policy`): full access bypasses native checks, an `ask` policy
+     * forwards requests to the dsh approval seam, and anything else auto-denies.
+     * A pinned mode overrides the session for every query: `dontAsk` auto-denies,
+     * `acceptEdits` accepts edits, `auto` uses the native classifier, `plan`
+     * returns a plan without approving execution, and `bypassPermissions`
+     * explicitly skips permission checks.
+     */
+    permissionMode?: ClaudeCodePermissionMode;
+    /** Explicit environment entries layered over the credential-scrubbed parent environment. */
+    env?: Record<string, string>;
+    /** Model label for the logged request header; Claude Code native settings own the actual model. */
+    model?: string;
+    /** Grace in milliseconds for Claude Code process-tree termination. */
+    disposeGraceMs?: number;
+    /** Cap on the number of conversation turns before each query stops. */
+    maxTurns?: number;
+}
+/** Schema of the Claude Code loop plugin configuration. */
+export declare const Config: z<Config>;
+/** Host-face ctx key for the Claude Code loop service. */
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoopClaudeCode: ClaudeCodeLoop;
+    }
+}
+/**
+ * Concrete AgentFactory and driver service of the Claude Code loop. Creation
+ * and resume follow the registry factory contract and the shared publication
+ * transaction: prepare, run setup, then publish through both registries,
+ * announce, and emit `agent/session-start`.
+ */
+export declare class ClaudeCodeLoop extends Service implements AgentFactory {
+    /** Services the loop resolves through its own fiber; blessed identically to the package-level entry inject. */
+    static inject: string[];
+    /** Validated configuration owned by the loop plugin. */
+    readonly config: ResolvedConfig;
+    private readonly ownership;
+    /** Plain holder prevents Cordis from re-tracing the factory's dependency context through a caller shadow. */
+    private readonly runtime;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Construct the driver, scope, and one memoized reverse teardown for a new
+     * agent. The teardown is registered with the factory and the owner fiber
+     * BEFORE publication, so a mid-setup unload rolls everything back; `signal`
+     * fuses caller cancellation with lifecycle teardown for setup awaits.
+     */
+    private prepare;
+    /** Prepare one Agent around an acquired Session, run setup, and publish it. */
+    private setupAndPublish;
+    /**
+     * Create an agent and session under one caller-supplied identity, owned by
+     * the accessing fiber.
+     * @param ownerCtx - caller context that structurally owns the lifecycle.
+     * @param options - identities, session seed/metadata, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>;
+    /**
+     * Resume an owned agent from the configured persistence service.
+     * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
+     * @param options - persisted identity, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>;
+    /** Resume through an explicit persistence handle. */
+    private resumeWith;
+}
+//# sourceMappingURL=loop.d.ts.map