@sigrun/memory-honcho 0.0.0-stage → 0.1.1

package/dist/index.js

@@ -0,0 +1,345 @@
+/**
+ * @sigrun/memory-honcho: the public surface.
+ *
+ * The DEFAULT export is the factory the sigrun extension loader calls.
+ * ARITY IS THE CONTRACT: the loader passes the host only when
+ * `factory.length > 0`, and a defaulted FIRST parameter would consume the
+ * host as a real dependency — so the host is declared bare and the test
+ * seam (`deps`) is the defaulted SECOND parameter, keeping `length === 1`.
+ *
+ * The factory composes Tasks 1-4: per-event it resolves settings and the
+ * API key LIVE (a key written after boot applies at the next event), gates
+ * capture on the conversation's extension selection (POSITIVE verdicts
+ * memoized per conversation — a cached `false` is re-read on the next
+ * event, so a mid-conversation opt-in captures; a mid-conversation
+ * array-form opt-out keeps capturing until restart, the accepted residual
+ * the README documents), appends the outbox record ALWAYS (a missing key
+ * skips only the kick; the sweeper delivers later), and kicks
+ * fire-and-forget delivery. The engine is constructed lazily on first use.
+ *
+ * Task 8's wiring: both prompt sections render from the representation
+ * cache (`renderMemorySection`, sync reads only); the delivery engine's
+ * `onDelivered` is the LEADING-EDGE injection point — a delivered
+ * conversation with NO cache file refreshes once; and the idle/archived
+ * worker re-refreshes from the ledger's owner.
+ */
+import { AgentDoc, defineExtension, section } from "@earendil-works/pi-durable";
+import { buildCaptureBatch } from "./capture.js";
+import { resolveApiKey, resolveSettings, } from "./config.js";
+import { DeliveryEngine } from "./delivery.js";
+import { HonchoClient } from "./honcho.js";
+import { refreshRepresentation, renderMemorySection } from "./representations.js";
+import { createStatusHandler } from "./status.js";
+import { ExtensionStores } from "./stores.js";
+import { createSweepTask, SWEEP_TASK_NAME } from "./sweep.js";
+import { createTools } from "./tools.js";
+/** This extension's registry name AND its selection-gate sentinel. */
+const EXTENSION_NAME = "@sigrun/memory-honcho";
+/** The shutdown drain deadline (spec: 25s under the host's shutdown budget). */
+const DRAIN_DEADLINE_MS = 25_000;
+/** The missing-API-key notice fires once per process, not per event. */
+let missingKeyWarned = false;
+function warnMissingKeyOnce() {
+    if (missingKeyWarned)
+        return;
+    missingKeyWarned = true;
+    console.warn("memory-honcho: no API key (secrets 'api-key' or SIGRUN_EXT_MEMORY_HONCHO_API_KEY) — capturing to the outbox without delivery");
+}
+/**
+ * Structural equality over the resolved settings (an engine rebuild is
+ * warranted only when an actual value changed, not on a fresh object).
+ */
+function settingsEqual(a, b) {
+    return (a.agentPeerId === b.agentPeerId &&
+        a.baseUrl === b.baseUrl &&
+        a.workspaceId === b.workspaceId &&
+        a.contextTokens === b.contextTokens &&
+        a.maxMessageLength === b.maxMessageLength &&
+        a.searchLimit === b.searchLimit &&
+        a.toolPreviewLength === b.toolPreviewLength &&
+        a.representationTtlMs === b.representationTtlMs &&
+        a.outboxRetentionDays === b.outboxRetentionDays &&
+        a.deliveredBatchWindow === b.deliveredBatchWindow &&
+        a.anchorWindow === b.anchorWindow);
+}
+export function createHonchoMemory(host, deps = {}) {
+    const settingsStore = host.stores.settings;
+    const secretsStore = host.stores.secrets;
+    const paths = host.stores.paths;
+    // Lazily constructed on first use — settings/key are resolved at that
+    // moment, so configuration written after boot still applies.
+    let storesPromise;
+    // The sync-readable slot behind `storesPromise` (promise .then callbacks
+    // are microtasks, NEVER synchronous, so the prompt sections — sync by
+    // contract — cannot inspect the promise; they read this slot instead).
+    let resolvedStores;
+    let enginePromise;
+    // The configuration the cached engine was built with: it is reused ONLY
+    // while both are unchanged (stored wins without restart — the key can
+    // arrive after boot).
+    let engineKey;
+    let engineSettings;
+    // The client the cached engine was built with. Session marks live on
+    // THIS instance (establishment marks its ConversationClients), so the
+    // worker's refresh gate (`hasSession`) is only meaningful through it —
+    // a per-run fresh client would always gate false and the idle-wake
+    // refresh would never fire (Task-8 review finding 2).
+    let engineClient;
+    function makeClient(settings, apiKey) {
+        return (deps.createClient ?? ((s, key) => new HonchoClient(s, key)))(settings, apiKey);
+    }
+    function stores() {
+        storesPromise ??= resolveSettings(settingsStore).then((settings) => {
+            resolvedStores = new ExtensionStores(paths, settings);
+            return resolvedStores;
+        });
+        return storesPromise;
+    }
+    /**
+     * The prompt-section posture: render ONLY once the stores are
+     * constructed — the reads are sync, so a section must never block
+     * prompt assembly on the settings read behind the stores' lazy
+     * construction. Before the first event (or from a section render
+     * racing it), there is nothing to render.
+     */
+    function renderMemorySectionSync(conversationId) {
+        if (resolvedStores === undefined)
+            return undefined;
+        return renderMemorySection(resolvedStores, conversationId, Date.now());
+    }
+    async function engine() {
+        // Resolve FIRST, cache-compare second: a key/settings change rebuilds.
+        const settings = await resolveSettings(settingsStore);
+        const apiKey = await resolveApiKey(secretsStore);
+        if (enginePromise !== undefined &&
+            apiKey === engineKey &&
+            engineSettings !== undefined &&
+            settingsEqual(settings, engineSettings)) {
+            return enginePromise;
+        }
+        const building = (async () => {
+            const client = makeClient(settings, apiKey);
+            engineClient = client;
+            // The leading-edge hook: a delivered conversation whose
+            // representation cache is ABSENT refreshes once (a present cache
+            // is fresh enough — the idle worker owns re-refreshes). The
+            // delivery engine calls the hook OUT of the conversation chain,
+            // so this refresh chains behind the delivery that just settled
+            // (never a circular wait). Failures log and are swallowed: a
+            // failed refresh must never fault the delivery it rode in on.
+            const hooks = {
+                onDelivered: async (conversationId) => {
+                    const store = await stores();
+                    if (store.readRepresentationSync(conversationId) !== undefined)
+                        return;
+                    const ledger = store.readLedgerSync(conversationId);
+                    if (ledger === undefined)
+                        return;
+                    try {
+                        await refreshRepresentation(client, store, settings, conversationId, ledger.ownerAtFirstCapture);
+                    }
+                    catch (error) {
+                        console.error(`memory-honcho: leading-edge representation refresh failed for conversation ${conversationId}`, error);
+                    }
+                },
+            };
+            return (deps.createEngine ?? ((c, st, s, h) => new DeliveryEngine(c, st, s, h)))(client, await stores(), settings, hooks);
+        })();
+        enginePromise = building;
+        engineKey = apiKey;
+        engineSettings = settings;
+        // A rejected build is never memoized (identity-guarded, same class as
+        // the Task-2 peer memo): the next event retries the construction.
+        building.catch(() => {
+            if (enginePromise === building) {
+                enginePromise = undefined;
+                engineKey = undefined;
+                engineSettings = undefined;
+                engineClient = undefined;
+            }
+        });
+        return building;
+    }
+    // Per-conversation selection memo: POSITIVE verdicts only (a `configure`
+    // or owner transfer can rewrite the selection mid-conversation). A cached
+    // `false` is never trusted — the AgentDoc is re-read on the next event, so
+    // a later opt-in captures; the residual (an array-form opt-out AFTER a
+    // positive verdict keeps capturing until restart) is the accepted v1
+    // semantics, documented in the README.
+    const selectionMemo = new Map();
+    async function isSelected(conversationId, api, context) {
+        const memoized = selectionMemo.get(conversationId);
+        if (memoized !== undefined)
+            return memoized;
+        const agent = await api.document(AgentDoc, 
+        // SAFETY: the seam's event carries plain numbers; branded ids are
+        // structurally identical (src/types.ts), so the value the host
+        // passes satisfies both spellings.
+        conversationId, context);
+        // Array form selects exactly its members; the object form edits the
+        // host default (a `remove` of us is a no-op — we are not host-default).
+        const selected = !Array.isArray(agent?.extensions) ||
+            agent.extensions.includes(EXTENSION_NAME);
+        if (selected)
+            selectionMemo.set(conversationId, true);
+        return selected;
+    }
+    const workerStatus = new Map([
+        ["honcho-representations", { runs: 0 }],
+    ]);
+    // The tools need the engine, which is lazy. The extension's tools array
+    // is static, so the tools are built once (eagerly) with a lazy engine
+    // accessor: each tool's execute closure awaits the engine before its
+    // first Honcho call.
+    const tools = createTools({
+        host,
+        client: () => engineClient,
+        engine: () => engine(),
+        settings: () => engineSettings,
+    });
+    return {
+        extension: defineExtension({
+            name: EXTENSION_NAME,
+            tools,
+            sections: [
+                // Both sections render the same cache snapshot.
+                section("long-term-memory", (input) => renderMemorySectionSync(Number(input.conversationId))),
+                section("honcho-memory", (input) => renderMemorySectionSync(Number(input.conversationId))),
+            ],
+            tasks: [
+                // The outbox sweeper (fired by the outbox-sweep cron job below).
+                createSweepTask({ engine, stores, settings: () => resolveSettings(settingsStore) }),
+            ],
+        }),
+        workerStatus,
+        async runSettled(event, api, context) {
+            const settings = await resolveSettings(settingsStore);
+            const owner = event.owner ?? "user";
+            const record = buildCaptureBatch(event, owner, settings.maxMessageLength);
+            if (record === undefined)
+                return;
+            if (!(await isSelected(event.conversationId, api, context)))
+                return;
+            // Append ALWAYS — under the outbox mutex so the sweeper's rewrite
+            // never loses a concurrent capture (Task 7's posture).
+            const store = await stores();
+            await store.withOutbox(() => store.appendOutboxRecord(record));
+            // A missing key skips ONLY the kick: the sweeper delivers later.
+            const apiKey = await resolveApiKey(secretsStore);
+            if (apiKey === undefined) {
+                warnMissingKeyOnce();
+                return;
+            }
+            (await engine()).kick(event.conversationId, owner);
+        },
+        async conversationForked(event) {
+            // The fork ANCHOR is all this handler writes; the clone itself
+            // happens on the child's first delivery (zero network here).
+            const store = await stores();
+            await store.writePendingFork({
+                childId: event.childId,
+                parentId: event.parentId,
+                at: event.at,
+                createdAt: Date.now(),
+            });
+        },
+        async harnessShutdown() {
+            const settings = await resolveSettings(settingsStore);
+            const apiKey = await resolveApiKey(secretsStore);
+            await makeClient(settings, apiKey).drainAll(DRAIN_DEADLINE_MS);
+        },
+        workers: [
+            {
+                name: "honcho-representations",
+                wakeOn: ["conversationIdle", "conversationArchived"],
+                async run(_context, wake) {
+                    const status = workerStatus.get("honcho-representations");
+                    if (status !== undefined) {
+                        status.runs += 1;
+                        status.startedAt = Date.now();
+                    }
+                    try {
+                        // The wake carries the conversation to re-refresh; the
+                        // owner comes from the ledger (the same record the
+                        // render gates on, so a ledger-less conversation is a
+                        // bookkeeping-only no-op). The engine resolution keeps
+                        // client/stores warm and honors the live-settings seam;
+                        // a custom `createEngine` (tests) skips the refresh.
+                        if (wake !== undefined) {
+                            const resolvedEngine = await engine();
+                            if (resolvedEngine instanceof DeliveryEngine &&
+                                engineSettings !== undefined) {
+                                const store = await stores();
+                                // SAFETY: the host's WorkerWake carries a branded
+                                // ConversationId; branded ids are plain numbers (see
+                                // src/types.ts), so Number() is the honest unwrapping.
+                                const conversationId = Number(wake.conversationId);
+                                const ledger = store.readLedgerSync(conversationId);
+                                if (ledger !== undefined) {
+                                    // Refresh through the ENGINE's client: session
+                                    // marks live there (a fresh client would always
+                                    // gate false). A conversation without an
+                                    // established session (never delivered — e.g.
+                                    // idle before the first capture) has nothing to
+                                    // snapshot; skip quietly. `engineClient` is set
+                                    // alongside the engine the `instanceof` check
+                                    // just confirmed.
+                                    if (engineClient === undefined)
+                                        return;
+                                    const conversation = engineClient.for(String(conversationId));
+                                    if (conversation.hasSession()) {
+                                        await refreshRepresentation(engineClient, store, engineSettings, conversationId, ledger.ownerAtFirstCapture);
+                                    }
+                                }
+                            }
+                        }
+                        if (status !== undefined)
+                            status.endedAt = Date.now();
+                    }
+                    catch (error) {
+                        if (status !== undefined) {
+                            const message = error instanceof Error ? error.message : String(error);
+                            // Bounded: the status route projects this verbatim and a
+                            // runaway error string must not blow up the body.
+                            status.lastError = message.slice(0, 500);
+                            status.endedAt = Date.now();
+                        }
+                        throw error;
+                    }
+                },
+            },
+        ],
+        jobs: [
+            {
+                name: "outbox-sweep",
+                schedule: { cron: "*/15 * * * *" },
+                action: { kind: "task", task: SWEEP_TASK_NAME },
+            },
+        ],
+        routes: [
+            {
+                method: "GET",
+                path: "status",
+                auth: "user",
+                // Display-only observability over the on-disk state. The deps
+                // resolve LIVE per request (settings/key/stores written after
+                // boot apply at the next read); the worker bookkeeping is the
+                // factory-closure map this result also exposes as
+                // `workerStatus`. No key material crosses the body —
+                // buildStatus projects the key to the `configured` boolean.
+                handler: createStatusHandler({
+                    settings: () => resolveSettings(settingsStore),
+                    apiKey: () => resolveApiKey(secretsStore),
+                    stores,
+                    workerStatus,
+                    workerName: "honcho-representations",
+                }),
+            },
+        ],
+        userDeleted(event) {
+            // Departure notice only — no data movement (Task 11 pins it).
+            console.info(`memory-honcho: user "${event.user}" deleted (resources transferred to "${event.transferTo}")`);
+        },
+    };
+}
+export default createHonchoMemory;

package/dist/representations.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The representation cache and the prompt sections that render it.
+ *
+ * `refreshRepresentation` is the WRITER: inside the conversation's
+ * serialization chain it asks the established Honcho session for its
+ * curated context (summary + the user peer's representation, as seen by
+ * the agent peer) and writes the snapshot to
+ * `cache/representations/<conversationId>.json` — the SDK's
+ * `peerRepresentation` / `summary.content` fields normalized into the
+ * cache's `userProfile` / `projectSummary` names.
+ *
+ * `renderMemorySection` is the READER: SYNCHRONOUS (the prompt-section
+ * render posture), reading the ledger and cache straight off disk. A
+ * conversation with no ledger (never captured) renders nothing; a
+ * ledgered conversation with no cache file yet (refresh still pending)
+ * renders nothing; a stale-beyond-TTL cache renders its LAST snapshot
+ * anyway (last-good — only ABSENT renders nothing). A snapshot with both
+ * parts null renders nothing.
+ */
+import type { HonchoSettings } from "./config.js";
+import type { HonchoClient } from "./honcho.js";
+import type { ExtensionStores } from "./stores.js";
+/**
+ * Refresh the conversation's cached representation snapshot.
+ *
+ * Runs INSIDE the conversation's chain (`client.for(id).chain`), so the
+ * `context()` call is serialized with delivery and establishment (the
+ * spec's one-chain-per-conversation rule). The owner resolves the user
+ * peer whose representation is fetched; callers pass the ledger's
+ * `ownerAtFirstCapture`.
+ */
+export declare function refreshRepresentation(client: HonchoClient, stores: ExtensionStores, settings: HonchoSettings, conversationId: number, owner: string): Promise<void>;
+/**
+ * Render the `[Persistent memory]` prompt section for a conversation.
+ *
+ * Sync reads only (see the module comment). `now` is the caller's clock,
+ * kept as a parameter so staleness is decided against an explicit
+ * instant; the current posture renders the last snapshot regardless of
+ * age (last-good), so `now` is reserved for the TTL comparison and does
+ * not gate output.
+ */
+export declare function renderMemorySection(stores: ExtensionStores, conversationId: number, now: number): string | undefined;

package/dist/representations.js

@@ -0,0 +1,81 @@
+/**
+ * The representation cache and the prompt sections that render it.
+ *
+ * `refreshRepresentation` is the WRITER: inside the conversation's
+ * serialization chain it asks the established Honcho session for its
+ * curated context (summary + the user peer's representation, as seen by
+ * the agent peer) and writes the snapshot to
+ * `cache/representations/<conversationId>.json` — the SDK's
+ * `peerRepresentation` / `summary.content` fields normalized into the
+ * cache's `userProfile` / `projectSummary` names.
+ *
+ * `renderMemorySection` is the READER: SYNCHRONOUS (the prompt-section
+ * render posture), reading the ledger and cache straight off disk. A
+ * conversation with no ledger (never captured) renders nothing; a
+ * ledgered conversation with no cache file yet (refresh still pending)
+ * renders nothing; a stale-beyond-TTL cache renders its LAST snapshot
+ * anyway (last-good — only ABSENT renders nothing). A snapshot with both
+ * parts null renders nothing.
+ */
+const SECTION_HEADER = "[Persistent memory]";
+/**
+ * Refresh the conversation's cached representation snapshot.
+ *
+ * Runs INSIDE the conversation's chain (`client.for(id).chain`), so the
+ * `context()` call is serialized with delivery and establishment (the
+ * spec's one-chain-per-conversation rule). The owner resolves the user
+ * peer whose representation is fetched; callers pass the ledger's
+ * `ownerAtFirstCapture`.
+ */
+export async function refreshRepresentation(client, stores, settings, conversationId, owner) {
+    await client.for(String(conversationId)).chain(async () => {
+        const conversation = client.for(String(conversationId));
+        const session = await conversation.established();
+        // Peer OBJECTS, exactly as Task 2's accessors return them — the SDK
+        // accepts `string | Peer` here, and the peers resolve inside the
+        // chain so a transient peer failure cannot stick.
+        const [agentPeer, userPeer] = await Promise.all([
+            client.agentPeer(),
+            client.userPeerFor(owner),
+        ]);
+        const context = await session.context({
+            summary: true,
+            peerPerspective: agentPeer,
+            peerTarget: userPeer,
+            tokens: settings.contextTokens,
+        });
+        const snapshot = {
+            userProfile: context.peerRepresentation ?? null,
+            projectSummary: context.summary?.content ?? null,
+            fetchedAt: Date.now(),
+        };
+        await stores.writeRepresentation(conversationId, snapshot);
+    });
+}
+/**
+ * Render the `[Persistent memory]` prompt section for a conversation.
+ *
+ * Sync reads only (see the module comment). `now` is the caller's clock,
+ * kept as a parameter so staleness is decided against an explicit
+ * instant; the current posture renders the last snapshot regardless of
+ * age (last-good), so `now` is reserved for the TTL comparison and does
+ * not gate output.
+ */
+export function renderMemorySection(stores, conversationId, now) {
+    if (stores.readLedgerSync(conversationId) === undefined)
+        return undefined;
+    const snapshot = stores.readRepresentationSync(conversationId);
+    if (snapshot === undefined)
+        return undefined;
+    void now; // staleness never suppresses: the last snapshot is last-good.
+    const parts = [SECTION_HEADER];
+    if (snapshot.userProfile !== null) {
+        parts.push(`User profile:\n${snapshot.userProfile}`);
+    }
+    if (snapshot.projectSummary !== null) {
+        parts.push(`Project summary:\n${snapshot.projectSummary}`);
+    }
+    if (parts.length === 1)
+        return undefined;
+    return parts.join("\n");
+}

package/dist/status.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The `GET /v1/ext/memory-honcho/status` route (auth: user).
+ *
+ * A display-only observability projection over the extension's on-disk
+ * state: the outbox backlog, the newest delivery timestamp, ledger/session
+ * and pending-fork counts, the live settings' identity fields, whether an
+ * API key resolves, and the representation worker's last-run bookkeeping.
+ *
+ * Two hard rules from the spec:
+ *
+ * - NO key material ever crosses the response body — `configured` is the
+ *   boolean projection of the key resolution, and the key string is
+ *   discarded immediately (the tests assert the fake key's absence from
+ *   the serialized response).
+ * - The read is a best-effort snapshot: the outbox read outside `withOutbox`
+ *   is explicitly a display-only read (the stores' own posture), and every
+ *   count comes from fresh disk reads — never from cached state.
+ */
+import type { ExtensionStores } from "./stores.js";
+import type { HonchoSettings } from "./config.js";
+import type { WorkerRunStatus } from "./types.js";
+/** Alias for the shared worker bookkeeping (the one declaration lives in types.ts). */
+export type { WorkerRunStatus as StatusWorkerRun } from "./types.js";
+/** The status response body (the spec's exact field set). */
+export interface HonchoStatus {
+    readonly configured: boolean;
+    readonly workspaceId: string;
+    readonly agentPeerId: string;
+    readonly baseUrl?: string;
+    /** The newest delivered outbox record's `createdAt`; `null` before the first delivery. */
+    readonly lastDeliveryAt: number | null;
+    /** Outbox records still awaiting delivery. */
+    readonly pendingOutbox: number;
+    /** Per-conversation ledger count. */
+    readonly ledgers: number;
+    /** Pending-fork records with no `resolvedAt` stamp. */
+    readonly pendingForks: number;
+    /** Ledgers with an established Honcho session (clone-duplicate visibility). */
+    readonly sessions: number;
+    readonly worker: {
+        readonly lastRunAt?: number;
+        readonly lastError?: string;
+    };
+}
+/** Everything the route needs, resolved live per request (settings/key written after boot apply at the next read). */
+export interface StatusDeps {
+    readonly settings: () => Promise<HonchoSettings>;
+    readonly apiKey: () => Promise<string | undefined>;
+    readonly stores: () => Promise<ExtensionStores>;
+    /** The factory's worker bookkeeping map (Task 5/8's `workerStatus`). */
+    readonly workerStatus: ReadonlyMap<string, WorkerRunStatus>;
+    /** The bookkeeping map key of the representation worker. */
+    readonly workerName: string;
+}
+export declare function buildStatus(deps: StatusDeps): Promise<HonchoStatus>;
+/** Build the web-standard route handler from live-resolving deps. */
+export declare function createStatusHandler(deps: StatusDeps): (request: Request) => Promise<Response>;

package/dist/status.js

@@ -0,0 +1,89 @@
+/**
+ * The `GET /v1/ext/memory-honcho/status` route (auth: user).
+ *
+ * A display-only observability projection over the extension's on-disk
+ * state: the outbox backlog, the newest delivery timestamp, ledger/session
+ * and pending-fork counts, the live settings' identity fields, whether an
+ * API key resolves, and the representation worker's last-run bookkeeping.
+ *
+ * Two hard rules from the spec:
+ *
+ * - NO key material ever crosses the response body — `configured` is the
+ *   boolean projection of the key resolution, and the key string is
+ *   discarded immediately (the tests assert the fake key's absence from
+ *   the serialized response).
+ * - The read is a best-effort snapshot: the outbox read outside `withOutbox`
+ *   is explicitly a display-only read (the stores' own posture), and every
+ *   count comes from fresh disk reads — never from cached state.
+ */
+/** `lastError` is display-only and bounded — a huge error string must not blow up the status body. */
+const LAST_ERROR_MAX = 500;
+export async function buildStatus(deps) {
+    const [settings, apiKey, stores] = await Promise.all([
+        deps.settings(),
+        deps.apiKey(),
+        deps.stores(),
+    ]);
+    // Best-effort snapshot: a corrupt file degrades that bucket's counts to
+    // zero rather than 500ing the route (display-only observability).
+    const safe = (read) => read.catch(() => []);
+    const [outbox, ledgers, forks, marker] = await Promise.all([
+        safe(stores.readOutbox()),
+        safe(stores.readLedgers()),
+        safe(stores.readPendingForks()),
+        stores.readLastDelivery().catch(() => undefined),
+    ]);
+    let lastDeliveryAt = null;
+    let pendingOutbox = 0;
+    for (const record of outbox) {
+        if (record.status === "delivered") {
+            if (lastDeliveryAt === null || record.createdAt > lastDeliveryAt) {
+                lastDeliveryAt = record.createdAt;
+            }
+        }
+        else {
+            pendingOutbox += 1;
+        }
+    }
+    // The marker wins when present: the sweeper drops delivered records
+    // every 15 minutes, so the retained-records derivation dies with them.
+    // The derivation is the fallback for an install that delivered before
+    // the marker existed.
+    if (marker !== undefined) {
+        lastDeliveryAt =
+            lastDeliveryAt === null
+                ? marker.at
+                : Math.max(lastDeliveryAt, marker.at);
+    }
+    const run = deps.workerStatus.get(deps.workerName);
+    // `endedAt` is the last COMPLETED run; a still-running worker's most
+    // recent activity is its `startedAt`.
+    const lastRunAt = run === undefined ? undefined : (run.endedAt ?? run.startedAt);
+    const lastError = run?.lastError === undefined
+        ? undefined
+        : run.lastError.slice(0, LAST_ERROR_MAX);
+    const worker = {
+        ...(lastRunAt !== undefined ? { lastRunAt } : {}),
+        ...(lastError !== undefined ? { lastError } : {}),
+    };
+    // The key string is discarded the instant the boolean is taken — it can
+    // never reach the body.
+    const configured = apiKey !== undefined;
+    return {
+        configured,
+        workspaceId: settings.workspaceId,
+        agentPeerId: settings.agentPeerId,
+        ...(settings.baseUrl !== undefined ? { baseUrl: settings.baseUrl } : {}),
+        lastDeliveryAt,
+        pendingOutbox,
+        ledgers: ledgers.length,
+        pendingForks: forks.filter((fork) => fork.resolvedAt === undefined).length,
+        sessions: ledgers.filter((ledger) => ledger.honchoSessionId !== undefined)
+            .length,
+        worker,
+    };
+}
+/** Build the web-standard route handler from live-resolving deps. */
+export function createStatusHandler(deps) {
+    return async () => Response.json(await buildStatus(deps), { status: 200 });
+}