agent-tempo 1.2.0 → 1.4.0

package/dist/config.d.ts

@@ -48,6 +48,37 @@ export declare const ENV: {
      * sandboxed contexts. Mutually exclusive with {@link PERMISSION_MODE}.
      */
     readonly DANGEROUSLY_SKIP_PERMISSIONS: "AGENT_TEMPO_DANGEROUSLY_SKIP_PERMISSIONS";
+    /**
+     * Phase 3a — headless Pi runtime model selector. Pi takes a `provider/model`
+     * string (e.g. `anthropic/claude-opus-4-7`); absent → Pi's own default
+     * provider/model (the 3a anthropic-default path). Recruit `model` arg →
+     * this env → Pi default.
+     */
+    readonly PI_MODEL: "AGENT_TEMPO_PI_MODEL";
+    /**
+     * Phase 3a — headless Pi restart-resume. The daemon reads `metadata.sessionId`
+     * (the Pi conversation id the player was in when it died) and passes it here;
+     * the headless entry resumes via Pi `continueSession(<id>)`. Absent on a fresh
+     * recruit → a new Pi session.
+     */
+    readonly PI_CONTINUE_SESSION: "AGENT_TEMPO_PI_CONTINUE_SESSION";
+    /**
+     * Phase 3a / MD-C — headless Pi tool-access policy. One of
+     * `restricted` (default; Bash/shell/exec HARD-BLOCKED) | `standard` (scoped
+     * Bash) | `full` (unsandboxed; admin-gated at recruit). Read by the Pi
+     * extension's `tool_call` gate (mode='headless' only). Mirrors
+     * {@link PERMISSION_MODE}'s threading.
+     */
+    readonly TOOL_ACCESS: "AGENT_TEMPO_TOOL_ACCESS";
+    /**
+     * 3c Tier-2 ingest auth. The daemon mints a per-player ingest token (scoped to
+     * the session workflowId) BEFORE spawning a headless Pi player and threads it
+     * into the subprocess env here. The player's inner-loop publisher presents it
+     * on `POST /inner/ingest` + `GET /inner/presence` (loopback), where the daemon
+     * validates it against the URL-derived workflowId (cross-player-spoof guard).
+     * Absent → the publisher's HTTP client is a no-op (no fine-tail forwarding).
+     */
+    readonly INGEST_TOKEN: "AGENT_TEMPO_INGEST_TOKEN";
     /**
      * v0.25 PR-D attachment resume plumbing. When `restart` / `migrate`
      * enqueues a spawn outbox entry, the workflow passes the pre-claimed
@@ -72,6 +103,16 @@ export declare const ENV: {
     readonly DAEMON_PORT: "AGENT_TEMPO_DAEMON_PORT";
     readonly CORS_ORIGINS: "AGENT_TEMPO_CORS_ORIGINS";
     readonly SSE_MAX_CONNECTIONS: "AGENT_TEMPO_SSE_MAX_CONNECTIONS";
+    /**
+     * 3e RBAC (MD-E). Two-token model: the READ token (T1 — observe) may live in
+     * env or config.json and auto-generates; the ADMIN token (T1+T2+T3 — mutate +
+     * supervisory gate/inner) is ENV-VAR-ONLY (never config.json/disk, never
+     * auto-generated). `TLS_ACKNOWLEDGED=1` suppresses the non-loopback-bind
+     * plaintext-HTTP startup warning.
+     */
+    readonly HTTP_READ_TOKEN: "AGENT_TEMPO_HTTP_READ_TOKEN";
+    readonly HTTP_ADMIN_TOKEN: "AGENT_TEMPO_HTTP_ADMIN_TOKEN";
+    readonly TLS_ACKNOWLEDGED: "AGENT_TEMPO_TLS_ACKNOWLEDGED";
     /**
      * Dev profile gate (ADR 0014 §5.2). One source of truth — every layer
      * (paths, namespace, port, task queue, banner, registry gating) consults
@@ -115,8 +156,19 @@ export interface PersistedConfig {
      * a request with a non-loopback `Origin`) and no token is set:
      * `crypto.randomBytes(32).toString('base64url')`, 0600 on POSIX.
      * Rotation = delete this field; next daemon boot regenerates.
+     *
+     * 3e: this LEGACY single token is migrated to the READ tier (T1) — a daemon
+     * with only `httpToken` set keeps read access and emits a one-time startup
+     * warning to set an admin token for writes/gate/inner. Prefer `readToken`.
      */
     httpToken?: string;
+    /**
+     * 3e RBAC — the READ-tier (T1) bearer token. Env `AGENT_TEMPO_HTTP_READ_TOKEN`
+     * takes precedence over this; auto-generated here on first bearer-mode boot if
+     * neither is set. The ADMIN token is deliberately ABSENT from this file (it is
+     * env-var-only, never persisted).
+     */
+    readToken?: string;
 }
 /**
  * Dev profile defaults — one switch (`--dev` top-level flag, or
@@ -278,6 +330,33 @@ export declare function parseTemporalYaml(content: string): PersistedConfig;
  * for empty/unset values so callers can use it as a source-aware default.
  */
 export declare function parseAgent(value: string | undefined, source: ConfigSource): AgentType;
+/**
+ * Result of {@link parsePiProviderModel}: the parsed parts, OR an `{ error }`
+ * describing why the selector is malformed. Non-throwing by design — a pure
+ * mapper returning a discriminated union (the recruit wiring branches
+ * `if ('error' in r) return fail(r.error)`, no try/catch).
+ */
+export type ProviderModel = {
+    provider: string;
+    model: string;
+} | {
+    error: string;
+};
+/**
+ * Parse a Pi provider/model selector (e.g. `"github-copilot/gpt-4o"`) into its
+ * `{ provider, model }` parts for Pi's `createAgentSession` model option.
+ *
+ * Provider-agnostic: the segment before the FIRST `/` is the provider id,
+ * passed through VERBATIM (Copilot's pi-ai provider id is literally
+ * `github-copilot` — no normalization needed); everything after is the model
+ * id, which may itself contain `/` (e.g. `openrouter/anthropic/claude`).
+ *
+ * Fail-loud (no silent default): returns `{ error }` — never a fallback model —
+ * when the selector has no `/`, an empty provider, or an empty model. A bare
+ * provider with no model is rejected here; omitting the recruit `model` arg
+ * ENTIRELY is a different path (Pi's own default), handled upstream, not here.
+ */
+export declare function parsePiProviderModel(model: string): ProviderModel;
 /** CLI flag overrides — passed down from the arg parser. */
 export interface CliOverrides {
     temporalAddress?: string;

package/dist/config.js

@@ -11,6 +11,7 @@ exports.saveConfigFile = saveConfigFile;
 exports.loadTemporalCliConfig = loadTemporalCliConfig;
 exports.parseTemporalYaml = parseTemporalYaml;
 exports.parseAgent = parseAgent;
+exports.parsePiProviderModel = parsePiProviderModel;
 exports.getConfig = getConfig;
 exports.getConfigWithSources = getConfigWithSources;
 exports.hostTaskQueue = hostTaskQueue;
@@ -78,6 +79,37 @@ exports.ENV = {
      * sandboxed contexts. Mutually exclusive with {@link PERMISSION_MODE}.
      */
     DANGEROUSLY_SKIP_PERMISSIONS: 'AGENT_TEMPO_DANGEROUSLY_SKIP_PERMISSIONS',
+    /**
+     * Phase 3a — headless Pi runtime model selector. Pi takes a `provider/model`
+     * string (e.g. `anthropic/claude-opus-4-7`); absent → Pi's own default
+     * provider/model (the 3a anthropic-default path). Recruit `model` arg →
+     * this env → Pi default.
+     */
+    PI_MODEL: 'AGENT_TEMPO_PI_MODEL',
+    /**
+     * Phase 3a — headless Pi restart-resume. The daemon reads `metadata.sessionId`
+     * (the Pi conversation id the player was in when it died) and passes it here;
+     * the headless entry resumes via Pi `continueSession(<id>)`. Absent on a fresh
+     * recruit → a new Pi session.
+     */
+    PI_CONTINUE_SESSION: 'AGENT_TEMPO_PI_CONTINUE_SESSION',
+    /**
+     * Phase 3a / MD-C — headless Pi tool-access policy. One of
+     * `restricted` (default; Bash/shell/exec HARD-BLOCKED) | `standard` (scoped
+     * Bash) | `full` (unsandboxed; admin-gated at recruit). Read by the Pi
+     * extension's `tool_call` gate (mode='headless' only). Mirrors
+     * {@link PERMISSION_MODE}'s threading.
+     */
+    TOOL_ACCESS: 'AGENT_TEMPO_TOOL_ACCESS',
+    /**
+     * 3c Tier-2 ingest auth. The daemon mints a per-player ingest token (scoped to
+     * the session workflowId) BEFORE spawning a headless Pi player and threads it
+     * into the subprocess env here. The player's inner-loop publisher presents it
+     * on `POST /inner/ingest` + `GET /inner/presence` (loopback), where the daemon
+     * validates it against the URL-derived workflowId (cross-player-spoof guard).
+     * Absent → the publisher's HTTP client is a no-op (no fine-tail forwarding).
+     */
+    INGEST_TOKEN: 'AGENT_TEMPO_INGEST_TOKEN',
     /**
      * v0.25 PR-D attachment resume plumbing. When `restart` / `migrate`
      * enqueues a spawn outbox entry, the workflow passes the pre-claimed
@@ -102,6 +134,16 @@ exports.ENV = {
     DAEMON_PORT: 'AGENT_TEMPO_DAEMON_PORT',
     CORS_ORIGINS: 'AGENT_TEMPO_CORS_ORIGINS',
     SSE_MAX_CONNECTIONS: 'AGENT_TEMPO_SSE_MAX_CONNECTIONS',
+    /**
+     * 3e RBAC (MD-E). Two-token model: the READ token (T1 — observe) may live in
+     * env or config.json and auto-generates; the ADMIN token (T1+T2+T3 — mutate +
+     * supervisory gate/inner) is ENV-VAR-ONLY (never config.json/disk, never
+     * auto-generated). `TLS_ACKNOWLEDGED=1` suppresses the non-loopback-bind
+     * plaintext-HTTP startup warning.
+     */
+    HTTP_READ_TOKEN: 'AGENT_TEMPO_HTTP_READ_TOKEN',
+    HTTP_ADMIN_TOKEN: 'AGENT_TEMPO_HTTP_ADMIN_TOKEN',
+    TLS_ACKNOWLEDGED: 'AGENT_TEMPO_TLS_ACKNOWLEDGED',
     /**
      * Dev profile gate (ADR 0014 §5.2). One source of truth — every layer
      * (paths, namespace, port, task queue, banner, registry gating) consults
@@ -420,6 +462,38 @@ function parseAgent(value, source) {
     }
     return value;
 }
+/**
+ * Parse a Pi provider/model selector (e.g. `"github-copilot/gpt-4o"`) into its
+ * `{ provider, model }` parts for Pi's `createAgentSession` model option.
+ *
+ * Provider-agnostic: the segment before the FIRST `/` is the provider id,
+ * passed through VERBATIM (Copilot's pi-ai provider id is literally
+ * `github-copilot` — no normalization needed); everything after is the model
+ * id, which may itself contain `/` (e.g. `openrouter/anthropic/claude`).
+ *
+ * Fail-loud (no silent default): returns `{ error }` — never a fallback model —
+ * when the selector has no `/`, an empty provider, or an empty model. A bare
+ * provider with no model is rejected here; omitting the recruit `model` arg
+ * ENTIRELY is a different path (Pi's own default), handled upstream, not here.
+ */
+function parsePiProviderModel(model) {
+    const raw = model.trim();
+    const slash = raw.indexOf('/');
+    if (slash < 0) {
+        return {
+            error: `model "${model}" must be a "provider/model" selector (e.g. "github-copilot/gpt-4o") — no "/" found.`,
+        };
+    }
+    const provider = raw.slice(0, slash).trim();
+    const modelId = raw.slice(slash + 1).trim();
+    if (!provider) {
+        return { error: `model "${model}" has an empty provider before "/" — expected e.g. "github-copilot/gpt-4o".` };
+    }
+    if (!modelId) {
+        return { error: `model "${model}" has an empty model after "/" — specify a model, e.g. "github-copilot/gpt-4o".` };
+    }
+    return { provider, model: modelId };
+}
 /**
  * Resolve `defaultAgent` through the standard precedence chain and validate
  * against the {@link AgentType} union. Each step passes its own source tag

package/dist/daemon.js

@@ -66,6 +66,11 @@ const config_1 = require("./config");
 const dev_banner_1 = require("./cli/dev-banner");
 const worker_1 = require("./worker");
 const connection_1 = require("./connection");
+const inner_loop_1 = require("./http/inner-loop");
+const ingest_registry_1 = require("./http/ingest-registry");
+const gate_registry_1 = require("./http/gate-registry");
+const gate_audit_1 = require("./http/gate-audit");
+const grpc_shutdown_guard_1 = require("./utils/grpc-shutdown-guard");
 const daemon_1 = require("./cli/daemon");
 const client_3 = require("./client");
 const orphans_1 = require("./reconcile/orphans");
@@ -684,6 +689,10 @@ function startCleanupLoop(client, daemonConfig, hostname = os.hostname()) {
     };
 }
 async function main() {
+    // Neutralize the Temporal/grpc-js "Channel has been shut down" retry-after-
+    // close race so a stray retry timer can't kill the long-lived daemon. See
+    // src/utils/grpc-shutdown-guard.ts.
+    (0, grpc_shutdown_guard_1.installGrpcShutdownGuard)();
     // ADR 0014 §5.4 / gate 4 — dev daemon log self-identifies. Banner fires
     // first so it lands at the top of `~/.agent-tempo-dev/daemon.log` for
     // grep-friendly identification regardless of subsequent log volume.
@@ -823,6 +832,19 @@ async function main() {
     // #94/#95 PR-2 — aggregate poll loop + per-ensemble buses. Owned by
     // the daemon process; `close()` drains every per-ensemble bus.
     let aggregateRunner = null;
+    // 3c Tier-2 — daemon-owned singletons shared between the Temporal worker
+    // (outbox pi-spawn mints / destroy revokes) and the HTTP server (/inner SSE
+    // + /inner/ingest validation). Both the worker and startHttpServer run in
+    // THIS process, so one instance each suffices. Constructed eagerly (no I/O)
+    // so the shutdown handler — declared just below — can drain them.
+    const innerLoop = new inner_loop_1.InnerLoopRegistry();
+    const ingestTokens = new ingest_registry_1.IngestTokenRegistry();
+    // 3d MD-G — the operator-gate registry, same daemon-owned-singleton pattern.
+    // Audit sink = the append-only JSONL writer; publishToInner = innerLoop.publish
+    // (the DI that emits gate_resolved on the player's /inner stream without a
+    // GateRegistry↔inner-loop circular import).
+    const gate = new gate_registry_1.GateRegistry((0, gate_audit_1.createGateAuditSink)(), Date.now, undefined, // default 45s auto-allow
+    (workflowId, frame) => innerLoop.publish(workflowId, frame));
     const shutdown = () => {
         if (shuttingDown)
             return;
@@ -856,6 +878,12 @@ async function main() {
         // sockets — preventing wasted work in the drain window.
         aggregateRunner?.close();
         httpServerHandle?.close().catch((err) => log('http close error (non-fatal):', err instanceof Error ? err.message : err));
+        // 3c Tier-2 — clear-all on shutdown: drop every minted ingest token (no
+        // dead token outlives the daemon) and close every open /inner subscriber
+        // (streams end cleanly rather than dangling).
+        ingestTokens.revokeAll();
+        innerLoop.close();
+        gate.clear();
         sharedWorker?.shutdown();
         hostWorker?.shutdown();
     };
@@ -863,7 +891,7 @@ async function main() {
     process.on('SIGINT', shutdown);
     // Create workers (signal handlers already active via mutable refs)
     log(`Connecting to Temporal at ${config.temporalAddress} (namespace: ${config.temporalNamespace})`);
-    const workers = await (0, worker_1.createWorkers)(config);
+    const workers = await (0, worker_1.createWorkers)(config, ingestTokens, gate);
     sharedWorker = workers.sharedWorker;
     hostWorker = workers.hostWorker;
     log('Workers created — processing tasks');
@@ -948,6 +976,14 @@ async function main() {
                 taskQueue: config.taskQueue,
                 version: daemonVersion(),
                 aggregate: aggregateRunner,
+                // 3c Tier-2 — same singletons the worker's outbox activities use, so
+                // the operator /inner SSE reads the registry the publisher POSTs into
+                // and /inner/ingest validates against the tokens the spawn path minted.
+                innerLoop,
+                ingestTokens,
+                // 3d MD-G — the same gate registry the worker's outbox auto-disarms on
+                // detach/destroy; the HTTP server serves arm/disarm/decide + resolution.
+                gate,
             });
             log(`HTTP listening on http://${httpServerHandle.bindAddr}:${httpServerHandle.port}`);
             log(`Aggregate poll loop running (bootEpoch=${bootEpoch})`);

package/dist/http/aggregate.d.ts

@@ -41,6 +41,21 @@ export declare class TickSkipped extends Error {
     readonly name = "TickSkipped";
     constructor(reason: string);
 }
+/**
+ * 3c Tier-1 coarse activity snapshot for a single player — the bits the
+ * aggregate diffs to decide whether to emit `player.activity`. `currentTool`
+ * is normalized to `null` when idle/absent; the context fields are `undefined`
+ * when Pi can't report usage (e.g. right after compaction).
+ */
+export interface PlayerCoarse {
+    currentTool: string | null;
+    contextTokens?: number;
+    contextPercent?: number;
+}
+/** Extract the coarse-activity tuple from a player summary, normalizing idle → null. */
+export declare function coarseOf(p: PlayerSummaryV1): PlayerCoarse;
+/** True when two coarse snapshots differ in any field. */
+export declare function coarseChanged(a: PlayerCoarse | undefined, b: PlayerCoarse): boolean;
 /** Per-ensemble tracking state across ticks. */
 interface EnsembleTrack {
     bus: EnsembleEventBus;
@@ -56,6 +71,12 @@ interface EnsembleTrack {
     consecutiveFailures: number;
     /** Last seen player phase, keyed by playerId. */
     playerPhases: Map<string, string | undefined>;
+    /**
+     * 3c Tier-1 — last-seen coarse activity per playerId (currentTool + context
+     * usage). Diffed each poll to emit `player.activity` on change. Seeded on
+     * `player.added`, dropped on `player.removed` — lockstep with `playerPhases`.
+     */
+    playerCoarse: Map<string, PlayerCoarse>;
     /**
      * Adapter family per playerId — used to faithfully reconstruct the
      * prior `AggregateEnsembleSnapshot` view at tick boundaries (see #535).
@@ -175,7 +196,7 @@ export interface DiffEvent {
     type: import('./event-types').SseEventKind;
     payload: unknown;
 }
-export declare function diffEnsembleSnapshot(prev: AggregateEnsembleSnapshot | null, next: AggregateEnsembleSnapshot, track: Pick<EnsembleTrack, 'playerPhases' | 'playerAgentTypes' | 'flags' | 'schedulesHash' | 'chatIds' | 'chatIdOrder'>, capturedAt: string): DiffEvent[];
+export declare function diffEnsembleSnapshot(prev: AggregateEnsembleSnapshot | null, next: AggregateEnsembleSnapshot, track: Pick<EnsembleTrack, 'playerPhases' | 'playerCoarse' | 'playerAgentTypes' | 'flags' | 'schedulesHash' | 'chatIds' | 'chatIdOrder'>, capturedAt: string): DiffEvent[];
 /**
  * Diff host profiles map → per-host events. Pure function.
  */

package/dist/http/aggregate.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AggregateRunner = exports.TickSkipped = exports.MAX_CONSECUTIVE_FAILURES = exports.AGGREGATE_LIST_DEADLINE_MS = exports.DEFAULT_POLL_INTERVAL_MS = void 0;
+exports.coarseOf = coarseOf;
+exports.coarseChanged = coarseChanged;
 exports.canonicalize = canonicalize;
 exports.hashOf = hashOf;
 exports.diffEnsembleSnapshot = diffEnsembleSnapshot;
@@ -84,6 +86,21 @@ class TickSkipped extends Error {
     constructor(reason) { super(reason); }
 }
 exports.TickSkipped = TickSkipped;
+/** Extract the coarse-activity tuple from a player summary, normalizing idle → null. */
+function coarseOf(p) {
+    return {
+        currentTool: p.currentTool ?? null,
+        ...(p.contextTokens !== undefined ? { contextTokens: p.contextTokens } : {}),
+        ...(p.contextPercent !== undefined ? { contextPercent: p.contextPercent } : {}),
+    };
+}
+/** True when two coarse snapshots differ in any field. */
+function coarseChanged(a, b) {
+    return (!a ||
+        a.currentTool !== b.currentTool ||
+        a.contextTokens !== b.contextTokens ||
+        a.contextPercent !== b.contextPercent);
+}
 /**
  * Stable JSON canonicalization — keys sorted, no extraneous whitespace.
  * Used for SHA-256 diff suppression so reordered key emits don't
@@ -118,6 +135,9 @@ function diffEnsembleSnapshot(prev, next, track, capturedAt) {
         if (!prevPlayers.has(p.playerId)) {
             events.push({ type: 'player.added', payload: p });
             track.playerPhases.set(p.playerId, p.phase);
+            // 3c — seed coarse so the first real change (not the add itself, whose
+            // payload already carries currentTool/context) emits player.activity.
+            track.playerCoarse.set(p.playerId, coarseOf(p));
             // #535 — record the adapter family so the prior reconstruction at
             // the next tick (aggregate.ts ~L600) carries the real agentType
             // instead of a hardcoded `'claude'` stand-in. Treated as immutable
@@ -140,6 +160,25 @@ function diffEnsembleSnapshot(prev, next, track, capturedAt) {
             });
             track.playerPhases.set(p.playerId, p.phase);
         }
+        // player.activity (3c Tier-1) — emit when coarse currentTool/context
+        // changes between polls. Distinct from phase_changed (phase vs activity).
+        // Source freshness ~30s (heartbeat metadata piggyback); the live, fine
+        // tail is the off-wire /inner side-channel.
+        const nextCoarse = coarseOf(p);
+        if (coarseChanged(track.playerCoarse.get(p.playerId), nextCoarse)) {
+            events.push({
+                type: 'player.activity',
+                payload: {
+                    playerId: p.playerId,
+                    ensemble,
+                    currentTool: nextCoarse.currentTool,
+                    ...(nextCoarse.contextTokens !== undefined ? { contextTokens: nextCoarse.contextTokens } : {}),
+                    ...(nextCoarse.contextPercent !== undefined ? { contextPercent: nextCoarse.contextPercent } : {}),
+                    at: capturedAt,
+                },
+            });
+            track.playerCoarse.set(p.playerId, nextCoarse);
+        }
     }
     // player.removed — iterate prev.
     if (prev) {
@@ -159,6 +198,7 @@ function diffEnsembleSnapshot(prev, next, track, capturedAt) {
                     },
                 });
                 track.playerPhases.delete(p.playerId);
+                track.playerCoarse.delete(p.playerId);
                 track.playerAgentTypes.delete(p.playerId);
             }
         }
@@ -377,6 +417,7 @@ class AggregateRunner {
                 bus,
                 consecutiveFailures: 0,
                 playerPhases: new Map(),
+                playerCoarse: new Map(),
                 playerAgentTypes: new Map(),
                 flags: null,
                 schedulesHash: null,

package/dist/http/auth.d.ts

@@ -51,17 +51,103 @@ export declare function extractBearerToken(authHeader: string | undefined): stri
  */
 export declare function tokensMatch(received: string, expected: string): boolean;
 /**
- * Load (or auto-generate) the daemon's HTTP bearer token.
- *
- * - When `bearerRequired` is true and the persisted config has no
- *   `httpToken`, generate one (`crypto.randomBytes(32).toString('base64url')`)
- *   and persist it via `saveConfigFile` (which sets 0600 on POSIX).
- * - When `bearerRequired` is false, return whatever is in the config
- *   without generating — operators may still want a token saved for
- *   future use, and we shouldn't write secrets the user didn't request.
+ * @deprecated 3e — superseded by {@link loadRbacTokens} (read + admin split).
+ * Kept only until every caller migrates; do NOT add new callers. Resolves the
+ * legacy single `httpToken` (env-less) for back-compat shims.
  */
 export declare function loadOrGenerateHttpToken(opts: {
     bearerRequired: boolean;
     load?: () => PersistedConfig;
     save?: (cfg: PersistedConfig) => void;
 }): string | null;
+/** Resolved RBAC tokens for the daemon HTTP surface (3e). */
+export interface RbacTokens {
+    /** T1 read token (env > config.json > auto-gen), or `null` when none + not required. */
+    readToken: string | null;
+    /** T1+T2+T3 admin token — ENV-VAR-ONLY, or `null` when unset (→ 503 on T≥2). */
+    adminToken: string | null;
+    /**
+     * True when a LEGACY `httpToken` (no `readToken`) was adopted as the read token.
+     * The daemon emits a one-time startup warning so the operator sets an admin token.
+     */
+    legacyMigrated: boolean;
+}
+/** Admin token — ENV-VAR-ONLY (never config.json/disk, never auto-generated). */
+export declare function loadAdminToken(env?: NodeJS.ProcessEnv): string | null;
+/**
+ * Read token (T1). Priority: env `AGENT_TEMPO_HTTP_READ_TOKEN` > config.json
+ * `readToken` > LEGACY config.json `httpToken` (adopted → `legacy:true`) >
+ * auto-generate when bearer mode is required (persisted as `readToken`).
+ */
+export declare function loadReadToken(opts: {
+    bearerRequired: boolean;
+    env?: NodeJS.ProcessEnv;
+    load?: () => PersistedConfig;
+    save?: (cfg: PersistedConfig) => void;
+}): {
+    token: string | null;
+    legacy: boolean;
+};
+/** Load both RBAC tokens. The daemon calls this once at startup. */
+export declare function loadRbacTokens(opts: {
+    bearerRequired: boolean;
+    env?: NodeJS.ProcessEnv;
+    load?: () => PersistedConfig;
+    save?: (cfg: PersistedConfig) => void;
+}): RbacTokens;
+/** Access tiers (MD-E): 1 = read/observe, 2 = write/mutate, 3 = supervisory (gate/inner). */
+export type Tier = 1 | 2 | 3;
+/**
+ * Granted tier for a presented bearer, given the RBAC tokens (timing-safe).
+ * Admin grants the FULL ladder (3 ⊇ 2 ⊇ 1); read grants T1 only; no match → 0.
+ * There is no T2-only token — T2 and T3 are both "admin required".
+ */
+export declare function tierForToken(presented: string, tokens: {
+    readToken: string | null;
+    adminToken: string | null;
+}): 0 | 1 | 3;
+export interface TierGuardInput {
+    /** Daemon bind address — decides loopback trust. */
+    bindAddr: string;
+    /** Request `Origin` header (may be absent for a non-browser client). */
+    originHeader: string | undefined;
+    /** Request `Authorization` header. */
+    authHeader: string | undefined;
+    /** Read-tier token, or `null`. */
+    readToken: string | null;
+    /** Admin token, or `null` when unset (→ 503 on T≥2). */
+    adminToken: string | null;
+}
+export type TierGuardResult = {
+    ok: true;
+} | {
+    ok: false;
+    status: 401;
+    error: 'unauthorized';
+} | {
+    ok: false;
+    status: 403;
+    error: 'insufficient-tier';
+    detail: string;
+} | {
+    ok: false;
+    status: 503;
+    error: 'admin-token-not-configured';
+    detail: string;
+};
+/**
+ * Authorization guard (3e MD-E). Assumes the shared upstream pass already settled
+ * AUTHENTICATION + CORS + the DNS-rebind/Origin defense (architect's Layer 2);
+ * this is Layer-3 authZ — it ONLY decides tier ≥ N and emits 503/403/401.
+ *
+ * Matrix (bearer mode):
+ *   - loopback (`!bearerRequired`)        → PASS all tiers (local-trust short-circuit).
+ *   - N ≥ 2 AND adminToken unset          → 503 admin-token-not-configured.
+ *   - no/invalid bearer (granted 0)       → 401 unauthorized.
+ *   - granted < N (read token on T≥2)     → 403 insufficient-tier (+ migration hint).
+ *   - granted ≥ N (admin, or read on T1)  → PASS.
+ *
+ * Keyed off the `Authorization` bearer only (no `Origin`/cookie requirement) so a
+ * headless Node client passes once its token validates. View-agnostic by design.
+ */
+export declare function requireTier(tier: Tier, input: TierGuardInput): TierGuardResult;

package/dist/http/auth.js

@@ -39,6 +39,11 @@ exports.bearerRequired = bearerRequired;
 exports.extractBearerToken = extractBearerToken;
 exports.tokensMatch = tokensMatch;
 exports.loadOrGenerateHttpToken = loadOrGenerateHttpToken;
+exports.loadAdminToken = loadAdminToken;
+exports.loadReadToken = loadReadToken;
+exports.loadRbacTokens = loadRbacTokens;
+exports.tierForToken = tierForToken;
+exports.requireTier = requireTier;
 /**
  * Authentication for the daemon HTTP surface (SSE-PROTOCOL.md §3).
  *
@@ -152,14 +157,9 @@ function tokensMatch(received, expected) {
     return crypto.timingSafeEqual(a, b);
 }
 /**
- * Load (or auto-generate) the daemon's HTTP bearer token.
- *
- * - When `bearerRequired` is true and the persisted config has no
- *   `httpToken`, generate one (`crypto.randomBytes(32).toString('base64url')`)
- *   and persist it via `saveConfigFile` (which sets 0600 on POSIX).
- * - When `bearerRequired` is false, return whatever is in the config
- *   without generating — operators may still want a token saved for
- *   future use, and we shouldn't write secrets the user didn't request.
+ * @deprecated 3e — superseded by {@link loadRbacTokens} (read + admin split).
+ * Kept only until every caller migrates; do NOT add new callers. Resolves the
+ * legacy single `httpToken` (env-less) for back-compat shims.
  */
 function loadOrGenerateHttpToken(opts) {
     const load = opts.load ?? config_1.loadConfigFile;
@@ -170,8 +170,92 @@ function loadOrGenerateHttpToken(opts) {
     }
     if (!opts.bearerRequired)
         return null;
-    // Auto-generate. base64url chars are safe inside Authorization values.
     const token = crypto.randomBytes(32).toString('base64url');
     save({ ...cfg, httpToken: token });
     return token;
 }
+/** Admin token — ENV-VAR-ONLY (never config.json/disk, never auto-generated). */
+function loadAdminToken(env = process.env) {
+    const t = env[config_1.ENV.HTTP_ADMIN_TOKEN];
+    return t && t.length > 0 ? t : null;
+}
+/**
+ * Read token (T1). Priority: env `AGENT_TEMPO_HTTP_READ_TOKEN` > config.json
+ * `readToken` > LEGACY config.json `httpToken` (adopted → `legacy:true`) >
+ * auto-generate when bearer mode is required (persisted as `readToken`).
+ */
+function loadReadToken(opts) {
+    const env = opts.env ?? process.env;
+    const load = opts.load ?? config_1.loadConfigFile;
+    const save = opts.save ?? config_1.saveConfigFile;
+    const envTok = env[config_1.ENV.HTTP_READ_TOKEN];
+    if (envTok && envTok.length > 0)
+        return { token: envTok, legacy: false };
+    const cfg = load();
+    if (cfg.readToken && cfg.readToken.length > 0)
+        return { token: cfg.readToken, legacy: false };
+    // LEGACY: a pre-3e single `httpToken` becomes the READ token (T1) — NOT admin.
+    if (cfg.httpToken && cfg.httpToken.length > 0)
+        return { token: cfg.httpToken, legacy: true };
+    if (!opts.bearerRequired)
+        return { token: null, legacy: false };
+    const token = crypto.randomBytes(32).toString('base64url');
+    save({ ...cfg, readToken: token });
+    return { token, legacy: false };
+}
+/** Load both RBAC tokens. The daemon calls this once at startup. */
+function loadRbacTokens(opts) {
+    const { token: readToken, legacy } = loadReadToken(opts);
+    const adminToken = loadAdminToken(opts.env);
+    return { readToken, adminToken, legacyMigrated: legacy };
+}
+/**
+ * Granted tier for a presented bearer, given the RBAC tokens (timing-safe).
+ * Admin grants the FULL ladder (3 ⊇ 2 ⊇ 1); read grants T1 only; no match → 0.
+ * There is no T2-only token — T2 and T3 are both "admin required".
+ */
+function tierForToken(presented, tokens) {
+    if (tokens.adminToken && tokensMatch(presented, tokens.adminToken))
+        return 3;
+    if (tokens.readToken && tokensMatch(presented, tokens.readToken))
+        return 1;
+    return 0;
+}
+/** Migration hint surfaced in the 403 body so a read-token holder knows what's missing. */
+const INSUFFICIENT_TIER_HINT = 'This token is read-tier. Writes, the operator gate, and the inner-tail require the admin token (set AGENT_TEMPO_HTTP_ADMIN_TOKEN).';
+const ADMIN_UNSET_HINT = 'Set AGENT_TEMPO_HTTP_ADMIN_TOKEN (env-var only) to enable writes / gate / inner-tail.';
+/**
+ * Authorization guard (3e MD-E). Assumes the shared upstream pass already settled
+ * AUTHENTICATION + CORS + the DNS-rebind/Origin defense (architect's Layer 2);
+ * this is Layer-3 authZ — it ONLY decides tier ≥ N and emits 503/403/401.
+ *
+ * Matrix (bearer mode):
+ *   - loopback (`!bearerRequired`)        → PASS all tiers (local-trust short-circuit).
+ *   - N ≥ 2 AND adminToken unset          → 503 admin-token-not-configured.
+ *   - no/invalid bearer (granted 0)       → 401 unauthorized.
+ *   - granted < N (read token on T≥2)     → 403 insufficient-tier (+ migration hint).
+ *   - granted ≥ N (admin, or read on T1)  → PASS.
+ *
+ * Keyed off the `Authorization` bearer only (no `Origin`/cookie requirement) so a
+ * headless Node client passes once its token validates. View-agnostic by design.
+ */
+function requireTier(tier, input) {
+    // Loopback trust: local clients (TUI / CLI / future Pi widget) get full access.
+    if (!bearerRequired(input.bindAddr, input.originHeader))
+        return { ok: true };
+    // A tier that needs admin is UNAVAILABLE when no admin token is configured —
+    // the honest answer is 503, regardless of what the caller presents.
+    if (tier >= 2 && input.adminToken === null) {
+        return { ok: false, status: 503, error: 'admin-token-not-configured', detail: ADMIN_UNSET_HINT };
+    }
+    const provided = extractBearerToken(input.authHeader);
+    if (!provided)
+        return { ok: false, status: 401, error: 'unauthorized' };
+    const granted = tierForToken(provided, input);
+    if (granted === 0)
+        return { ok: false, status: 401, error: 'unauthorized' };
+    if (granted < tier) {
+        return { ok: false, status: 403, error: 'insufficient-tier', detail: INSUFFICIENT_TIER_HINT };
+    }
+    return { ok: true };
+}

package/dist/http/body.d.ts

@@ -13,6 +13,9 @@ import type { IncomingMessage, ServerResponse } from 'http';
 import { type AgentType } from '../types';
 /** Hard cap on incoming JSON body size (1 MiB). */
 export declare const WRITE_BODY_MAX: number;
+/** 3c Tier-2 ingest cap (32 KiB) — the DOS backstop for `/inner/ingest`; the
+ *  source already ~2KB-truncates summaries, so real frames are far smaller. */
+export declare const INGEST_BODY_MAX: number;
 export declare const BODY_TOO_LARGE: unique symbol;
 export declare const BODY_INVALID_JSON: unique symbol;
 export type ReadJsonBodyResult = Record<string, unknown> | typeof BODY_TOO_LARGE | typeof BODY_INVALID_JSON;
@@ -26,7 +29,7 @@ export type ReadJsonBodyResult = Record<string, unknown> | typeof BODY_TOO_LARGE
  * handler ends. Explicit `req.destroy()` would race the response
  * write — left alone.
  */
-export declare function readJsonBody(req: IncomingMessage): Promise<ReadJsonBodyResult>;
+export declare function readJsonBody(req: IncomingMessage, maxBytes?: number): Promise<ReadJsonBodyResult>;
 /**
  * Pluck a string field from a parsed JSON body. Returns `undefined`
  * for absent or non-string values; with `requireNonEmpty: true`, also