@sigrun/memory-honcho 0.0.0-stage → 0.1.1

package/dist/stores.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The extension's filesystem stores, rooted at `host.stores.paths`:
+ *
+ * - `data/outbox/capture.jsonl` — the durable outbox (the only durable copy
+ *   of not-yet-delivered conversation content, so it takes the backed-up
+ *   bucket), one JSON record per line in append order.
+ * - `state/last-delivery.json` — the persistent newest-delivery marker the
+ *   status route reads (the sweeper drops delivered records, so the marker
+ *   is the only surviving source of `lastDeliveryAt` in steady state).
+ * - `state/ledger/<conversationId>.json` — per-conversation bookkeeping
+ *   (session mapping, delivered-batch window, fork anchors).
+ * - `state/forks/pending/<childId>.json` — pending-fork records.
+ * - `cache/representations/<conversationId>.json` — the representation
+ *   snapshots the prompt section renders.
+ *
+ * `withOutbox` is a single MODULE-LEVEL mutex serializing every outbox
+ * read-modify-write cycle across ALL conversations and ALL ExtensionStores
+ * instances (the spec's serialization requirement: the sweeper's rewrite
+ * must not lose a concurrent capture append). In-process only — a restart
+ * loses in-flight work exactly as the outbox posture already accepts.
+ *
+ * All writes are atomic (temp file + rename in the same directory). The
+ * `*Sync` reads use `readFileSync` because the prompt-section render is
+ * synchronous (the spec'd cache-read posture).
+ */
+import type { HonchoSettings } from "./config.js";
+import type { LastDeliveryMarker, Ledger, OutboxRecord, PendingForkRecord, RepresentationSnapshot } from "./types.js";
+/** The three store roots, exactly `host.stores.paths`' shape. */
+export interface StorePaths {
+    readonly data: string;
+    readonly state: string;
+    readonly cache: string;
+}
+export declare class ExtensionStores {
+    #private;
+    constructor(paths: StorePaths, settings: HonchoSettings);
+    /**
+     * Run `work` holding the outbox mutex. The caller's promise settles with
+     * the work's own result (rejection included); the internal tail is
+     * self-catching so one failing caller cannot poison the queue.
+     * NOT re-entrant: do not call `withOutbox` from within `work`.
+     */
+    withOutbox<T>(work: () => Promise<T>): Promise<T>;
+    readLedger(conversationId: number): Promise<Ledger | undefined>;
+    /** Every ledger on disk (status/observability reads; missing dir → []). */
+    readLedgers(): Promise<Ledger[]>;
+    readLedgerSync(conversationId: number): Ledger | undefined;
+    writeLedger(conversationId: number, ledger: Ledger): Promise<void>;
+    /**
+     * Read every outbox record in file order. For anything other than a
+     * display-only read, call inside `withOutbox` (see the module comment).
+     */
+    readOutbox(): Promise<OutboxRecord[]>;
+    /** Append one record (one JSONL line). Call inside `withOutbox`. */
+    appendOutboxRecord(record: OutboxRecord): Promise<void>;
+    /** Replace the outbox (atomic). Call inside `withOutbox`. */
+    rewriteOutbox(records: OutboxRecord[]): Promise<void>;
+    readPendingFork(childId: number): Promise<PendingForkRecord | undefined>;
+    /**
+     * Every pending-fork record on disk, resolved ones included (they are
+     * kept stamped so a late duplicate establish never re-clones; callers
+     * wanting the still-pending count filter on `resolvedAt`).
+     */
+    readPendingForks(): Promise<PendingForkRecord[]>;
+    writePendingFork(record: PendingForkRecord): Promise<void>;
+    /**
+     * Stamp `resolvedAt` on the record (kept on disk, so a late duplicate
+     * establish never re-clones). Returns the resolved record, or `undefined`
+     * when no pending fork exists for the child.
+     */
+    resolvePendingFork(childId: number): Promise<PendingForkRecord | undefined>;
+    readRepresentationSync(conversationId: number): RepresentationSnapshot | undefined;
+    writeRepresentation(conversationId: number, snapshot: RepresentationSnapshot): Promise<void>;
+    /**
+     * `state/last-delivery.json` — the persistent "newest delivery" marker.
+     * The delivery engine writes it when it flips a record (inside the same
+     * outbox critical section), because the sweeper drops delivered records
+     * every 15 minutes — the status route's retained-records derivation dies
+     * with them.
+     */
+    readLastDelivery(): Promise<LastDeliveryMarker | undefined>;
+    writeLastDelivery(marker: LastDeliveryMarker): Promise<void>;
+}

package/dist/stores.js

@@ -0,0 +1,244 @@
+/**
+ * The extension's filesystem stores, rooted at `host.stores.paths`:
+ *
+ * - `data/outbox/capture.jsonl` — the durable outbox (the only durable copy
+ *   of not-yet-delivered conversation content, so it takes the backed-up
+ *   bucket), one JSON record per line in append order.
+ * - `state/last-delivery.json` — the persistent newest-delivery marker the
+ *   status route reads (the sweeper drops delivered records, so the marker
+ *   is the only surviving source of `lastDeliveryAt` in steady state).
+ * - `state/ledger/<conversationId>.json` — per-conversation bookkeeping
+ *   (session mapping, delivered-batch window, fork anchors).
+ * - `state/forks/pending/<childId>.json` — pending-fork records.
+ * - `cache/representations/<conversationId>.json` — the representation
+ *   snapshots the prompt section renders.
+ *
+ * `withOutbox` is a single MODULE-LEVEL mutex serializing every outbox
+ * read-modify-write cycle across ALL conversations and ALL ExtensionStores
+ * instances (the spec's serialization requirement: the sweeper's rewrite
+ * must not lose a concurrent capture append). In-process only — a restart
+ * loses in-flight work exactly as the outbox posture already accepts.
+ *
+ * All writes are atomic (temp file + rename in the same directory). The
+ * `*Sync` reads use `readFileSync` because the prompt-section render is
+ * synchronous (the spec'd cache-read posture).
+ */
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { mkdir, open, readdir, readFile, rename, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+/**
+ * The module-level outbox tail: every `withOutbox` caller queues behind the
+ * previous one, so a rewrite can never lose a concurrent append. The tail
+ * never rejects (a failing caller settles for ITS caller, the next queued
+ * work still runs).
+ */
+let outboxTail = Promise.resolve();
+export class ExtensionStores {
+    #paths;
+    #anchorWindow;
+    #deliveredBatchWindow;
+    constructor(paths, settings) {
+        this.#paths = paths;
+        this.#anchorWindow = settings.anchorWindow;
+        this.#deliveredBatchWindow = settings.deliveredBatchWindow;
+    }
+    /**
+     * Run `work` holding the outbox mutex. The caller's promise settles with
+     * the work's own result (rejection included); the internal tail is
+     * self-catching so one failing caller cannot poison the queue.
+     * NOT re-entrant: do not call `withOutbox` from within `work`.
+     */
+    async withOutbox(work) {
+        const previous = outboxTail;
+        let release;
+        outboxTail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return await work();
+        }
+        finally {
+            release();
+        }
+    }
+    // -- ledger (state) -------------------------------------------------------
+    async readLedger(conversationId) {
+        return readJson(this.#ledgerPath(conversationId));
+    }
+    /** Every ledger on disk (status/observability reads; missing dir → []). */
+    async readLedgers() {
+        return readJsonDir(join(this.#paths.state, "ledger"));
+    }
+    readLedgerSync(conversationId) {
+        return readJsonSync(this.#ledgerPath(conversationId));
+    }
+    async writeLedger(conversationId, ledger) {
+        // Window bounds fold oldest-first on write (spec §ledger).
+        const bounded = {
+            ...ledger,
+            deliveredBatchIds: ledger.deliveredBatchIds.slice(-this.#deliveredBatchWindow),
+            anchors: ledger.anchors.slice(-this.#anchorWindow),
+        };
+        await writeJsonAtomic(this.#ledgerPath(conversationId), bounded);
+    }
+    // -- outbox (data) --------------------------------------------------------
+    /**
+     * Read every outbox record in file order. For anything other than a
+     * display-only read, call inside `withOutbox` (see the module comment).
+     */
+    async readOutbox() {
+        let raw;
+        try {
+            raw = await readFile(this.#outboxPath(), "utf8");
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return [];
+            throw error;
+        }
+        return raw
+            .split("\n")
+            .filter((line) => line !== "")
+            .map((line) => JSON.parse(line));
+    }
+    /** Append one record (one JSONL line). Call inside `withOutbox`. */
+    async appendOutboxRecord(record) {
+        const path = this.#outboxPath();
+        await mkdir(dirname(path), { recursive: true });
+        const file = await open(path, "a");
+        try {
+            await file.appendFile(JSON.stringify(record) + "\n", "utf8");
+        }
+        finally {
+            await file.close();
+        }
+    }
+    /** Replace the outbox (atomic). Call inside `withOutbox`. */
+    async rewriteOutbox(records) {
+        await writeTextAtomic(this.#outboxPath(), records.map((record) => JSON.stringify(record)).join("\n") +
+            (records.length === 0 ? "" : "\n"));
+    }
+    // -- pending forks (state) ------------------------------------------------
+    async readPendingFork(childId) {
+        return readJson(this.#pendingForkPath(childId));
+    }
+    /**
+     * Every pending-fork record on disk, resolved ones included (they are
+     * kept stamped so a late duplicate establish never re-clones; callers
+     * wanting the still-pending count filter on `resolvedAt`).
+     */
+    async readPendingForks() {
+        return readJsonDir(join(this.#paths.state, "forks", "pending"));
+    }
+    async writePendingFork(record) {
+        await writeJsonAtomic(this.#pendingForkPath(record.childId), record);
+    }
+    /**
+     * Stamp `resolvedAt` on the record (kept on disk, so a late duplicate
+     * establish never re-clones). Returns the resolved record, or `undefined`
+     * when no pending fork exists for the child.
+     */
+    async resolvePendingFork(childId) {
+        const existing = await this.readPendingFork(childId);
+        if (existing === undefined)
+            return undefined;
+        const resolved = { ...existing, resolvedAt: Date.now() };
+        await this.writePendingFork(resolved);
+        return resolved;
+    }
+    // -- representations (cache) ----------------------------------------------
+    readRepresentationSync(conversationId) {
+        return readJsonSync(this.#representationPath(conversationId));
+    }
+    async writeRepresentation(conversationId, snapshot) {
+        await writeJsonAtomic(this.#representationPath(conversationId), snapshot);
+    }
+    // -- last-delivery marker (state) -------------------------------------------
+    /**
+     * `state/last-delivery.json` — the persistent "newest delivery" marker.
+     * The delivery engine writes it when it flips a record (inside the same
+     * outbox critical section), because the sweeper drops delivered records
+     * every 15 minutes — the status route's retained-records derivation dies
+     * with them.
+     */
+    async readLastDelivery() {
+        return readJson(this.#lastDeliveryPath());
+    }
+    async writeLastDelivery(marker) {
+        await writeJsonAtomic(this.#lastDeliveryPath(), marker);
+    }
+    // -- paths ------------------------------------------------------------------
+    #ledgerPath(conversationId) {
+        return join(this.#paths.state, "ledger", `${conversationId}.json`);
+    }
+    #outboxPath() {
+        return join(this.#paths.data, "outbox", "capture.jsonl");
+    }
+    #pendingForkPath(childId) {
+        return join(this.#paths.state, "forks", "pending", `${childId}.json`);
+    }
+    #representationPath(conversationId) {
+        return join(this.#paths.cache, "representations", `${conversationId}.json`);
+    }
+    #lastDeliveryPath() {
+        return join(this.#paths.state, "last-delivery.json");
+    }
+}
+function isNotFound(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+async function readJson(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+/** Parse every `*.json` file in a directory; a missing directory is empty. */
+async function readJsonDir(dir) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return [];
+        throw error;
+    }
+    const values = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        values.push(JSON.parse(await readFile(join(dir, name), "utf8")));
+    }
+    return values;
+}
+function readJsonSync(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
+    }
+}
+/** Atomic JSON write: temp file in the same directory, then rename. */
+async function writeJsonAtomic(path, value) {
+    await writeTextAtomic(path, JSON.stringify(value));
+}
+async function writeTextAtomic(path, content) {
+    const dir = dirname(path);
+    await mkdir(dir, { recursive: true });
+    const temp = join(dir, `.${basename(path)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    await writeFile(temp, content, "utf8");
+    await rename(temp, path);
+}

package/dist/sweep.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The outbox sweeper task (`honcho-outbox-sweep`), fired by the
+ * `outbox-sweep` cron job every 15 minutes.
+ *
+ * Body: group the outbox by conversation in file order; ESTABLISH every
+ * planned conversation (unresolved pending-forks first — a cloned child's
+ * establishment must land before its own deliveries), so the spec's
+ * recovery lane works: a pending record whose conversation has no ledger
+ * and no in-memory session mark (the missing-key / Honcho-down-at-capture
+ * state) gets the get-or-create it needs, because `establish` is
+ * idempotent (one ledger read when the ledger exists, no network). Then
+ * `deliverPending` each conversation; then compact inside `withOutbox`
+ * (drop delivered records — including the skipped-but-lingering kind whose
+ * batchId already sits in the ledger's delivered window — and pending
+ * records older than `outboxRetentionDays`, warning per retention drop;
+ * rewrite). Idempotent under re-fire: a sweep with a fully-delivered
+ * outbox touches nothing but the terminal commit.
+ *
+ * Failure posture: per-conversation try/catch + `console.error` +
+ * continue. ONE poisoned conversation can never fault the task, block the
+ * rest of the file, or skip compaction — a phase rejection faults the
+ * task, and a faulted sweep leaves retention drops and later-conversation
+ * deliveries undone forever.
+ *
+ * Lock discipline: the engine calls happen OUTSIDE the outbox mutex
+ * (`deliverPending` owns its own `withOutbox`; the mutex is not
+ * re-entrant). The planning read runs inside `withOutbox` (a read-only
+ * hold; nothing here calls the engine inside it). The compaction pass
+ * re-reads inside its own `withOutbox`, so records appended between the
+ * planning read and the rewrite are re-examined, never clobbered.
+ * Settings are resolved FRESH per sweep (the stores freeze
+ * `anchorWindow`/`deliveredBatchWindow` at first use, but retention must
+ * follow live settings).
+ *
+ * The real pi-durable `TaskDefinition` shape: `{name, version, initial,
+ * phases, abort}` — there is NO `run` member. A phase must commit durable
+ * progress before returning (returning without a commit faults the task),
+ * so `phases.sweep` ends in the terminal-completed commit and `abort`
+ * commits terminal-failed.
+ */
+import type { HonchoSettings } from "./config.js";
+import type { DeliveryEngine } from "./delivery.js";
+import type { ExtensionStores } from "./stores.js";
+/** The registered task kind; the cron job's action names it. */
+export declare const SWEEP_TASK_NAME = "honcho-outbox-sweep";
+/** The sweep's dependencies — the factory wires the real ones; tests inject fakes. */
+export interface SweepTaskDeps {
+    readonly engine: () => DeliveryEngine | Promise<DeliveryEngine>;
+    readonly stores: () => ExtensionStores | Promise<ExtensionStores>;
+    readonly settings: () => HonchoSettings | Promise<HonchoSettings>;
+}
+/** The sweep body, shared by the task phase and directly unit-testable. */
+export declare function runSweep(deps: SweepTaskDeps, signal?: AbortSignal): Promise<void>;
+/** The sweep is one phase; the checkpoint never carries data. */
+type SweepCheckpoint = {
+    phase: "sweep";
+};
+/** The task object the extension registers (`extension.tasks`). */
+export declare function createSweepTask(deps: SweepTaskDeps): import("@earendil-works/pi-durable").Task<unknown, SweepCheckpoint, unknown, object>;
+export {};

package/dist/sweep.js

@@ -0,0 +1,198 @@
+/**
+ * The outbox sweeper task (`honcho-outbox-sweep`), fired by the
+ * `outbox-sweep` cron job every 15 minutes.
+ *
+ * Body: group the outbox by conversation in file order; ESTABLISH every
+ * planned conversation (unresolved pending-forks first — a cloned child's
+ * establishment must land before its own deliveries), so the spec's
+ * recovery lane works: a pending record whose conversation has no ledger
+ * and no in-memory session mark (the missing-key / Honcho-down-at-capture
+ * state) gets the get-or-create it needs, because `establish` is
+ * idempotent (one ledger read when the ledger exists, no network). Then
+ * `deliverPending` each conversation; then compact inside `withOutbox`
+ * (drop delivered records — including the skipped-but-lingering kind whose
+ * batchId already sits in the ledger's delivered window — and pending
+ * records older than `outboxRetentionDays`, warning per retention drop;
+ * rewrite). Idempotent under re-fire: a sweep with a fully-delivered
+ * outbox touches nothing but the terminal commit.
+ *
+ * Failure posture: per-conversation try/catch + `console.error` +
+ * continue. ONE poisoned conversation can never fault the task, block the
+ * rest of the file, or skip compaction — a phase rejection faults the
+ * task, and a faulted sweep leaves retention drops and later-conversation
+ * deliveries undone forever.
+ *
+ * Lock discipline: the engine calls happen OUTSIDE the outbox mutex
+ * (`deliverPending` owns its own `withOutbox`; the mutex is not
+ * re-entrant). The planning read runs inside `withOutbox` (a read-only
+ * hold; nothing here calls the engine inside it). The compaction pass
+ * re-reads inside its own `withOutbox`, so records appended between the
+ * planning read and the rewrite are re-examined, never clobbered.
+ * Settings are resolved FRESH per sweep (the stores freeze
+ * `anchorWindow`/`deliveredBatchWindow` at first use, but retention must
+ * follow live settings).
+ *
+ * The real pi-durable `TaskDefinition` shape: `{name, version, initial,
+ * phases, abort}` — there is NO `run` member. A phase must commit durable
+ * progress before returning (returning without a commit faults the task),
+ * so `phases.sweep` ends in the terminal-completed commit and `abort`
+ * commits terminal-failed.
+ */
+import { defineTask } from "@earendil-works/pi-durable";
+/** The registered task kind; the cron job's action names it. */
+export const SWEEP_TASK_NAME = "honcho-outbox-sweep";
+const DAY_MS = 86_400_000;
+/**
+ * The planning read, INSIDE the outbox mutex (read-only; it never calls
+ * the engine, so the non-reentrancy rule is never tripped): which
+ * conversations have outbox records, and which of their pending-fork
+ * records are still unresolved.
+ */
+async function plan(stores) {
+    return stores.withOutbox(async () => {
+        const records = await stores.readOutbox();
+        const conversationIds = [];
+        const seen = new Set();
+        const ownerByConversation = new Map();
+        for (const record of records) {
+            if (!seen.has(record.conversationId)) {
+                seen.add(record.conversationId);
+                conversationIds.push(record.conversationId);
+                ownerByConversation.set(record.conversationId, record.owner);
+            }
+        }
+        const unresolvedForks = [];
+        for (const conversationId of conversationIds) {
+            const fork = await stores.readPendingFork(conversationId);
+            if (fork !== undefined && fork.resolvedAt === undefined) {
+                unresolvedForks.push(conversationId);
+            }
+        }
+        return { conversationIds, ownerByConversation, unresolvedForks };
+    });
+}
+/**
+ * Compact: drop delivered records (a re-read inside the mutex catches
+ * records the engine flipped after the planning read, and the ledger's
+ * delivered window catches the skipped-but-lingering kind — a pending
+ * record whose batchId is already delivered, dropped SILENTLY: the ledger
+ * already counts the batch, so this is housekeeping, not data loss), and
+ * pending records older than the retention cutoff (warned, per record).
+ * Records appended between the planning read and here are re-examined by
+ * the same rules. The rewrite is skipped when nothing was dropped. The
+ * counts are logged for observability.
+ */
+async function compact(stores, retentionDays) {
+    const cutoff = Date.now() - retentionDays * DAY_MS;
+    const counts = await stores.withOutbox(async () => {
+        const records = await stores.readOutbox();
+        let droppedDelivered = 0;
+        let droppedExpired = 0;
+        const deliveredWindows = new Map();
+        const kept = [];
+        for (const record of records) {
+            if (record.status === "delivered") {
+                droppedDelivered += 1;
+                continue;
+            }
+            let delivered = deliveredWindows.get(record.conversationId);
+            if (delivered === undefined) {
+                const ledger = await stores.readLedger(record.conversationId);
+                delivered = new Set(ledger?.deliveredBatchIds ?? []);
+                deliveredWindows.set(record.conversationId, delivered);
+            }
+            if (delivered.has(record.batchId)) {
+                // Skipped-but-lingering: the ledger already counts the batch as
+                // delivered but the record never flipped (the accepted crash
+                // window) — drop it silently so every later sweep stops
+                // revisiting it.
+                droppedDelivered += 1;
+                continue;
+            }
+            if (record.createdAt < cutoff) {
+                droppedExpired += 1;
+                console.warn(`memory-honcho: dropping over-retention outbox record ${record.batchId} (conversation ${record.conversationId}, created ${new Date(record.createdAt).toISOString()}, older than ${retentionDays}d retention)`);
+                continue;
+            }
+            kept.push(record);
+        }
+        if (droppedDelivered + droppedExpired > 0) {
+            await stores.rewriteOutbox(kept);
+        }
+        return { delivered: droppedDelivered, expired: droppedExpired };
+    });
+    if (counts.delivered + counts.expired > 0) {
+        console.info(`memory-honcho: outbox compaction dropped ${counts.delivered} delivered, ${counts.expired} expired`);
+    }
+}
+/** The sweep body, shared by the task phase and directly unit-testable. */
+export async function runSweep(deps, signal) {
+    const stores = await deps.stores();
+    const settings = await deps.settings();
+    const engine = await deps.engine();
+    const { conversationIds, ownerByConversation, unresolvedForks } = await plan(stores);
+    // Establish EVERY planned conversation — idempotent (one ledger read
+    // when the ledger exists, no network), and for a ledger-less
+    // conversation the get-or-create the recovery lane needs. Unresolved
+    // forks go first (a clone decision reads the parent's ledger, which
+    // this very sweep may have just advanced). One failure logs and moves
+    // on: a poisoned conversation can never block the rest.
+    const establishOrder = [
+        ...unresolvedForks,
+        ...conversationIds.filter((id) => !unresolvedForks.includes(id)),
+    ];
+    for (const conversationId of establishOrder) {
+        if (signal?.aborted === true)
+            break;
+        const owner = ownerByConversation.get(conversationId) ?? "user";
+        try {
+            await engine.establish(conversationId, owner);
+        }
+        catch (error) {
+            console.error(`memory-honcho: sweep establish failed for conversation ${conversationId}`, error);
+        }
+    }
+    for (const conversationId of conversationIds) {
+        if (signal?.aborted === true)
+            break;
+        const owner = ownerByConversation.get(conversationId) ?? "user";
+        try {
+            await engine.deliverPending(conversationId, owner);
+        }
+        catch (error) {
+            console.error(`memory-honcho: sweep delivery failed for conversation ${conversationId}`, error);
+        }
+    }
+    // Compaction runs even when conversations above failed: retention and
+    // delivered-record drops must not be hostage to a poisoned entry.
+    await compact(stores, settings.outboxRetentionDays);
+}
+/** The task object the extension registers (`extension.tasks`). */
+export function createSweepTask(deps) {
+    return defineTask({
+        name: SWEEP_TASK_NAME,
+        version: 1,
+        initial: () => ({ phase: "sweep" }),
+        phases: {
+            sweep: async (_task, runtime, context) => {
+                await runSweep(deps, runtime.signal);
+                // REQUIRED: a phase returning without durable progress faults the
+                // task. The sweep's bookkeeping lives in the outbox files; the
+                // task's own terminal outcome is the durable progress.
+                await runtime.commit(() => ({
+                    status: "terminal",
+                    outcome: { status: "completed", result: undefined },
+                }), context);
+            },
+        },
+        abort: async (_task, runtime, context) => {
+            await runtime.commit(() => ({
+                status: "terminal",
+                outcome: {
+                    status: "failed",
+                    error: { message: "aborted" },
+                },
+            }), context);
+        },
+    });
+}

package/dist/tools.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The three recall tools: `honcho_search`, `honcho_chat`, `honcho_remember`.
+ *
+ * All three:
+ * - resolve the calling conversation's owner from `host.conversations.meta`
+ *   (memoized in-process per conversation; ownerless conversations → `"user"`);
+ * - await `engine.establish(conversationId, owner)` first (the spec's second
+ *   clone trigger — a rebuilt client re-establishes from the ledger);
+ * - convert Honcho failures to `memory-honcho: Honcho unavailable (<message>)`.
+ *
+ * `honcho_remember` passes NO `sessionId` in v1: a remembered fact is a
+ * user-level conclusion, matching the cross-conversation recall ruling.
+ * The README documents the visibility caveat.
+ */
+import { type ToolRegistration } from "@earendil-works/pi-durable";
+import type { ConversationId } from "@earendil-works/pi-durable";
+import type { HonchoSettings } from "./config.js";
+import type { DeliveryEngine } from "./delivery.js";
+import type { HonchoClient } from "./honcho.js";
+/** Structural slice of `host.conversations.meta` the tools read. */
+interface MetaReader {
+    meta(id: ConversationId): Promise<{
+        owner?: string;
+    }>;
+}
+/**
+ * Test seam: the factory wires the real accessors; tests inject fakes.
+ * The accessors are functions (not the values themselves) because the
+ * engine/client are lazily constructed and rebuilt on settings/key change.
+ */
+export interface ToolsDeps {
+    readonly host: {
+        conversations: MetaReader;
+    };
+    readonly client: () => HonchoClient | undefined;
+    readonly engine: () => Promise<DeliveryEngine>;
+    readonly settings: () => HonchoSettings | undefined;
+}
+/** Build the three recall tools. */
+export declare function createTools(deps: ToolsDeps): readonly ToolRegistration[];
+export {};