@cluesmith/codev 3.3.5 → 3.3.6

package/dist/agent-farm/servers/agent-state/liveness.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Agent liveness: the one place Tower decides whether an agent's process is
+ * running (Spec 1595, SC7, Constraint 14).
+ *
+ * A sweep every `LIVENESS_SWEEP_INTERVAL_MS` takes one process snapshot through
+ * the shared `listProcessCensus()` (#1227) and walks each registered agent's
+ * process tree from its session's pid:
+ *
+ * - shellper-backed builder: shellper → launch loop → agent. Alive while some
+ *   launch loop has a child. The loop's relaunch-pause `sleep` is a child, so it
+ *   counts as alive; its `read -r` relaunch prompt is not, so a loop waiting
+ *   there reads as not alive although the loop itself still runs.
+ * - direct builder: `session.pid` is the launch loop; same child test.
+ * - shellper-backed architect: shellper → agent. Alive while the shellper has a
+ *   child.
+ * - direct architect: `session.pid` is the agent; alive while it is running.
+ * - any agent: not alive with no session, an exited session, or (architects) a
+ *   session in restart wait.
+ *
+ * A transition to not alive is published only after `NOT_ALIVE_CONFIRMATIONS`
+ * consecutive not-alive sweeps, so a transient gap never flashes `dead`. A
+ * failed snapshot (`[]`) publishes `alive: null` (unknown) for every agent, and
+ * an unrecognized process shape for its agent; neither advances nor resets the
+ * confirmation, so a not-alive observation before an unknown sweep still counts.
+ * A published not alive's `since` is the confirming sweep, up to one interval
+ * after the process went. Lifecycle reports never feed liveness.
+ *
+ * The sweep also drops the store entries of agents no longer registered (SC11)
+ * and raises `AGENT_STATE_CHANGED` whenever a published value changes. The
+ * snapshot's command lines can carry secrets, so only pid and ppid are read and
+ * nothing from it is logged.
+ */
+import { EventEmitter } from 'node:events';
+import { type ProcessCensusEntry } from '../process-census.js';
+import { type AgentStateStore } from './store.js';
+import type { WorkspaceTerminals } from '../tower-types.js';
+/** How often liveness is swept. */
+export declare const LIVENESS_SWEEP_INTERVAL_MS = 5000;
+/** Consecutive not-alive sweeps before not alive is published. */
+export declare const NOT_ALIVE_CONFIRMATIONS = 2;
+/** The session facts liveness reads (a `PtySession` satisfies it). */
+export interface LivenessSession {
+    /** The shellper's pid for a shellper-backed session, else the PTY child's. */
+    pid: number;
+    shellperBacked: boolean;
+    status: 'running' | 'exited';
+    awaitingRestart: boolean;
+}
+/** One agent registered with Tower, with its session when it has one. */
+export interface RegisteredAgent {
+    /** Normalized workspace path. */
+    workspacePath: string;
+    /** Canonical id: a builder's lowercased role id, or an architect's name. */
+    agentId: string;
+    kind: 'builder' | 'architect';
+    session: LivenessSession | undefined;
+}
+/** An agent's published liveness. */
+export interface AgentLiveness {
+    /** `null` while liveness cannot be determined. */
+    alive: boolean | null;
+    /** When `alive` took its current value (epoch ms). */
+    since: number;
+}
+export interface AgentLivenessOptions {
+    /** The registered agents, read once per sweep. */
+    agents: () => RegisteredAgent[];
+    /** The process snapshot. Defaults to `listProcessCensus`. */
+    census?: () => Promise<ProcessCensusEntry[]>;
+    /** The store whose entries follow registration. Defaults to Tower's store. */
+    store?: AgentStateStore;
+    now?: () => number;
+    log?: (message: string) => void;
+}
+export declare class AgentLivenessTracker extends EventEmitter {
+    private readonly options;
+    private readonly records;
+    private readonly census;
+    private readonly store;
+    private readonly now;
+    private timer;
+    private sweeping;
+    constructor(options: AgentLivenessOptions);
+    /** An agent's published liveness, or `undefined` when it is not registered. */
+    get(workspacePath: string, agentId: string): AgentLiveness | undefined;
+    /** Run one sweep: observe every registered agent, publish, and drop the removed. */
+    sweep(): Promise<void>;
+    /** Sweep now and then every `intervalMs`, until `stop`. */
+    start(intervalMs?: number): void;
+    stop(): void;
+    /** A timer-driven sweep: never overlaps another, never throws. */
+    private runSweep;
+    private publish;
+}
+/**
+ * The agents Tower's terminal registry holds: every builder and architect in
+ * each workspace's entry, keyed as the store keys them, with its session when
+ * the terminal manager still has one.
+ */
+export declare function registeredAgents(workspaceTerminals: Map<string, WorkspaceTerminals>, getSession: (terminalId: string) => LivenessSession | undefined, normalizeWorkspace: (workspacePath: string) => string): RegisteredAgent[];
+/** Start Tower's one liveness sweep; returns the tracker so boot can subscribe to it. */
+export declare function startAgentLiveness(options: AgentLivenessOptions): AgentLivenessTracker;
+/** Stop Tower's liveness sweep (shutdown). */
+export declare function stopAgentLiveness(): void;
+/** Tower's published liveness for an agent; `undefined` before the sweep has seen it. */
+export declare function getAgentLiveness(workspacePath: string, agentId: string): AgentLiveness | undefined;
+//# sourceMappingURL=liveness.d.ts.map

package/dist/agent-farm/servers/agent-state/liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveness.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/servers/agent-state/liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,EAA+D,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAC/G,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,mCAAmC;AACnC,eAAO,MAAM,0BAA0B,OAAQ,CAAC;AAEhD,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,OAAO,CAAC;IACxB,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC7B,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,GAAG,WAAW,CAAC;IAC9B,OAAO,EAAE,eAAe,GAAG,SAAS,CAAC;CACtC;AAED,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,kDAAkD;IAClD,MAAM,EAAE,MAAM,eAAe,EAAE,CAAC;IAChC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAC7C,8EAA8E;IAC9E,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AA8DD,qBAAa,oBAAqB,SAAQ,YAAY;IAQxC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;IAC7D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAS;gBAEI,OAAO,EAAE,oBAAoB;IAO1D,+EAA+E;IAC/E,GAAG,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAItE,oFAAoF;IAC9E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B5B,2DAA2D;IAC3D,KAAK,CAAC,UAAU,GAAE,MAAmC,GAAG,IAAI;IAO5D,IAAI,IAAI,IAAI;IAMZ,kEAAkE;IAClE,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,OAAO;CAuBhB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACnD,UAAU,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,eAAe,GAAG,SAAS,EAC/D,kBAAkB,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,MAAM,GACpD,eAAe,EAAE,CAYnB;AAID,yFAAyF;AACzF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,CAKtF;AAED,8CAA8C;AAC9C,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC;AAED,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAElG"}

package/dist/agent-farm/servers/agent-state/liveness.js

@@ -0,0 +1,224 @@
+/**
+ * Agent liveness: the one place Tower decides whether an agent's process is
+ * running (Spec 1595, SC7, Constraint 14).
+ *
+ * A sweep every `LIVENESS_SWEEP_INTERVAL_MS` takes one process snapshot through
+ * the shared `listProcessCensus()` (#1227) and walks each registered agent's
+ * process tree from its session's pid:
+ *
+ * - shellper-backed builder: shellper → launch loop → agent. Alive while some
+ *   launch loop has a child. The loop's relaunch-pause `sleep` is a child, so it
+ *   counts as alive; its `read -r` relaunch prompt is not, so a loop waiting
+ *   there reads as not alive although the loop itself still runs.
+ * - direct builder: `session.pid` is the launch loop; same child test.
+ * - shellper-backed architect: shellper → agent. Alive while the shellper has a
+ *   child.
+ * - direct architect: `session.pid` is the agent; alive while it is running.
+ * - any agent: not alive with no session, an exited session, or (architects) a
+ *   session in restart wait.
+ *
+ * A transition to not alive is published only after `NOT_ALIVE_CONFIRMATIONS`
+ * consecutive not-alive sweeps, so a transient gap never flashes `dead`. A
+ * failed snapshot (`[]`) publishes `alive: null` (unknown) for every agent, and
+ * an unrecognized process shape for its agent; neither advances nor resets the
+ * confirmation, so a not-alive observation before an unknown sweep still counts.
+ * A published not alive's `since` is the confirming sweep, up to one interval
+ * after the process went. Lifecycle reports never feed liveness.
+ *
+ * The sweep also drops the store entries of agents no longer registered (SC11)
+ * and raises `AGENT_STATE_CHANGED` whenever a published value changes. The
+ * snapshot's command lines can carry secrets, so only pid and ppid are read and
+ * nothing from it is logged.
+ */
+import { EventEmitter } from 'node:events';
+import { listProcessCensus } from '../process-census.js';
+import { AGENT_STATE_CHANGED, agentStateStore } from './store.js';
+/** How often liveness is swept. */
+export const LIVENESS_SWEEP_INTERVAL_MS = 5_000;
+/** Consecutive not-alive sweeps before not alive is published. */
+export const NOT_ALIVE_CONFIRMATIONS = 2;
+function agentKey(workspacePath, agentId) {
+    return `${workspacePath}\0${agentId}`;
+}
+function processTree(census) {
+    const running = new Set();
+    const children = new Map();
+    for (const entry of census) {
+        running.add(entry.pid);
+        const siblings = children.get(entry.ppid);
+        if (siblings === undefined) {
+            children.set(entry.ppid, [entry.pid]);
+        }
+        else {
+            siblings.push(entry.pid);
+        }
+    }
+    return { running, children };
+}
+function hasChild(tree, pid) {
+    return tree.children.has(pid);
+}
+/** Whether a launch loop at `pid` is running an agent. */
+function launchLoopRunsAgent(tree, pid) {
+    return tree.running.has(pid) && hasChild(tree, pid);
+}
+/**
+ * This sweep's observation for one agent; `null` when it cannot be told. A
+ * failed snapshot makes every observation unknown, session facts included, so a
+ * failing `ps` never advances any agent toward not alive.
+ */
+function observe(agent, tree) {
+    if (tree === null)
+        return null;
+    const session = agent.session;
+    if (session === undefined || session.status === 'exited')
+        return false;
+    if (agent.kind === 'architect' && session.awaitingRestart)
+        return false;
+    if (!Number.isInteger(session.pid) || session.pid <= 0)
+        return null;
+    if (agent.kind === 'builder') {
+        if (!session.shellperBacked)
+            return launchLoopRunsAgent(tree, session.pid);
+        const loops = tree.children.get(session.pid) ?? [];
+        return loops.some(loop => hasChild(tree, loop));
+    }
+    if (session.shellperBacked)
+        return hasChild(tree, session.pid);
+    return tree.running.has(session.pid);
+}
+export class AgentLivenessTracker extends EventEmitter {
+    options;
+    records = new Map();
+    census;
+    store;
+    now;
+    timer = null;
+    sweeping = false;
+    constructor(options) {
+        super();
+        this.options = options;
+        this.census = options.census ?? listProcessCensus;
+        this.store = options.store ?? agentStateStore;
+        this.now = options.now ?? Date.now;
+    }
+    /** An agent's published liveness, or `undefined` when it is not registered. */
+    get(workspacePath, agentId) {
+        return this.records.get(agentKey(workspacePath, agentId))?.published;
+    }
+    /** Run one sweep: observe every registered agent, publish, and drop the removed. */
+    async sweep() {
+        const agents = this.options.agents();
+        let tree = null;
+        if (agents.length > 0) {
+            const census = await this.census();
+            if (census.length > 0)
+                tree = processTree(census);
+        }
+        const registered = new Set();
+        for (const agent of agents) {
+            const key = agentKey(agent.workspacePath, agent.agentId);
+            if (registered.has(key))
+                continue;
+            registered.add(key);
+            this.publish(agent, key, observe(agent, tree));
+        }
+        for (const key of this.records.keys()) {
+            if (!registered.has(key))
+                this.records.delete(key);
+        }
+        for (const held of this.store.agents()) {
+            if (!registered.has(agentKey(held.workspacePath, held.agentId))) {
+                this.store.drop(held.workspacePath, held.agentId);
+            }
+        }
+    }
+    /** Sweep now and then every `intervalMs`, until `stop`. */
+    start(intervalMs = LIVENESS_SWEEP_INTERVAL_MS) {
+        if (this.timer !== null)
+            return;
+        this.runSweep();
+        this.timer = setInterval(() => this.runSweep(), intervalMs);
+        this.timer.unref();
+    }
+    stop() {
+        if (this.timer === null)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+    }
+    /** A timer-driven sweep: never overlaps another, never throws. */
+    runSweep() {
+        if (this.sweeping)
+            return;
+        this.sweeping = true;
+        this.sweep()
+            .catch((err) => {
+            this.options.log?.(`Agent liveness sweep failed: ${err.message}`);
+        })
+            .finally(() => {
+            this.sweeping = false;
+        });
+    }
+    publish(agent, key, observed) {
+        let record = this.records.get(key);
+        if (record === undefined) {
+            record = { published: { alive: null, since: this.now() }, notAliveSweeps: 0 };
+            this.records.set(key, record);
+        }
+        let next = record.published.alive;
+        if (observed === null) {
+            next = null;
+        }
+        else if (observed) {
+            record.notAliveSweeps = 0;
+            next = true;
+        }
+        else {
+            record.notAliveSweeps += 1;
+            if (record.notAliveSweeps >= NOT_ALIVE_CONFIRMATIONS)
+                next = false;
+        }
+        if (next === record.published.alive)
+            return;
+        record.published = { alive: next, since: this.now() };
+        const change = { workspacePath: agent.workspacePath, agentId: agent.agentId };
+        this.emit(AGENT_STATE_CHANGED, change);
+    }
+}
+/**
+ * The agents Tower's terminal registry holds: every builder and architect in
+ * each workspace's entry, keyed as the store keys them, with its session when
+ * the terminal manager still has one.
+ */
+export function registeredAgents(workspaceTerminals, getSession, normalizeWorkspace) {
+    const agents = [];
+    for (const [rawWorkspacePath, entry] of workspaceTerminals) {
+        const workspacePath = normalizeWorkspace(rawWorkspacePath);
+        for (const [roleId, terminalId] of entry.builders) {
+            agents.push({ workspacePath, agentId: roleId.toLowerCase(), kind: 'builder', session: getSession(terminalId) });
+        }
+        for (const [name, terminalId] of entry.architects) {
+            agents.push({ workspacePath, agentId: name, kind: 'architect', session: getSession(terminalId) });
+        }
+    }
+    return agents;
+}
+let towerLiveness = null;
+/** Start Tower's one liveness sweep; returns the tracker so boot can subscribe to it. */
+export function startAgentLiveness(options) {
+    towerLiveness?.stop();
+    towerLiveness = new AgentLivenessTracker(options);
+    towerLiveness.start();
+    return towerLiveness;
+}
+/** Stop Tower's liveness sweep (shutdown). */
+export function stopAgentLiveness() {
+    towerLiveness?.stop();
+    towerLiveness = null;
+}
+/** Tower's published liveness for an agent; `undefined` before the sweep has seen it. */
+export function getAgentLiveness(workspacePath, agentId) {
+    return towerLiveness?.get(workspacePath, agentId);
+}
+//# sourceMappingURL=liveness.js.map

package/dist/agent-farm/servers/agent-state/liveness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveness.js","sourceRoot":"","sources":["../../../../src/agent-farm/servers/agent-state/liveness.ts"],"names":[],"mappings":"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"}

package/dist/agent-farm/servers/agent-state/route.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `POST /api/agent-lifecycle`: the one write-only agent-state route (Spec 1595,
+ * Constraint 16).
+ *
+ * An agent's lifecycle reporter posts one `AgentLifecycleEvent` per harness hook.
+ * The route validates it strictly against the contract and its limits, resolves
+ * the launch identity to the agent Tower knows, applies it to the in-memory
+ * store, and answers an empty 204. It writes nothing else: no PTY, no mailbox,
+ * no database. There is no read route; state is served on the overview.
+ *
+ * Auth is the existing `isRequestAllowed` choke point in `handleRequest`; this
+ * route is not on the public allowlist. A rejection is a 4xx carrying only an
+ * error code. The reporter ignores every response.
+ */
+import type http from 'node:http';
+import type { AgentLaunchIdentity, AgentLifecycleEvent } from '@cluesmith/codev-types';
+import type { AgentStateStore } from './store.js';
+import type { ResolvedAgent } from './identity.js';
+/** Request body cap, in bytes. */
+export declare const MAX_LIFECYCLE_BODY_BYTES = 8192;
+export declare const MAX_PATH_LENGTH = 4096;
+export declare const MAX_NAME_LENGTH = 128;
+export declare const MAX_SESSION_ID_LENGTH = 128;
+export declare const MAX_TOOL_LENGTH = 64;
+export declare const MAX_SUMMARY_LENGTH = 200;
+export interface AgentLifecycleDeps {
+    store: AgentStateStore;
+    resolve: (identity: AgentLaunchIdentity) => ResolvedAgent | null;
+}
+/**
+ * Validate a parsed body against the `AgentLifecycleEvent` contract, or `null`.
+ * Strict: unknown keys anywhere are rejected, `needsInput` is accepted only on a
+ * `needs-input` event and `backgroundWork` only on `turn-ended`.
+ */
+export declare function parseLifecycleEvent(value: unknown): AgentLifecycleEvent | null;
+/** Handle one lifecycle report. Auth has already passed in `handleRequest`. */
+export declare function handleAgentLifecycle(req: http.IncomingMessage, res: http.ServerResponse, deps: AgentLifecycleDeps): Promise<void>;
+//# sourceMappingURL=route.d.ts.map

package/dist/agent-farm/servers/agent-state/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/servers/agent-state/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EAGpB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,kCAAkC;AAClC,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAC7C,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,eAAe,MAAM,CAAC;AACnC,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAkBtC,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,aAAa,GAAG,IAAI,CAAC;CAClE;AAmDD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,GAAG,IAAI,CAyB9E;AAOD,+EAA+E;AAC/E,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,IAAI,CAAC,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EACxB,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,IAAI,CAAC,CAwCf"}

package/dist/agent-farm/servers/agent-state/route.js

@@ -0,0 +1,170 @@
+/**
+ * `POST /api/agent-lifecycle`: the one write-only agent-state route (Spec 1595,
+ * Constraint 16).
+ *
+ * An agent's lifecycle reporter posts one `AgentLifecycleEvent` per harness hook.
+ * The route validates it strictly against the contract and its limits, resolves
+ * the launch identity to the agent Tower knows, applies it to the in-memory
+ * store, and answers an empty 204. It writes nothing else: no PTY, no mailbox,
+ * no database. There is no read route; state is served on the overview.
+ *
+ * Auth is the existing `isRequestAllowed` choke point in `handleRequest`; this
+ * route is not on the public allowlist. A rejection is a 4xx carrying only an
+ * error code. The reporter ignores every response.
+ */
+import { isAbsolute } from 'node:path';
+import { readBody } from '../../utils/server-utils.js';
+/** Request body cap, in bytes. */
+export const MAX_LIFECYCLE_BODY_BYTES = 8192;
+export const MAX_PATH_LENGTH = 4096;
+export const MAX_NAME_LENGTH = 128;
+export const MAX_SESSION_ID_LENGTH = 128;
+export const MAX_TOOL_LENGTH = 64;
+export const MAX_SUMMARY_LENGTH = 200;
+const EVENT_NAMES = new Set([
+    'session-started',
+    'turn-started',
+    'tool-activity',
+    'needs-input',
+    'turn-ended',
+]);
+const NEEDS_INPUT_KINDS = new Set(['permission', 'question', 'other']);
+const EVENT_KEYS = new Set(['agent', 'sessionId', 'event', 'at', 'needsInput', 'backgroundWork']);
+const BUILDER_KEYS = new Set(['kind', 'worktreePath']);
+const ARCHITECT_KEYS = new Set(['kind', 'workspacePath', 'name']);
+const DETAIL_KEYS = new Set(['kind', 'tool', 'summary']);
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasOnlyKeys(value, allowed) {
+    return Object.keys(value).every(key => allowed.has(key));
+}
+function isBoundedString(value, maxLength) {
+    return typeof value === 'string' && value.length > 0 && value.length <= maxLength;
+}
+function isPlainText(value, maxLength) {
+    return isBoundedString(value, maxLength) && !CONTROL_CHARACTERS.test(value);
+}
+function isAbsolutePath(value) {
+    return isPlainText(value, MAX_PATH_LENGTH) && isAbsolute(value);
+}
+function parseIdentity(value) {
+    if (!isRecord(value))
+        return null;
+    if (value.kind === 'builder') {
+        if (!hasOnlyKeys(value, BUILDER_KEYS) || !isAbsolutePath(value.worktreePath))
+            return null;
+        return { kind: 'builder', worktreePath: value.worktreePath };
+    }
+    if (value.kind === 'architect') {
+        if (!hasOnlyKeys(value, ARCHITECT_KEYS) || !isAbsolutePath(value.workspacePath))
+            return null;
+        if (!isPlainText(value.name, MAX_NAME_LENGTH))
+            return null;
+        return { kind: 'architect', workspacePath: value.workspacePath, name: value.name };
+    }
+    return null;
+}
+function parseDetail(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, DETAIL_KEYS))
+        return null;
+    if (typeof value.kind !== 'string' || !NEEDS_INPUT_KINDS.has(value.kind))
+        return null;
+    const detail = { kind: value.kind };
+    if (value.tool !== undefined) {
+        if (!isPlainText(value.tool, MAX_TOOL_LENGTH))
+            return null;
+        detail.tool = value.tool;
+    }
+    if (value.summary !== undefined) {
+        if (!isPlainText(value.summary, MAX_SUMMARY_LENGTH))
+            return null;
+        detail.summary = value.summary;
+    }
+    return detail;
+}
+/**
+ * Validate a parsed body against the `AgentLifecycleEvent` contract, or `null`.
+ * Strict: unknown keys anywhere are rejected, `needsInput` is accepted only on a
+ * `needs-input` event and `backgroundWork` only on `turn-ended`.
+ */
+export function parseLifecycleEvent(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, EVENT_KEYS))
+        return null;
+    const agent = parseIdentity(value.agent);
+    if (agent === null)
+        return null;
+    if (!isPlainText(value.sessionId, MAX_SESSION_ID_LENGTH))
+        return null;
+    if (typeof value.event !== 'string' || !EVENT_NAMES.has(value.event))
+        return null;
+    if (typeof value.at !== 'number' || !Number.isFinite(value.at) || value.at <= 0)
+        return null;
+    const event = {
+        agent,
+        sessionId: value.sessionId,
+        event: value.event,
+        at: value.at,
+    };
+    if (value.needsInput !== undefined) {
+        if (event.event !== 'needs-input')
+            return null;
+        const detail = parseDetail(value.needsInput);
+        if (detail === null)
+            return null;
+        event.needsInput = detail;
+    }
+    if (value.backgroundWork !== undefined) {
+        if (event.event !== 'turn-ended' || typeof value.backgroundWork !== 'boolean')
+            return null;
+        event.backgroundWork = value.backgroundWork;
+    }
+    return event;
+}
+function reject(res, status, code) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: code }));
+}
+/** Handle one lifecycle report. Auth has already passed in `handleRequest`. */
+export async function handleAgentLifecycle(req, res, deps) {
+    let raw;
+    try {
+        raw = await readBody(req, MAX_LIFECYCLE_BODY_BYTES);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message === 'Request body too large') {
+            reject(res, 413, 'BODY_TOO_LARGE');
+        }
+        else {
+            reject(res, 400, 'UNREADABLE_BODY');
+        }
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        reject(res, 400, 'INVALID_JSON');
+        return;
+    }
+    const event = parseLifecycleEvent(parsed);
+    if (event === null) {
+        reject(res, 400, 'INVALID_EVENT');
+        return;
+    }
+    const agent = deps.resolve(event.agent);
+    if (agent === null) {
+        reject(res, 404, 'UNKNOWN_AGENT');
+        return;
+    }
+    if (deps.store.apply(agent.workspacePath, agent.agentId, event) === 'future') {
+        reject(res, 400, 'AT_IN_FUTURE');
+        return;
+    }
+    res.writeHead(204);
+    res.end();
+}
+//# sourceMappingURL=route.js.map

package/dist/agent-farm/servers/agent-state/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../../../src/agent-farm/servers/agent-state/route.ts"],"names":[],"mappings":"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"}

package/dist/agent-farm/servers/agent-state/serve.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Serve an agent's attention state on the overview (Spec 1595).
+ *
+ * Gathers Tower's facts about one agent (porch's `blocked`, the caller already
+ * holds; the published liveness; the stored reported activity) and hands them to
+ * the one projection policy in codev-core. Called per request: nothing here is
+ * cached, so a served row is never older than the store and the liveness sweep.
+ */
+import type { ServedAgentState } from '@cluesmith/codev-types';
+import { type AgentStateStore } from './store.js';
+import { type AgentLiveness } from './liveness.js';
+/** The porch facts the overview already computed for the agent. */
+export interface AgentPorchFacts {
+    /** Whether porch reports a requested, pending gate (`detectBlocked` is non-null). */
+    blocked: boolean;
+    blockedSince: string | null;
+    /** The builder's display phase; `''` for an architect. */
+    phase: string;
+}
+export interface ServeAgentStateOptions {
+    store?: AgentStateStore;
+    liveness?: (workspacePath: string, agentId: string) => AgentLiveness | undefined;
+    now?: () => number;
+}
+/**
+ * The served state for the agent `(workspacePath, agentId)`, keyed as the store
+ * and liveness key it: the normalized workspace path and the canonical agent id
+ * (a builder's lowercased role id, an architect's name). `null` when unknown.
+ */
+export declare function serveAgentState(workspacePath: string, agentId: string, porch: AgentPorchFacts, options?: ServeAgentStateOptions): ServedAgentState | null;
+//# sourceMappingURL=serve.d.ts.map

package/dist/agent-farm/servers/agent-state/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../../../src/agent-farm/servers/agent-state/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAM/D,OAAO,EAAmB,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAErE,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,qFAAqF;IACrF,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,QAAQ,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAC;IACjF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAoBD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,sBAA2B,GACnC,gBAAgB,GAAG,IAAI,CAYzB"}

package/dist/agent-farm/servers/agent-state/serve.js

@@ -0,0 +1,49 @@
+/**
+ * Serve an agent's attention state on the overview (Spec 1595).
+ *
+ * Gathers Tower's facts about one agent (porch's `blocked`, the caller already
+ * holds; the published liveness; the stored reported activity) and hands them to
+ * the one projection policy in codev-core. Called per request: nothing here is
+ * cached, so a served row is never older than the store and the liveness sweep.
+ */
+import { projectAgentState, } from '@cluesmith/codev-core/agent-state';
+import { agentStateStore } from './store.js';
+import { getAgentLiveness } from './liveness.js';
+function livenessFact(liveness) {
+    if (liveness === undefined)
+        return null;
+    return { alive: liveness.alive, since: new Date(liveness.since).toISOString() };
+}
+function reportedFact(store, workspacePath, agentId) {
+    const stored = store.get(workspacePath, agentId);
+    if (stored === undefined)
+        return null;
+    const fact = {
+        activity: stored.activity,
+        since: new Date(stored.activitySince).toISOString(),
+        at: new Date(stored.reportedAt).toISOString(),
+        backgroundWork: stored.backgroundWork,
+    };
+    if (stored.needsInput !== undefined)
+        fact.needsInput = stored.needsInput;
+    return fact;
+}
+/**
+ * The served state for the agent `(workspacePath, agentId)`, keyed as the store
+ * and liveness key it: the normalized workspace path and the canonical agent id
+ * (a builder's lowercased role id, an architect's name). `null` when unknown.
+ */
+export function serveAgentState(workspacePath, agentId, porch, options = {}) {
+    const store = options.store ?? agentStateStore;
+    const liveness = options.liveness ?? getAgentLiveness;
+    const now = options.now ?? Date.now;
+    return projectAgentState({
+        blocked: porch.blocked,
+        blockedSince: porch.blockedSince,
+        phase: porch.phase,
+        liveness: livenessFact(liveness(workspacePath, agentId)),
+        reported: reportedFact(store, workspacePath, agentId),
+        now: new Date(now()).toISOString(),
+    });
+}
+//# sourceMappingURL=serve.js.map