dsh-loop-engine-allinone 0.0.0-stage → 0.4.1

package/lib/types/engine-minimaxcode/profile.d.ts

@@ -0,0 +1,72 @@
+/**
+ * MiniMax Code's ACP dialect: the shared ACP body with mcode's own handshake.
+ *
+ * Measured against MiniMax Code 0.6.12 on this fork's reference host (raw frames
+ * with `scripts/probe/acp-handshake.mjs`), and the reason each hook below exists:
+ *
+ *   1. `initialize` answers `protocolVersion: 1`, advertises NO auth method (the
+ *      CLI reads its own `~/.minimax/auth/prod/<region>/…` state and its
+ *      subscription is chosen with `mcode provider use token-plan`), and reports
+ *      `promptCapabilities.image: true` — so this engine does receive image blocks;
+ *   2. `session/new` succeeds WITHOUT a prior `authenticate` and answers a
+ *      `sessionId`, ACP `modes` (`default`/`plan`), and `configOptions` for
+ *      `permissionMode`, `model` and `thinkingEffort`. The model ids are the
+ *      engine's own composite form (`m:minimax:MiniMax-M3:v:thinking`);
+ *   3. a model or permission is changed with `session/set_config_option` and a BARE
+ *      value (`value: 'm:…'`) — the `{ value }` wrapper that Grok's documentation
+ *      shows is REJECTED here with `-32602 Invalid params`. `session/set_model`
+ *      does not exist on this engine at all (`-32601 Method not found`), which is
+ *      why the shared driver's model selection is a profile hook;
+ *   4. `session/load` is accepted, so engine-side resume exists even though this
+ *      driver replays the durable transcript and opens a fresh session per step.
+ *
+ * ## The permission fold
+ *
+ * The engine's `permissionMode` option is its own gate (`default` = Ask,
+ * `auto` = Auto, `bypassPermissions` = Full access). The driver maps the session's
+ * dsh approval knob onto it only where the knob is decisive — `never` becomes
+ * `bypassPermissions` and `ask` becomes `default` — and otherwise LEAVES the
+ * engine's own default alone (`auto`), rather than inventing a policy the user
+ * never chose. Whatever the engine still asks for arrives as the reverse-RPC
+ * `session/request_permission`, answered by the shared fold.
+ *
+ * @module dsh-loop-engine-allinone/engine-minimaxcode/profile
+ */
+import type { AcpEngineProfile } from '../driver-acp/profile.ts';
+import type { Session } from '@deepseek-ai/dsh-session';
+/** The engine's model config option id, as `session/new` advertises it. */
+export declare const MCODE_MODEL_CONFIG_ID = "model";
+/** The engine's tool-permission config option id (category `_permission`). */
+export declare const MCODE_PERMISSION_CONFIG_ID = "permissionMode";
+/**
+ * The engine's `permissionMode` value for one session's dsh approval knob.
+ *
+ * ALWAYS decisive, never "leave the engine's default alone". That default is not
+ * a safe resting state: `session/new` on this engine reports the option's
+ * `currentValue` from whatever the CLI last persisted in `~/.minimax/config.yaml`,
+ * and a previous run — including a probe, measured on this fork's reference
+ * host — can leave `bypassPermissions` there. A driver that only spoke when the
+ * knob was decisive would then inherit Full access for a session that asked for
+ * nothing of the sort.
+ *
+ * The mapping itself follows the shared fold's semantics:
+ *   - `never` (auto-approve) means the human is not in the loop at all, so the
+ *     engine is told its most permissive mode rather than asking a gate that
+ *     would always answer yes;
+ *   - `ask` means there IS no human in the unattended runtime, so the engine's Ask
+ *     mode is selected and the reverse-RPC fold denies — fail-closed, exactly like
+ *     the kimi and codex bridges;
+ *   - an unset knob is not a choice, so the engine's own middle mode is selected:
+ *     it may still ask, and the fold (which approves under this policy) answers.
+ *
+ * KNOWN SIDE EFFECT, documented rather than hidden: this option is
+ * process-scoped, and the engine persists it, so setting it here rewrites the
+ * user's `~/.minimax/config.yaml`. Stating the mode per session is the price of
+ * never inheriting a stale Full-access default.
+ * @param session - the session whose durable knobs are read.
+ * @returns the `permissionMode` value to set.
+ */
+export declare function mcodePermissionMode(session: Session): string;
+/** MiniMax Code's ACP dialect, as the shared driver reads it. */
+export declare function minimaxcodeProfile(bin: string): AcpEngineProfile;
+//# sourceMappingURL=profile.d.ts.map

package/lib/types/engine-of-session.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The engine one session runs: the single authoritative read, shared by the
+ * router's routing decision and the plugin's own Remote.
+ *
+ * Two facts can answer it, in this order:
+ *
+ *  1. THE PLUGIN'S OWN RECORD — `$DSH_HOME/.loop-engine/engines.json` (see
+ *     `./session-engine-store.ts`). It exists because a user may move a session
+ *     to another engine at any time, including long after the session started,
+ *     and the harness's preset channel refuses exactly that
+ *     (`agent-preset/locked`), so the plugin keeps the choice itself. When the
+ *     record names an engine, that IS the session's engine and nothing else is
+ *     consulted — not even the durable log, which is why a session with a record
+ *     still reads correctly when its persistence is unavailable.
+ *  2. THE RECORDED AGENT PRESET, for every session the plugin has no record
+ *     for: a session created before per-session switching existed, one created
+ *     on a preset this plugin does not own, or one in a deployment whose record
+ *     file is gone. That answer comes from the durable log — the harness's
+ *     `agentPreset` projection folds the session header together with every
+ *     committed `agent-preset/selected`, so reading it IS reading the log — and
+ *     it never comes from the session header alone (a creation fact, deep-frozen)
+ *     or from a client-side listing hint (a partial cache).
+ *
+ * This module is the ONLY read: the router routes on what it returns and the
+ * plugin's own Remote reports the same value, so the engine a session is driven
+ * by and the engine it is shown as running cannot disagree.
+ *
+ * There is one refinement on top of it, and it is the whole reason
+ * {@link engineReportOfSession} exists: a session with a LIVE agent has a better
+ * answer than its record — the agent in front of it — and the two can differ
+ * (only when a release of that agent did not take, since every other switch
+ * either swaps the agent in place or leaves the session cold). The report
+ * carries both, never blending them (see {@link SessionEngineReport}).
+ *
+ * The secondary read goes through the same seam the host itself uses before
+ * choosing the composition to mount
+ * (`ctx.sessionQuery.observeSession(id, { projectionMode: 'all' })`, see
+ * `packages/api/session-controller/src/agent.ts` in the harness). The
+ * observation is a read-only lease: it is released immediately through `using`,
+ * takes no write handle, and holds no write lock.
+ *
+ * @module dsh-loop-engine-allinone/engine-of-session
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import { type LoopEngineId, type SessionEngine, type SessionEngineReport } from './agent-preset-ids.ts';
+import type { EngineRecordSource } from './session-engine-store.ts';
+/**
+ * The engine one session runs, read from the plugin's own record first and from
+ * the durable `agentPreset` projection otherwise.
+ *
+ * A deployment that composes no `sessionQuery` service has no durable log to
+ * ask, so a session with no record reads as {@link SessionEngine} `unset`: no
+ * engine is claimed for it, and the router falls back exactly as it does for a
+ * session that recorded nothing.
+ * @param ctx - the context carrying the session-query seam.
+ * @param sessionId - the persisted session to inspect.
+ * @param records - the plugin's own per-session engine record.
+ * @returns what the plugin's record, or else the durable log, says about that
+ * session's engine.
+ */
+export declare function engineOfSession(ctx: Context, sessionId: SessionId, records: EngineRecordSource): Promise<SessionEngine>;
+/**
+ * Reports the engine of one session's LIVE agent, when this process has one:
+ * the loop router's own bookkeeping (`RouterLoop.live`), which is the only
+ * record of what it actually built for a session.
+ *
+ * A reader rather than the router itself, so this fold can be exercised without
+ * one — and so the router stays the only thing that owns its bookkeeping.
+ */
+export type LiveEngineReader = (sessionId: SessionId) => LoopEngineId | undefined;
+/**
+ * What one session actually runs, and — when they differ — the engine its own
+ * record names.
+ *
+ * The live agent outranks the record, because it is the answer to the question
+ * this report exists to answer honestly: what is driving this session NOW. The
+ * record is still consulted, but as the OTHER fact — the engine this session
+ * takes when it is next built. A record that equals the live agent is no news
+ * and travels as absent; a live agent with no record at all has nothing to
+ * report beside it, because a session with no record was never switched.
+ *
+ * A session with NO live agent answers exactly as {@link engineOfSession} does:
+ * nothing is running, so the record (or, with no record, the recorded preset) IS
+ * the engine that session runs — the one its next build will use, which is the
+ * state a switch that released the session's agent leaves it in. There is no
+ * second fact to report and never a pending one.
+ * @param ctx - the context carrying the session-query seam.
+ * @param sessionId - the session to report on.
+ * @param records - the plugin's own per-session engine record.
+ * @param liveEngineOf - the engine of this session's live agent, when this
+ * process has one (the router's bookkeeping).
+ * @returns the engine driving the session, plus the recorded engine it is not
+ * running when the two differ.
+ */
+export declare function engineReportOfSession(ctx: Context, sessionId: SessionId, records: EngineRecordSource, liveEngineOf: LiveEngineReader): Promise<SessionEngineReport>;
+//# sourceMappingURL=engine-of-session.d.ts.map

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

@@ -0,0 +1,230 @@
+/**
+ * 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-allinone/engine-pi/agent
+ */
+import type { Agent, AgentCancelCause, AgentOptions, AgentStatus, CancelOptions, InboxTarget } 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 { DriverInbox } from '../driver-core/inbox.ts';
+import { type PiSpawnCapability } from './rpc/client.ts';
+/**
+ * Provider route label this driver logs into request/header snapshots and
+ * message provenance — the ONE route every hosted engine shares
+ * ({@link HOSTED_ROUTE_LABEL}), so all four engines select `external/default`
+ * and the model menu carries a single group instead of one per engine.
+ */
+export declare const PROVIDER = "external";
+/** 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: DriverInbox;
+    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;
+    /** Agent-lifecycle-local counter naming each streamed attempt. */
+    private streamAttempts;
+    /** This step's RPC child; released by the step teardown and the scope teardown. */
+    private rpc;
+    /**
+     * Resolves the read-only path behind each image block of the prompt. The
+     * attachment service is read lazily on every call, so a host that composes it
+     * after this agent still reaches the transcript.
+     */
+    private readonly imageAccess;
+    /**
+     * 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;
+    /**
+     * The current step's calls, and which of them already carry a result.
+     *
+     * Pi announces a call from its streamed assistant message and reports the
+     * outcome from a separate execution event, so "which calls of THIS step are
+     * still open" is state the driver has to keep. Both halves of the Session V4
+     * rule read it: a call may not be given a second result in one step, and a
+     * step may not end while a call it announced has no result at all — the
+     * closing pass writes the missing outcome instead ({@link closeStep}).
+     *
+     * Reset per step (see {@link step}), never on an internal segment rotation:
+     * call ids are unique for the life of the session, so retaining the marks only
+     * widens duplicate suppression and can never hide a legitimate result.
+     */
+    private readonly stepTools;
+    /**
+     * 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.
+     *
+     * A step that still OWES a result does not rotate: Pi announces several calls
+     * in one turn and reports their outcomes one at a time, and rotating on the
+     * first one would strand the rest in a step that can never resolve them
+     * (`step/end leaves unresolved tool call …`). Those calls run one model turn
+     * later instead, which is what they belong to, and a call the engine never
+     * answers is closed by {@link closeStep} rather than by moving on.
+     * @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);
+    /**
+     * 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. */
+    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.
+     *
+     * The model comes from the session's own selection when it names a real dsh
+     * model, else from the deployment's pinned configuration
+     * ({@link sessionModelOverrideOf}). Pi's `--model` flag is
+     * `"provider/id"`-qualified, so a session pick travels as the composite —
+     * which also carries the provider, leaving the deployment's `--provider` out
+     * of the argv for that step. A step with neither a selection nor a pin sends
+     * no `--model` at all and lets Pi's own configuration decide. Read every step,
+     * so a model picked mid-conversation lands on the next child.
+     *
+     * When dsh also discloses that model's ENDPOINT, the child is pointed at it:
+     * `--provider` names the provider pi's `models.json` declares, `--api-key`
+     * carries the credential, and `PI_CODING_AGENT_DIR` redirects pi's agent
+     * directory to the plugin-owned one holding that `models.json`
+     * ({@link piAgentDir}) — so the child runs on dsh's endpoint instead of its
+     * own `~/.pi` configuration, which is never touched. The handover reaching here
+     * is already judged: {@link supportedHandover} dropped one that named no
+     * protocol and refused one pi cannot speak.
+     */
+    private spawnSpec;
+    /**
+     * The endpoint handover this step may point the child at, or `undefined` to
+     * leave pi on its own configuration.
+     *
+     * Pi is the one engine that cannot run a provider handed over without a wire
+     * protocol: its `models.json` rejects a provider without `api` (verified
+     * against pi 0.84.3 — `{"status":"invalid","reason":"invalid_state"}`), and the
+     * plugin will not write a document it knows pi refuses. So a handover that
+     * names no protocol is dropped here rather than materialized into a broken
+     * agent directory. It is unreachable for every route `SHIPPED_ROUTE_APIS`
+     * names, which today is the only way `api` goes missing.
+     *
+     * A protocol pi does not SPEAK is a different answer, and a refusal rather than
+     * a drop: dropping it would leave the user's dsh model selection in place while
+     * pi quietly ran its own default model — the exact silent degradation this
+     * driver exists not to produce, and the shape of GitHub issue #2 (a third-party
+     * provider plugin declaring `api: "anthropic"`, which pi has no implementation
+     * for). The step fails instead, naming the provider, the model, and the
+     * offending protocol — so the user can pick `external/default` or fix it.
+     *
+     * The returned handover carries the PI spelling of its protocol
+     * ({@link resolvePiApi}), so everything downstream — `models.json` above all —
+     * sees the one protocol pi will actually be configured with.
+     * @param resolved - the endpoint dsh disclosed for this step's model selection.
+     * @returns the handover to point the child at, or `undefined` for none.
+     */
+    private supportedHandover;
+    /**
+     * 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.
+     * @param messages - the messages this step delivers; only their images ride
+     *   with the prompt as bytes, and only they.
+     */
+    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,72 @@
+/**
+ * Pi loop engine module: drives every session it is handed 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. The router routes a session here on the plugin's own engine
+ * record, else its agent preset; 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-allinone/engine-pi
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import { PiAgent } from './agent.ts';
+import type { PiProcess, PiSpawnSpec } from './rpc/client.ts';
+import type { PiSandboxMode, ResolvedConfig } from './types.ts';
+import { HostedEngineRuntime } from '../driver-core/hosted-engine-runtime.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;
+    /** Fallback model for the `pi` child (`--model`), used when the session selects none; 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>;
+    /**
+     * An EXTERNAL Pi CLI entrypoint, replacing this package's bundled
+     * `@earendil-works/pi-coding-agent`. Omitted keeps the bundled copy, which is
+     * what every earlier release ran.
+     */
+    bin?: string;
+}
+/** Schema of the Pi loop plugin configuration. */
+export declare const Config: z<Config>;
+/** Host-face ctx key this engine's runtime is registered under. */
+export declare const PI_ENGINE_LABEL = "agentLoopPi";
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentLoopPi: PiLoop;
+    }
+}
+/**
+ * Creation/resume machinery for the Pi engine. The process-wide AgentFactory
+ * slot belongs to the router, which delegates each session to the engine its
+ * preset names; this class is that engine's driver, not a plugin.
+ */
+export declare class PiLoop extends HostedEngineRuntime<ResolvedConfig, PiAgent> {
+    /** 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 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/model-handover.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Pi's dialect for a dsh endpoint: a self-built agent directory plus the argv
+ * flags that point the `pi --mode rpc` child at dsh's model.
+ *
+ * Pi resolves a model through its own agent directory — `models.json` under
+ * `PI_CODING_AGENT_DIR` (or `~/.pi` when unset) — and its custom-provider schema
+ * has no `apiKeyEnv`: a provider's credential is either a literal `apiKey` in
+ * that file or the CLI's own `--api-key`. There is no `PI_*` variable for a base
+ * URL either. So the only automatic way to hand pi a dsh endpoint is to give it
+ * an agent directory THIS PLUGIN owns, containing a `models.json` that declares
+ * the dsh provider, and to point `PI_CODING_AGENT_DIR` at it.
+ *
+ * The user's `~/.pi` is deliberately never written or read: the plugin owns a
+ * separate directory under the OS temp dir, one per distinct endpoint, created
+ * 0700 with a 0600 file because it carries the credential. The cost is real and
+ * documented: redirecting the agent directory means the child no longer sees the
+ * user's own `~/.pi` skills/auth/theme. That is the trade the deployment makes
+ * by selecting a real dsh model on pi.
+ *
+ * pi's provider schema requires a wire protocol (`api`) AND requires that pi
+ * itself has an implementation for the one it is given, so this is the one
+ * engine whose dialect has to judge the protocol rather than pass it along:
+ * {@link resolvePiApi} answers "is this a protocol pi can speak", and the driver
+ * drops a protocol-less handover or refuses an unspeakable one before either
+ * reaches here. What does reach here is written in pi's own spelling
+ * ({@link PI_API_ALIASES}) instead of dsh's raw string.
+ *
+ * @module dsh-loop-engine-allinone/engine-pi/model-handover
+ */
+import type { DshModelHandover } from '../driver-core/model-handover.ts';
+/**
+ * What pi can be told about one handover's wire protocol.
+ *
+ * A discriminated answer rather than an `api: string | undefined`, because the
+ * driver treats the two negative cases differently: no protocol at all is
+ * dropped, while a protocol pi does not speak is REFUSED — dropping the second
+ * one would leave the user's dsh model selection standing while pi quietly ran
+ * its OWN default model, the misleading failure this driver exists not to
+ * produce (the driver's gate is `PiAgent.supportedHandover`, `agent.ts`).
+ */
+export type PiApiResolution = {
+    readonly kind: 'absent';
+} | {
+    readonly kind: 'supported';
+    readonly api: string;
+} | {
+    readonly kind: 'unsupported';
+};
+/**
+ * Judge one handover's wire protocol against pi's own vocabulary.
+ * @param api - dsh's protocol name for the endpoint, or `undefined` when neither
+ *   the provider's settings section nor a shipped-route entry declares one.
+ * @returns `absent` for no protocol, `supported` (carrying the pi spelling to
+ *   use) for one pi speaks, `unsupported` for anything else.
+ */
+export declare function resolvePiApi(api: string | undefined): PiApiResolution;
+/**
+ * A handover whose wire protocol pi can speak — i.e. one that came through
+ * {@link resolvePiApi}.
+ *
+ * The type is the point: {@link piAgentDir} materializes an endpoint pi will be
+ * pointed at, and pi rejects a provider whose `api` is missing or unknown, so a
+ * protocol-less handover has no business reaching this module's write path.
+ * Narrowing `api` to a required string makes that a compile-time obligation at
+ * every call site instead of a runtime check the writer would have to fail on.
+ */
+export interface PiSupportedHandover extends DshModelHandover {
+    /** The endpoint's wire protocol, in pi's own vocabulary. */
+    readonly api: string;
+}
+/**
+ * The agent directory for one handover, materialized on first use.
+ *
+ * The directory name is a hash of the endpoint facts, so two sessions on the
+ * same provider/model share one directory and a changed endpoint gets its own;
+ * `models.json` declares exactly the provider pi is told to use (`--provider`)
+ * and the one model it is told to run (`--model`), keyed the way pi's own
+ * schema reads it (`baseUrl`/`api`/`apiKey`/`models`).
+ * @param handover - the resolved dsh endpoint for the session's selection, whose
+ *   protocol {@link resolvePiApi} already accepted.
+ * @returns the absolute path to hand the child as `PI_CODING_AGENT_DIR`.
+ */
+export declare function piAgentDir(handover: PiSupportedHandover): string;
+//# sourceMappingURL=model-handover.d.ts.map

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

@@ -0,0 +1,47 @@
+/**
+ * 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. 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`.
+ *
+ * @module dsh-loop-engine-allinone/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 {
+    /** The resolved sandbox stance; selects the tool set, not a process sandbox. */
+    readonly sandboxMode: PiSandboxMode;
+    /** 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. 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
+ * 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`.
+ */
+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