dsh-loop-engine 1.0.0-rc10

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

@@ -0,0 +1,135 @@
+/**
+ * Pi loop Agent: drives one session through turn and step boundaries by
+ * spawning a `pi --mode rpc` child process and speaking strict-LF JSONL over
+ * stdio. The dsh session log is the sole source of truth and each step runs one
+ * stateless Pi session (a fresh `new_session` + a single `prompt`), so the
+ * prompt is a pure serialization of the durable history plus the assembled dsh
+ * system prompt. Pi owns its tools natively but has no permission system, so
+ * the whole child is sandboxed by the dsh subprocess seam and its `--tools`
+ * are pruned to the resolved stance.
+ *
+ * @module dsh-loop-engine/engine-pi/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';
+import { type PiSpawnCapability } from './rpc/client.ts';
+/** Provider route label used for logged header snapshots and message provenance. */
+export declare const PROVIDER = "pi";
+/** Drives one session through turn and step boundaries on Pi. */
+export declare class PiAgent implements Agent {
+    private loopCtx;
+    readonly id: SessionId;
+    readonly options: AgentOptions;
+    readonly session: Session;
+    private readonly config;
+    private readonly spawn;
+    private readonly bin;
+    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;
+    /** Lazily created RPC client, reused across steps and released on scope teardown. */
+    private rpc;
+    /** The spawn spec the cached client was built from; a change forces a respawn. */
+    private lastSpec;
+    constructor(loopCtx: Context, id: SessionId, options: AgentOptions, session: Session, config: ResolvedConfig, spawn: PiSpawnCapability, bin: string);
+    /** Return the cached RPC client, respawning when the spec or process changed. */
+    private rpcClient;
+    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 runtime permission stance for one query. Deployment-pinned
+     * fields win; anything unpinned follows the session's durable dsh permission
+     * knobs, re-folded per query so mid-session preset switches take effect on the
+     * next step.
+     * @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;
+    /**
+     * The harness Session's web-side model selection, if any was stored. The
+     * durable `model/selection` event carries `{ provider, model, ... }`; when a
+     * user picked a model via `/model`, this is the newest pick, and it overrides
+     * the deployment config (which stays the fallback). Returns `undefined` when
+     * no selection was stored, so the deployment config governs.
+     */
+    private dynamicModel;
+    /** Build the `pi --mode rpc` argv/cwd/env for one step's child process. */
+    private spawnSpec;
+    /**
+     * Run one Pi RPC query for the current step and map its event stream into the
+     * session log. The step opens a fresh Pi session (`new_session`) and sends the
+     * serialized session history as one prompt, then consumes events until the
+     * agent settles. Like the Codex/Claude drivers, Pi owns its own system prompt
+     * natively, so the dsh system-prompt assembly (which pulls dsh tool schemas
+     * and `agent.ctx.tools`) is deliberately not run — the durable session log is
+     * the sole source of model context.
+     */
+    private step;
+    /** Append one Pi tool result to the durable log as a `tool/result` message. */
+    private appendToolResult;
+}
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +1,123 @@
+/**
+ * Pi loop engine module: hosts the AgentFactory that drives every session
+ * through the Pi CLI (`@earendil-works/pi-coding-agent`) over its JSONL RPC
+ * mode, one stateless session per dsh step, with the durable session log as the
+ * sole source of model context. dsh-loop-engine constructs this factory when
+ * the Pi engine is selected; this module is a library, not a Cordis plugin
+ * entry. Pi has no permission system, so the entire `pi --mode rpc` child is
+ * spawned through the dsh subprocess seam — the only available privilege
+ * boundary — and its `--tools` are pruned to the resolved sandbox stance.
+ *
+ * @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 { PiModelEntry } from './probe.ts';
+import type { PiProcess, PiSpawnSpec } from './rpc/client.ts';
+import type { PiSandboxMode, ResolvedConfig } from './types.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. */
+export declare const PI_DISPOSE_GRACE_MS = 3000;
+/** Deployment-owned configuration for the Pi loop plugin. */
+export interface Config {
+    /**
+     * Pinned sandbox stance for every RPC child. When omitted, each query follows
+     * the session's dsh permission knobs (`sandbox/mode` and `approval/policy`):
+     * full access runs native, `workspace-write` wraps the child in the dsh
+     * sandbox with a write-capable tool set, an `ask` policy degrades to a
+     * read-only denial, and anything else fails closed with `read-only`.
+     */
+    sandboxMode?: PiSandboxMode;
+    /** LLM provider for the `pi` child (`--provider`), when the deployment pins one. */
+    provider?: string;
+    /** Model pattern for the `pi` child (`--model`); Pi native settings own the model when omitted. */
+    model?: string;
+    /** Thinking/reasoning level, appended to the `--model` pattern when pinned. */
+    thinkingLevel?: string;
+    /** Explicit environment entries passed to the `pi` child. */
+    env?: Record<string, string>;
+    /** Shared Pi model catalog holder; the loop writes its `pi --list-models` probe result here. */
+    piCatalogHolder?: {
+        entries: readonly PiModelEntry[];
+    };
+}
+/** Schema of the Pi loop plugin configuration. */
+export declare const Config: z<Config>;
+/** Host-face ctx key for the Pi loop service. */
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoopPi: PiLoop;
+    }
+}
+/**
+ * Concrete AgentFactory and driver service of the Pi 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 PiLoop 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;
+    /** 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. */
+    readonly bin: string;
+    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, 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, 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=loop.d.ts.map

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

@@ -0,0 +1,43 @@
+/**
+ * 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;
+ *   - 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`.
+ *
+ * @module dsh-loop-engine/engine-pi/permission
+ */
+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. */
+    readonly sandboxMode: PiSandboxMode;
+    /** The `--tools` allowlist; empty means "use Pi's native tools" (no pruning). */
+    readonly tools: readonly string[];
+}
+/** Conservative unattended default: read-only sandbox, no write/exec tools. */
+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.
+ * @param mode - the resolved sandbox stance.
+ * @returns the tool set to pass as `--tools`.
+ */
+export declare function toolsForSandbox(mode: PiSandboxMode): readonly string[];
+/**
+ * Resolve the session's effective Pi runtime stance.
+ * @param events - the durable session log.
+ * @returns the stance one Pi RPC process should run under.
+ */
+export declare function resolveSessionPermission(events: readonly PermissionEvent[]): PiPermission;
+//# sourceMappingURL=permission.d.ts.map

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

@@ -0,0 +1,23 @@
+import type { PiProcess, PiSpawnSpec } from './rpc/client.ts';
+/** One discoverable Pi model: the raw two-part identity `pi` exposes. */
+export interface PiModelEntry {
+    readonly provider: string;
+    readonly model: string;
+}
+/**
+ * Parse the output of `pi --list-models`: a column-aligned table whose first
+ * two columns are `provider` and `model`. The header row and blank lines are
+ * skipped; long model ids simply occupy more columns. Splitting on 2+ spaces
+ * yields provider and model in the first two fields regardless of alignment.
+ */
+export declare function parsePiModelList(output: string): PiModelEntry[];
+/**
+ * Spawn `pi --list-models` and return the parsed model entries. Failures
+ * (non-zero exit, no stdout, spawn throw) resolve to an empty array so the
+ * catalog stays advisory and a probe glitch never breaks the engine mount.
+ * @param bin - the Pi CLI entrypoint (from `piCliEntrypoint()`); becomes spec.argv[0].
+ * @param spawn - the process-spawn adapter; `piSubprocessSpec` prepends the node
+ *   prefix, so spec.argv must NOT carry it.
+ */
+export declare function probePiModels(bin: string, spawn: (spec: PiSpawnSpec) => PiProcess): Promise<readonly PiModelEntry[]>;
+//# sourceMappingURL=probe.d.ts.map

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

@@ -0,0 +1,105 @@
+/**
+ * Strict-LF JSONL client for the Pi RPC subprocess (`pi --mode rpc`).
+ *
+ * The driver hands the client a process handle carrying its stdin/stdout/stderr
+ * (projected from the dsh subprocess seam, so the whole `pi` child is sandboxed
+ * by the harness). The client frames records on a bare `\n` only — not on
+ * Unicode separators — using a byte decoder, tolerates a trailing `\r`, and
+ * correlates command responses by the optional `id` field while dispatching
+ * every non-response line to a buffered event stream.
+ *
+ * @module dsh-loop-engine/engine-pi/rpc/client
+ */
+import type { ChildProcess } from 'node:child_process';
+import type { Readable, Writable } from 'node:stream';
+import type { PiCommand, PiEvent, PiResponse } from './types.ts';
+/** A spawned Pi RPC process as the protocol transport needs it. */
+export interface PiProcess {
+    /** Child stdin (command JSON lines). */
+    readonly stdin: Writable;
+    /** Child stdout (response + event JSON lines). */
+    readonly stdout: Readable;
+    /** Child stderr (diagnostics; buffered and dropped). */
+    readonly stderr: Readable;
+    /** Register a single human-readable termination callback. */
+    onExit(handler: () => void): void;
+    /** Request process-tree termination. */
+    terminate(): void;
+}
+/** The exact argv/cwd/env the driver requests for one `pi --mode rpc` child. */
+export interface PiSpawnSpec {
+    /** The program plus its flags; `argv[0]` is the Pi CLI entrypoint. */
+    readonly argv: readonly string[];
+    readonly cwd: string;
+    readonly env: Record<string, string>;
+}
+/** Spawns one Pi RPC process over the given spec (the driver's spawn capability). */
+export type PiSpawnCapability = (spec: PiSpawnSpec) => PiProcess;
+/** Callback receiving every non-response event line. */
+export type PiEventHandler = (event: PiEvent) => void;
+/** Options for one `prompt` command. */
+export interface PiPromptOptions {
+    readonly streamingBehavior?: 'steer' | 'followUp';
+}
+/** Project a `node:child_process` child onto the Pi protocol transport. */
+export declare function fromChildProcess(child: ChildProcess): PiProcess;
+/** Prompt the agent and stream its events. */
+export declare class PiRpcClient {
+    private readonly process;
+    private reqId;
+    private pending;
+    private readonly eventBuffer;
+    private eventWake;
+    private eventHandler;
+    private disposed;
+    private readonly decoder;
+    private buffer;
+    private readonly onStderr;
+    /** Whether this client was disposed or its process exited. */
+    get closed(): boolean;
+    /** Mount a client over an already-spawned Pi RPC process. */
+    constructor(process: PiProcess);
+    /**
+     * Create a client, spawning the Pi RPC child through the supplied capability
+     * (or the default node-runtime spawn when none is given).
+     * @param spec - the Pi CLI argv/cwd/env the child should run with.
+     * @param spawn - optional process-spawn capability (the subprocess seam);
+     *   absent falls back to the plain node child spawn.
+     * @returns the connected client.
+     */
+    static create(spec: PiSpawnSpec, spawn?: PiSpawnCapability): PiRpcClient;
+    /** Register the event dispatch handler. */
+    onEvent(handler: PiEventHandler): void;
+    /** Drop any events still buffered from a previous step (stateless per-step sessions). */
+    clearEvents(): void;
+    /** Start a fresh Pi session. */
+    newSession(): Promise<PiResponse>;
+    /** Prompt the agent and await the acceptance response. */
+    prompt(message: string, options?: PiPromptOptions): Promise<PiResponse>;
+    /** Abort the current agent operation. */
+    abort(): Promise<PiResponse>;
+    /** Query session stats. */
+    getSessionStats(): Promise<PiResponse>;
+    /** Send a command without awaiting its response (fire-and-forget). */
+    send(command: PiCommand): void;
+    /**
+     * Send a command and await the correlated response. Assigns a fresh `id`
+     * when the command carries none, so responses always round-trip.
+     */
+    request(command: PiCommand): Promise<PiResponse>;
+    /**
+     * Consume every buffered event as an async generator, waking as fresh lines
+     * arrive. The caller bounds the iteration by a terminal event; unmatched
+     * lines stay buffered for a later iteration.
+     */
+    events(): AsyncGenerator<PiEvent, void, void>;
+    /** Dispose the client and request child termination. */
+    dispose(): void;
+    /** Feed one chunk of stdout into the framing state machine. */
+    private feed;
+    /** Dispatch one parsed line to the pending map or the event queue. */
+    private dispatch;
+    /** Drain decoded stderr bytes (no-op consumer keeps the pipe flowing). */
+    private consumeStderr;
+}
+//# sourceMappingURL=client.d.ts.map

package/lib/types/engine-pi/rpc/mapping.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Maps Pi RPC messages and end-of-execution events to dsh session-log events.
+ * Token-level streaming deltas are folded inline by the driver's step loop
+ * (they carry live progress); this module projects the end-state items — a
+ * completed tool call, a completed tool execution, and a finished turn's usage
+ * — into the durable `tool/call`, `tool/result`, and usage events.
+ *
+ * @module dsh-loop-engine/engine-pi/rpc/mapping
+ */
+import type { TokenUsage, ToolResultMessage } from '@deepseek-ai/dsh-llm';
+import type { PiUsage } from './types.ts';
+/** Map one Pi usage snapshot to dsh TokenUsage. */
+export declare function mapUsage(usage: PiUsage): TokenUsage;
+/**
+ * Derive the compact transcript text of a Pi content block, joining nested
+ * text segments so the durable tool-result block carries the read model text.
+ * @param content - the result payload (e.g. `{ content: [{ type, text }, ...] }`).
+ * @returns the joined text.
+ */
+export declare function resultText(content: unknown): string;
+/** Map a completed Pi tool-execution end event to the durable tool/result message. */
+export declare function mapToolResult(ev: {
+    toolCallId: string;
+    result: unknown;
+    isError: boolean;
+}): ToolResultMessage;
+/** Map the identity of a Pi message tool call or execution start to a durable tool/call. */
+export declare function mapToolCall(ev: {
+    callId: string;
+    name: string;
+    arguments: unknown;
+}): {
+    callId: string;
+    name: string;
+    arguments: string;
+};
+//# sourceMappingURL=mapping.d.ts.map