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

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

@@ -42,14 +42,33 @@ export declare class PiAgent implements Agent {
     private requestHeaderLogged;
     /** Agent-lifecycle-local counter naming each streamed attempt. */
     private streamAttempts;
-    /** Lazily created RPC client, reused across steps and released on scope teardown. */
+    /** This step's RPC child; released by the step teardown and the scope teardown. */
     private rpc;
-    /** The spawn spec the cached client was built from; a change forces a respawn. */
-    private lastSpec;
+    /**
+     * 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 at a message boundary keeps calls
+     * announced together — one model turn — in one step.
+     * @param phase - the running phase carrying the open step's position.
+     */
+    private beginSegment;
     constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig, spawn: PiSpawnCapability, bin: string, catalog: {
         readonly entries: readonly PiModelEntry[];
     });
-    /** Return the cached RPC client, respawning when the spec or process changed. */
+    /**
+     * Open this step's RPC child. The Pi RPC process is single-session, so a step
+     * never reuses one: the step teardown disposes it and the next step respawns
+     * a fresh child.
+     */
     private rpcClient;
     get status(): AgentStatus;
     /** Commit a phase and publish its externally visible status transition. */

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

@@ -10,13 +10,15 @@
  *
  * @module dsh-loop-engine/engine-pi
  */
-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 { PiAgent } from './agent.ts';
 import type { PiModelEntry } from './probe.ts';
 import type { PiProcess, PiSpawnSpec } from './rpc/client.ts';
 import type { PiSandboxMode, ResolvedConfig } from './types.ts';
+import { HostedLoopFactory } from '../driver-core/hosted-loop-factory.ts';
 /** Pi CLI sandbox modes a deployment may pin. */
 export declare const PI_SANDBOX_MODES: readonly PiSandboxMode[];
 /** Grace in milliseconds for Pi process-tree termination. */
@@ -58,14 +60,9 @@ declare module '@deepseek-ai/cordis' {
  * prepare, run setup, then publish through both registries, announce, and emit
  * `agent/session-start`.
  */
-export declare class PiLoop extends Service implements AgentFactory {
+export declare class PiLoop extends HostedLoopFactory<ResolvedConfig, PiAgent> {
     /** 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;
     /** Process-tree spawn capability handed to every agent, sandboxed by the subprocess seam. */
     readonly spawn: (spec: PiSpawnSpec) => PiProcess;
     /** Resolved Pi CLI entrypoint; `argv[0]` of every Pi RPC child. */
@@ -73,53 +70,7 @@ export declare class PiLoop extends Service implements AgentFactory {
     /** Discovered Pi model catalog, forwarded to each agent so it can validate the session-selected model against what pi can actually serve. */
     private readonly catalog;
     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 Pi RPC driver for one prepared session. */
+    protected buildAgent(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session): PiAgent;
 }
 //# sourceMappingURL=loop.d.ts.map

package/lib/types/engine-pi/permission.d.ts

@@ -2,13 +2,12 @@
  * Mapping from the dsh session's durable permission knobs to one Pi RPC
  * process's runtime stance. Pi carries no native permission system — "runs
  * with the permissions of the user" — so the driver cannot ask it to sandbox or
- * approve. The only available boundary is the process environment: the driver
- * either wraps the whole `pi --mode rpc` child in the dsh subprocess sandbox
- * and prunes its `--tools`, or (full access) lets it run under the dsh user.
- * The fold mirrors the codex bridge, mapping the session's `sandbox/mode` and
- * `approval/policy` events directly:
- *   - full access → `danger-full-access`, no tool pruning (native tools);
- *   - `workspace-write` → sandbox wrap with a write-capable tool set;
+ * approve. What is left is the `--tools` allowlist: the child runs under the
+ * dsh user either way (the subprocess seam carries no confinement of its own),
+ * so withholding a tool IS the stance. The fold mirrors the codex bridge,
+ * mapping the session's `sandbox/mode` and `approval/policy` events directly:
+ *   - full access → `danger-full-access`, no pruning (Pi's native tools);
+ *   - `workspace-write` → a write-capable set, still without a shell;
  *   - an `ask` policy → degraded to a read-only denial (Pi has no request
  *     callback, so interactive approval can only become a rejection);
  *   - anything else fails closed → `read-only`.
@@ -19,17 +18,22 @@ import type { PermissionEvent } from '../driver-core/permission-knobs.ts';
 import type { PiSandboxMode } from './types.ts';
 /** The runtime stance one Pi RPC process should run under. */
 export interface PiPermission {
-    /** Sandbox mode driving whether the child is wrapped in the dsh sandbox. */
+    /** The resolved sandbox stance; selects the tool set, not a process sandbox. */
     readonly sandboxMode: PiSandboxMode;
-    /** The `--tools` allowlist; empty means "use Pi's native tools" (no pruning). */
+    /** The `--tools` allowlist — the stance's only enforcement; empty means no pruning. */
     readonly tools: readonly string[];
 }
-/** Conservative unattended default: read-only sandbox, no write/exec tools. */
+/**
+ * Conservative unattended default: read-only sandbox, no write/exec tools. The
+ * allowlist names pi's built-ins (`read`, `bash`, `edit`, `write`) and nothing
+ * else — a name pi does not know matches no tool at all, silently, so a list
+ * carrying invented entries would enforce less than it claims to.
+ */
 export declare const DEFAULT_PI_PERMISSION: PiPermission;
 /**
  * Derive the `--tools` allowlist for a given sandbox stance. Full access prunes
- * nothing; `workspace-write` allows a write-capable set; `read-only` allows read
- * and search only.
+ * nothing; `workspace-write` allows a write-capable set; `read-only` allows
+ * reading and nothing else. Only pi's own built-in tool names appear here.
  * @param mode - the resolved sandbox stance.
  * @returns the tool set to pass as `--tools`.
  */

package/lib/types/engine-pi/skills.d.ts

@@ -19,9 +19,13 @@
  * at composition time — the filesystem subset above is authoritative for the
  * web menu.
  *
+ * The discovery algorithm itself lives in {@link AgentsMdSkillProvider}; this
+ * module supplies only Pi's locations and ranks.
+ *
  * @module dsh-loop-engine/engine-pi/skills
  */
-import type { SkillCandidate, SkillDefinition, SkillLookupOptions, SkillProvider, SkillProviderControl } from '../skills.ts';
+import { AgentsMdSkillProvider } from '../driver-core/agents-md-skill-provider.ts';
+import type { SkillProviderControl } from '../skills.ts';
 /**
  * Resolve the pi config directory, honoring the `PI_CODING_AGENT_DIR`
  * environment override and falling back to `~/.pi/agent`.
@@ -36,20 +40,8 @@ export declare function piAgentDir(): string;
  *   - project `.pi/skills/` and user `~/.pi/agent/skills/` — each `SKILL.md`
  *     entry surfaced under its own name.
  */
-export declare class PiSkillProvider implements SkillProvider {
-    private readonly control;
-    readonly name = "pi";
+export declare class PiSkillProvider extends AgentsMdSkillProvider {
     constructor(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 pi 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;
 }
 export default PiSkillProvider;
 //# sourceMappingURL=skills.d.ts.map

package/lib/types/patch-manager.d.ts

@@ -42,6 +42,13 @@ export declare const MANAGED_BLOCK_END = "# -- /dsh-loop-engine managed block --
 export declare function renderManagedBlock(engine: LoopEngineId): string;
 /** Whether a patch-file text contains the managed block span. */
 export declare function hasManagedBlock(text: string): boolean;
+/**
+ * The engine id the managed block's begin marker names, when this build knows
+ * it. `undefined` covers both "no managed block" and "the block names an engine
+ * this build does not recognize" — the second being the state where the block
+ * still disables the base `agent-loop` row while no factory can take the slot.
+ */
+export declare function managedBlockEngineOf(text: string): LoopEngineId | undefined;
 /** Derive the current engine from a patch-file text by the managed block's begin marker. */
 export declare function currentEngineOf(text: string): LoopEngineId;
 /**

package/lib/types/provider-route.d.ts

@@ -7,8 +7,9 @@
  * host derives a session's model selection from that header and refuses a turn
  * whose provider no registered adapter serves, so without a placeholder route
  * the SECOND prompt of every hosted session fails with `model-unavailable`.
- * The placeholder serves the label while advertising no models; catalog groups
- * that advertise nothing are dropped, so the model picker is unchanged.
+ * The placeholder serves the label and advertises no models unless a deployment
+ * injects a catalog (only `pi` does, from its model probe); catalog groups that
+ * advertise nothing are dropped, so the picker is otherwise unchanged.
  *
  * @module dsh-loop-engine/provider-route
  */
@@ -29,10 +30,11 @@ export interface HostedEngineRouteAdapterOptions {
 }
 /**
  * Placeholder adapter serving one hosted engine's provider route label. It
- * inherits the empty catalog and default metadata (the engine's model is not a
- * harness-selectable endpoint), and {@link stream} fails loud: a call reaching
- * it means a real model query was routed to an engine that owns its model
- * natively — a wiring bug, not a request to serve.
+ * advertises the injected catalog when a deployment provides one and stays
+ * empty otherwise (the engine's model is not itself a harness-selectable
+ * endpoint), and {@link stream} fails loud: a call reaching it means a real
+ * model query was routed to an engine that owns its model natively — a wiring
+ * bug, not a request to serve.
  */
 export declare class HostedEngineRouteAdapter extends LlmAdapter {
     private readonly label;
@@ -42,7 +44,14 @@ export declare class HostedEngineRouteAdapter extends LlmAdapter {
      * @param options - optional catalog source; omit for an empty catalog.
      */
     constructor(label: string, options?: HostedEngineRouteAdapterOptions);
-    /** Advertise the injected Pi models (if any) under this route's provider label. */
+    /**
+     * Advertise the injected Pi models (if any) under this route's provider label.
+     *
+     * The model is what the picker shows at the top level, so `name` is the bare
+     * model; the `provider/model` composite stays the submitted `id`, which is
+     * both what the engine receives as `--model` and how the driver validates a
+     * session-selected model against its catalog.
+     */
     listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
     stream(_options: GenerateOptions): AsyncIterable<StreamChunk>;
 }

package/lib/types/settings.d.ts

@@ -24,7 +24,10 @@ export interface LoopEngineSettings {
     /** Whether the composer's loop engine picker is shown on the chat page. */
     showInComposer: boolean;
 }
-/** Schema of the loop engine settings section. */
+/**
+ * Schema of the loop engine settings section. The engine union derives from
+ * {@link LOOP_ENGINE_IDS}, so adding an engine there also admits it here.
+ */
 export declare const LOOP_ENGINE_SETTINGS_SCHEMA: z<LoopEngineSettings>;
 /** The shared literal branded as a settings namespace on the node side. */
 export declare function loopEngineSettingsNamespace(): SettingsNamespace;

package/lib/types/skills.d.ts

@@ -6,6 +6,7 @@
  *
  * @module dsh-loop-engine/skills
  */
+import type { SkillDefinition } from './driver-core/skill-inject.ts';
 export interface SkillInvocationPolicy {
     readonly modelInvocable: boolean;
     readonly userInvocable: boolean;
@@ -26,20 +27,11 @@ export interface SkillCandidate {
         readonly path: string;
     };
 }
-export interface SkillDefinition {
-    readonly name: string;
-    readonly description: string;
-    readonly whenToUse?: string;
-    readonly invocation: SkillInvocationPolicy;
-    readonly source: SkillSource;
-    readonly provider: string;
-    readonly content: string;
-    readonly path?: string;
-    readonly resourceBase?: {
-        readonly kind: string;
-        readonly path: string;
-    };
-}
+/**
+ * The providers' loaded-skill shape is the driver-core one, so the skill
+ * providers and the engine agents that consume them cannot drift apart.
+ */
+export type { SkillDefinition } from './driver-core/skill-inject.ts';
 export interface SkillLookupOptions {
     readonly cwd?: string;
     readonly signal?: AbortSignal;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-loop-engine",
   "description": "Web-switchable agent loop engine selection for the DeepSeek Harness - out-of-tree plugin (Claude Code / Codex / Pi / Kimi Code drivers) maintained by @kuun993, zero main-repo changes",
-  "version": "0.1.5-rc1",
+  "version": "0.1.5-rc2",
   "publishConfig": {
     "access": "public"
   },