dsh-loop-engine 0.1.5-rc1 → 0.1.5-rc2

package/lib/invariant.js

@@ -2,7 +2,7 @@
 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"),
+  engine: z.union(LOOP_ENGINE_IDS.map((id) => z.const(id))).default("in-process"),
   showInComposer: z.boolean().default(true)
 });
 
@@ -23,9 +23,12 @@ function renderManagedBlock(engine) {
   ].join("\n");
 }
 var BEGIN_MARKER_RE = /^# -- dsh-loop-engine managed block: (\S+) --$/m;
-function currentEngineOf(text) {
+function managedBlockEngineOf(text) {
   const engine = BEGIN_MARKER_RE.exec(text)?.[1];
-  return LOOP_ENGINE_IDS.includes(engine ?? "") ? engine : "in-process";
+  return LOOP_ENGINE_IDS.includes(engine ?? "") ? engine : void 0;
+}
+function currentEngineOf(text) {
+  return managedBlockEngineOf(text) ?? "in-process";
 }
 function managedSpan(text) {
   const begin = text.indexOf(MANAGED_BLOCK_BEGIN);

package/lib/types/client/turn-status.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Per-engine styling for the chat turn-status line (the "深度求索中..." row).
+ *
+ * That row is rendered from inside the harness's ChatView and its words belong
+ * to ui-chat: the row is not a slot, and ui-chat owns the `chat` locale
+ * namespace (a second `locale.register` for the same namespace throws), so a
+ * plugin cannot change the text. What it CAN do is restyle the element, and
+ * that is all this module does — it paints an engine-specific glyph and color
+ * onto the row while a hosted engine is selected, and leaves the stock look
+ * alone otherwise.
+ *
+ * Three facts about the harness markup make that safe and specific:
+ *   - the row carries exactly one class whose `[hash]_turnStatus` suffix is
+ *     stable across rebuilds (the hash in front is not), so
+ *     `[class$="_turnStatus"]` matches it and not the sibling clock;
+ *   - its gradient paints through the `--dsw-static-deepseek-*` custom
+ *     properties, so recoloring is a variable override rather than a fight
+ *     over `background` and `background-clip`;
+ *   - the glyph rides a `::before` pseudo-element, so the row's real text node
+ *     — and the status it announces — is untouched.
+ *
+ * This sheet deliberately keeps the row animating even when the OS reports
+ * `prefers-reduced-motion: reduce` (see the re-asserted sweep below): the
+ * deployment's Windows images ship with client-area animation off, which
+ * otherwise freezes every indicator here — the sweep and the glyph alike.
+ * In-process sessions keep the stock reduced-motion behaviour.
+ *
+ * @module dsh-loop-engine/client/turn-status
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { LoopEngineState } from './store.ts';
+/**
+ * Install the per-engine turn-status styling for the lifetime of `ctx`.
+ *
+ * Keyed off the shared controller store, so it follows a live engine switch
+ * exactly as the settings section and header chip do; the store is read rather
+ * than the settings scope so all three surfaces cannot disagree.
+ * @param ctx - the client root context.
+ * @param store - the loop-engine controller's snapshot source.
+ */
+export declare function installTurnStatusStyles(ctx: ClientContext, store: SnapshotStore<LoopEngineState>): void;
+//# sourceMappingURL=turn-status.d.ts.map

package/lib/types/driver-core/agents-md-skill-provider.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Data-driven skill provider for the hosted engines whose discovery surface is
+ * "per-directory instruction files plus a skills catalog".
+ *
+ * Codex, Pi, and Kimi Code each expose the same two things through the dsh
+ * skill-injection seam: an `agents-md` candidate merging the per-directory
+ * instruction files found between the session cwd and the git root, and one
+ * candidate per `SKILL.md` catalog entry. Only the *locations*, *names*, and
+ * *precedence ranks* differ — never the algorithm — so those are the entire
+ * configuration surface here, and each engine module supplies one
+ * {@link AgentsMdProviderSpec} and a thin subclass.
+ *
+ * `.agents/skills` roots are deliberately absent from every engine's spec:
+ * dsh's own `skill-filesystem` provider already serves them through the same
+ * registry in the web profile.
+ *
+ * @module dsh-loop-engine/driver-core/agents-md-skill-provider
+ */
+import { type ContextFilePolicy } from './context-files.ts';
+import type { SkillCandidate, SkillDefinition, SkillLookupOptions, SkillProvider, SkillProviderControl } from '../skills.ts';
+/** A skills catalog: a per-ancestor project directory plus one user-level directory. */
+export interface SkillCatalogSpec {
+    /** Directory path, relative to each ancestor of the session cwd. */
+    readonly project: readonly string[];
+    /** Rank of project catalog entries — project instructions beat project skills. */
+    readonly projectRank: number;
+    /** Directory name under the user install root. */
+    readonly userDir: string;
+    /** Rank of user catalog entries — project files win duplicate names. */
+    readonly userRank: number;
+}
+/** Everything that varies between the codex, pi, and kimi discovery surfaces. */
+export interface AgentsMdProviderSpec {
+    /** Provider identity registered against the host skills service. */
+    readonly name: string;
+    /** Description of the merged `agents-md` candidate. */
+    readonly agentsMdDescription: string;
+    /** Per-directory instruction files this engine reads, and its override. */
+    readonly contextPolicy: ContextFilePolicy;
+    /** The engine's user-level install root. */
+    readonly userDir: () => string;
+    /** Rank of the project `agents-md` candidate. */
+    readonly projectRank: number;
+    /** User-level instruction file inside {@link userDir}, when the engine reads one. */
+    readonly userContext?: {
+        readonly file: string;
+        readonly rank: number;
+    };
+    /** Skill catalogs, when the engine has any. */
+    readonly skills?: SkillCatalogSpec;
+}
+/**
+ * Skill provider that discovers an engine's per-directory instruction files and
+ * `SKILL.md` catalogs from the locations its spec names.
+ */
+export declare class AgentsMdSkillProvider implements SkillProvider {
+    private readonly spec;
+    private readonly control;
+    readonly name: string;
+    constructor(spec: AgentsMdProviderSpec, control: SkillProviderControl);
+    list(options: SkillLookupOptions): Promise<readonly SkillCandidate[]>;
+    get(candidate: SkillCandidate, _options: SkillLookupOptions): Promise<SkillDefinition | undefined>;
+    /** One merged `agents-md` candidate for a ranked file set. */
+    private agentsCandidate;
+    /** Collect every skill in one skills directory, both nesting layouts. */
+    private collectSkillsDir;
+    /** One parsed skill as a ranked candidate. */
+    private skillCandidate;
+    /** Parse one SKILL.md file, or `undefined` when it is unreadable or invalid. */
+    private tryParse;
+}
+//# sourceMappingURL=agents-md-skill-provider.d.ts.map

package/lib/types/driver-core/hosted-loop-factory.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Shared AgentFactory transaction machinery for the hosted loop engines.
+ *
+ * All four engines (Claude Code, Codex, Pi, Kimi Code) implement the harness's
+ * single AgentFactory slot the same way: prepare a driver, scope, and one
+ * memoized reverse teardown for a session; run the caller's setup under a fused
+ * abort signal; publish through both registries and announce; and on resume,
+ * own a session's write handle across the cold read, crash repair, and
+ * re-publication. None of that touches an engine protocol — the whole
+ * engine-specific surface is one call, {@link HostedLoopFactory.buildAgent}.
+ *
+ * This body mirrors the default in-process `agent-loop` factory; depending on
+ * the `dsh-agent-loop` package is forbidden (it would claim the slot this
+ * plugin exists to hand over), so the machinery is replicated here once instead
+ * of four times.
+ *
+ * Subclasses supply:
+ *   - the cordis service label, which is also the prefix of every effect label
+ *     (`<label>.transactions()`, `<label>.setFactory()`, `<label>.lifecycle(id)`,
+ *     `<label>.resume-load(id)`) — the lifecycle label is asserted by tests, so
+ *     it must stay `<label>.lifecycle(...)`;
+ *   - their own `static inject` (Codex needs no `subprocess`);
+ *   - {@link HostedLoopFactory.buildAgent}.
+ *
+ * @module dsh-loop-engine/driver-core/hosted-loop-factory
+ */
+import { Service } from '@deepseek-ai/cordis';
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentFactory, AgentHandle, AgentOptions, CreateAgentOptions, ResumeAgentOptions } from '@deepseek-ai/dsh-agent';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { Scope } from '@deepseek-ai/dsh-scope';
+/**
+ * What the transaction machinery needs of a driver beyond the harness `Agent`
+ * contract: a teardown entry point that also unwinds the driver's own scope.
+ * The concrete engines declare these; the base only spells them out so the
+ * shared body can call them generically.
+ */
+export interface HostedAgent extends Agent {
+    /** Stop the machine with the given cause, without waiting for it to settle. */
+    cancel(cause: Parameters<Agent['cancel']>[0]): void;
+    /** Resolves when the machine has no work in flight. */
+    whenIdle(): Promise<void>;
+    /** The driver's own resource scope, unwound after the machine settles. */
+    readonly scope: Scope;
+}
+/**
+ * Concrete AgentFactory base for one hosted engine. 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 abstract class HostedLoopFactory<TConfig, TAgent extends HostedAgent> extends Service implements AgentFactory {
+    /** Validated configuration owned by the loop plugin. */
+    readonly config: TConfig;
+    private readonly ownership;
+    /** Plain holder prevents Cordis from re-tracing the factory's dependency context through a caller shadow. */
+    protected readonly runtime: {
+        ctx: Context;
+    };
+    /** Cordis service name, also the prefix of every effect label. */
+    private readonly label;
+    constructor(ctx: Context, label: string, config: TConfig);
+    /**
+     * Construct this engine's driver for one prepared session. Called once per
+     * create or resume, after the session exists and before setup runs; the
+     * hook is the engine's entire protocol surface.
+     */
+    protected abstract buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): TAgent;
+    /**
+     * 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. When a persistence backend is mounted, the session's
+     * durable identity is stored before publication.
+     * @param ownerCtx - caller context that structurally owns the lifecycle.
+     * @param options - identities, optional live parent, session seed/metadata, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>;
+    /**
+     * Take a fresh session's write ownership when persistence is mounted.
+     * Nothing is appended here: the constructor seed (which never re-emits
+     * through `session/event`) is stored by {@link appendUnstoredSuffix} at the
+     * publication commit point, so a failed or cancelled setup closes an
+     * unmaterialized handle and leaves no stored residue — the same id can be
+     * created again.
+     * @param session - the unpublished session to store.
+     * @param signal - optional cancellation forwarded to the backend create.
+     * @returns the owned handle and stored cursor, or `undefined` without a backend.
+     */
+    private createStoredSession;
+    /**
+     * Durably store the session events appended since the last stored cursor.
+     * Pre-publication appends (constructor seed markers, setup-window events)
+     * never re-emit through `session/event`, so publication must flush them
+     * through the handle before live events start routing into it.
+     * @param stored - the session's owned handle and stored cursor, if any.
+     * @param session - the unpublished session whose suffix is stored.
+     */
+    private appendUnstoredSuffix;
+    /**
+     * 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, optional live parent, loop options, setup, and cancellation.
+     * @returns the published handle.
+     */
+    resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>;
+    /** Resume through an explicit persistence service. */
+    private resumeWith;
+}
+//# sourceMappingURL=hosted-loop-factory.d.ts.map

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

@@ -1,11 +1,11 @@
 /**
  * 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.
+ * All four loop drivers (Claude Code, Codex, Pi, Kimi Code) 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
+ * loop modules share them verbatim.
  *
  * @module dsh-loop-engine/driver-core/ownership
  */

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

@@ -1,6 +1,6 @@
 /**
  * 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
+ * Every hosted driver folds 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.
  *

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

@@ -1,6 +1,6 @@
 /**
  * Serialization of the durable session history into the prompt text of one
- * hosted-engine query. Both the Claude Code and Codex drivers build their
+ * hosted-engine query. Every hosted driver builds its
  * 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).

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

@@ -1,6 +1,6 @@
 /**
- * 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
+ * Skill-injection helpers shared by the hosted engine drivers. Each hosted
+ * engine's agent replicates 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

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

@@ -33,6 +33,17 @@ export declare class ClaudeCodeAgent implements Agent {
     private requestHeaderLogged;
     /** Agent-lifecycle-local counter naming each streamed attempt. */
     private streamAttempts;
+    /**
+     * Tool results logged into the currently open step. A result means the
+     * segment that requested the call is finished, so the next assistant content
+     * opens the next step (see {@link beginSegment}).
+     */
+    private stepSettledTools;
+    /**
+     * Whether the current query has rotated into a second step. The query-total
+     * usage record is only meaningful while one step holds the whole query.
+     */
+    private rotated;
     constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig);
     get status(): AgentStatus;
     /** Commit a phase and publish its externally visible status transition. */
@@ -96,6 +107,17 @@ export declare class ClaudeCodeAgent implements Agent {
     private queryPermission;
     /** Open one turn before claiming its first proposed step. */
     private turn;
+    /**
+     * Rotate to the next step when the segment that ran a tool has finished, so
+     * each assistant segment lands in its own step.
+     *
+     * Called as new assistant content begins. A step holding a settled tool
+     * result means the previous segment is complete, and the content about to be
+     * written belongs to the next one. Rotating here (rather than when a call is
+     * announced) keeps calls announced together — one model turn — in one step.
+     * @param phase - the running phase carrying the open step's position.
+     */
+    private beginSegment;
     /** Model label recorded in the request header for one lifecycle. */
     private modelLabel;
     /** Append the request header snapshot once per loop instance. */

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

@@ -7,11 +7,13 @@
  *
  * @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 { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import { ClaudeCodeAgent } from './agent.ts';
 import type { ClaudeCodePermissionMode, ResolvedConfig } from './types.ts';
+import { HostedLoopFactory } from '../driver-core/hosted-loop-factory.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. */
@@ -50,62 +52,11 @@ declare module '@deepseek-ai/cordis' {
  * transaction: prepare, run setup, then publish through both registries,
  * announce, and emit `agent/session-start`.
  */
-export declare class ClaudeCodeLoop extends Service implements AgentFactory {
+export declare class ClaudeCodeLoop extends HostedLoopFactory<ResolvedConfig, ClaudeCodeAgent> {
     /** 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. When a persistence backend is mounted, the session's
-     * durable identity is stored before publication.
-     * @param ownerCtx - caller context that structurally owns the lifecycle.
-     * @param options - identities, optional live parent, session seed/metadata, loop options, setup, and cancellation.
-     * @returns the published handle.
-     */
-    createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>;
-    /**
-     * Take a fresh session's write ownership when persistence is mounted.
-     * Nothing is appended here: the constructor seed (which never re-emits
-     * through `session/event`) is stored by {@link appendUnstoredSuffix} at the
-     * publication commit point, so a failed or cancelled setup closes an
-     * unmaterialized handle and leaves no stored residue — the same id can be
-     * created again.
-     * @param session - the unpublished session to store.
-     * @param signal - optional cancellation forwarded to the backend create.
-     * @returns the owned handle and stored cursor, or `undefined` without a backend.
-     */
-    private createStoredSession;
-    /**
-     * Durably store the session events appended since the last stored cursor.
-     * Pre-publication appends (constructor seed markers, setup-window events)
-     * never re-emit through `session/event`, so publication must flush them
-     * through the handle before live events start routing into it.
-     * @param stored - the session's owned handle and stored cursor, if any.
-     * @param session - the unpublished session whose suffix is stored.
-     */
-    private appendUnstoredSuffix;
-    /**
-     * 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, optional live parent, loop options, setup, and cancellation.
-     * @returns the published handle.
-     */
-    resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>;
-    /** Resume through an explicit persistence service. */
-    private resumeWith;
+    /** Construct the Claude Code driver for one prepared session. */
+    protected buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): ClaudeCodeAgent;
 }
 //# sourceMappingURL=loop.d.ts.map

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

@@ -6,7 +6,7 @@
  *
  * @module dsh-loop-engine/engine-claude/mapping
  */
-import type { BetaMessage, BetaRawMessageStreamEvent, BetaUsage } from '@anthropic-ai/sdk/resources/beta/messages/messages.mjs';
+import type { BetaMessage, BetaRawMessageStreamEvent } from '@anthropic-ai/sdk/resources/beta/messages/messages.mjs';
 import type { MessageParam } from '@anthropic-ai/sdk/resources';
 import { ToolCallId, type ContentBlock, type StreamChunk, type TokenUsage, type ToolResultMessage } from '@deepseek-ai/dsh-llm';
 /** One tool invocation surfaced from a Claude Code assistant message. */
@@ -54,13 +54,38 @@ export declare function mapAssistantMessage(message: BetaMessage): MappedAssista
  * @returns the mapped tool-result messages, in block order.
  */
 export declare function mapToolResults(message: MessageParam): ToolResultMessage[];
+/**
+ * The counters {@link mapUsage} reads. The SDK reports these on an assistant
+ * message's `usage`, on a stream `message_delta`'s narrower usage, and on the
+ * query `result`'s totals, so the parameter is the common shape rather than any
+ * one of those types.
+ */
+export interface ReportedUsage {
+    readonly input_tokens: number | null;
+    readonly output_tokens: number | null;
+    readonly cache_read_input_tokens?: number | null;
+    readonly cache_creation_input_tokens?: number | null;
+}
 /**
  * Translate SDK token accounting into the dsh token-usage shape. Cache
  * breakpoints are optional; absent or null SDK counters stay absent.
- * @param usage - SDK-reported usage for one assistant message.
+ * @param usage - SDK-reported usage for one assistant message, stream delta, or query result.
  * @returns dsh token accounting, omitting absent optional counters.
  */
-export declare function mapUsage(usage: BetaUsage): TokenUsage;
+export declare function mapUsage(usage: ReportedUsage): TokenUsage;
+/**
+ * Keep a usage sample only when it accounts for something.
+ *
+ * The SDK zero-fills `usage` on streamed assistant messages it cannot attribute
+ * (gateway-fronted models report the real counters on the stream's
+ * `message_delta` and the query's `result` instead). A sample with every bucket
+ * at zero is that placeholder, not a measurement: keeping it would both show an
+ * empty usage row and — because the token meter trusts a present sample over
+ * the stream — hide the real one.
+ * @param usage - a mapped usage sample, or undefined.
+ * @returns the sample when it is non-empty, otherwise undefined.
+ */
+export declare function meaningfulUsage(usage: TokenUsage | undefined): TokenUsage | undefined;
 /** Per-block-index tool-call identity captured at `content_block_start`, reused by `input_json_delta`. */
 export interface StreamToolCall {
     readonly callId: ToolCallId;

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

@@ -5,9 +5,11 @@
  * the source of truth and the thread input is a pure serialization of it.
  * The app-server streams token-level deltas via `item/agentMessage/delta` and
  * `item/reasoning/summaryTextDelta`, so the visible partial paints
- * progressively as the model generates — not all at once at the end. It offers
- * no interactive approval callback, so permissions are folded declaratively
- * into each thread's `sandboxMode`/`approvalPolicy`.
+ * progressively as the model generates — not all at once at the end. Native
+ * approval requests (the `item/…/requestApproval` family) are server-initiated
+ * requests, not notifications: the client answers them through the dsh approval
+ * seam (`agent/requestPermission` → `ctx.approval`), while the thread still
+ * starts with a declarative `sandboxMode`/`approvalPolicy` stance.
  *
  * @module dsh-loop-engine/engine-codex/agent
  */
@@ -38,11 +40,52 @@ export declare class CodexAgent implements Agent {
     private requestHeaderLogged;
     /** Agent-lifecycle-local counter naming each streamed attempt. */
     private streamAttempts;
+    /**
+     * Tool results logged into the currently open step. A result means the
+     * segment that requested the call is finished, so the next assistant content
+     * opens the next step (see {@link beginSegment}).
+     */
+    private stepSettledTools;
+    /**
+     * Rotate to the next step when the segment that ran a tool has finished, so
+     * each assistant segment lands in its own step.
+     *
+     * Called as new assistant content begins. A step holding a settled tool
+     * result means the previous segment is complete, and the content about to be
+     * written belongs to the next one. Rotating here (rather than when a call is
+     * announced) keeps calls announced together — one model turn — in one step.
+     * @param phase - the running phase carrying the open step's position.
+     */
+    private beginSegment;
     /** Lazily created app-server client, reused across steps and released on scope teardown. */
     private appServer;
     constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig);
     /** Return the cached app-server client, spawning one on first use or after a dead process. */
     private appServerClient;
+    /**
+     * Answer one server-initiated interaction. Approvals go through the dsh
+     * approval seam; a `request_user_input` question goes to the user-questions
+     * seam (both fail closed when their seam is absent), and an MCP elicitation is
+     * declined outright. Anything else is a protocol error.
+     * @param method - the server request method.
+     * @param params - the server request params.
+     * @returns the JSON-RPC outcome to send back.
+     */
+    private answerRequest;
+    /** Resolve one native Codex approval request through the dsh approval seam. */
+    private answerApproval;
+    /**
+     * Put one `request_user_input` question to the human through the dsh
+     * user-questions seam. The seam itself fails closed (`NO_PROVIDER`) when no
+     * answerer is composed, so a refusal degrades to "no answers given" and the
+     * turn continues; asking is never silently skipped, and the degradation is
+     * logged rather than swallowed.
+     * @param params - the request params carrying the questions.
+     * @returns the response payload (or the empty answer when nobody answered).
+     */
+    private answerUserInput;
+    /** Ask the dsh approval seam; fail closed to a denial when it is absent. */
+    private requestApproval;
     get status(): AgentStatus;
     /** Commit a phase and publish its externally visible status transition. */
     private setPhase;

package/lib/types/engine-codex/appserver/client.d.ts

@@ -8,6 +8,17 @@
 import type { InitializeResult, ThreadResumeParams, ThreadStartParams, ThreadStartResult, TurnInterruptParams, TurnStartParams, TurnStartResult } from './types.ts';
 /** Callback for receiving server notifications. */
 export type NotificationHandler = (method: string, params: unknown) => void;
+/** A JSON-RPC reply the client writes back for one inbound server request. */
+export type RequestOutcome = {
+    readonly result: unknown;
+} | {
+    readonly error: {
+        readonly code: number;
+        readonly message: string;
+    };
+};
+/** Callback answering one server-initiated JSON-RPC request. */
+export type RequestHandler = (method: string, params: unknown, id: number | string) => RequestOutcome | Promise<RequestOutcome>;
 /** Callback for receiving raw stderr lines from the server process. */
 export type StderrHandler = (line: string) => void;
 /** JSON-RPC client for the codex app-server. */
@@ -17,6 +28,7 @@ export declare class AppServerClient {
     private reqId;
     private pending;
     private notificationHandler;
+    private requestHandler;
     private stderrHandler;
     private disposed;
     /** Whether this client was disposed or its server process exited. */
@@ -27,6 +39,8 @@ export declare class AppServerClient {
     static create(): Promise<AppServerClient>;
     /** Set the notification handler for streaming events. */
     onNotification(handler: NotificationHandler): void;
+    /** Set the handler for server-initiated requests (e.g. approvals). */
+    onRequest(handler: RequestHandler): void;
     /** Set the stderr handler for server log lines. */
     onStderr(handler: StderrHandler): void;
     /** Send the initialize handshake. */
@@ -45,5 +59,7 @@ export declare class AppServerClient {
     private request;
     /** Handle one line of stdout from the server. */
     private handleLine;
+    /** Resolve one inbound server request and write the JSON-RPC reply to stdin. */
+    private answerRequest;
 }
 //# sourceMappingURL=client.d.ts.map