agent-tempo 1.2.0 → 1.4.0

package/dist/pi/mission-control/inner-tail.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Fine inner-loop tail consumer (3f) — the OPERATOR egress side of the 3c
+ * side-channel: `GET /v1/players/:e/:p/inner` (SSE, T3 admin bearer). Distinct
+ * from `src/pi/inner-loop-client.ts` (the player→daemon INGRESS). Opened on
+ * `/tail <player>`, torn down on deselect / shutdown.
+ *
+ * The SSE-frame parser is pure + unit-tested; the stream pump is injectable
+ * (fetch) so the extension wires real `fetch` while tests drive frames directly.
+ *
+ * NOTE (cross-host): `/inner` is daemon-LOCAL to the player's host. Single-host
+ * (Meijer container) uses the local daemon; multi-host should resolve the
+ * player's `preferredHost` via `/v1/hosts` and target that daemon — the
+ * `baseUrl` option is the seam for that (don't hardcode localhost forever).
+ */
+import type { InnerFrame } from '../inner-loop-publisher';
+/**
+ * Parse the `data:` payloads out of one SSE text chunk, returning the decoded
+ * InnerFrames + any trailing partial buffer to prepend to the next chunk. Pure.
+ * Tolerates keepalive comment lines (`:`) and multi-line frames split on `\n\n`.
+ */
+export declare function parseInnerSse(chunk: string, carry?: string): {
+    frames: InnerFrame[];
+    carry: string;
+};
+export type TailFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    body: AsyncIterable<Uint8Array> | null;
+}>;
+export interface OpenInnerTailOptions {
+    baseUrl: string;
+    adminToken: string;
+    ensemble: string;
+    playerId: string;
+    onFrame: (frame: InnerFrame) => void;
+    signal: AbortSignal;
+    fetchFn: TailFetch;
+    /** Called on a non-200 / stream error (e.g. to surface in the widget). */
+    onError?: (message: string) => void;
+}
+/**
+ * Open the per-player inner SSE and pump frames to `onFrame` until `signal`
+ * aborts. Resolves when the stream ends/aborts; never throws (errors → onError).
+ */
+export declare function openInnerTail(opts: OpenInnerTailOptions): Promise<void>;

package/dist/pi/mission-control/inner-tail.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseInnerSse = parseInnerSse;
+exports.openInnerTail = openInnerTail;
+/**
+ * Parse the `data:` payloads out of one SSE text chunk, returning the decoded
+ * InnerFrames + any trailing partial buffer to prepend to the next chunk. Pure.
+ * Tolerates keepalive comment lines (`:`) and multi-line frames split on `\n\n`.
+ */
+function parseInnerSse(chunk, carry = '') {
+    const buf = carry + chunk;
+    const parts = buf.split('\n\n');
+    const rest = parts.pop() ?? ''; // last element is an incomplete event (or '')
+    const frames = [];
+    for (const evt of parts) {
+        // An SSE event may have multiple lines; collect `data:` lines, ignore `:`/`event:`/`id:`.
+        const data = evt
+            .split('\n')
+            .filter((l) => l.startsWith('data:'))
+            .map((l) => l.slice(5).trimStart())
+            .join('\n');
+        if (!data)
+            continue;
+        try {
+            const parsed = JSON.parse(data);
+            if (parsed && typeof parsed.type === 'string' && parsed.type.startsWith('inner.')) {
+                frames.push(parsed);
+            }
+        }
+        catch {
+            // ignore malformed/non-frame data
+        }
+    }
+    return { frames, carry: rest };
+}
+/**
+ * Open the per-player inner SSE and pump frames to `onFrame` until `signal`
+ * aborts. Resolves when the stream ends/aborts; never throws (errors → onError).
+ */
+async function openInnerTail(opts) {
+    const url = `${opts.baseUrl.replace(/\/$/, '')}/v1/players/` +
+        `${encodeURIComponent(opts.ensemble)}/${encodeURIComponent(opts.playerId)}/inner`;
+    let res;
+    try {
+        res = await opts.fetchFn(url, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${opts.adminToken}`, Accept: 'text/event-stream' },
+            signal: opts.signal,
+        });
+    }
+    catch (err) {
+        if (!opts.signal.aborted)
+            opts.onError?.(err instanceof Error ? err.message : String(err));
+        return;
+    }
+    if (res.status !== 200 || !res.body) {
+        opts.onError?.(`inner tail HTTP ${res.status}`);
+        return;
+    }
+    const decoder = new TextDecoder();
+    let carry = '';
+    try {
+        for await (const chunk of res.body) {
+            if (opts.signal.aborted)
+                break;
+            const { frames, carry: next } = parseInnerSse(decoder.decode(chunk, { stream: true }), carry);
+            carry = next;
+            for (const f of frames)
+                opts.onFrame(f);
+        }
+    }
+    catch (err) {
+        if (!opts.signal.aborted)
+            opts.onError?.(err instanceof Error ? err.message : String(err));
+    }
+}

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

@@ -0,0 +1,43 @@
+/**
+ * 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`.
+ */
+export interface ExtensionUIDialogOptions {
+    signal?: AbortSignal;
+    timeout?: number;
+}
+/** The `ctx.ui` surface (present only when `ctx.hasUI`). */
+export interface ExtensionUIContext {
+    /** Persistent widget: re-call with new lines to update; `undefined` clears it. */
+    setWidget(key: string, content: string[] | undefined, options?: {
+        placement?: 'aboveEditor' | 'belowEditor';
+    }): void;
+    select(title: string, options: string[], opts?: ExtensionUIDialogOptions): Promise<string | undefined>;
+    confirm(title: string, message: string, opts?: ExtensionUIDialogOptions): Promise<boolean>;
+    input(title: string, placeholder?: string, opts?: ExtensionUIDialogOptions): Promise<string | undefined>;
+    notify(message: string): void;
+}
+/** Context passed to every handler. `ui` is only safe to use when `hasUI`. */
+export interface McExtensionContext {
+    ui: ExtensionUIContext;
+    hasUI: boolean;
+}
+export type McEventHandler = (event: unknown, ctx: McExtensionContext) => void | Promise<void>;
+export type McCommandHandler = (args: string, ctx: McExtensionContext) => void | Promise<void>;
+export type McShortcutHandler = (ctx: McExtensionContext) => void | Promise<void>;
+/** The `pi` object passed to the extension's default export — slice we use. */
+export interface McExtensionAPI {
+    on(event: string, handler: McEventHandler): void;
+    registerCommand(name: string, options: {
+        description?: string;
+        handler: McCommandHandler;
+    }): void;
+    registerShortcut(shortcut: unknown, options: {
+        description?: string;
+        handler: McShortcutHandler;
+    }): void;
+}

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;