agent-tempo 1.2.0 → 1.4.0

package/dist/http/gate-routes.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleGateArm = handleGateArm;
+exports.handleGateDisarm = handleGateDisarm;
+exports.handleGateDecide = handleGateDecide;
+exports.handleGateResolution = handleGateResolution;
+const config_1 = require("../config");
+const responses_1 = require("./responses");
+const body_1 = require("./body");
+const inner_loop_routes_1 = require("./inner-loop-routes");
+/** Decision body cap — the payload is a tiny `{decision}`; this is the DOS backstop. */
+const GATE_BODY_MAX = 4 * 1024;
+function headerValue(v) {
+    if (v === undefined)
+        return undefined;
+    return Array.isArray(v) ? v[0] : v;
+}
+/**
+ * SOURCE-plane INGRESS gate (loopback + ingest-token vs URL workflowId), shared
+ * with the inner-loop ingest contract. Returns the workflowId on success, or
+ * `null` after writing a uniform 403 (no info leak — callers just `return`).
+ */
+function gateIngress(req, res, deps, ensemble, playerId) {
+    const deny = () => { (0, responses_1.errorResponse)(res, 403, { error: 'forbidden' }); return null; };
+    if (!(0, inner_loop_routes_1.isLoopbackRemote)(req))
+        return deny();
+    const token = headerValue(req.headers[inner_loop_routes_1.INGEST_TOKEN_HEADER]);
+    if (!token)
+        return deny();
+    const workflowId = (0, config_1.sessionWorkflowId)(ensemble, playerId);
+    if (!deps.ingestTokens.validate(workflowId, token))
+        return deny();
+    return workflowId;
+}
+/**
+ * Best-effort short audit hint from the operator's bearer (last 6 chars) — never
+ * the full token. Absent on a loopback-trust request with no Authorization.
+ */
+function operatorTokenHint(req) {
+    const auth = headerValue(req.headers.authorization);
+    if (!auth)
+        return undefined;
+    const m = /^Bearer\s+(.+)$/i.exec(auth.trim());
+    const tok = m?.[1];
+    return tok && tok.length >= 6 ? `…${tok.slice(-6)}` : undefined;
+}
+// ── OPERATOR plane (server.ts applies requireTier(3) before dispatch) ──────────
+/** POST /gate-arm — arm the operator gate for a player. 204. */
+function handleGateArm(req, res, deps, ensemble, playerId) {
+    const workflowId = (0, config_1.sessionWorkflowId)(ensemble, playerId);
+    deps.gate.arm(workflowId, ensemble, operatorTokenHint(req));
+    res.writeHead(204);
+    res.end();
+}
+/** POST /gate-disarm — disarm the operator gate for a player. 204. */
+function handleGateDisarm(req, res, deps, ensemble, playerId) {
+    const workflowId = (0, config_1.sessionWorkflowId)(ensemble, playerId);
+    deps.gate.disarm(workflowId, operatorTokenHint(req));
+    res.writeHead(204);
+    res.end();
+}
+/**
+ * POST /gate/:requestId — operator decision on a pending gated tool call.
+ * Body `{ decision: 'allow' | 'deny' }`. 204 on success; 404 unknown requestId;
+ * 409 already-decided (idempotency — a double-POST or post-timeout race can't
+ * flip a recorded answer); 400 malformed body / bad decision value.
+ */
+async function handleGateDecide(req, res, deps, ensemble, playerId, requestId) {
+    const workflowId = (0, config_1.sessionWorkflowId)(ensemble, playerId);
+    const body = await (0, body_1.readJsonBody)(req, GATE_BODY_MAX);
+    if (body === body_1.BODY_TOO_LARGE || body === body_1.BODY_INVALID_JSON) {
+        return (0, responses_1.errorResponse)(res, 400, { error: 'bad-request' });
+    }
+    const decision = body.decision;
+    if (decision !== 'allow' && decision !== 'deny') {
+        return (0, responses_1.errorResponse)(res, 400, { error: 'bad-request', detail: "decision must be 'allow' or 'deny'" });
+    }
+    const result = deps.gate.decide(workflowId, requestId, decision, operatorTokenHint(req));
+    if (result.ok) {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    if (result.reason === 'not-found')
+        return (0, responses_1.errorResponse)(res, 404, { error: 'not-found' });
+    return (0, responses_1.errorResponse)(res, 409, { error: 'already-decided' });
+}
+// ── SOURCE plane (ingest-token; Pi subprocess polls) ───────────────────────────
+/**
+ * GET /gate/:requestId/resolution — the Pi subprocess polls for the decision.
+ * 200 `{ status:'pending' }` | `{ status:'resolved', decision, source }`; 404 for
+ * an unknown requestId; uniform 403 on any INGRESS gate failure (no leak).
+ */
+function handleGateResolution(req, res, deps, ensemble, playerId, requestId) {
+    const workflowId = gateIngress(req, res, deps, ensemble, playerId);
+    if (workflowId === null)
+        return;
+    const resolution = deps.gate.getResolution(workflowId, requestId);
+    if (resolution === null)
+        return (0, responses_1.errorResponse)(res, 404, { error: 'not-found' });
+    return (0, responses_1.jsonResponse)(res, 200, resolution);
+}

package/dist/http/ingest-registry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * In-memory map of `workflowId → ingest token`, owned by the daemon (one
+ * instance shared between the outbox minter and the HTTP ingest/presence
+ * validators). Tokens never persist — they live only for the player's lifetime.
+ */
+export declare class IngestTokenRegistry {
+    private readonly tokens;
+    /**
+     * Mint a fresh ingest token for a player, replacing any prior one (a restart
+     * re-mints). Returns the token to inject into the subprocess env.
+     */
+    mint(workflowId: string): string;
+    /**
+     * Validate a presented token against the token minted for `workflowId`
+     * (timing-safe, via {@link tokensMatch}). Returns `false` for an unknown
+     * player or a mismatch — so a compromised player presenting its OWN token for
+     * another player's URL is rejected (cross-player-spoof guard). The workflowId
+     * is public (it's in the URL); the token is the secret, and only its
+     * comparison is constant-time.
+     */
+    validate(workflowId: string, presented: string): boolean;
+    /** Revoke a player's ingest token (detach / destroy). Idempotent. */
+    revoke(workflowId: string): void;
+    /** Revoke every token (daemon shutdown / clear-all). */
+    revokeAll(): void;
+    /** Whether a player currently holds a minted token. */
+    has(workflowId: string): boolean;
+    /** Active token count (diagnostics / tests). */
+    size(): number;
+}

package/dist/http/ingest-registry.js

@@ -0,0 +1,108 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IngestTokenRegistry = void 0;
+/**
+ * Ingest-token registry (3c Tier-2 ingest-auth) — per security's design.
+ *
+ * The `/inner/ingest` + `/inner/presence` endpoints are the SOURCE-side
+ * (publisher → daemon) half of the off-wire fine-tail channel. Loopback-only is
+ * necessary but NOT sufficient: any local process could POST fake frames or
+ * inject into ANOTHER player's tail. So each headless Pi player is minted a
+ * per-player ingest token at spawn, scoped to its session `workflowId`; the
+ * ingest/presence handlers validate the presented token against the token minted
+ * for the URL-derived workflowId, binding every frame to its owning player.
+ *
+ * Lifecycle (driven from the daemon-only outbox.ts — NOT spawn.ts, which runs
+ * outside the daemon and must not import this):
+ *   - MINT before `spawnPiHeadless` (token injected into the subprocess env).
+ *   - REVOKE on detach + destroy.
+ *   - REVOKE-ALL on daemon shutdown.
+ *
+ * Phase-4+ deferrals (carry-items, NOT 3c): token rotation, per-token
+ * rate-limiting, durable ingest audit.
+ */
+const crypto = __importStar(require("crypto"));
+const auth_1 = require("./auth");
+/** Bytes of entropy per ingest token (base64url → 43 chars, same as the HTTP bearer). */
+const INGEST_TOKEN_BYTES = 32;
+/**
+ * In-memory map of `workflowId → ingest token`, owned by the daemon (one
+ * instance shared between the outbox minter and the HTTP ingest/presence
+ * validators). Tokens never persist — they live only for the player's lifetime.
+ */
+class IngestTokenRegistry {
+    tokens = new Map();
+    /**
+     * Mint a fresh ingest token for a player, replacing any prior one (a restart
+     * re-mints). Returns the token to inject into the subprocess env.
+     */
+    mint(workflowId) {
+        const token = crypto.randomBytes(INGEST_TOKEN_BYTES).toString('base64url');
+        this.tokens.set(workflowId, token);
+        return token;
+    }
+    /**
+     * Validate a presented token against the token minted for `workflowId`
+     * (timing-safe, via {@link tokensMatch}). Returns `false` for an unknown
+     * player or a mismatch — so a compromised player presenting its OWN token for
+     * another player's URL is rejected (cross-player-spoof guard). The workflowId
+     * is public (it's in the URL); the token is the secret, and only its
+     * comparison is constant-time.
+     */
+    validate(workflowId, presented) {
+        const expected = this.tokens.get(workflowId);
+        if (expected === undefined)
+            return false;
+        return (0, auth_1.tokensMatch)(presented, expected);
+    }
+    /** Revoke a player's ingest token (detach / destroy). Idempotent. */
+    revoke(workflowId) {
+        this.tokens.delete(workflowId);
+    }
+    /** Revoke every token (daemon shutdown / clear-all). */
+    revokeAll() {
+        this.tokens.clear();
+    }
+    /** Whether a player currently holds a minted token. */
+    has(workflowId) {
+        return this.tokens.has(workflowId);
+    }
+    /** Active token count (diagnostics / tests). */
+    size() {
+        return this.tokens.size;
+    }
+}
+exports.IngestTokenRegistry = IngestTokenRegistry;

package/dist/http/inner-loop-routes.d.ts

@@ -0,0 +1,66 @@
+/**
+ * HTTP route handlers for the 3c Tier-2 inner-loop side-channel (MD-F).
+ * server.ts dispatches to these; the logic lives here so it stays testable.
+ *
+ * THREE routes, TWO auth planes (security's ingest-auth design):
+ *
+ *   INGRESS (source → daemon; publisher-only). Mounted in server.ts BEFORE the
+ *   outer bearer gate so it works regardless of the daemon's bind address —
+ *   authenticated by its OWN gates, not the operator bearer:
+ *     - POST /v1/players/:ensemble/:playerId/inner/ingest  → publish a frame
+ *     - GET  /v1/players/:ensemble/:playerId/inner/presence → { subscribers }
+ *   Both gate on: (1) loopback `req.socket.remoteAddress`; (2) `X-Ingest-Token`
+ *   validated against the URL-derived workflowId (cross-player-spoof guard).
+ *   Every failure → 403 with no detail (no info leak).
+ *
+ *   EGRESS (daemon → operator/widget). Mounted AFTER the outer bearer gate with
+ *   an explicit `requireTier(3)`:
+ *     - GET /v1/players/:ensemble/:playerId/inner  → SSE fine-tail stream
+ *
+ * MD-F invariants preserved: off-Temporal, off the coordination bus,
+ * daemon-LOCAL (loopback ingest = same host), ephemeral (no ring/replay).
+ */
+import type { IncomingMessage, ServerResponse } from 'http';
+import type { InnerLoopRegistry } from './inner-loop';
+import type { IngestTokenRegistry } from './ingest-registry';
+import type { GateRegistry } from './gate-registry';
+/** Header carrying the per-player ingest token (the source-plane credential). */
+export declare const INGEST_TOKEN_HEADER = "x-ingest-token";
+export interface InnerLoopDeps {
+    innerLoop: InnerLoopRegistry;
+    ingestTokens: IngestTokenRegistry;
+    /**
+     * 3d MD-G — the operator-gate registry, when wired. Two narrow couplings:
+     *   - ingest: an `inner.gate_pending` frame ALSO registers the pending request
+     *     in the gate (`open()`) — atomic register-and-surface from one POST (the
+     *     "engagement IS registration" path; no separate open-route).
+     *   - presence: the response carries `gateArmed` so the polling subprocess
+     *     evaluates engagement (armed + present) from one fetch.
+     * The coupling is one-directional (inner-routes → GateRegistry); the gate's
+     * `gate_resolved` emission flows back via its injected publishToInner.
+     */
+    gate?: GateRegistry;
+}
+/** True when the request originates from the same host (loopback). */
+export declare function isLoopbackRemote(req: IncomingMessage): boolean;
+/**
+ * POST /v1/players/:e/:p/inner/ingest — the publisher forwards ONE InnerFrame.
+ * 204 on success; uniform 403 on any gate/shape/oversize failure (no-leak). The
+ * daemon TRUSTS the authenticated publisher's summaries (already ~2KB-truncated
+ * at source) — the 32KB cap is purely the DOS backstop; no re-truncation.
+ */
+export declare function handleInnerIngest(req: IncomingMessage, res: ServerResponse, deps: InnerLoopDeps, ensemble: string, playerId: string): Promise<void>;
+/**
+ * GET /v1/players/:e/:p/inner/presence — publisher-only presence probe.
+ * Same gates as ingest (presence is publisher-only; leaking "is someone
+ * watching X" would be a covert channel). 200 `{ subscribers }` or 403.
+ */
+export declare function handleInnerPresence(req: IncomingMessage, res: ServerResponse, deps: InnerLoopDeps, ensemble: string, playerId: string): void;
+/**
+ * GET /v1/players/:e/:p/inner — operator/widget SSE fine-tail stream (EGRESS).
+ * server.ts has already applied the outer bearer + `requireTier(3)` gate. Plain
+ * `event:`/`data:` framing (fetch-consumable, no EventSource-specific framing);
+ * `:ka` keepalive; `:closed` when the player goes away. No ring/seq/replay —
+ * ephemeral best-effort tail (a disconnect loses in-flight deltas, by design).
+ */
+export declare function handleInnerSse(req: IncomingMessage, res: ServerResponse, deps: InnerLoopDeps, ensemble: string, playerId: string): Promise<void>;

package/dist/http/inner-loop-routes.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INGEST_TOKEN_HEADER = void 0;
+exports.isLoopbackRemote = isLoopbackRemote;
+exports.handleInnerIngest = handleInnerIngest;
+exports.handleInnerPresence = handleInnerPresence;
+exports.handleInnerSse = handleInnerSse;
+const config_1 = require("../config");
+const responses_1 = require("./responses");
+const body_1 = require("./body");
+/** Loopback remote addresses Node may report for a same-host connection. */
+const LOOPBACK_REMOTES = new Set(['127.0.0.1', '::1', '::ffff:127.0.0.1']);
+/** Header carrying the per-player ingest token (the source-plane credential). */
+exports.INGEST_TOKEN_HEADER = 'x-ingest-token';
+/** Max bytes buffered to a slow `/inner` SSE socket before we drop the connection. */
+const MAX_SSE_WRITE_BUFFER = 1024 * 1024;
+/** Keepalive comment cadence on an idle `/inner` stream. */
+const INNER_KEEPALIVE_MS = 15_000;
+/** True when the request originates from the same host (loopback). */
+function isLoopbackRemote(req) {
+    const addr = req.socket?.remoteAddress;
+    return addr != null && LOOPBACK_REMOTES.has(addr);
+}
+function headerValue(v) {
+    if (v === undefined)
+        return undefined;
+    return Array.isArray(v) ? v[0] : v;
+}
+/**
+ * Run the shared INGRESS gate (loopback + ingest-token vs URL workflowId).
+ * Returns the resolved workflowId on success, or `null` after having written a
+ * uniform `403` (no info leak — callers just `return` on null).
+ */
+function gateIngress(req, res, deps, ensemble, playerId) {
+    // Uniform 403 on EVERY failure — never reveal which gate tripped.
+    const deny = () => {
+        (0, responses_1.errorResponse)(res, 403, { error: 'forbidden' });
+        return null;
+    };
+    if (!isLoopbackRemote(req))
+        return deny();
+    const token = headerValue(req.headers[exports.INGEST_TOKEN_HEADER]);
+    if (!token)
+        return deny();
+    const workflowId = (0, config_1.sessionWorkflowId)(ensemble, playerId);
+    if (!deps.ingestTokens.validate(workflowId, token))
+        return deny();
+    return workflowId;
+}
+/**
+ * POST /v1/players/:e/:p/inner/ingest — the publisher forwards ONE InnerFrame.
+ * 204 on success; uniform 403 on any gate/shape/oversize failure (no-leak). The
+ * daemon TRUSTS the authenticated publisher's summaries (already ~2KB-truncated
+ * at source) — the 32KB cap is purely the DOS backstop; no re-truncation.
+ */
+async function handleInnerIngest(req, res, deps, ensemble, playerId) {
+    const workflowId = gateIngress(req, res, deps, ensemble, playerId);
+    if (workflowId === null)
+        return;
+    const body = await (0, body_1.readJsonBody)(req, body_1.INGEST_BODY_MAX);
+    // Oversize / malformed / non-frame → uniform 403 (no-leak; the publisher just
+    // drops the frame on any non-204).
+    if (body === body_1.BODY_TOO_LARGE || body === body_1.BODY_INVALID_JSON) {
+        return (0, responses_1.errorResponse)(res, 403, { error: 'forbidden' });
+    }
+    const type = body.type;
+    if (typeof type !== 'string' || !type.startsWith('inner.')) {
+        return (0, responses_1.errorResponse)(res, 403, { error: 'forbidden' });
+    }
+    // S1 (security): `type` is interpolated RAW into the operator SSE `event:`
+    // line (handleInnerSse) — a CR/LF here would let an authenticated source
+    // inject/garble frames in the operator's stream. Reject at the INGRESS
+    // boundary so a malformed type never enters the registry. (Every other frame
+    // field is JSON.stringify'd into `data:`, which escapes control chars.)
+    if (/[\r\n]/.test(type)) {
+        return (0, responses_1.errorResponse)(res, 403, { error: 'forbidden' });
+    }
+    // Trust the authenticated publisher's frame shape (it owns the schema +
+    // truncation). Publish to local subscribers and ack with no body.
+    deps.innerLoop.publish(workflowId, body);
+    // 3d MD-G — a gate_pending frame ALSO registers the pending request in the
+    // gate (atomic register-and-surface from one POST; the "engagement IS
+    // registration" path, no separate open-route). Narrow, one-directional
+    // coupling: inner-routes → GateRegistry.open(). Guarded on the type so it
+    // never fires for ordinary inner frames. `open` is idempotent on requestId.
+    if (type === 'inner.gate_pending' && deps.gate) {
+        const f = body;
+        if (typeof f.requestId === 'string' && typeof f.tool === 'string') {
+            deps.gate.open(workflowId, f.requestId, {
+                tool: f.tool,
+                argsSummary: typeof f.argsSummary === 'string' ? f.argsSummary : '',
+                ensemble,
+            });
+        }
+    }
+    res.writeHead(204);
+    res.end();
+}
+/**
+ * GET /v1/players/:e/:p/inner/presence — publisher-only presence probe.
+ * Same gates as ingest (presence is publisher-only; leaking "is someone
+ * watching X" would be a covert channel). 200 `{ subscribers }` or 403.
+ */
+function handleInnerPresence(req, res, deps, ensemble, playerId) {
+    const workflowId = gateIngress(req, res, deps, ensemble, playerId);
+    if (workflowId === null)
+        return;
+    // 3d MD-G — fold `gateArmed` into the presence response so the polling
+    // subprocess reads BOTH engagement inputs (operator-present + armed) from one
+    // fetch (avoids a stale-armed / fresh-present mismatch). `false` when the gate
+    // is unwired or unarmed.
+    (0, responses_1.jsonResponse)(res, 200, {
+        subscribers: deps.innerLoop.subscriberCount(workflowId),
+        gateArmed: deps.gate?.isArmed(workflowId) ?? false,
+    });
+}
+/**
+ * GET /v1/players/:e/:p/inner — operator/widget SSE fine-tail stream (EGRESS).
+ * server.ts has already applied the outer bearer + `requireTier(3)` gate. Plain
+ * `event:`/`data:` framing (fetch-consumable, no EventSource-specific framing);
+ * `:ka` keepalive; `:closed` when the player goes away. No ring/seq/replay —
+ * ephemeral best-effort tail (a disconnect loses in-flight deltas, by design).
+ */
+async function handleInnerSse(req, res, deps, ensemble, playerId) {
+    const workflowId = (0, config_1.sessionWorkflowId)(ensemble, playerId);
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream; charset=utf-8',
+        'Cache-Control': 'no-cache, no-transform',
+        Connection: 'keep-alive',
+        'X-Accel-Buffering': 'no',
+    });
+    // Flush headers immediately so the operator's stream OPENS now, not on the
+    // first frame/keepalive — otherwise Node buffers the head until the first
+    // body write and a fetch/EventSource client blocks up to INNER_KEEPALIVE_MS.
+    // (Mirrors the main SSE handler in sse-handler.ts.)
+    res.flushHeaders?.();
+    const sub = deps.innerLoop.subscribe(workflowId);
+    let cleanedUp = false;
+    const keepalive = setInterval(() => {
+        try {
+            res.write(':ka\n\n');
+        }
+        catch { /* socket gone — close handler cleans up */ }
+    }, INNER_KEEPALIVE_MS);
+    if (typeof keepalive.unref === 'function')
+        keepalive.unref();
+    const cleanup = () => {
+        if (cleanedUp)
+            return;
+        cleanedUp = true;
+        clearInterval(keepalive);
+        deps.innerLoop.unsubscribe(workflowId, sub);
+    };
+    req.on('close', cleanup);
+    res.on('close', cleanup);
+    try {
+        for await (const frame of sub) {
+            res.write(`event: ${frame.type}\ndata: ${JSON.stringify(frame)}\n\n`);
+            // Bound the per-connection write buffer: a slow operator socket must not
+            // grow the daemon's memory unboundedly. Drop the connection if it backs up
+            // (ephemeral tail — reconnect re-tails live).
+            const buffered = res.socket?.writableLength ?? 0;
+            if (buffered > MAX_SSE_WRITE_BUFFER)
+                break;
+        }
+        // Subscription ended (player gone / unsubscribe) — signal a clean close.
+        try {
+            res.write(':closed\n\n');
+        }
+        catch { /* already closed */ }
+    }
+    catch {
+        /* write-after-close or iterator error — fall through to cleanup */
+    }
+    finally {
+        cleanup();
+        try {
+            res.end();
+        }
+        catch { /* already ended */ }
+    }
+}

package/dist/http/inner-loop.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Inner-loop registry + subscription (3c Tier-2, MD-F) — the DAEMON-LOCAL,
+ * off-wire fine-tail sink. NOT on the coordination EnsembleEventBus, NOT on
+ * Temporal, NOT replayable (no ring / Last-Event-ID / seq). A per-player live
+ * tail of a headless Pi player's inner loop (thinking deltas, tool calls/results,
+ * token pressure, turn markers), served by the daemon RUNNING that player.
+ *
+ * Two clients meet here:
+ *   - The OPERATOR side: `GET /v1/players/:e/:p/inner` opens an SSE stream →
+ *     {@link InnerLoopRegistry.subscribe} → drains an {@link InnerSubscription}.
+ *   - The SOURCE side: eng's `InnerLoopPublisher` (in the detached Pi subprocess)
+ *     forwards frames via the thin loopback-HTTP client → `POST /inner/ingest` →
+ *     {@link InnerLoopRegistry.publish}. The publisher presence-gates on
+ *     {@link InnerLoopRegistry.subscriberCount} (read via `GET /inner/presence`)
+ *     so zero watchers ⇒ zero forwarding.
+ *
+ * Backpressure (registry-owned, per the split with the source-side coalescing):
+ * each subscriber has a bounded queue with DROP-OLDEST. When frames are dropped,
+ * a single `compacted{dropped,sinceTs}` marker is delivered ahead of the next
+ * real frame so the operator knows the tail has gaps. (Source-side coalescing of
+ * thinking deltas + ~2KB summary truncation already bound the inbound rate; this
+ * is the last-resort guard against a stalled SSE socket.)
+ *
+ * This module implements eng's `InnerLoopRegistry` DI interface
+ * (`publish` + `subscriberCount`) as a SUPERSET that also owns subscriber
+ * lifecycle (`subscribe` / `unsubscribe` / `closePlayer`).
+ */
+import type { InnerFrame, InnerLoopRegistry as InnerLoopSink } from '../pi/inner-loop-publisher';
+/** Per-subscriber bounded queue depth before drop-oldest engages. */
+export declare const INNER_SUB_QUEUE_MAX = 256;
+/**
+ * A frame as delivered on the `/inner` wire — eng's source {@link InnerFrame}
+ * plus the registry-injected `compacted` backpressure marker (never produced by
+ * the source; purely the sink's gap signal).
+ */
+export type InnerWireFrame = InnerFrame | {
+    type: 'compacted';
+    dropped: number;
+    sinceTs: number;
+};
+/**
+ * One connected `/inner` SSE subscriber. Async-iterable: the SSE handler does
+ * `for await (const frame of sub) { write(frame) }`. Bounded queue with
+ * drop-oldest; a `compacted{dropped,sinceTs}` marker is injected before the next
+ * real frame whenever drops have occurred since the last delivery.
+ *
+ * No ring / replay / seq — this is an ephemeral best-effort tail (MD-F): a
+ * disconnect loses in-flight deltas, by design.
+ */
+export declare class InnerSubscription implements AsyncIterableIterator<InnerWireFrame> {
+    private readonly now;
+    private readonly queue;
+    private dropped;
+    private droppedSinceTs;
+    private waiter;
+    private closed;
+    constructor(now?: () => number);
+    /** Enqueue a frame, dropping the oldest if the queue is full. Source → sub. */
+    push(frame: InnerFrame): void;
+    /** Pull the next deliverable, injecting a `compacted` marker first if drops are pending. */
+    private take;
+    next(): Promise<IteratorResult<InnerWireFrame>>;
+    /** Terminate the stream — wakes a parked consumer with `done: true`. Idempotent. */
+    close(): void;
+    return(): Promise<IteratorResult<InnerWireFrame>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<InnerWireFrame>;
+}
+/**
+ * Per-daemon registry of inner-loop subscribers, keyed by the player's fixed
+ * session `workflowId`. Implements eng's {@link InnerLoopSink} interface
+ * (`publish` + `subscriberCount`) so the publisher's thin client and this sink
+ * share one contract.
+ */
+export declare class InnerLoopRegistry implements InnerLoopSink {
+    private readonly now;
+    private readonly subs;
+    constructor(now?: () => number);
+    /** Open a new SSE subscription for a player. Caller drains it, then `unsubscribe`. */
+    subscribe(workflowId: string): InnerSubscription;
+    /** Remove + close one subscription (on SSE disconnect). Prunes the empty player set. */
+    unsubscribe(workflowId: string, sub: InnerSubscription): void;
+    /** Fan a frame out to every live subscriber for the player. Source → subs. */
+    publish(workflowId: string, frame: InnerFrame): void;
+    /** Live subscriber count — the publisher's presence gate reads this (via `/inner/presence`). */
+    subscriberCount(workflowId: string): number;
+    /** Close every subscriber for a player (player gone → streams end with `:closed`). */
+    closePlayer(workflowId: string): void;
+    /** Total live inner-tail subscribers across all players (diagnostics). */
+    totalSubscriberCount(): number;
+    /** Close everything (daemon shutdown). */
+    close(): void;
+}