agent-tempo 1.3.1 → 1.4.1

package/dist/pi/pi-types.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Local, hand-written structural declarations of the slice of Pi's
+ * `ExtensionAPI` surface that the agent-tempo Phase 0 PoC consumes.
+ *
+ * WHY HAND-WRITTEN (Phase 0 shortcut — see src/pi/README.md "Known limitations"):
+ *   The real types live in `@earendil-works/pi-coding-agent`, which is an
+ *   OPTIONAL dependency requiring Node 22.19+. Declaring these locally keeps
+ *   `tsc` (root build + test build) green WITHOUT Pi installed, so the unit
+ *   suite runs on any CI node. The cost is drift risk: if Pi's real
+ *   `ExtensionAPI` changes, these decls won't catch it at compile time.
+ *
+ *   Phase 1 should switch to importing the real Pi types at type-check time
+ *   (Pi as a true optional/peer dep) so we get compile-time API-drift
+ *   detection. These decls are a temporary stand-in, NOT the end state.
+ *
+ * Surface mirrored against `badlogic/pi-mono` @ 564ad70 (packages 0.78.0):
+ *   - `core/extensions/types.ts` (ExtensionAPI, ToolDefinition, events)
+ *   - `core/agent-session.ts` (sendCustomMessage / steer / followUp)
+ */
+/**
+ * Pi lifecycle events. Phase 0 only wires the lifecycle-relevant subset; the
+ * real `ExtensionAPI.on` accepts many more event names.
+ *
+ * IMPORTANT (architect's phase spec): `turn_start` / `turn_end` /
+ * `tool_execution_start` / `tool_execution_end` fire MULTIPLE times within a
+ * single agent run and therefore MUST NOT drive the attachment phase — they
+ * only stamp a last-activity timestamp. See `phase-driver.ts`.
+ */
+export type PiLifecycleEvent = 'session_start' | 'agent_start' | 'agent_end' | 'turn_start' | 'turn_end' | 'tool_call' | 'tool_execution_start' | 'tool_execution_end' | 'message_update' | 'session_shutdown';
+/** Options for `sendCustomMessage` — D10 (FLIPPED): default `steer` + `triggerTurn`. */
+export interface PiCustomMessageOptions {
+    /** Start a new agent turn after delivery. */
+    triggerTurn?: boolean;
+    /**
+     * `steer`  — interrupt an in-flight turn and inject immediately (priority).
+     * `followUp` — queue behind the current turn.
+     */
+    deliverAs?: 'steer' | 'followUp';
+}
+/** A message injected into a live Pi session. */
+export interface PiOutboundMessage {
+    /** Free-form tag Pi surfaces to the agent (we use `'cue'`). */
+    customType?: string;
+    content: string;
+    /** Render the injected content in the human-visible transcript. */
+    display?: boolean;
+}
+/**
+ * The live, human-attached agent session. `sendCustomMessage` is bound in the
+ * `AgentSession` constructor (no mode gate) — confirmed by the spike — so a
+ * cue can be injected into a running interactive session.
+ */
+export interface PiAgentSession {
+    /**
+     * Inject a message into the live session. Pi's `AgentSession` exposes this as
+     * `sendCustomMessage` (NOT `sendMessage` — verified against the installed SDK's
+     * `agent-session.d.ts` during the 3a live smoke). The earlier spike modeled it
+     * as `sendMessage`; the real method name is `sendCustomMessage`.
+     */
+    sendCustomMessage(msg: PiOutboundMessage, opts?: PiCustomMessageOptions): void | Promise<void>;
+    /**
+     * 3d D14 — wipe the conversation and start a FRESH context (no replay). The
+     * reset handler calls this on a clean-wipe reset. Optional in the slice (Pi
+     * provides it; older Pi / a fake session in tests may not).
+     */
+    newSession?(): void | Promise<void>;
+    /** Pi's stable session identifier (reconciled with workflow metadata — D11). */
+    readonly id?: string;
+}
+/**
+ * Payload delivered to a `pi.on(event, handler)` callback. Kept structural and
+ * open: Pi passes an event-specific object; we read only what Phase 0 needs and
+ * RE-ACQUIRE the session from each payload (never cache across switches — D11).
+ */
+export interface PiEventPayload {
+    /** The live session, present on most lifecycle events. */
+    session?: PiAgentSession;
+    /** A per-message/per-turn identifier when the event carries one. */
+    messageId?: string;
+    /**
+     * Discriminator on `session_start` / `session_shutdown`:
+     * `{ new | resume | fork | reload | quit }`. Drives Option-C teardown — only
+     * `quit` detaches; switch reasons rebind. Unknown/missing → treated as a
+     * switch (no detach), so a future Pi value can't cause a flap.
+     */
+    reason?: string;
+    /** Open for forward-compat with Pi event fields we don't consume yet. */
+    [key: string]: unknown;
+}
+/**
+ * Pi context-window usage — the PULL-only token signal (3c). There is NO token
+ * event in Pi 0.78; usage is queried on demand via `ExtensionContext.getContextUsage()`.
+ * Mirrors pi-ai's `ContextUsage` (verified against the installed 0.78 `.d.ts`).
+ */
+export interface PiContextUsage {
+    /** Estimated context tokens in use, or `null` when unknown. */
+    tokens: number | null;
+    /** Model context-window size. */
+    contextWindow: number;
+    /** Usage as a fraction/percent of the window, or `null` when unknown. */
+    percent: number | null;
+}
+/**
+ * Second argument Pi passes to every `pi.on(event, handler)` callback
+ * (`ExtensionHandler<E,R> = (event, ctx) => …`). Minimal structural slice — only
+ * the members 3c consumes. `getContextUsage()` is the sole source of token/usage
+ * data (pull-only — see {@link PiContextUsage}).
+ */
+export interface PiExtensionContext {
+    getContextUsage(): PiContextUsage | undefined;
+    isIdle(): boolean;
+    /**
+     * 3d — the in-flight turn's AbortSignal (Esc / cancel). Pi passes it to handlers
+     * (the shipped `permission-gate.ts` precedent threads it into an awaited gate);
+     * the operator-gate await uses it to cancel a pending poll so a cancelled turn
+     * never hangs on an unresolved decision (Pi #2381). Optional — absent on older
+     * Pi / non-turn handlers.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Handlers may take an optional second `ctx` arg (3c — needed for
+ * `getContextUsage()`). Optional so existing one-arg handlers (Phase 0-2) still
+ * satisfy the type — widening is additive/backward-compatible.
+ */
+export type PiEventHandler = (payload: PiEventPayload, ctx?: PiExtensionContext) => void | Promise<void>;
+/**
+ * One streaming delta inside a `message_update` event's `assistantMessageEvent`
+ * (a discriminated union in pi-ai). 3c forwards `thinking_delta` / `text_delta`
+ * as `inner.thinking` frames; `.delta` is the incremental string.
+ */
+export interface PiAssistantDelta {
+    /** `'text_delta'` | `'thinking_delta'` | `'toolcall_delta'` | … */
+    type?: string;
+    /** Orders multi-block content within a turn. */
+    contentIndex?: number;
+    /** The incremental text fragment. */
+    delta?: string;
+    /** Cumulative `AssistantMessage` so far (unused by 3c). */
+    partial?: unknown;
+}
+/** `message_update` payload — carries the streaming `assistantMessageEvent`. */
+export interface PiMessageUpdatePayload extends PiEventPayload {
+    assistantMessageEvent?: PiAssistantDelta;
+}
+/** `tool_execution_start` payload. `toolName` is a bare string (NOT a literal union). */
+export interface PiToolExecutionStartPayload extends PiEventPayload {
+    toolCallId?: string;
+    toolName?: string;
+    args?: unknown;
+}
+/** `tool_execution_end` payload — structured result + error flag. */
+export interface PiToolExecutionEndPayload extends PiEventPayload {
+    toolCallId?: string;
+    toolName?: string;
+    result?: unknown;
+    isError?: boolean;
+}
+/** `turn_start` / `turn_end` payload. No phase field, no token counts (3c finding). */
+export interface PiTurnPayload extends PiEventPayload {
+    turnIndex?: number;
+    timestamp?: number;
+}
+/**
+ * `tool_call` pre-execution event — Pi fires this before running a tool, letting
+ * an extension allow/deny it. `toolName` is Pi's built-in or registered tool id
+ * (`bash` | `read` | `edit` | `write` | `grep` | …). The MD-C headless gate reads
+ * it to hard-block the shell/exec class at `toolAccess='restricted'`.
+ */
+export interface PiToolCallEvent {
+    type?: 'tool_call';
+    toolCallId?: string;
+    toolName: string;
+    input?: Record<string, unknown>;
+}
+/** Result of a `tool_call` handler: `block:true` denies the tool (with a reason). */
+export interface PiToolCallResult {
+    block?: boolean;
+    reason?: string;
+}
+/**
+ * Pi tool result (`AgentToolResult`). The exact streaming shape is UNCONFIRMED
+ * (spike gap D12b) — Phase 0 uses the minimal `{ output, isError }` form, which
+ * is sufficient for a non-streaming tool like `report`.
+ */
+export interface PiToolResult {
+    output?: string;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Pi native tool definition. `parameters` is a TypeBox schema (NOT zod) — see
+ * `render-tools.ts` (derives it from the zod descriptor via the converter).
+ */
+export interface PiToolDefinition {
+    name: string;
+    description?: string;
+    /** TypeBox schema object. Typed `unknown` to avoid coupling pi-types to typebox. */
+    parameters: unknown;
+    /**
+     * Pi invokes `execute` POSITIONALLY at runtime:
+     *   execute(toolCallId, params, signal?, onUpdate?, ctx?)
+     * (installed Pi 0.78 `core/extensions/types.d.ts:354` + the wrapper at
+     * `core/tools/tool-definition-wrapper.js:10,31`). The VALIDATED params object
+     * is the SECOND positional — the FIRST is the `toolCallId` string.
+     *
+     * Declaring the full positional shape (not a single `args`) is LOAD-BEARING: a
+     * one-arg signature silently accepts `(args) => handler(args)`, which binds the
+     * toolCallId string to what the handler treats as the params object — the
+     * shipped arg-order bug (v1.4.0) this corrected type now makes a compile error.
+     * `signal`/`onUpdate`/`ctx` are optional + `unknown`: we don't consume them and
+     * avoid coupling to Pi's internal callback/context types.
+     */
+    execute: (toolCallId: string, params: Record<string, unknown>, signal?: unknown, onUpdate?: unknown, ctx?: unknown) => Promise<PiToolResult> | PiToolResult;
+}
+/** The `pi` object passed to `export default function(pi: ExtensionAPI) {}`. */
+export interface ExtensionAPI {
+    on(event: PiLifecycleEvent | string, handler: PiEventHandler): void;
+    registerTool(def: PiToolDefinition): void;
+}
+/** An extension is a default-exported function receiving the `ExtensionAPI`. */
+export type PiExtension = (pi: ExtensionAPI) => void | Promise<void>;

package/dist/pi/pi-types.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Local, hand-written structural declarations of the slice of Pi's
+ * `ExtensionAPI` surface that the agent-tempo Phase 0 PoC consumes.
+ *
+ * WHY HAND-WRITTEN (Phase 0 shortcut — see src/pi/README.md "Known limitations"):
+ *   The real types live in `@earendil-works/pi-coding-agent`, which is an
+ *   OPTIONAL dependency requiring Node 22.19+. Declaring these locally keeps
+ *   `tsc` (root build + test build) green WITHOUT Pi installed, so the unit
+ *   suite runs on any CI node. The cost is drift risk: if Pi's real
+ *   `ExtensionAPI` changes, these decls won't catch it at compile time.
+ *
+ *   Phase 1 should switch to importing the real Pi types at type-check time
+ *   (Pi as a true optional/peer dep) so we get compile-time API-drift
+ *   detection. These decls are a temporary stand-in, NOT the end state.
+ *
+ * Surface mirrored against `badlogic/pi-mono` @ 564ad70 (packages 0.78.0):
+ *   - `core/extensions/types.ts` (ExtensionAPI, ToolDefinition, events)
+ *   - `core/agent-session.ts` (sendCustomMessage / steer / followUp)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/pi/probe.d.ts

@@ -0,0 +1,99 @@
+/** Canonical Pi package (the npm `@mariozechner/...` name is an alias). */
+export declare const PI_PACKAGE = "@earendil-works/pi-coding-agent";
+/** Pi's model/typing helpers (`StringEnum`, providers). */
+export declare const PI_AI_PACKAGE = "@earendil-works/pi-ai";
+/** Tested-pinned Pi version — drift is a maintainer decision (D6). */
+export declare const TESTED_PI_VERSION = "~0.78";
+/**
+ * Minimum Pi version the integration requires. 0.78.0 covers the Pi fixes the
+ * cue-pump + headless paths rely on (#2860 / #5080 / #5115). Bumping this is a
+ * D6 maintainer decision; the headless/Copilot pre-flight hard-fails below it.
+ */
+export declare const PI_VERSION_FLOOR = "0.78.0";
+/** Node floor imposed by the Pi packages (NOT by typebox or agent-tempo core). */
+export declare const PI_NODE_FLOOR = "22.19.0";
+export interface PiProbeResult {
+    available: boolean;
+    /** Human-readable, actionable reason when unavailable. */
+    reason?: string;
+}
+/**
+ * Check whether the Pi runtime packages are installed. Returns a structured
+ * result so callers choose whether to warn or hard-fail (the extension warns;
+ * a headless spawner would hard-fail).
+ */
+export declare function probePi(): PiProbeResult;
+/**
+ * Pure semver FLOOR check: is `installed` >= `floor`? Compares major, then
+ * minor, then patch (a missing patch defaults to 0). Any pre-release/build
+ * suffix (`-beta`, `+sha`) is ignored — a pre-release of a version at/above the
+ * floor counts as meeting it. An unparseable `installed` returns `false`
+ * (conservative: unknown version is treated as below the floor).
+ */
+export declare function meetsVersionFloor(installed: string, floor?: string): boolean;
+/**
+ * Node-floor preflight (Decision B, #645). The Pi optional deps require
+ * Node >= {@link PI_NODE_FLOOR} (22.19). Enforced ONLY at the Pi recruit/spawn
+ * boundary — `package.json#engines` stays `>=20` so non-Pi users are untouched.
+ *
+ * Pure + injectable (`nodeVersion` defaults to the live runtime) so it is the
+ * single source of truth shared by the recruit pre-flight (authoritative,
+ * pre-spawn) AND the {@link runHeadlessPi} backstop (direct/manual launches).
+ * Reuses {@link meetsVersionFloor}'s major.minor.patch comparison.
+ *
+ * @returns `{ ok: true }` when the floor is met, else `{ ok: false, reason }`
+ *   with an actionable, fail-clean message (mirrors the `probeSdkInstall` /
+ *   `resolveModel` style). The `reason` omits any `force: true` hint so each
+ *   caller can frame the bypass in its own voice.
+ */
+export declare function checkPiNodeFloor(nodeVersion?: string): {
+    ok: boolean;
+    reason?: string;
+};
+/**
+ * Injectable collaborators for {@link probeCopilotPiPreflight}. All default to
+ * real implementations; tests override them to exercise each branch without a
+ * live Pi install or real `~/.pi` / env.
+ */
+export interface CopilotPiPreflightDeps {
+    /** Whether a package is installed. Default: filesystem-walk {@link probeSdkInstall}. */
+    isInstalled?: (pkg: string) => boolean;
+    /** Installed version of a package, or null. Default: {@link readSdkPackageVersion}. */
+    installedVersion?: (pkg: string) => string | null;
+    /** Environment to read `COPILOT_GITHUB_TOKEN` from. Default: `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Whether the mounted `~/.pi/agent/auth.json` exists. Default: real `existsSync`. */
+    authFileExists?: () => boolean;
+    /**
+     * The parsed recruit selector to validate against Pi's model index (the
+     * `{ provider, model }` from {@link parsePiProviderModel}). Omit it — e.g. no
+     * `model` recruit arg, the Pi-default path — to SKIP the model-index gate.
+     */
+    requestedModel?: {
+        provider: string;
+        model: string;
+    };
+    /**
+     * Resolve a `(provider, modelName)` against Pi's build-time model index,
+     * returning a truthy Model when indexed and `undefined` when not (the
+     * empirically-confirmed contract of pi-ai's `getModel`). The recruit caller
+     * (A4) injects pi-ai's `getModel` here — B2 deliberately does NOT import the
+     * ESM-only `@earendil-works/pi-ai` from the CJS recruit context. Omit it to
+     * SKIP the model-index gate (e.g. unit tests, or callers without pi-ai); the
+     * A4 `getModel` backstop then covers an unindexed model.
+     */
+    resolveModel?: (provider: string, modelName: string) => unknown;
+}
+/**
+ * Hard pre-flight for recruiting a Copilot-backed Pi player (headless). Three
+ * gates, each with an actionable, `force: true`-bypassable error:
+ *   1. The Pi optional deps (`@earendil-works/pi-coding-agent` + `pi-ai`) are
+ *      installed.
+ *   2. The Pi SDK version meets {@link PI_VERSION_FLOOR}.
+ *   3. Copilot auth is present — either `COPILOT_GITHUB_TOKEN` in the env or a
+ *      mounted `~/.pi/agent/auth.json`.
+ *
+ * Mirrors the opencode / claude-code-headless recruit pre-flights. Returns a
+ * {@link PiProbeResult} so the caller (recruit) chooses warn vs hard-fail.
+ */
+export declare function probeCopilotPiPreflight(deps?: CopilotPiPreflightDeps): PiProbeResult;

package/dist/pi/probe.js

@@ -0,0 +1,179 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PI_NODE_FLOOR = exports.PI_VERSION_FLOOR = exports.TESTED_PI_VERSION = exports.PI_AI_PACKAGE = exports.PI_PACKAGE = void 0;
+exports.probePi = probePi;
+exports.meetsVersionFloor = meetsVersionFloor;
+exports.checkPiNodeFloor = checkPiNodeFloor;
+exports.probeCopilotPiPreflight = probeCopilotPiPreflight;
+/**
+ * Pi dependency preflight — mirrors the opencode / claude-api optional-dep gate.
+ *
+ * `@earendil-works/pi-coding-agent` (and `@earendil-works/pi-ai`) are OPTIONAL
+ * dependencies requiring Node 22.19+. The extension only runs INSIDE Pi, so the
+ * runtime guarantees Pi is present — this probe exists for the headless path and
+ * for a clear, actionable error if someone wires the extension where Pi isn't
+ * installed.
+ *
+ * Uses `probeSdkInstall` (filesystem walk) rather than `require.resolve` because
+ * Pi packages ship ESM-only `exports` maps with no CJS-resolvable entry.
+ */
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const sdk_probe_1 = require("../utils/sdk-probe");
+/** Canonical Pi package (the npm `@mariozechner/...` name is an alias). */
+exports.PI_PACKAGE = '@earendil-works/pi-coding-agent';
+/** Pi's model/typing helpers (`StringEnum`, providers). */
+exports.PI_AI_PACKAGE = '@earendil-works/pi-ai';
+/** Tested-pinned Pi version — drift is a maintainer decision (D6). */
+exports.TESTED_PI_VERSION = '~0.78';
+/**
+ * Minimum Pi version the integration requires. 0.78.0 covers the Pi fixes the
+ * cue-pump + headless paths rely on (#2860 / #5080 / #5115). Bumping this is a
+ * D6 maintainer decision; the headless/Copilot pre-flight hard-fails below it.
+ */
+exports.PI_VERSION_FLOOR = '0.78.0';
+/** Node floor imposed by the Pi packages (NOT by typebox or agent-tempo core). */
+exports.PI_NODE_FLOOR = '22.19.0';
+/**
+ * Check whether the Pi runtime packages are installed. Returns a structured
+ * result so callers choose whether to warn or hard-fail (the extension warns;
+ * a headless spawner would hard-fail).
+ */
+function probePi() {
+    if (!(0, sdk_probe_1.probeSdkInstall)(exports.PI_PACKAGE)) {
+        return {
+            available: false,
+            reason: `${exports.PI_PACKAGE} is not installed.\n` +
+                `Install it with: npm install -g ${exports.PI_PACKAGE}\n` +
+                `(requires Node >= ${exports.PI_NODE_FLOOR}).`,
+        };
+    }
+    return { available: true };
+}
+/**
+ * Pure semver FLOOR check: is `installed` >= `floor`? Compares major, then
+ * minor, then patch (a missing patch defaults to 0). Any pre-release/build
+ * suffix (`-beta`, `+sha`) is ignored — a pre-release of a version at/above the
+ * floor counts as meeting it. An unparseable `installed` returns `false`
+ * (conservative: unknown version is treated as below the floor).
+ */
+function meetsVersionFloor(installed, floor = exports.PI_VERSION_FLOOR) {
+    const parse = (v) => {
+        const m = v.trim().match(/^v?(\d+)\.(\d+)(?:\.(\d+))?/);
+        if (!m)
+            return [-1, -1, -1];
+        return [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)];
+    };
+    const [iMaj, iMin, iPat] = parse(installed);
+    if (iMaj < 0)
+        return false; // unparseable → below floor
+    const [fMaj, fMin, fPat] = parse(floor);
+    if (iMaj !== fMaj)
+        return iMaj > fMaj;
+    if (iMin !== fMin)
+        return iMin > fMin;
+    return iPat >= fPat;
+}
+/**
+ * Node-floor preflight (Decision B, #645). The Pi optional deps require
+ * Node >= {@link PI_NODE_FLOOR} (22.19). Enforced ONLY at the Pi recruit/spawn
+ * boundary — `package.json#engines` stays `>=20` so non-Pi users are untouched.
+ *
+ * Pure + injectable (`nodeVersion` defaults to the live runtime) so it is the
+ * single source of truth shared by the recruit pre-flight (authoritative,
+ * pre-spawn) AND the {@link runHeadlessPi} backstop (direct/manual launches).
+ * Reuses {@link meetsVersionFloor}'s major.minor.patch comparison.
+ *
+ * @returns `{ ok: true }` when the floor is met, else `{ ok: false, reason }`
+ *   with an actionable, fail-clean message (mirrors the `probeSdkInstall` /
+ *   `resolveModel` style). The `reason` omits any `force: true` hint so each
+ *   caller can frame the bypass in its own voice.
+ */
+function checkPiNodeFloor(nodeVersion = process.versions.node) {
+    if (meetsVersionFloor(nodeVersion, exports.PI_NODE_FLOOR))
+        return { ok: true };
+    return {
+        ok: false,
+        reason: `agent: "pi" requires Node >= ${exports.PI_NODE_FLOOR}, but this host runs Node ${nodeVersion}. ` +
+            `Upgrade Node (e.g. via nvm/fnm) and retry.`,
+    };
+}
+/** Default `~/.pi/agent/auth.json` presence check. */
+function defaultAuthFileExists() {
+    return (0, fs_1.existsSync)((0, path_1.join)((0, os_1.homedir)(), '.pi', 'agent', 'auth.json'));
+}
+/**
+ * Hard pre-flight for recruiting a Copilot-backed Pi player (headless). Three
+ * gates, each with an actionable, `force: true`-bypassable error:
+ *   1. The Pi optional deps (`@earendil-works/pi-coding-agent` + `pi-ai`) are
+ *      installed.
+ *   2. The Pi SDK version meets {@link PI_VERSION_FLOOR}.
+ *   3. Copilot auth is present — either `COPILOT_GITHUB_TOKEN` in the env or a
+ *      mounted `~/.pi/agent/auth.json`.
+ *
+ * Mirrors the opencode / claude-code-headless recruit pre-flights. Returns a
+ * {@link PiProbeResult} so the caller (recruit) chooses warn vs hard-fail.
+ */
+function probeCopilotPiPreflight(deps = {}) {
+    const isInstalled = deps.isInstalled ?? ((pkg) => (0, sdk_probe_1.probeSdkInstall)(pkg));
+    const installedVersion = deps.installedVersion ?? ((pkg) => (0, sdk_probe_1.readSdkPackageVersion)(pkg));
+    const env = deps.env ?? process.env;
+    const authFileExists = deps.authFileExists ?? defaultAuthFileExists;
+    // 1. Optional Pi deps present.
+    const missing = [exports.PI_PACKAGE, exports.PI_AI_PACKAGE].filter((pkg) => !isInstalled(pkg));
+    if (missing.length > 0) {
+        return {
+            available: false,
+            reason: `Copilot-via-Pi requires the Pi optional dependencies (missing: ${missing.join(', ')}).\n` +
+                `Install with: npm install -g ${exports.PI_PACKAGE} ${exports.PI_AI_PACKAGE} (requires Node >= ${exports.PI_NODE_FLOOR}).\n` +
+                `Or recruit with force: true to bypass this pre-flight.`,
+        };
+    }
+    // 2. Version floor.
+    const version = installedVersion(exports.PI_PACKAGE);
+    if (!version) {
+        return {
+            available: false,
+            reason: `Could not read ${exports.PI_PACKAGE} version to verify the >= ${exports.PI_VERSION_FLOOR} floor.\n` +
+                `Reinstall ${exports.PI_PACKAGE}, or recruit with force: true to bypass.`,
+        };
+    }
+    if (!meetsVersionFloor(version, exports.PI_VERSION_FLOOR)) {
+        return {
+            available: false,
+            reason: `${exports.PI_PACKAGE} ${version} is below the required >= ${exports.PI_VERSION_FLOOR} floor ` +
+                `(covers Pi #2860/#5080/#5115).\n` +
+                `Upgrade with: npm install -g ${exports.PI_PACKAGE}@latest, or recruit with force: true to bypass.`,
+        };
+    }
+    // 3. Copilot auth.
+    if (!env.COPILOT_GITHUB_TOKEN && !authFileExists()) {
+        return {
+            available: false,
+            reason: `Copilot auth not found. Set COPILOT_GITHUB_TOKEN, or run \`pi /login\` (GitHub Copilot) ` +
+                `to write ~/.pi/agent/auth.json.\n` +
+                `Or recruit with force: true to bypass this pre-flight.`,
+        };
+    }
+    // 4. Model indexability (catch-early; runs only when BOTH the requested model
+    //    and a resolver are supplied — A4 injects pi-ai's getModel). Pi's Copilot
+    //    model set is compiled at build time from models.dev, so a model on the
+    //    user's subscription but unindexed resolves to `undefined` (NOT a throw,
+    //    NOT null — empirically confirmed). Fail the recruit cleanly here rather
+    //    than spawning a process getModel kills at the headless entry. A4's
+    //    getModel backstop covers the skip cases (no resolver / session-only).
+    if (deps.requestedModel && deps.resolveModel) {
+        const { provider, model } = deps.requestedModel;
+        if (deps.resolveModel(provider, model) === undefined) {
+            return {
+                available: false,
+                reason: `model "${provider}/${model}" is not in Pi's model index (getModel returned undefined).\n` +
+                    `Run \`pi --list-models\` for valid ids; the Copilot set is compiled from models.dev, ` +
+                    `so a model on your subscription but unindexed is rejected (Pi #4599/#2891).\n` +
+                    `Or recruit with force: true to bypass this pre-flight.`,
+            };
+        }
+    }
+    return { available: true };
+}

package/dist/pi/render-tools.d.ts

@@ -0,0 +1,17 @@
+import type { TempoToolDescriptor, TempoToolResult } from '../tools/descriptor';
+import type { ExtensionAPI, PiToolResult } from './pi-types';
+/**
+ * Map a neutral {@link TempoToolResult} onto Pi's `AgentToolResult` shape.
+ *
+ * Phase 0 confirmed Pi's result is `{ output, isError }` for a non-streaming
+ * tool (D12). The neutral `{ text, isError? }` maps directly: `text → output`,
+ * `isError` passes through.
+ */
+export declare function toPiResult(r: TempoToolResult): PiToolResult;
+/**
+ * Register every descriptor onto the Pi extension API. The TypeBox schema is
+ * derived per-tool from the zod shape; an unsupported zod construct throws
+ * `UnsupportedZodFeatureError` from the converter (fail-loud — D1), surfacing
+ * the offending `tool.field` so the parity test points at the exact site.
+ */
+export declare function renderToPi(pi: ExtensionAPI, descriptors: TempoToolDescriptor[]): void;

package/dist/pi/render-tools.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPiResult = toPiResult;
+exports.renderToPi = renderToPi;
+/**
+ * Pi front-end renderer — registers transport-neutral tool descriptors onto a
+ * Pi `ExtensionAPI` (the counterpart to `renderToMcp` in src/tools/descriptor.ts).
+ *
+ * The MCP renderer passes the zod param shape to `server.tool` raw; here we
+ * DERIVE a TypeBox schema from the same zod shape via the converter
+ * (`zod-to-typebox.ts`). zod stays the single source of truth — no dual-define,
+ * no drift. The CI parity test (test/pi-tool-parity.test.ts) asserts the MCP
+ * and Pi front-ends register the identical tool set with identical required
+ * params.
+ *
+ * OUTBOX-COMPLIANCE INVARIANT (load-bearing): `renderToPi` reuses the
+ * descriptor's `handler` VERBATIM — it never reimplements tool logic. The
+ * handler still routes through `handle.executeUpdate(submitOutboxUpdate, …)` on
+ * the player's OWN workflow handle. The Pi extension's WorkflowClient builds
+ * only that handle; there is ZERO `.signal()` to peer workflows.
+ *
+ * Determinism note: client-side only. src/pi imports the descriptor type FROM
+ * src/tools; never the reverse.
+ */
+const zod_to_typebox_1 = require("./zod-to-typebox");
+/**
+ * Map a neutral {@link TempoToolResult} onto Pi's `AgentToolResult` shape.
+ *
+ * Phase 0 confirmed Pi's result is `{ output, isError }` for a non-streaming
+ * tool (D12). The neutral `{ text, isError? }` maps directly: `text → output`,
+ * `isError` passes through.
+ */
+function toPiResult(r) {
+    return r.isError ? { output: r.text, isError: true } : { output: r.text };
+}
+/**
+ * Register every descriptor onto the Pi extension API. The TypeBox schema is
+ * derived per-tool from the zod shape; an unsupported zod construct throws
+ * `UnsupportedZodFeatureError` from the converter (fail-loud — D1), surfacing
+ * the offending `tool.field` so the parity test points at the exact site.
+ */
+function renderToPi(pi, descriptors) {
+    for (const d of descriptors) {
+        pi.registerTool({
+            name: d.name,
+            description: d.description,
+            parameters: (0, zod_to_typebox_1.zodShapeToTypeBox)(d.params, d.name),
+            // Pi calls execute POSITIONALLY: (toolCallId, params, signal, onUpdate, ctx).
+            // The validated params object is the SECOND positional — ignore the
+            // toolCallId string (1st) and hand `params` to the descriptor handler.
+            // (Passing the 1st positional was the v1.4.0 arg-order bug: handlers got the
+            // toolCallId string instead of params.) See PiToolDefinition.execute.
+            execute: async (_toolCallId, params) => toPiResult(await d.handler(params)),
+        });
+    }
+}

package/dist/pi/reset-pump.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Reset pump (3d D14) — polls the session workflow's single-slot pending reset
+ * and performs a CLEAN-WIPE on the live Pi session, then acks it. Sibling to
+ * {@link CuePump}: Pi has no reverse-RPC from Temporal, so reset (an operator/
+ * conductor CONTROL op — it bypasses the MD-G tool gate) is delivered by polling
+ * `pendingReset` and acking via the race-safe `ackReset(resetId)` (the workflow
+ * clears the slot only if the id still matches, so a newer reset landing during
+ * the wipe is preserved for the next tick).
+ *
+ * D14 (maintainer-ruled): reset = clean-wipe via Pi `session.newSession()` (fresh
+ * context, NO replay). Seeded reset is a separate concern (`restart` +
+ * `loadFromState`), so a `fresh:false` here is defensively logged + acked (never
+ * silently wiped) — the reset tool only ever sends `fresh:true` today.
+ */
+import type { PendingReset } from '../types';
+import type { PiAgentSession } from './pi-types';
+/** Source of the pending reset + ack — satisfied by `PiWorkflowClient`. */
+export interface ResetSource {
+    fetchPendingReset(): Promise<PendingReset | null>;
+    ackReset(resetId: string): Promise<void>;
+}
+/** Resolves the CURRENT live Pi session at wipe time (re-acquired each tick — D11). */
+export type SessionResolver = () => PiAgentSession | null;
+export interface ResetPumpOptions {
+    source: ResetSource;
+    resolveSession: SessionResolver;
+    /** Poll interval (ms). */
+    intervalMs?: number;
+}
+export declare class ResetPump {
+    private readonly source;
+    private readonly resolveSession;
+    private readonly intervalMs;
+    private timer;
+    private draining;
+    constructor(opts: ResetPumpOptions);
+    start(): void;
+    stop(): void;
+    /**
+     * One poll cycle: fetch the pending reset; if present + a live session is
+     * attached, perform the wipe and ack. Re-entrancy guarded so a slow tick never
+     * overlaps the next interval. Public for unit tests to drive directly.
+     */
+    tick(): Promise<void>;
+    /** Wipe (D14 clean-wipe) + deliver the "context wiped" notice. */
+    private performReset;
+}