agent-tempo 1.3.1 → 1.4.1

package/dist/pi/headless.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Headless Pi runtime (Phase 3a). Spawned by the daemon (spawnPiHeadless →
+ * src/adapters/pi/adapter.ts) for a recruited `agent: 'pi'` player. No human, no
+ * terminal: it constructs Pi's `createAgentSession` with the agent-tempo
+ * extension injected INLINE, and the module-scope extension singleton
+ * (createPiExtension, mode='headless') owns claim/heartbeat/tool-registration/
+ * cue-pump on `session_start`. Reuses ~everything from Phases 1–2.
+ *
+ * Lifecycle:
+ *   1. probe Pi SDK; resolve the model via pi-ai `getModel` — a bad/unindexed
+ *      model fails CLEAN (exit before attach, no orphan — architect's backstop).
+ *   2. createAgentSession({ resourceLoader: DefaultResourceLoader({
+ *        extensionFactories: [ext] }), model? }).
+ *   3. await session.bindExtensions({}) → fires session_start → the singleton
+ *      attaches (claim + heartbeat + tools + cue pump). bindExtensions IS the
+ *      explicit bootstrap (not "hope session_start fires").
+ *   4. stay alive until a shutdown signal (SIGTERM/SIGINT).
+ *   5. RELIABLE detach (headless owns the exit): detachAllPiRuntimesForExit()
+ *      [await adapterExited] → session.dispose() → process exit.
+ *
+ * ESM note: the Pi SDK is an ESM-only optional dep; we import it via a
+ * `Function`-wrapped dynamic `import()` so tsc (module=commonjs) doesn't
+ * downlevel it to `require()` — Node resolves the real ESM module at runtime.
+ *
+ * Determinism boundary: client-side only.
+ */
+import { type Config } from '../config';
+import { type PiToolAccess } from './extension';
+export interface RunHeadlessPiOptions {
+    config?: Config;
+    toolAccess?: PiToolAccess;
+    /** `provider/model` selector; absent → Pi default. */
+    model?: string;
+    /** Restart-resume: prior Pi conversation id (A4 wires SessionManager). */
+    continueSessionId?: string;
+}
+/**
+ * Build the `DefaultResourceLoader` options for a headless Pi player.
+ *
+ * SECURITY — S2 (MD-C deny-list soundness). The `restricted` tool gate is a
+ * DENY-LIST over shell/exec tool *names* (tool-capability.ts EXEC_TOOLS, via
+ * `classify(name) === 'exec'` — F1 replaced extension.ts's former local set). That
+ * guarantee — "restricted = no host execution" — holds ONLY IF no third-party
+ * extension can register an un-blacklisted execution tool (e.g. a custom
+ * `python` / `npm` / `run` tool). It therefore depends on a hard structural
+ * fact: which extensions Pi loads.
+ *
+ * Verified against the installed Pi SDK 0.78 source (NOT assumed):
+ *   - `DefaultResourceLoader.reload()` (resource-loader.js:271-276) builds
+ *     `extensionPaths = noExtensions ? cliEnabledExtensions
+ *                                     : merge(cliEnabledExtensions, enabledExtensions)`
+ *     where `enabledExtensions` (line 229) are the DISK/package extensions from
+ *     `packageManager.resolve()` (`~/.pi/agent/extensions/`, `<cwd>/.pi/extensions/`,
+ *     installed packages). `loadExtensions(extensionPaths)` then loads them and
+ *     MERGES with our inline factories (lines 274-276).
+ *   - `noExtensions` defaults to `false` (constructor, line 132) — so the naive
+ *     loader DOES load disk extensions. That is the S2 gap.
+ *
+ * Fix (= security's "exclude the extensions dir", done structurally):
+ *   - `noExtensions: true` → `extensionPaths` collapses to `cliEnabledExtensions`,
+ *     which is empty because we pass NO `additionalExtensionPaths`. So
+ *     `loadExtensions([])` registers nothing from disk/packages.
+ *   - Inline `extensionFactories` load UNCONDITIONALLY (reload() line 275 is not
+ *     gated by `noExtensions`), so our agent-tempo extension still attaches.
+ * Net: the ONLY tools present are Pi's built-ins (bash/read/edit/write/grep —
+ * all covered by the deny-list) + our agent-tempo MCP tools (no exec). No
+ * third-party tool can slip past the deny-list. Skills/prompts/themes cannot
+ * register tools, so they are not a vector and are left at defaults.
+ *
+ * Kept as a pure, exported helper so the `noExtensions: true` invariant has a
+ * unit regression test (test/pi-headless-loader.test.ts) without needing the Pi
+ * SDK installed.
+ */
+export declare function buildPiResourceLoaderOptions(params: {
+    cwd: string;
+    agentDir: string;
+    /** The inline agent-tempo extension factory (`createPiExtension(...)`). Typed
+     *  with a bottom param so any concrete factory arity is assignable. */
+    extensionFactory: (pi: never) => void;
+}): Record<string, unknown>;
+/**
+ * Boot + run a headless Pi player until shutdown. Resolves when the process has
+ * cleanly detached + disposed (it also calls process.exit on the terminal path).
+ */
+export declare function runHeadlessPi(opts?: RunHeadlessPiOptions): Promise<void>;

package/dist/pi/headless.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPiResourceLoaderOptions = buildPiResourceLoaderOptions;
+exports.runHeadlessPi = runHeadlessPi;
+/**
+ * Headless Pi runtime (Phase 3a). Spawned by the daemon (spawnPiHeadless →
+ * src/adapters/pi/adapter.ts) for a recruited `agent: 'pi'` player. No human, no
+ * terminal: it constructs Pi's `createAgentSession` with the agent-tempo
+ * extension injected INLINE, and the module-scope extension singleton
+ * (createPiExtension, mode='headless') owns claim/heartbeat/tool-registration/
+ * cue-pump on `session_start`. Reuses ~everything from Phases 1–2.
+ *
+ * Lifecycle:
+ *   1. probe Pi SDK; resolve the model via pi-ai `getModel` — a bad/unindexed
+ *      model fails CLEAN (exit before attach, no orphan — architect's backstop).
+ *   2. createAgentSession({ resourceLoader: DefaultResourceLoader({
+ *        extensionFactories: [ext] }), model? }).
+ *   3. await session.bindExtensions({}) → fires session_start → the singleton
+ *      attaches (claim + heartbeat + tools + cue pump). bindExtensions IS the
+ *      explicit bootstrap (not "hope session_start fires").
+ *   4. stay alive until a shutdown signal (SIGTERM/SIGINT).
+ *   5. RELIABLE detach (headless owns the exit): detachAllPiRuntimesForExit()
+ *      [await adapterExited] → session.dispose() → process exit.
+ *
+ * ESM note: the Pi SDK is an ESM-only optional dep; we import it via a
+ * `Function`-wrapped dynamic `import()` so tsc (module=commonjs) doesn't
+ * downlevel it to `require()` — Node resolves the real ESM module at runtime.
+ *
+ * Determinism boundary: client-side only.
+ */
+const config_1 = require("../config");
+const sdk_probe_1 = require("../utils/sdk-probe");
+const extension_1 = require("./extension");
+const probe_1 = require("./probe");
+const session_seed_1 = require("./session-seed");
+const log = (...args) => {
+    // eslint-disable-next-line no-console
+    console.error('[agent-tempo:pi-headless]', ...args);
+};
+/**
+ * True dynamic ESM import that survives tsc's commonjs downleveling. `import(x)`
+ * with a literal would be rewritten to a `require`-based helper (breaks on an
+ * ESM-only package); the `Function` indirection keeps a native `import()` at
+ * runtime so Node loads the real ESM module.
+ */
+// eslint-disable-next-line @typescript-eslint/no-implied-eval
+const esmImport = new Function('specifier', 'return import(specifier)');
+/**
+ * Resolve a Pi `Model` object from a `provider/model` string via pi-ai's
+ * `getModel`. Returns `{ model }` on success, `{ fatal }` with an actionable
+ * message on an invalid/unindexed model (getModel returns `undefined` — a plain
+ * check, no throw), or `{}` when no model was requested (Pi uses its own default
+ * — the 3a anthropic-default path).
+ */
+async function resolveModel(modelStr) {
+    if (!modelStr)
+        return {};
+    const slash = modelStr.indexOf('/');
+    if (slash <= 0 || slash === modelStr.length - 1) {
+        return { fatal: `Invalid Pi model "${modelStr}" — expected "provider/model" (e.g. anthropic/claude-opus-4-5).` };
+    }
+    const provider = modelStr.slice(0, slash);
+    const modelName = modelStr.slice(slash + 1);
+    try {
+        const piAi = await esmImport(probe_1.PI_AI_PACKAGE);
+        const getModel = piAi.getModel;
+        const model = getModel(provider, modelName);
+        if (model === undefined || model === null) {
+            return {
+                fatal: `Pi model "${modelStr}" not found in Pi's provider index (provider="${provider}"). ` +
+                    `Check the model id against \`pi --list-models\` / models.dev.`,
+            };
+        }
+        return { model };
+    }
+    catch (err) {
+        return { fatal: `Failed to resolve Pi model "${modelStr}": ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
+/**
+ * Build the `DefaultResourceLoader` options for a headless Pi player.
+ *
+ * SECURITY — S2 (MD-C deny-list soundness). The `restricted` tool gate is a
+ * DENY-LIST over shell/exec tool *names* (tool-capability.ts EXEC_TOOLS, via
+ * `classify(name) === 'exec'` — F1 replaced extension.ts's former local set). That
+ * guarantee — "restricted = no host execution" — holds ONLY IF no third-party
+ * extension can register an un-blacklisted execution tool (e.g. a custom
+ * `python` / `npm` / `run` tool). It therefore depends on a hard structural
+ * fact: which extensions Pi loads.
+ *
+ * Verified against the installed Pi SDK 0.78 source (NOT assumed):
+ *   - `DefaultResourceLoader.reload()` (resource-loader.js:271-276) builds
+ *     `extensionPaths = noExtensions ? cliEnabledExtensions
+ *                                     : merge(cliEnabledExtensions, enabledExtensions)`
+ *     where `enabledExtensions` (line 229) are the DISK/package extensions from
+ *     `packageManager.resolve()` (`~/.pi/agent/extensions/`, `<cwd>/.pi/extensions/`,
+ *     installed packages). `loadExtensions(extensionPaths)` then loads them and
+ *     MERGES with our inline factories (lines 274-276).
+ *   - `noExtensions` defaults to `false` (constructor, line 132) — so the naive
+ *     loader DOES load disk extensions. That is the S2 gap.
+ *
+ * Fix (= security's "exclude the extensions dir", done structurally):
+ *   - `noExtensions: true` → `extensionPaths` collapses to `cliEnabledExtensions`,
+ *     which is empty because we pass NO `additionalExtensionPaths`. So
+ *     `loadExtensions([])` registers nothing from disk/packages.
+ *   - Inline `extensionFactories` load UNCONDITIONALLY (reload() line 275 is not
+ *     gated by `noExtensions`), so our agent-tempo extension still attaches.
+ * Net: the ONLY tools present are Pi's built-ins (bash/read/edit/write/grep —
+ * all covered by the deny-list) + our agent-tempo MCP tools (no exec). No
+ * third-party tool can slip past the deny-list. Skills/prompts/themes cannot
+ * register tools, so they are not a vector and are left at defaults.
+ *
+ * Kept as a pure, exported helper so the `noExtensions: true` invariant has a
+ * unit regression test (test/pi-headless-loader.test.ts) without needing the Pi
+ * SDK installed.
+ */
+function buildPiResourceLoaderOptions(params) {
+    return {
+        cwd: params.cwd,
+        agentDir: params.agentDir,
+        extensionFactories: [params.extensionFactory],
+        // SECURITY (S2): hard-exclude all disk/package extensions. Do NOT add
+        // `additionalExtensionPaths` here — that would re-introduce the exec-tool
+        // vector this flag closes.
+        noExtensions: true,
+    };
+}
+/**
+ * Boot + run a headless Pi player until shutdown. Resolves when the process has
+ * cleanly detached + disposed (it also calls process.exit on the terminal path).
+ */
+async function runHeadlessPi(opts = {}) {
+    const config = opts.config ?? (0, config_1.getConfig)();
+    const toolAccess = opts.toolAccess ?? 'restricted';
+    // 0) Node-floor backstop (Decision B, #645). The recruit pre-flight is the
+    //    AUTHORITATIVE gate; this covers direct/manual launches that bypass recruit.
+    //    Checked before the SDK probe because Pi's ESM packages can't even import on
+    //    sub-22.19 Node — a clean floor message beats a cryptic import failure.
+    const nodeFloor = (0, probe_1.checkPiNodeFloor)();
+    if (!nodeFloor.ok) {
+        log(`FATAL: ${nodeFloor.reason} Exiting.`);
+        process.exit(3);
+        return;
+    }
+    // 1) Probe — the spawn entry is the only place the Pi SDK is REQUIRED.
+    if (!(0, sdk_probe_1.probeSdkInstall)(probe_1.PI_PACKAGE)) {
+        log(`FATAL: ${probe_1.PI_PACKAGE} is not installed — cannot run headless Pi. Exiting.`);
+        process.exit(1);
+        return;
+    }
+    // 2) Resolve the model BEFORE creating the session — a bad model fails clean
+    //    (exit before attach, no half-attached orphan).
+    const { model, fatal } = await resolveModel(opts.model);
+    if (fatal) {
+        log(`FATAL: ${fatal} Exiting without attaching.`);
+        process.exit(2);
+        return;
+    }
+    // 3) Inline extension factory — headless mode → the MD-C tool gate is active.
+    const extensionFactory = (0, extension_1.createPiExtension)({ mode: 'headless', toolAccess });
+    // 4) Construct the Pi SDK session with the extension injected inline.
+    const piSdk = await esmImport(probe_1.PI_PACKAGE);
+    const createAgentSession = piSdk.createAgentSession;
+    const DefaultResourceLoader = piSdk.DefaultResourceLoader;
+    // H1 (#645): ALWAYS run in-memory. A disk-backed SessionManager loads
+    // ~/.pi/agent/sessions/<cwd>/*.jsonl on startup; a stale/partial entry with
+    // malformed `content` throws "content is not iterable" during Pi's
+    // compaction/consumption scan (agent-session.js:2486/2493). inMemory loads
+    // nothing from disk → that crash vector is gone. `sessionManager` and
+    // `resourceLoader` are INDEPENDENT createAgentSession options (no conflict with
+    // the noExtensions/reload() path above).
+    const SessionManager = piSdk.SessionManager;
+    const sessionManager = SessionManager.inMemory(process.cwd());
+    // Single appendMessage chokepoint (session-seed.ts). For a fresh recruit the
+    // transcript is empty → no-op; H2 supplies the durable replay read here
+    // (fetch_state on ENV.PI_CONTINUE_SESSION). headless.ts NEVER calls
+    // appendMessage directly — sanitization is the only crash lever we control.
+    (0, session_seed_1.seedSessionManager)(sessionManager, undefined /* H2: durable replay transcript */);
+    // Pi's DefaultResourceLoader REQUIRES agentDir (normalizePath does
+    // `.startsWith()` on it) — getAgentDir() resolves ~/.pi/agent. Pass it to BOTH
+    // createAgentSession and the loader. (Found in the 3a live smoke — devops.)
+    const getAgentDir = piSdk.getAgentDir;
+    const agentDir = getAgentDir();
+    const resourceLoader = new DefaultResourceLoader(buildPiResourceLoaderOptions({ cwd: process.cwd(), agentDir, extensionFactory }));
+    // CRITICAL (3a live smoke — devops): createAgentSession only calls
+    // resourceLoader.reload() when IT constructs the loader (sdk.js:99-101). When we
+    // pass our OWN loader, reload() is skipped — and DefaultResourceLoader inits
+    // `extensionsResult.extensions = []` (resource-loader.js:146) and only populates
+    // it during reload(). So without this explicit reload our extension never
+    // registers, and session_start fires into an empty handler list (no claim, no
+    // heartbeat). The SDK's own doc comment (sdk.js:74-83) prescribes this exact
+    // construct → reload() → pass-as-resourceLoader sequence.
+    await resourceLoader.reload();
+    const { session } = await createAgentSession({
+        cwd: process.cwd(),
+        agentDir,
+        ...(model ? { model } : {}),
+        resourceLoader,
+        // H1 (#645): in-memory session (seeded above via the session-seed chokepoint).
+        // H2 will seed it from agent-tempo durable state (ENV.PI_CONTINUE_SESSION
+        // saveable-state key) before this call — a true continuation, not a cue.
+        sessionManager,
+    });
+    // 5) Explicit bootstrap — fires session_start → the singleton claims/attaches.
+    await session.bindExtensions({});
+    // Headless session_start carries NO `session` field (interactive does), so the
+    // extension can't wire the cue pump's session ref itself. We hold the SDK
+    // session here — set it on the now-claimed runtime so the cue pump can inject.
+    // (3a live smoke — devops; the headless-vs-interactive session-wiring gap.)
+    const playerId = process.env[config_1.ENV.PLAYER_NAME] || `pi-${process.pid}`;
+    (0, extension_1.setRuntimeSession)((0, config_1.sessionWorkflowId)(config.ensemble, playerId), session);
+    log(`headless Pi session bound (toolAccess=${toolAccess}, ` +
+        `model=${opts.model ?? 'pi-default'}${opts.continueSessionId ? `, continue=${opts.continueSessionId}` : ''}, ` +
+        `sessionId=${session.sessionId ?? '?'})`);
+    // 6) Stay alive until a shutdown signal, then RELIABLE detach → dispose → exit.
+    // Keep the event loop alive with a REF'd timer: the heartbeat + cue-pump timers
+    // are `.unref()`'d by design (so they never block a clean exit), and the
+    // SIGTERM/SIGINT once-listeners aren't active handles — so WITHOUT this the loop
+    // drains and Node exits code 0 immediately after bindExtensions in headless mode.
+    // (Found in the 3a live smoke — devops.)
+    const keepAlive = setInterval(() => { }, 30_000);
+    try {
+        await new Promise((resolveShutdown) => {
+            const onSignal = (sig) => { log(`received ${sig} — shutting down`); resolveShutdown(); };
+            process.once('SIGTERM', () => onSignal('SIGTERM'));
+            process.once('SIGINT', () => onSignal('SIGINT'));
+        });
+    }
+    finally {
+        clearInterval(keepAlive);
+    }
+    // Headless owns the exit sequence: await adapterExited (unmaps the runtime)
+    // THEN dispose the SDK session (the dispose-fired session_shutdown finds no
+    // mapped runtime → no-op, so no double-detach).
+    try {
+        await (0, extension_1.detachAllPiRuntimesForExit)();
+    }
+    catch (err) {
+        log('detach failed (reaper backstops):', err);
+    }
+    try {
+        session.dispose();
+    }
+    catch (err) {
+        log('dispose failed:', err);
+    }
+    log('headless Pi clean-exit complete');
+    // eslint-disable-next-line no-process-exit
+    process.exit(0);
+}

package/dist/pi/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * agent-tempo Pi integration — barrel.
+ *
+ * Default export is the Pi extension factory (`export default function(pi)`).
+ * Named exports expose the testable units and the client-side wrapper for reuse
+ * by the headless Pi runtime (Phase 3).
+ *
+ * Tool registration: the extension renders the shared transport-neutral tool
+ * descriptors (src/tools/descriptor.ts) onto Pi via `renderToPi`, deriving
+ * TypeBox param schemas from zod through `zod-to-typebox.ts`. There is no
+ * Pi-specific re-implementation of any tool.
+ *
+ * See src/pi/README.md for the Phase 0/2 findings (abrupt-death / MD-A, D12a)
+ * and known limitations.
+ */
+export { default } from './extension';
+export { PhaseDriver } from './phase-driver';
+export type { PiPhase, WorkflowAction, PhaseDriverResult } from './phase-driver';
+export { PiWorkflowClient } from './workflow-client';
+export type { PiWorkflowClientOptions } from './workflow-client';
+export { CuePump } from './cue-pump';
+export type { CueSource, SessionResolver, CuePumpOptions } from './cue-pump';
+export { renderToPi, toPiResult } from './render-tools';
+export { createLazyProxy } from './lazy-proxy';
+export { zodShapeToTypeBox, UnsupportedZodFeatureError } from './zod-to-typebox';
+export { probePi, PI_PACKAGE, PI_AI_PACKAGE, TESTED_PI_VERSION, PI_NODE_FLOOR } from './probe';
+export type { PiProbeResult } from './probe';
+export type { ExtensionAPI, PiExtension, PiAgentSession, PiEventPayload, PiToolDefinition, PiToolResult, PiLifecycleEvent, } from './pi-types';

package/dist/pi/index.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PI_NODE_FLOOR = exports.TESTED_PI_VERSION = exports.PI_AI_PACKAGE = exports.PI_PACKAGE = exports.probePi = exports.UnsupportedZodFeatureError = exports.zodShapeToTypeBox = exports.createLazyProxy = exports.toPiResult = exports.renderToPi = exports.CuePump = exports.PiWorkflowClient = exports.PhaseDriver = exports.default = void 0;
+/**
+ * agent-tempo Pi integration — barrel.
+ *
+ * Default export is the Pi extension factory (`export default function(pi)`).
+ * Named exports expose the testable units and the client-side wrapper for reuse
+ * by the headless Pi runtime (Phase 3).
+ *
+ * Tool registration: the extension renders the shared transport-neutral tool
+ * descriptors (src/tools/descriptor.ts) onto Pi via `renderToPi`, deriving
+ * TypeBox param schemas from zod through `zod-to-typebox.ts`. There is no
+ * Pi-specific re-implementation of any tool.
+ *
+ * See src/pi/README.md for the Phase 0/2 findings (abrupt-death / MD-A, D12a)
+ * and known limitations.
+ */
+var extension_1 = require("./extension");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return __importDefault(extension_1).default; } });
+var phase_driver_1 = require("./phase-driver");
+Object.defineProperty(exports, "PhaseDriver", { enumerable: true, get: function () { return phase_driver_1.PhaseDriver; } });
+var workflow_client_1 = require("./workflow-client");
+Object.defineProperty(exports, "PiWorkflowClient", { enumerable: true, get: function () { return workflow_client_1.PiWorkflowClient; } });
+var cue_pump_1 = require("./cue-pump");
+Object.defineProperty(exports, "CuePump", { enumerable: true, get: function () { return cue_pump_1.CuePump; } });
+var render_tools_1 = require("./render-tools");
+Object.defineProperty(exports, "renderToPi", { enumerable: true, get: function () { return render_tools_1.renderToPi; } });
+Object.defineProperty(exports, "toPiResult", { enumerable: true, get: function () { return render_tools_1.toPiResult; } });
+var lazy_proxy_1 = require("./lazy-proxy");
+Object.defineProperty(exports, "createLazyProxy", { enumerable: true, get: function () { return lazy_proxy_1.createLazyProxy; } });
+var zod_to_typebox_1 = require("./zod-to-typebox");
+Object.defineProperty(exports, "zodShapeToTypeBox", { enumerable: true, get: function () { return zod_to_typebox_1.zodShapeToTypeBox; } });
+Object.defineProperty(exports, "UnsupportedZodFeatureError", { enumerable: true, get: function () { return zod_to_typebox_1.UnsupportedZodFeatureError; } });
+var probe_1 = require("./probe");
+Object.defineProperty(exports, "probePi", { enumerable: true, get: function () { return probe_1.probePi; } });
+Object.defineProperty(exports, "PI_PACKAGE", { enumerable: true, get: function () { return probe_1.PI_PACKAGE; } });
+Object.defineProperty(exports, "PI_AI_PACKAGE", { enumerable: true, get: function () { return probe_1.PI_AI_PACKAGE; } });
+Object.defineProperty(exports, "TESTED_PI_VERSION", { enumerable: true, get: function () { return probe_1.TESTED_PI_VERSION; } });
+Object.defineProperty(exports, "PI_NODE_FLOOR", { enumerable: true, get: function () { return probe_1.PI_NODE_FLOOR; } });

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

@@ -0,0 +1,67 @@
+import type { InnerFrame, InnerLoopRegistry } from './inner-loop-publisher';
+/** Env var carrying the per-player ingest token (threaded in at spawn). */
+export declare const INGEST_TOKEN_ENV = "AGENT_TEMPO_INGEST_TOKEN";
+/** DOS backstop — frames over this are dropped (summaries are already ~2KB-truncated). */
+export declare const MAX_FRAME_BYTES: number;
+/** Minimal `fetch` shape this client needs — injectable for tests. */
+export type InnerLoopFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    status: number;
+    json(): Promise<unknown>;
+}>;
+export interface InnerLoopHttpClientOptions {
+    /** The player's ensemble (URL path segment). */
+    ensemble: string;
+    /** The player's id (URL path segment). */
+    playerId: string;
+    /** Ingest token. Defaults to `process.env[INGEST_TOKEN_ENV]`. */
+    ingestToken?: string;
+    /** Daemon port discovery. Defaults to {@link readPortFile}. */
+    readPort?: () => number | null;
+    /** HTTP transport. Defaults to global `fetch` (no-op if absent). */
+    fetchFn?: InnerLoopFetch;
+    /** Min interval between presence GETs (default 1000ms). */
+    presencePollMs?: number;
+    /** Injected clock (tests). Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * 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.
+ */
+export declare class InnerLoopHttpClient implements InnerLoopRegistry {
+    private readonly ensemble;
+    private readonly playerId;
+    private readonly ingestToken;
+    private readonly readPort;
+    private readonly fetchFn;
+    private readonly presencePollMs;
+    private readonly now;
+    /** Last presence count from the daemon. 0 until the first GET resolves / on failure. */
+    private cachedSubscribers;
+    /** 3d — last gateArmed flag from the daemon (folded into the presence response). */
+    private cachedGateArmed;
+    private lastPresenceRefresh;
+    constructor(opts: InnerLoopHttpClientOptions);
+    /** Whether the client can talk to the daemon at all (token + transport present). */
+    private get enabled();
+    private baseUrl;
+    /** Fire-and-forget POST of one frame. Drops (never throws/blocks) on any failure. */
+    publish(_workflowId: string, frame: InnerFrame): void;
+    /** Synchronous cached presence (stale-while-revalidate). Default 0 / fail-safe 0. */
+    subscriberCount(_workflowId: string): number;
+    /**
+     * 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: string): boolean;
+    /** Fire a rate-limited background presence GET that updates the cache. */
+    private maybeRefreshPresence;
+}

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;