agent-tempo 1.2.0 → 1.4.0

package/dist/pi/inner-loop-client.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InnerLoopHttpClient = exports.MAX_FRAME_BYTES = exports.INGEST_TOKEN_ENV = void 0;
+/**
+ * Inner-loop HTTP client (3c Part 5) — the PRODUCTION {@link InnerLoopRegistry}
+ * impl the {@link InnerLoopPublisher} injects.
+ *
+ * Why HTTP, not in-process: a headless Pi player is a DETACHED subprocess,
+ * separate from the daemon that hosts the real fine-tail registry + SSE
+ * side-channel. So `publish` / `subscriberCount` are thin loopback-HTTP calls to
+ * the daemon, discovered via the port-file. This client lives on the player side
+ * of that boundary; lead owns the daemon endpoints.
+ *
+ * LOCKED wire contract (lead, Part 4):
+ *   - Discovery: {@link readPortFile} → daemon HTTP port (`null` ⇒ daemon HTTP
+ *     not up ⇒ no-op gracefully). Base `http://127.0.0.1:${port}` (loopback only).
+ *   - Auth: `X-Ingest-Token: <token>` on BOTH calls, from `AGENT_TEMPO_INGEST_TOKEN`
+ *     (threaded in at spawn). Token unset ⇒ no-op (publish drops, presence ⇒ 0).
+ *   - POST `/v1/players/:ensemble/:playerId/inner/ingest` — body = the InnerFrame
+ *     JSON object DIRECTLY (no wrapper), ≤32KB (DOS backstop). 204 ⇒ ok; ANY
+ *     other status / network error ⇒ DROP the frame, never throw, never block
+ *     the Pi loop (fire-and-forget).
+ *   - GET `/v1/players/:ensemble/:playerId/inner/presence` — 200 `{subscribers:number}`;
+ *     anything else (e.g. 403) ⇒ treat as 0.
+ *
+ * `subscriberCount` MUST be synchronous (the interface) — it returns a CACHED
+ * value, refreshed stale-while-revalidate: each call fires a rate-limited
+ * background GET (≤1/`presencePollMs`) and returns the last known count (default
+ * 0 until the first GET resolves, and on any failure — fail-safe: unknown ⇒ no
+ * forwarding). The publisher additionally rate-limits how often it calls this.
+ */
+const port_file_1 = require("../http/port-file");
+/** Env var carrying the per-player ingest token (threaded in at spawn). */
+exports.INGEST_TOKEN_ENV = 'AGENT_TEMPO_INGEST_TOKEN';
+/** DOS backstop — frames over this are dropped (summaries are already ~2KB-truncated). */
+exports.MAX_FRAME_BYTES = 32 * 1024;
+const DEFAULT_PRESENCE_POLL_MS = 1000;
+const log = (...args) => {
+    // eslint-disable-next-line no-console
+    console.error('[agent-tempo:pi]', ...args);
+};
+/** Default transport — global `fetch` adapted to {@link InnerLoopFetch}, or a no-op. */
+function resolveFetch() {
+    const g = globalThis.fetch;
+    if (typeof g !== 'function')
+        return null;
+    return g;
+}
+/**
+ * Loopback-HTTP {@link InnerLoopRegistry}. Construct one per headless player with
+ * its ensemble + playerId; the publisher calls `publish` / `subscriberCount`.
+ * The `workflowId` argument is the player's own and is unused — the URL is built
+ * from the ctor ensemble + playerId.
+ */
+class InnerLoopHttpClient {
+    ensemble;
+    playerId;
+    ingestToken;
+    readPort;
+    fetchFn;
+    presencePollMs;
+    now;
+    /** Last presence count from the daemon. 0 until the first GET resolves / on failure. */
+    cachedSubscribers = 0;
+    /** 3d — last gateArmed flag from the daemon (folded into the presence response). */
+    cachedGateArmed = false;
+    lastPresenceRefresh = -Infinity;
+    constructor(opts) {
+        this.ensemble = opts.ensemble;
+        this.playerId = opts.playerId;
+        this.ingestToken = opts.ingestToken ?? process.env[exports.INGEST_TOKEN_ENV];
+        this.readPort = opts.readPort ?? (() => (0, port_file_1.readPortFile)());
+        this.fetchFn = opts.fetchFn ?? resolveFetch();
+        this.presencePollMs = opts.presencePollMs ?? DEFAULT_PRESENCE_POLL_MS;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Whether the client can talk to the daemon at all (token + transport present). */
+    get enabled() {
+        return Boolean(this.ingestToken) && this.fetchFn !== null;
+    }
+    baseUrl(port) {
+        return `http://127.0.0.1:${port}/v1/players/` +
+            `${encodeURIComponent(this.ensemble)}/${encodeURIComponent(this.playerId)}/inner`;
+    }
+    /** Fire-and-forget POST of one frame. Drops (never throws/blocks) on any failure. */
+    publish(_workflowId, frame) {
+        if (!this.enabled)
+            return;
+        const port = this.readPort();
+        if (port == null)
+            return; // daemon HTTP not up → drop gracefully
+        let body;
+        try {
+            body = JSON.stringify(frame);
+        }
+        catch {
+            return; // unserializable frame → drop
+        }
+        if (Buffer.byteLength(body, 'utf8') > exports.MAX_FRAME_BYTES) {
+            log(`inner frame ${frame.type} exceeds ${exports.MAX_FRAME_BYTES}B — dropped`);
+            return;
+        }
+        void this.fetchFn(`${this.baseUrl(port)}/ingest`, {
+            method: 'POST',
+            headers: { 'X-Ingest-Token': this.ingestToken, 'Content-Type': 'application/json' },
+            body,
+        })
+            .then((res) => {
+            if (res.status !== 204) {
+                // 403 (loopback/token/shape) / 413 (oversize) / other — drop silently.
+            }
+        })
+            .catch(() => { });
+    }
+    /** Synchronous cached presence (stale-while-revalidate). Default 0 / fail-safe 0. */
+    subscriberCount(_workflowId) {
+        this.maybeRefreshPresence();
+        return this.cachedSubscribers;
+    }
+    /**
+     * 3d — synchronous cached `gateArmed` (same stale-while-revalidate presence GET
+     * that feeds subscriberCount; short-poll keeps it within ~1s). Default false /
+     * fail-safe false (a missed/failed presence read never spuriously engages the
+     * gate). The engagement check reads this together with subscriberCount.
+     */
+    gateArmed(_workflowId) {
+        this.maybeRefreshPresence();
+        return this.cachedGateArmed;
+    }
+    /** Fire a rate-limited background presence GET that updates the cache. */
+    maybeRefreshPresence() {
+        if (!this.enabled)
+            return;
+        const t = this.now();
+        if (t - this.lastPresenceRefresh < this.presencePollMs)
+            return;
+        const port = this.readPort();
+        if (port == null)
+            return;
+        this.lastPresenceRefresh = t;
+        void this.fetchFn(`${this.baseUrl(port)}/presence`, {
+            method: 'GET',
+            headers: { 'X-Ingest-Token': this.ingestToken },
+        })
+            .then(async (res) => {
+            if (res.status !== 200) {
+                this.cachedSubscribers = 0; // 403/etc → treat as no subscribers
+                this.cachedGateArmed = false;
+                return;
+            }
+            try {
+                const data = (await res.json());
+                this.cachedSubscribers = typeof data.subscribers === 'number' ? data.subscribers : 0;
+                this.cachedGateArmed = data.gateArmed === true;
+            }
+            catch {
+                this.cachedSubscribers = 0;
+                this.cachedGateArmed = false;
+            }
+        })
+            .catch(() => { this.cachedSubscribers = 0; this.cachedGateArmed = false; });
+    }
+}
+exports.InnerLoopHttpClient = InnerLoopHttpClient;

package/dist/pi/inner-loop-publisher.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Inner-loop publisher (3c) — the single Pi-source observer of the headless
+ * agent loop. It subscribes to `pi.on(...)` events ONCE and routes what it
+ * observes two ways, never touching extension.ts (the singleton imports + wires
+ * this module on bootstrap):
+ *
+ *   TIER 1 — COARSE, always-on (route A, poll-derived). Maintains a small
+ *     {@link CoarseState} ({ currentTool, contextTokens?, contextPercent? }) that
+ *     the heartbeat sender samples via {@link InnerLoopPublisher.getCoarseState}
+ *     and piggybacks onto the EXISTING heartbeat (additive optional fields — ZERO
+ *     new Temporal signals). lead's AggregateRunner poll-diffs that metadata into
+ *     a `player.activity` SSE event. This module never touches the bus or
+ *     Temporal — it only produces the values.
+ *
+ *   TIER 2 — FINE, on-demand (push). Forwards inner frames to the injected
+ *     {@link InnerLoopRegistry} — but ONLY when `subscriberCount(workflowId) > 0`
+ *     (the subscriber-presence gate: zero watchers ⇒ zero forwarding ⇒ no
+ *     firehose). This module owns: source coalescing of thinking/text deltas
+ *     (flush on a timer OR a char threshold, bounding wire rate regardless of LLM
+ *     token speed), the presence gate (rate-limited so it can't hammer the
+ *     registry), and ~2KB summary truncation (never forward raw file/Bash output
+ *     inline — privacy + volume). The registry owns per-subscriber backpressure
+ *     (drop-oldest + `compacted{dropped:N}`).
+ *
+ * TOKENS ARE PULL-ONLY (Pi 0.78): there is no token event. Usage comes from the
+ * handler's 2nd arg `ctx.getContextUsage()` (sampled at `turn_end`), surfaced as
+ * context-window PRESSURE (tokens + percent) — the useful operational signal.
+ *
+ * Cross-process note: the headless Pi player is a DETACHED subprocess, separate
+ * from the daemon that hosts the real registry — so the production
+ * {@link InnerLoopRegistry} impl is a thin loopback-HTTP client, NOT an
+ * in-process call. This module is coded against the 2-method interface (DI) so
+ * it's unit-testable without the HTTP layer; the real client is wired at
+ * integration.
+ */
+import type { ExtensionAPI, PiExtensionContext, PiMessageUpdatePayload, PiToolCallEvent, PiToolExecutionStartPayload, PiToolExecutionEndPayload, PiTurnPayload } from './pi-types';
+/**
+ * A fine-tail frame (Tier 2). Matches lead's InnerLoopRegistry frame schema.
+ *
+ * 3d adds the two MD-G operator-gate frames. They ride the SAME /inner stream the
+ * operator already watches (per-player, so workflowId/playerId are implicit):
+ *   - `inner.gate_pending`  — emitted by the Pi tool_call handler when the gate
+ *     engages; the ingest route's side-effect registers the pending in the
+ *     GateRegistry (the "engagement IS registration" path). `argsSummary` is
+ *     source-truncated (~2KB). `timeoutMs` lets the operator UI render a countdown.
+ *   - `inner.gate_resolved` — emitted by the GateRegistry (via an injected
+ *     publishToInner callback) when a decision lands (operator) or the 45s
+ *     auto-allow fires (timeout), so the operator sees the outcome.
+ */
+export type InnerFrame = {
+    type: 'inner.thinking';
+    delta: string;
+    kind: 'thinking' | 'text';
+} | {
+    type: 'inner.tool_call';
+    tool: string;
+    argsSummary: string;
+    ts: number;
+} | {
+    type: 'inner.tool_result';
+    tool: string;
+    resultSummary: string;
+    isError: boolean;
+    ts: number;
+} | {
+    type: 'inner.token';
+    contextTokens?: number;
+    contextPercent?: number;
+} | {
+    type: 'inner.turn';
+    phase: 'start' | 'end';
+    turnIndex: number;
+    ts: number;
+} | {
+    type: 'inner.gate_pending';
+    requestId: string;
+    tool: string;
+    argsSummary: string;
+    classification: 'exec' | 'high-blast';
+    timeoutMs: number;
+    ts: number;
+} | {
+    type: 'inner.gate_resolved';
+    requestId: string;
+    decision: 'allow' | 'deny' | 'auto-allow';
+    source: 'operator' | 'timeout';
+    ts: number;
+};
+/**
+ * The daemon-side fine-tail sink (lead's `http/inner-loop.ts`). Injected so the
+ * publisher is unit-testable without the HTTP layer; production is a thin
+ * loopback-HTTP client to the daemon.
+ */
+export interface InnerLoopRegistry {
+    publish(workflowId: string, frame: InnerFrame): void;
+    /** Live fine-tail subscriber count for this player — the presence gate reads it. */
+    subscriberCount(workflowId: string): number;
+}
+/** Coarse always-on state the heartbeat sender samples (Tier 1). */
+export interface CoarseState {
+    /** Tool currently executing, or null when idle between tools. */
+    currentTool: string | null;
+    /** Context tokens in use (pressure), when known. */
+    contextTokens?: number;
+    /** Context-window usage fraction/percent, when known. */
+    contextPercent?: number;
+}
+export interface InnerLoopPublisherOptions {
+    /** The player's fixed session workflowId (the registry key). */
+    workflowId: string;
+    /** Fine-tail sink (DI). */
+    registry: InnerLoopRegistry;
+    /** Max chars for an args/result summary before truncation (default 2048 ≈ 2KB). */
+    maxSummaryChars?: number;
+    /** Flush a coalesced thinking/text buffer after this many chars (default 2048). */
+    coalesceChars?: number;
+    /** Flush a coalesced thinking/text buffer this long after the first buffered delta (default 100ms). */
+    coalesceMs?: number;
+    /** Re-check `subscriberCount` at most this often (default 1000ms) — bounds registry calls. */
+    presencePollMs?: number;
+    /** Injected clock (tests). Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** Truncate to `maxChars` with a marker — keeps a fine-tail summary bounded. */
+export declare function truncateSummary(value: unknown, maxChars?: number): string;
+/**
+ * Observes the Pi inner loop and routes coarse state + fine frames. Construct
+ * one per headless player; call {@link start} with the extension's `pi` on
+ * bootstrap and {@link stop} on teardown. Handler methods are public so unit
+ * tests drive them directly (no live Pi) — mirroring the CuePump test pattern.
+ */
+export declare class InnerLoopPublisher {
+    private readonly workflowId;
+    private readonly registry;
+    private readonly maxSummaryChars;
+    private readonly coalesceChars;
+    private readonly coalesceMs;
+    private readonly presencePollMs;
+    private readonly now;
+    /** Tier-1 coarse state, sampled by the heartbeat sender. */
+    private coarse;
+    /** Coalesce buffer for thinking/text deltas (single buffer, flushed on kind-switch). */
+    private pending;
+    private flushTimer;
+    /** Rate-limited presence cache (avoids per-frame registry calls). */
+    private presentCached;
+    private lastPresenceCheck;
+    constructor(opts: InnerLoopPublisherOptions);
+    /** Register the Pi event handlers and start the coalesce flush timer. */
+    start(pi: ExtensionAPI): void;
+    /** Tear down the flush timer (flushing any trailing buffer first). */
+    stop(): void;
+    /** Tier-1: the current coarse state, sampled by the heartbeat sender. */
+    getCoarseState(): CoarseState;
+    /**
+     * Stream delta → coalesce into the pending thinking/text buffer. Thinking/text
+     * is PURELY fine-tail (no coarse state), so the presence gate goes BEFORE
+     * buffering — when nobody's watching we do zero per-delta work on this hot path.
+     */
+    handleMessageUpdate(payload: PiMessageUpdatePayload): void;
+    /** Tool started → set coarse currentTool. (No fine frame here; tool_call carries args.) */
+    handleToolStart(payload: PiToolExecutionStartPayload): void;
+    /**
+     * Tool finished → clear coarse currentTool (Tier-1, ALWAYS) + forward a fine
+     * tool_result frame. The presence gate goes BEFORE `truncateSummary` so a large
+     * tool result is never JSON-stringified when nobody's tailing.
+     */
+    handleToolEnd(payload: PiToolExecutionEndPayload): void;
+    /** Pre-exec tool_call → forward a fine tool_call frame (args summarized). */
+    handleToolCall(payload: PiToolCallEvent): void;
+    /** Turn began → forward a fine turn frame. */
+    handleTurnStart(payload: PiTurnPayload): void;
+    /**
+     * Turn ended → flush pending deltas, sample context usage (the ONLY token
+     * source, pull-only), update coarse state, and forward turn + token frames.
+     */
+    handleTurnEnd(payload: PiTurnPayload, ctx?: PiExtensionContext): void;
+    /** Pull context usage from the handler ctx and fold it into coarse state. */
+    private sampleUsage;
+    private appendDelta;
+    /** Emit the buffered thinking/text as one inner.thinking frame (presence-gated). */
+    flushPending(): void;
+    /** Rate-limited presence check — caches `subscriberCount > 0` per presencePollMs. */
+    private isPresent;
+    /** Forward a fine frame iff a subscriber is present (the firehose gate). */
+    private forward;
+}

package/dist/pi/inner-loop-publisher.js

@@ -0,0 +1,236 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InnerLoopPublisher = void 0;
+exports.truncateSummary = truncateSummary;
+const DEFAULT_MAX_SUMMARY_CHARS = 2048;
+const DEFAULT_COALESCE_CHARS = 2048;
+const DEFAULT_COALESCE_MS = 100;
+const DEFAULT_PRESENCE_POLL_MS = 1000;
+const TRUNCATION_MARKER = '…[truncated]';
+const log = (...args) => {
+    // eslint-disable-next-line no-console
+    console.error('[agent-tempo:pi]', ...args);
+};
+/** Stringify an arbitrary tool arg/result for a summary (compact, never throws). */
+function stringifySummary(value) {
+    if (value == null)
+        return '';
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** Truncate to `maxChars` with a marker — keeps a fine-tail summary bounded. */
+function truncateSummary(value, maxChars = DEFAULT_MAX_SUMMARY_CHARS) {
+    const s = stringifySummary(value);
+    if (s.length <= maxChars)
+        return s;
+    return s.slice(0, Math.max(0, maxChars - TRUNCATION_MARKER.length)) + TRUNCATION_MARKER;
+}
+/**
+ * Observes the Pi inner loop and routes coarse state + fine frames. Construct
+ * one per headless player; call {@link start} with the extension's `pi` on
+ * bootstrap and {@link stop} on teardown. Handler methods are public so unit
+ * tests drive them directly (no live Pi) — mirroring the CuePump test pattern.
+ */
+class InnerLoopPublisher {
+    workflowId;
+    registry;
+    maxSummaryChars;
+    coalesceChars;
+    coalesceMs;
+    presencePollMs;
+    now;
+    /** Tier-1 coarse state, sampled by the heartbeat sender. */
+    coarse = { currentTool: null };
+    /** Coalesce buffer for thinking/text deltas (single buffer, flushed on kind-switch). */
+    pending = null;
+    flushTimer = null;
+    /** Rate-limited presence cache (avoids per-frame registry calls). */
+    presentCached = false;
+    lastPresenceCheck = -Infinity;
+    constructor(opts) {
+        this.workflowId = opts.workflowId;
+        this.registry = opts.registry;
+        this.maxSummaryChars = opts.maxSummaryChars ?? DEFAULT_MAX_SUMMARY_CHARS;
+        this.coalesceChars = opts.coalesceChars ?? DEFAULT_COALESCE_CHARS;
+        this.coalesceMs = opts.coalesceMs ?? DEFAULT_COALESCE_MS;
+        this.presencePollMs = opts.presencePollMs ?? DEFAULT_PRESENCE_POLL_MS;
+        this.now = opts.now ?? Date.now;
+    }
+    /** Register the Pi event handlers and start the coalesce flush timer. */
+    start(pi) {
+        pi.on('message_update', (payload) => this.handleMessageUpdate(payload));
+        pi.on('tool_call', (payload) => this.handleToolCall(payload));
+        pi.on('tool_execution_start', (payload) => this.handleToolStart(payload));
+        pi.on('tool_execution_end', (payload) => this.handleToolEnd(payload));
+        pi.on('turn_start', (payload) => this.handleTurnStart(payload));
+        pi.on('turn_end', (payload, ctx) => this.handleTurnEnd(payload, ctx));
+        if (!this.flushTimer) {
+            this.flushTimer = setInterval(() => this.flushPending(), this.coalesceMs);
+            if (typeof this.flushTimer.unref === 'function')
+                this.flushTimer.unref();
+        }
+    }
+    /** Tear down the flush timer (flushing any trailing buffer first). */
+    stop() {
+        this.flushPending();
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+    }
+    /** Tier-1: the current coarse state, sampled by the heartbeat sender. */
+    getCoarseState() {
+        return { ...this.coarse };
+    }
+    // ── Pi event handlers (public for unit tests) ──────────────────────────────
+    /**
+     * Stream delta → coalesce into the pending thinking/text buffer. Thinking/text
+     * is PURELY fine-tail (no coarse state), so the presence gate goes BEFORE
+     * buffering — when nobody's watching we do zero per-delta work on this hot path.
+     */
+    handleMessageUpdate(payload) {
+        const ev = payload.assistantMessageEvent;
+        if (!ev || typeof ev.delta !== 'string' || ev.delta.length === 0)
+            return;
+        const kind = ev.type === 'text_delta' ? 'text' : ev.type === 'thinking_delta' ? 'thinking' : null;
+        if (kind === null)
+            return; // ignore toolcall_delta and any other variant
+        if (!this.isPresent())
+            return; // no subscriber → don't buffer fine-tail text
+        this.appendDelta(kind, ev.delta);
+    }
+    /** Tool started → set coarse currentTool. (No fine frame here; tool_call carries args.) */
+    handleToolStart(payload) {
+        if (typeof payload.toolName === 'string' && payload.toolName.length > 0) {
+            this.coarse.currentTool = payload.toolName;
+        }
+    }
+    /**
+     * Tool finished → clear coarse currentTool (Tier-1, ALWAYS) + forward a fine
+     * tool_result frame. The presence gate goes BEFORE `truncateSummary` so a large
+     * tool result is never JSON-stringified when nobody's tailing.
+     */
+    handleToolEnd(payload) {
+        this.coarse.currentTool = null; // always-on coarse update — never gated
+        if (!this.isPresent())
+            return; // gate before the (potentially large) stringify
+        this.forward({
+            type: 'inner.tool_result',
+            tool: typeof payload.toolName === 'string' ? payload.toolName : '',
+            resultSummary: truncateSummary(payload.result, this.maxSummaryChars),
+            isError: payload.isError === true,
+            ts: this.now(),
+        });
+    }
+    /** Pre-exec tool_call → forward a fine tool_call frame (args summarized). */
+    handleToolCall(payload) {
+        if (!this.isPresent())
+            return; // gate before stringifying args
+        this.forward({
+            type: 'inner.tool_call',
+            tool: typeof payload.toolName === 'string' ? payload.toolName : '',
+            argsSummary: truncateSummary(payload.input, this.maxSummaryChars),
+            ts: this.now(),
+        });
+    }
+    /** Turn began → forward a fine turn frame. */
+    handleTurnStart(payload) {
+        this.forward({ type: 'inner.turn', phase: 'start', turnIndex: payload.turnIndex ?? -1, ts: this.now() });
+    }
+    /**
+     * Turn ended → flush pending deltas, sample context usage (the ONLY token
+     * source, pull-only), update coarse state, and forward turn + token frames.
+     */
+    handleTurnEnd(payload, ctx) {
+        this.flushPending();
+        this.sampleUsage(ctx);
+        this.forward({ type: 'inner.turn', phase: 'end', turnIndex: payload.turnIndex ?? -1, ts: this.now() });
+        if (this.coarse.contextTokens !== undefined || this.coarse.contextPercent !== undefined) {
+            this.forward({
+                type: 'inner.token',
+                ...(this.coarse.contextTokens !== undefined ? { contextTokens: this.coarse.contextTokens } : {}),
+                ...(this.coarse.contextPercent !== undefined ? { contextPercent: this.coarse.contextPercent } : {}),
+            });
+        }
+    }
+    /** Pull context usage from the handler ctx and fold it into coarse state. */
+    sampleUsage(ctx) {
+        if (!ctx || typeof ctx.getContextUsage !== 'function')
+            return;
+        let usage;
+        try {
+            usage = ctx.getContextUsage();
+        }
+        catch (err) {
+            log('getContextUsage failed:', err);
+            return;
+        }
+        if (!usage)
+            return;
+        if (typeof usage.tokens === 'number')
+            this.coarse.contextTokens = usage.tokens;
+        if (typeof usage.percent === 'number')
+            this.coarse.contextPercent = usage.percent;
+    }
+    // ── Coalescing (source-side; bounds wire rate) ─────────────────────────────
+    appendDelta(kind, delta) {
+        if (this.pending && this.pending.kind !== kind) {
+            // Kind switched (thinking→text or vice versa) — flush to preserve order.
+            this.flushPending();
+        }
+        if (!this.pending) {
+            this.pending = { kind, text: '', startedAt: this.now() };
+        }
+        this.pending.text += delta;
+        // The char-threshold flush also CAPS the `+=` concat window — the buffer
+        // never grows past ~coalesceChars before being cut loose, so repeated
+        // appends stay bounded regardless of total output length. Don't remove it.
+        if (this.pending.text.length >= this.coalesceChars) {
+            this.flushPending();
+        }
+    }
+    /** Emit the buffered thinking/text as one inner.thinking frame (presence-gated). */
+    flushPending() {
+        const p = this.pending;
+        if (!p || p.text.length === 0) {
+            this.pending = null;
+            return;
+        }
+        this.pending = null;
+        this.forward({ type: 'inner.thinking', delta: p.text, kind: p.kind });
+    }
+    // ── Presence gate + forward ────────────────────────────────────────────────
+    /** Rate-limited presence check — caches `subscriberCount > 0` per presencePollMs. */
+    isPresent() {
+        const t = this.now();
+        if (t - this.lastPresenceCheck >= this.presencePollMs) {
+            this.lastPresenceCheck = t;
+            try {
+                this.presentCached = this.registry.subscriberCount(this.workflowId) > 0;
+            }
+            catch (err) {
+                log('subscriberCount failed (treating as no subscribers):', err);
+                this.presentCached = false;
+            }
+        }
+        return this.presentCached;
+    }
+    /** Forward a fine frame iff a subscriber is present (the firehose gate). */
+    forward(frame) {
+        if (!this.isPresent())
+            return;
+        try {
+            this.registry.publish(this.workflowId, frame);
+        }
+        catch (err) {
+            log(`publish ${frame.type} failed:`, err);
+        }
+    }
+}
+exports.InnerLoopPublisher = InnerLoopPublisher;

package/dist/pi/lazy-proxy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Lazy resolution proxy (D11 — Phase 2).
+ *
+ * The Pi extension registers the FULL tool surface ONCE at extension load (Pi
+ * tools are registered up-front, not per session), yet each tool's neutral
+ * handler needs the player's live Temporal `Client` and session `WorkflowHandle`
+ * — which only exist AFTER the extension connects and claims a session workflow
+ * on `session_start`, and which are RE-ACQUIRED on a SessionManager switch
+ * (newSession / continueSession / fork) without caching across the switch.
+ *
+ * `createLazyProxy` bridges that gap: it returns an object that forwards every
+ * property access and method call to a target resolved FRESH per access via the
+ * `resolve` callback. So `buildAllTempoTools(opts)` can be built once at load
+ * with proxy `client` / `handle`, and each handler — invoked only during a live
+ * session — transparently hits the CURRENT client/handle.
+ *
+ * Additive to Phase 1: the proxy IS a `Client` / `WorkflowHandle` structurally,
+ * so the descriptor contract (`build*Tool(...)`) and the MCP renderer are
+ * unchanged — MCP passes a concrete handle, Pi passes a lazily-resolved one.
+ *
+ * Determinism note: client-side only (src/pi).
+ */
+/**
+ * Wrap a lazily-resolved target behind a transparent proxy.
+ *
+ * @param resolve Returns the current target, or `null`/`undefined` when none is
+ *                active yet (e.g. before the first session attaches).
+ * @param label   Human-readable name used in the "unavailable" error.
+ *
+ * Every property read resolves the target first:
+ *   - methods are returned bound to the live target,
+ *   - non-function properties (e.g. `client.workflow`) are returned as-is from
+ *     the live target,
+ *   - if no target is active, access throws a clear error (the calling tool
+ *     handler catches it and returns a `fail(...)` result).
+ */
+export declare function createLazyProxy<T extends object>(resolve: () => T | null | undefined, label: string): T;

package/dist/pi/lazy-proxy.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Lazy resolution proxy (D11 — Phase 2).
+ *
+ * The Pi extension registers the FULL tool surface ONCE at extension load (Pi
+ * tools are registered up-front, not per session), yet each tool's neutral
+ * handler needs the player's live Temporal `Client` and session `WorkflowHandle`
+ * — which only exist AFTER the extension connects and claims a session workflow
+ * on `session_start`, and which are RE-ACQUIRED on a SessionManager switch
+ * (newSession / continueSession / fork) without caching across the switch.
+ *
+ * `createLazyProxy` bridges that gap: it returns an object that forwards every
+ * property access and method call to a target resolved FRESH per access via the
+ * `resolve` callback. So `buildAllTempoTools(opts)` can be built once at load
+ * with proxy `client` / `handle`, and each handler — invoked only during a live
+ * session — transparently hits the CURRENT client/handle.
+ *
+ * Additive to Phase 1: the proxy IS a `Client` / `WorkflowHandle` structurally,
+ * so the descriptor contract (`build*Tool(...)`) and the MCP renderer are
+ * unchanged — MCP passes a concrete handle, Pi passes a lazily-resolved one.
+ *
+ * Determinism note: client-side only (src/pi).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLazyProxy = createLazyProxy;
+/**
+ * Wrap a lazily-resolved target behind a transparent proxy.
+ *
+ * @param resolve Returns the current target, or `null`/`undefined` when none is
+ *                active yet (e.g. before the first session attaches).
+ * @param label   Human-readable name used in the "unavailable" error.
+ *
+ * Every property read resolves the target first:
+ *   - methods are returned bound to the live target,
+ *   - non-function properties (e.g. `client.workflow`) are returned as-is from
+ *     the live target,
+ *   - if no target is active, access throws a clear error (the calling tool
+ *     handler catches it and returns a `fail(...)` result).
+ */
+function createLazyProxy(resolve, label) {
+    return new Proxy({}, {
+        get(_target, prop) {
+            const live = resolve();
+            if (!live) {
+                throw new Error(`Pi: ${label} unavailable — no active session is attached`);
+            }
+            const value = live[prop];
+            return typeof value === 'function' ? value.bind(live) : value;
+        },
+        has(_target, prop) {
+            const live = resolve();
+            return live ? prop in live : false;
+        },
+    });
+}