dsh-loop-engine 1.0.0-rc2

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

@@ -0,0 +1,215 @@
+/**
+ * App-server protocol type definitions. A minimal subset of the types generated
+ * by `codex app-server generate-ts`, covering only what the driver needs for
+ * streaming (initialize, thread/start, turn/start, notifications).
+ *
+ * @module dsh-loop-engine/engine-codex/appserver/types
+ */
+/** A JSON-RPC 2.0 request sent to the app-server. */
+export interface JsonRpcRequest {
+    readonly jsonrpc: '2.0';
+    readonly id: number;
+    readonly method: string;
+    readonly params?: unknown;
+}
+/** A JSON-RPC 2.0 response (success or error). */
+export interface JsonRpcResponse {
+    readonly id: number;
+    readonly result?: unknown;
+    readonly error?: {
+        readonly code: number;
+        readonly message: string;
+    };
+}
+/** A JSON-RPC 2.0 notification (no id). */
+export interface JsonRpcNotification {
+    readonly method: string;
+    readonly params: unknown;
+}
+export interface InitializeParams {
+    readonly clientInfo: {
+        readonly name: string;
+        readonly title: string | null;
+        readonly version: string;
+    };
+    readonly capabilities: {
+        readonly experimentalApi: boolean;
+        readonly requestAttestation: boolean;
+    } | null;
+}
+export interface InitializeResult {
+    readonly userAgent: string;
+    readonly codexHome: string;
+    readonly platformFamily: string;
+    readonly platformOs: string;
+}
+/** Sandbox mode accepted by `thread/start`; unlike turn policies, this is a string enum. */
+export type SandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** Internally tagged sandbox override accepted by `turn/start`. */
+export type SandboxPolicy = {
+    readonly type: 'dangerFullAccess';
+} | {
+    readonly type: 'readOnly';
+    readonly networkAccess: boolean;
+} | {
+    readonly type: 'externalSandbox';
+    readonly networkAccess: 'restricted' | 'enabled';
+} | {
+    readonly type: 'workspaceWrite';
+    readonly writableRoots: readonly string[];
+    readonly networkAccess: boolean;
+    readonly excludeTmpdirEnvVar: boolean;
+    readonly excludeSlashTmp: boolean;
+};
+export interface ThreadStartParams {
+    readonly model?: string | null;
+    readonly modelProvider?: string | null;
+    readonly cwd?: string | null;
+    readonly approvalPolicy?: string | null;
+    readonly sandbox?: SandboxMode | null;
+    readonly ephemeral?: boolean | null;
+    readonly [key: string]: unknown;
+}
+export interface ThreadInfo {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly modelProvider: string;
+    readonly [key: string]: unknown;
+}
+export interface ThreadStartResult {
+    readonly thread: ThreadInfo;
+}
+export interface ThreadResumeParams {
+    readonly threadId: string;
+    readonly cwd?: string | null;
+    readonly approvalPolicy?: string | null;
+    readonly sandbox?: string | null;
+    readonly [key: string]: unknown;
+}
+export interface TurnStartParams {
+    readonly threadId: string;
+    readonly input: readonly TurnInput[];
+    readonly cwd?: string | null;
+    readonly approvalPolicy?: string | null;
+    readonly sandboxPolicy?: SandboxPolicy | null;
+    readonly model?: string | null;
+    readonly [key: string]: unknown;
+}
+export interface TurnInput {
+    readonly type: 'text';
+    readonly text: string;
+}
+export interface TurnInfo {
+    readonly id: string;
+    readonly status: string;
+    readonly error: {
+        readonly message: string;
+    } | null;
+    readonly items: readonly unknown[];
+    readonly [key: string]: unknown;
+}
+export interface TurnStartResult {
+    readonly turn: TurnInfo;
+}
+export interface TurnInterruptParams {
+    readonly threadId: string;
+    readonly turnId: string;
+}
+/** item/agentMessage/delta — agent message token delta. */
+export interface AgentMessageDeltaNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly itemId: string;
+    readonly delta: string;
+}
+/** item/reasoning/summaryTextDelta — reasoning summary token delta. */
+export interface ReasoningSummaryTextDeltaNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly itemId: string;
+    readonly delta: string;
+    readonly summaryIndex: number;
+}
+/** item/reasoning/textDelta — reasoning content token delta. */
+export interface ReasoningTextDeltaNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly itemId: string;
+    readonly delta: string;
+    readonly contentIndex: number;
+}
+/** item/plan/delta — plan delta. */
+export interface PlanDeltaNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly itemId: string;
+    readonly delta: string;
+}
+/** item/started — item lifecycle start. */
+export interface ItemStartedNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly item: {
+        readonly type: string;
+        readonly id: string;
+        readonly [key: string]: unknown;
+    };
+    readonly startedAtMs: number;
+}
+/** item/completed — item lifecycle end. */
+export interface ItemCompletedNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly item: {
+        readonly type: string;
+        readonly id: string;
+        readonly text?: string;
+        readonly [key: string]: unknown;
+    };
+    readonly completedAtMs: number;
+}
+/** turn/completed — turn end with usage. */
+export interface TurnCompletedNotification {
+    readonly threadId: string;
+    readonly turn: TurnInfo & {
+        readonly usage?: {
+            readonly inputTokens: number;
+            readonly cachedInputTokens?: number;
+            readonly outputTokens: number;
+            readonly reasoningOutputTokens?: number;
+        };
+    };
+}
+/** thread/tokenUsage/updated — token usage update. */
+export interface ThreadTokenUsageUpdatedNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly tokenUsage: {
+        readonly total: {
+            readonly totalTokens: number;
+            readonly inputTokens: number;
+            readonly cachedInputTokens: number;
+            readonly outputTokens: number;
+            readonly reasoningOutputTokens: number;
+        };
+        readonly last: {
+            readonly totalTokens: number;
+            readonly inputTokens: number;
+            readonly cachedInputTokens: number;
+            readonly outputTokens: number;
+            readonly reasoningOutputTokens: number;
+        };
+    };
+}
+/** error notification. */
+export interface ErrorNotification {
+    readonly threadId: string;
+    readonly turnId: string;
+    readonly error: {
+        readonly message: string;
+        readonly codexErrorInfo?: string | null;
+        readonly additionalDetails?: string | null;
+    };
+    readonly willRetry: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,92 @@
+/**
+ * Codex loop engine module: hosts the AgentFactory that drives every session
+ * through the OpenAI Codex SDK, one stateless thread per dsh step, with the
+ * durable session log as the sole source of model context. dsh-loop-engine
+ * constructs this factory when the Codex engine is selected; this module is a
+ * library, not a Cordis plugin entry. The Codex SDK spawns its own CLI binary
+ * (no spawn injection seam), so this loop deliberately does not inject the dsh
+ * subprocess service.
+ *
+ * @module dsh-loop-engine/engine-codex
+ */
+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 { CodexApprovalPolicy, CodexSandboxMode, ResolvedConfig } from './types.ts';
+/** Codex CLI sandbox modes a deployment may pin. */
+export declare const CODEX_SANDBOX_MODES: readonly CodexSandboxMode[];
+/** Codex CLI approval policies a deployment may pin. */
+export declare const CODEX_APPROVAL_POLICIES: readonly CodexApprovalPolicy[];
+/** Deployment-owned configuration for the Codex loop plugin. */
+export interface Config {
+    /**
+     * Pinned sandbox mode for every thread. When omitted, each query follows the
+     * session's dsh permission knobs (`sandbox/mode` and `approval/policy`):
+     * full access maps to `danger-full-access`, an `ask` policy maps to
+     * `workspace-write`, and anything else fails closed with `read-only`.
+     */
+    sandboxMode?: CodexSandboxMode;
+    /**
+     * Pinned approval policy for every thread. When omitted, each query follows
+     * the session's dsh permission knobs: an `ask` policy maps to `on-request`
+     * (the CLI's own interactive prompt degrades to a denial in the unattended
+     * dsh runtime) and anything else maps to `never`.
+     */
+    approvalPolicy?: CodexApprovalPolicy;
+    /** Explicit environment entries layered over the credential-scrubbed parent environment. */
+    env?: Record<string, string>;
+    /** Model override for the SDK; Codex native settings own the model when omitted. */
+    model?: string;
+}
+/** Schema of the Codex loop plugin configuration. */
+export declare const Config: z<Config>;
+/** Host-face ctx key for the Codex loop service. */
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoopCodex: CodexLoop;
+    }
+}
+/**
+ * Concrete AgentFactory and driver service of the Codex 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 CodexLoop 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

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

@@ -0,0 +1,32 @@
+/**
+ * Mapping from the dsh session's durable permission knobs to one Codex query's
+ * declarative permission stance. Codex has no interactive approval callback:
+ * permissions are the `sandboxMode` + `approvalPolicy` pair chosen when the
+ * thread starts, so the fold maps the session's `sandbox/mode` and
+ * `approval/policy` events directly, mirroring the web surface's presets:
+ *   - full access → `danger-full-access` + `never` (no native checks at all),
+ *   - an `ask` policy → `workspace-write` + `on-request` (the CLI's own
+ *     interactive prompt degrades to a denial in the unattended dsh runtime),
+ *   - anything else fails closed → `read-only` + `never`.
+ *
+ * @module dsh-loop-engine/engine-codex/permission
+ */
+import type { PermissionEvent } from '../driver-core/permission-knobs.ts';
+import type { CodexApprovalPolicy, CodexSandboxMode } from './types.ts';
+/** The declarative permission stance one Codex thread runs under. */
+export interface CodexPermission {
+    readonly sandboxMode: CodexSandboxMode;
+    readonly approvalPolicy: CodexApprovalPolicy;
+}
+/** Conservative unattended default: read-only sandbox, never ask. */
+export declare const DEFAULT_CODEX_PERMISSION: CodexPermission;
+/**
+ * Resolve the session's effective Codex permission stance. Full access wins
+ * outright; otherwise an `ask` policy maps to the CLI's on-request approval
+ * inside a workspace-write sandbox; anything else — including a session with
+ * no recorded knobs — fails closed.
+ * @param events - the durable session log.
+ * @returns the stance one query should run under.
+ */
+export declare function resolveSessionPermission(events: readonly PermissionEvent[]): CodexPermission;
+//# sourceMappingURL=permission.d.ts.map

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

@@ -0,0 +1,26 @@
+/**
+ * Codex skill provider: exposes the codex CLI's instruction files as DSH
+ * skills. Codex has no per-skill catalog like Claude Code's `.claude/skills/`;
+ * it reads project and user instruction files named `AGENTS.md`. Each found
+ * `AGENTS.md` is surfaced as a single user-invocable skill whose content is
+ * the file body, so the dsh skill-injection seam (`/name` gestures) can carry
+ * it into the prompt.
+ *
+ * @module dsh-loop-engine/engine-codex/skills
+ */
+import { type SkillCandidate, type SkillDefinition, type SkillLookupOptions, type SkillProvider, type SkillProviderControl } from '../skills.ts';
+/**
+ * Skill provider that discovers `AGENTS.md` from the project root (git root
+ * when one exists) and the user home `~/.codex/AGENTS.md`.
+ */
+export declare class CodexSkillProvider implements SkillProvider {
+    private readonly control;
+    readonly name = "codex";
+    constructor(control: SkillProviderControl);
+    list(options: SkillLookupOptions): Promise<readonly SkillCandidate[]>;
+    get(candidate: SkillCandidate, _options: SkillLookupOptions): Promise<SkillDefinition | undefined>;
+    /** Read one AGENTS.md file and push a candidate when it exists. */
+    private collectAgentsMd;
+}
+export default CodexSkillProvider;
+//# sourceMappingURL=skills.d.ts.map

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

@@ -0,0 +1,19 @@
+/**
+ * Public types of the Codex loop driver. Types only — no runtime code.
+ *
+ * @module dsh-loop-engine/engine-codex/types
+ */
+/** Codex CLI sandbox modes, as spoken by the app-server `sandbox` field. */
+export type CodexSandboxMode = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** Codex CLI approval policies, as spoken by the app-server `approvalPolicy` field. */
+export type CodexApprovalPolicy = 'never' | 'on-request' | 'on-failure' | 'untrusted';
+/** Driver configuration after defaults and load-time validation. */
+export interface ResolvedConfig {
+    /** Pinned sandbox mode; `undefined` follows the session's dsh permission knobs per query. */
+    readonly sandboxMode: CodexSandboxMode | undefined;
+    /** Pinned approval policy; `undefined` follows the session's dsh permission knobs per query. */
+    readonly approvalPolicy: CodexApprovalPolicy | undefined;
+    readonly env: Record<string, string>;
+    readonly model: string | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1,125 @@
+/**
+ * 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';
+/** 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;
+    /** 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,96 @@
+/**
+ * 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 { 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>;
+}
+/** 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.
+     * @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

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