agent-tempo 1.3.1 → 1.4.0

package/dist/pi/mission-control/pi-ui.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Hand-written structural slice of Pi's extension UI + command API that
+ * mission-control consumes (3f). Kept LOCAL (not in the shared `src/pi/pi-types.ts`)
+ * so this feature is self-contained and `tsc` stays green WITHOUT the optional
+ * `@earendil-works/pi-coding-agent` dep installed. Mirrors the installed SDK's
+ * `dist/core/extensions/types.d.ts` (verified 0.78.0): `ctx.ui.setWidget` /
+ * `select` / `confirm` / `input` / `notify`, `registerCommand`, `registerShortcut`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/pi/mission-control/render.d.ts

@@ -0,0 +1,6 @@
+import { type BoardModel } from './board';
+/**
+ * Render the full board. Header + player rows (conductor first), then — when a
+ * player is selected — a fine inner-loop tail (last {@link TAIL_RENDER_LINES}).
+ */
+export declare function renderBoard(model: BoardModel): string[];

package/dist/pi/mission-control/render.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderBoard = renderBoard;
+const board_1 = require("./board");
+/** How many recent fine-tail frames to show under the selected player. */
+const TAIL_RENDER_LINES = 12;
+/** Compact phase glyph — ASCII-safe for the TUI. */
+function phaseGlyph(phase) {
+    switch (phase) {
+        case 'processing': return '*'; // working
+        case 'awaiting': return 'o'; // idle, attached
+        case 'attached': return '+';
+        case 'booting': return '.';
+        case 'draining': return '~';
+        case 'detached': return 'x';
+        case 'gone': return '#';
+        default: return '?';
+    }
+}
+function pct(contextPercent) {
+    if (contextPercent === undefined)
+        return '';
+    // contextPercent may be a 0..1 fraction or a 0..100 number — normalize to %.
+    const p = contextPercent <= 1 ? contextPercent * 100 : contextPercent;
+    return `${Math.round(p)}%`;
+}
+function renderRow(row, selected) {
+    const sel = selected ? '>' : ' ';
+    const glyph = phaseGlyph(row.phase);
+    const tool = row.currentTool ? `[${row.currentTool}]` : '';
+    const ctx = pct(row.contextPercent);
+    const part = row.part ? ` ${row.part}` : '';
+    // sel glyph id  part  tool  ctx
+    return [`${sel}${glyph} ${row.playerId}`, part, tool, ctx]
+        .filter((s) => s !== '')
+        .join('  ')
+        .trimEnd();
+}
+/** One-line summary of a fine inner-loop frame for the tail. */
+function renderInnerFrame(f) {
+    switch (f.type) {
+        case 'inner.thinking':
+            return `  ${f.kind === 'thinking' ? '~' : '"'} ${oneLine(f.delta, 80)}`;
+        case 'inner.tool_call':
+            return `  -> ${f.tool}(${oneLine(f.argsSummary, 60)})`;
+        case 'inner.tool_result':
+            return `  <- ${f.tool}${f.isError ? ' ERR' : ''}: ${oneLine(f.resultSummary, 60)}`;
+        case 'inner.token':
+            return `  · ctx ${f.contextTokens ?? '?'} tok${f.contextPercent !== undefined ? ` (${pct(f.contextPercent)})` : ''}`;
+        case 'inner.turn':
+            return `  -- turn ${f.phase} #${f.turnIndex}`;
+        case 'inner.gate_pending':
+            // requestId front-and-center — the operator types it into `/gate <requestId> allow|deny`.
+            return `  [GATE ${f.requestId} ${f.tool} (${f.classification}, ${Math.round(f.timeoutMs / 1000)}s)]`;
+        case 'inner.gate_resolved':
+            return `  [GATE ${f.requestId} -> ${f.decision}]`;
+        default:
+            return '  ·';
+    }
+}
+/** Collapse whitespace + truncate for a single tail line. */
+function oneLine(s, max) {
+    const flat = s.replace(/\s+/g, ' ').trim();
+    return flat.length <= max ? flat : flat.slice(0, max - 1) + '…';
+}
+/**
+ * Render the full board. Header + player rows (conductor first), then — when a
+ * player is selected — a fine inner-loop tail (last {@link TAIL_RENDER_LINES}).
+ */
+function renderBoard(model) {
+    const ids = (0, board_1.sortedPlayerIds)(model);
+    const lines = [];
+    lines.push(`MISSION CONTROL · ${model.ensemble} · ${ids.length} player${ids.length === 1 ? '' : 's'}`);
+    if (ids.length === 0) {
+        lines.push('  (no players — waiting for the ensemble…)');
+    }
+    else {
+        for (const id of ids) {
+            const row = model.players.get(id);
+            lines.push(renderRow(row, id === model.selected));
+        }
+    }
+    if (model.selected) {
+        lines.push(`── tail: ${model.selected} ──`);
+        const recent = model.innerTail.slice(-TAIL_RENDER_LINES);
+        if (recent.length === 0) {
+            lines.push('  (no inner-loop activity yet)');
+        }
+        else {
+            for (const f of recent)
+                lines.push(renderInnerFrame(f));
+        }
+    }
+    return lines;
+}

package/dist/pi/phase-driver.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Pi-event → attachment-phase state machine (PURE — no Temporal, no Pi imports).
+ *
+ * This is the de-risking core of the Phase 0 PoC and the primary unit-test
+ * target. It translates Pi lifecycle events into (a) the next attachment phase
+ * and (b) the workflow action the extension must perform to publish that phase
+ * through the EXISTING session-workflow wire surface (claimAttachment /
+ * processingStart / processingEnd / requestDetach + adapterExited).
+ *
+ * Architect's EXACT mapping (do not "improve" without an architect sign-off):
+ *
+ *   session_start          → claim           → phase `attached`
+ *   agent_start            → processingStart → phase `processing`
+ *   agent_end              → processingEnd   → phase `awaiting`   (NOT detached!)
+ *   session_shutdown       → detach          → phase `draining`   (→ `detached`
+ *                                               confirmed workflow-side after
+ *                                               adapterExited; see note below)
+ *   turn_start  / turn_end          → NONE   → phase UNCHANGED, stamp activity
+ *   tool_execution_start / _end     → NONE   → phase UNCHANGED, stamp activity
+ *
+ * CRITICAL INVARIANT: `turn_*` and `tool_execution_*` fire multiple times mid
+ * agent run. If they drove the phase, the session would oscillate
+ * processing↔awaiting many times per turn. They are ACTIVITY signals only.
+ */
+/** Attachment phases — mirrors `AttachmentPhase` in src/types.ts (kept local to stay import-free). */
+export type PiPhase = 'booting' | 'attached' | 'processing' | 'awaiting' | 'draining' | 'detached' | 'gone';
+/**
+ * The workflow-side action the extension should perform in response to an event.
+ * `none` means "no phase-affecting workflow call" (activity-only events).
+ */
+export type WorkflowAction = {
+    kind: 'claim';
+} | {
+    kind: 'processingStart';
+    messageId: string;
+} | {
+    kind: 'processingEnd';
+    messageId: string;
+} | {
+    kind: 'detach';
+} | {
+    kind: 'none';
+};
+export interface PhaseDriverResult {
+    /** The workflow call the extension must make (or `none`). */
+    action: WorkflowAction;
+    /** The phase AFTER applying this event (the driver's local view). */
+    phase: PiPhase;
+    /** True when this event bumped the last-activity timestamp. */
+    activityStamped: boolean;
+}
+/**
+ * Stateful (but side-effect-free) translator. One instance per attached Pi
+ * session. Re-instantiate on each `session_start` — never reuse across session
+ * switches (D11).
+ */
+export declare class PhaseDriver {
+    private _phase;
+    private _lastActivityAt;
+    /** The in-flight message id between agent_start and agent_end (idempotency). */
+    private _currentMessageId;
+    get phase(): PiPhase;
+    get lastActivityAt(): string | null;
+    /**
+     * Translate a Pi lifecycle event into a phase transition + workflow action.
+     *
+     * @param event   Pi lifecycle event name.
+     * @param payload Optional `{ messageId }` carried by the event.
+     * @param now     ISO timestamp injected by the caller (keeps this pure/testable).
+     */
+    handle(event: string, payload: {
+        messageId?: string;
+    } | undefined, now: string): PhaseDriverResult;
+}

package/dist/pi/phase-driver.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Pi-event → attachment-phase state machine (PURE — no Temporal, no Pi imports).
+ *
+ * This is the de-risking core of the Phase 0 PoC and the primary unit-test
+ * target. It translates Pi lifecycle events into (a) the next attachment phase
+ * and (b) the workflow action the extension must perform to publish that phase
+ * through the EXISTING session-workflow wire surface (claimAttachment /
+ * processingStart / processingEnd / requestDetach + adapterExited).
+ *
+ * Architect's EXACT mapping (do not "improve" without an architect sign-off):
+ *
+ *   session_start          → claim           → phase `attached`
+ *   agent_start            → processingStart → phase `processing`
+ *   agent_end              → processingEnd   → phase `awaiting`   (NOT detached!)
+ *   session_shutdown       → detach          → phase `draining`   (→ `detached`
+ *                                               confirmed workflow-side after
+ *                                               adapterExited; see note below)
+ *   turn_start  / turn_end          → NONE   → phase UNCHANGED, stamp activity
+ *   tool_execution_start / _end     → NONE   → phase UNCHANGED, stamp activity
+ *
+ * CRITICAL INVARIANT: `turn_*` and `tool_execution_*` fire multiple times mid
+ * agent run. If they drove the phase, the session would oscillate
+ * processing↔awaiting many times per turn. They are ACTIVITY signals only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PhaseDriver = void 0;
+/** Events that stamp last-activity but MUST NOT drive the phase. */
+const ACTIVITY_ONLY_EVENTS = new Set([
+    'turn_start',
+    'turn_end',
+    'tool_execution_start',
+    'tool_execution_end',
+]);
+/**
+ * Stateful (but side-effect-free) translator. One instance per attached Pi
+ * session. Re-instantiate on each `session_start` — never reuse across session
+ * switches (D11).
+ */
+class PhaseDriver {
+    _phase = 'booting';
+    _lastActivityAt = null;
+    /** The in-flight message id between agent_start and agent_end (idempotency). */
+    _currentMessageId = null;
+    get phase() {
+        return this._phase;
+    }
+    get lastActivityAt() {
+        return this._lastActivityAt;
+    }
+    /**
+     * Translate a Pi lifecycle event into a phase transition + workflow action.
+     *
+     * @param event   Pi lifecycle event name.
+     * @param payload Optional `{ messageId }` carried by the event.
+     * @param now     ISO timestamp injected by the caller (keeps this pure/testable).
+     */
+    handle(event, payload = {}, now) {
+        if (ACTIVITY_ONLY_EVENTS.has(event)) {
+            // Activity-only: stamp, but DO NOT touch the phase.
+            this._lastActivityAt = now;
+            return { action: { kind: 'none' }, phase: this._phase, activityStamped: true };
+        }
+        switch (event) {
+            case 'session_start': {
+                this._currentMessageId = null; // defensive: fresh attach has no in-flight turn.
+                this._phase = 'attached';
+                return { action: { kind: 'claim' }, phase: this._phase, activityStamped: false };
+            }
+            case 'agent_start': {
+                // processingStart requires a stable messageId for idempotency. Prefer the
+                // event-supplied id; fall back to a now-derived id when Pi omits one.
+                const messageId = payload.messageId ?? `pi-turn-${now}`;
+                this._currentMessageId = messageId;
+                this._phase = 'processing';
+                this._lastActivityAt = now;
+                return {
+                    action: { kind: 'processingStart', messageId },
+                    phase: this._phase,
+                    activityStamped: true,
+                };
+            }
+            case 'agent_end': {
+                // End the IN-FLIGHT turn. agent_end means the agent finished THIS run and
+                // is now waiting for input → `awaiting`, NOT `detached`.
+                //
+                // Hardening (P2-4): end with the id we STARTED the turn with — NOT the
+                // payload — so processingStart/End pair EXACTLY (the workflow keys its
+                // in-flight set on that id; a mismatched end would orphan the entry). And
+                // a spurious / duplicate agent_end with no turn in flight is INERT: it
+                // must not synthesize a bogus processingEnd nor flip the phase (which
+                // could mask a genuine `processing` state or spuriously leave `awaiting`).
+                const inFlightId = this._currentMessageId;
+                if (inFlightId === null) {
+                    return { action: { kind: 'none' }, phase: this._phase, activityStamped: false };
+                }
+                this._currentMessageId = null;
+                this._phase = 'awaiting';
+                this._lastActivityAt = now;
+                return {
+                    action: { kind: 'processingEnd', messageId: inFlightId },
+                    phase: this._phase,
+                    activityStamped: true,
+                };
+            }
+            case 'session_shutdown': {
+                // Graceful teardown: phase → draining; the extension performs
+                // requestDetach (→ draining) then adapterExited (→ detached). The
+                // `detached` collapse is authoritative WORKFLOW-side; the driver's
+                // local view rests at `draining` because the process is exiting.
+                // Clear any in-flight turn so a late stray event after shutdown is inert.
+                this._currentMessageId = null;
+                this._phase = 'draining';
+                return { action: { kind: 'detach' }, phase: this._phase, activityStamped: false };
+            }
+            default:
+                // Unknown / unhandled events are inert: no phase change, no activity stamp.
+                return { action: { kind: 'none' }, phase: this._phase, activityStamped: false };
+        }
+    }
+}
+exports.PhaseDriver = PhaseDriver;

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

@@ -0,0 +1,208 @@
+/**
+ * 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;
+    execute: (args: Record<string, 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,80 @@
+/** 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;
+/**
+ * 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;