@adecore/agents 0.0.1 → 0.17.0-beta.2

package/src/messages/deliver-notice.ts

@@ -0,0 +1,120 @@
+import type { ChatItem } from '@adecore/agent-contracts';
+import type { ChatCore } from '../chat/chat-core.ts';
+import type { Notice, NoticeStore } from './notice-store.ts';
+
+/* The words of a message, which are the host's: it names its app, its nodes and its CLI in them. */
+export interface MessageWords {
+    /* What the receiving agent hears of one message: the id to act on, the title to read, and the message itself. */
+    heard(notice: Notice): string;
+    /* The line a person reads in the thread about one message. */
+    shown(notice: Notice): string;
+    /* What the CLI is sent in a turn a message opened, under the messages its preamble carries. */
+    prompt(count: number): string;
+    /* The label above that turn in the thread. */
+    label(notices: readonly Notice[]): string;
+}
+
+/* How a chat under a node id stands, as a message on its way to it needs to know. */
+export interface ChatNoticeTargets {
+    /* What the host holds under this id: a chat between turns, one that is in a turn, or no chat at all. */
+    chat(id: string): Promise<'idle' | 'running' | 'none'>;
+    /* Whether the turn this node is running was opened by a message of its own, which is where waking stops. */
+    fromMessage(id: string): boolean;
+}
+
+/*
+ * Where a message for a chat went, and how many now wait for it. Only `wake` owes the chat a turn,
+ * which the host opens through a `deliver-message` entry; every other outcome waits in the queue for
+ * the chat's next turn.
+ */
+export interface ChatDelivery {
+    outcome: 'wake' | 'no-chat' | 'in-turn' | 'from-message';
+    waiting: number;
+}
+
+/*
+ * Whether the turn a chat is running was itself opened by a message. This is the whole of the stop:
+ * two agents that read each other would otherwise wake each other for as long as they kept writing,
+ * and nothing about that started with a person. It rides on the turn, so it survives a restart.
+ * Between turns the last one counts, since work it left running (a background subagent) may still
+ * write, and a turn the CLI opened by itself goes on with the step of the turn before it.
+ */
+export function turnFromMessage(items: readonly ChatItem[], activeTurnId: string | null): boolean {
+    const from = activeTurnId === null ? items.findLastIndex((item) => item.kind === 'turn') : items.findIndex((item) => item.id === activeTurnId);
+    for (let i = from; i >= 0; i--) {
+        const turn = items[i]!;
+        if (turn.kind !== 'turn') {
+            continue;
+        }
+        if ((turn.messageFrom ?? []).length > 0) {
+            return true;
+        }
+        if (turn.origin !== 'agent' || turn.taskIds !== undefined || turn.summaryFor !== undefined) {
+            return false;
+        }
+    }
+    return false;
+}
+
+/* The chats of a core as a message sees them. */
+export function chatNoticeTargets(chats: Pick<ChatCore, 'get' | 'hasStored'>): ChatNoticeTargets {
+    return {
+        chat: async (id) => {
+            const session = chats.get(id);
+            if (session) {
+                return session.info.activeTurnId === null ? 'idle' : 'running';
+            }
+            // A chat nobody has loaded is idle: the turn opens on the thread the host reads back from disk.
+            return (await chats.hasStored(id)) ? 'idle' : 'none';
+        },
+        fromMessage: (id) => {
+            const session = chats.get(id);
+            return session !== undefined && turnFromMessage(session.thread.list(), session.info.activeTurnId);
+        }
+    };
+}
+
+/*
+ * One message on its way to a chat, and whether the chat owes a turn on it. A chat between turns gets
+ * one, the way a settled task gives one: a person watching two agents cannot tell a message from an
+ * assignment, and a message nobody starts a turn for sits there until someone happens to prompt that
+ * chat. One step deep, so the turn a message opened wakes nobody with a message of its own. A node the
+ * host runs something else in, such as a terminal, is the host's to deliver to before this.
+ */
+export async function deliverToChat(store: Pick<NoticeStore, 'put'>, targets: ChatNoticeTargets, notice: Omit<Notice, 'createdAt'>): Promise<ChatDelivery> {
+    const waiting = await store.put(notice);
+    const chat = await targets.chat(notice.targetId);
+    if (chat === 'none') {
+        return { outcome: 'no-chat', waiting };
+    }
+    if (chat === 'running') {
+        return { outcome: 'in-turn', waiting };
+    }
+    if (targets.fromMessage(notice.from)) {
+        return { outcome: 'from-message', waiting };
+    }
+    return { outcome: 'wake', waiting };
+}
+
+/* The chat a message was left for, as the two things showing it needs: whether it is there, and a line in its thread. */
+export interface NoticeChat {
+    /* Whether the host holds a chat under the id, running or on disk. */
+    has(id: string): Promise<boolean>;
+    /* Puts a line in that chat's thread, loading the chat when nobody has. */
+    note(id: string, text: string): Promise<void>;
+}
+
+/*
+ * What a chat has to show a person, in its thread, the moment a message lands and not when the model
+ * gets round to it: without this a message left for a busy node is a file on disk and nothing else.
+ * An id no chat holds shows nothing and marks nothing, so the chat that opens on that id later still
+ * has all of it.
+ */
+export async function showNotices(store: Pick<NoticeStore, 'show'>, chat: NoticeChat, words: Pick<MessageWords, 'shown'>, targetId: string): Promise<void> {
+    if (!(await chat.has(targetId))) {
+        return;
+    }
+    for (const notice of await store.show(targetId)) {
+        await chat.note(targetId, words.shown(notice));
+    }
+}

package/src/messages/notice-notes.ts

@@ -0,0 +1,34 @@
+import type { PromptNotes } from '../chat/chat-session.ts';
+import type { MessageWords } from './deliver-notice.ts';
+import type { NoticeStore } from './notice-store.ts';
+
+/*
+ * What another node left for a chat, taken from the queue in front of its next prompt so the model
+ * hears it once. Nothing of it is shown: a person read each message in the thread as it landed
+ * (`showNotices`), so repeating it above the turn says the same thing twice.
+ */
+export class NoticeNotes implements PromptNotes {
+    private readonly store: Pick<NoticeStore, 'take'>;
+    private readonly chatId: string;
+    private readonly words: Pick<MessageWords, 'heard'>;
+
+    constructor(store: Pick<NoticeStore, 'take'>, chatId: string, words: Pick<MessageWords, 'heard'>) {
+        this.store = store;
+        this.chatId = chatId;
+        this.words = words;
+    }
+
+    next(): { shown: string[]; heard: string[] } {
+        return { shown: [], heard: this.store.take(this.chatId).map((notice) => this.words.heard(notice)) };
+    }
+
+    reset(): void {}
+}
+
+/*
+ * The lines a chat that just loaded owes a person for what landed while nobody held it, marked so a
+ * reload writes none again. The model still hears the messages themselves from the queue.
+ */
+export async function unshownNotes(store: Pick<NoticeStore, 'show'>, chatId: string, words: Pick<MessageWords, 'shown'>): Promise<string[]> {
+    return (await store.show(chatId)).map((notice) => words.shown(notice));
+}

package/src/messages/notice-store.ts

@@ -0,0 +1,142 @@
+import { join } from 'node:path';
+import { z } from 'zod';
+import { errorText } from '../error-text.ts';
+import { RecordDirectory } from '../record-directory.ts';
+
+// Per receiver. Past this the oldest goes: an agent in a loop must not fill a queue nobody reads.
+export const MAX_NOTICES = 10;
+
+/*
+ * A message nobody picked up in this long is dropped rather than delivered. It is news about work
+ * happening now ("the build is green"), and a model reading it six hours late would act on
+ * something that has moved on. The cap alone would not do it: one message in a queue of one waits
+ * for ever.
+ */
+export const NOTICE_MAX_AGE_MS = 6 * 60 * 60 * 1000;
+
+const NoticeSchema = z.object({
+    projectId: z.string().min(1),
+    /* The node the message is for; also the file it waits in. */
+    targetId: z.string().min(1),
+    /* The node that sent it, by id, since that is what the receiver can act on. */
+    from: z.string().min(1),
+    fromTitle: z.string(),
+    text: z.string().min(1),
+    createdAt: z.number(),
+    /*
+     * Whether a person was shown this message already. Its own mark, beside the queue: the queue is
+     * emptied by the model reading the message, and the two readers must not take it from each
+     * other. Absent is unshown, so a message left by an older host is still shown once.
+     */
+    shown: z.boolean().optional()
+});
+
+export type Notice = z.infer<typeof NoticeSchema>;
+
+/* A queue waits in the file of the node it is for, so the first message in it names that node. */
+const FileSchema = z.object({ notices: z.array(NoticeSchema).min(1) });
+
+type NoticeFile = z.infer<typeof FileSchema>;
+
+/*
+ * The messages waiting for each node, held until that node's agent has a moment to hear them, under
+ * `<dataDir>/notices`. On disk because the receiver may well be a node nobody has mounted yet, and a
+ * host that restarts must not lose what was left for it. Delivered once, whichever channel gets there
+ * first.
+ */
+export class NoticeStore {
+    readonly dir: string;
+    private readonly queues: RecordDirectory<NoticeFile>;
+    private readonly now: () => number;
+    private lastDrop: Promise<void> = Promise.resolve();
+
+    constructor(dataDir: string, now: () => number = Date.now) {
+        this.dir = join(dataDir, 'notices');
+        this.now = now;
+        this.queues = new RecordDirectory({
+            dir: this.dir,
+            schema: FileSchema,
+            idOf: (file) => file.notices[0]!.targetId,
+            // What went stale while the host was down is not delivered; a queue of nothing else goes.
+            keep: (file) => {
+                const fresh = file.notices.filter((notice) => this.fresh(notice));
+                return fresh[0] === undefined ? null : { notices: fresh };
+            }
+        });
+    }
+
+    load(): Promise<void> {
+        return this.queues.load();
+    }
+
+    /* Puts one message in a node's queue and answers how many now wait for it. */
+    async put(notice: Omit<Notice, 'createdAt'>): Promise<number> {
+        const queue = [...this.waiting(notice.targetId), { ...notice, createdAt: this.now() }].slice(-MAX_NOTICES);
+        await this.persist(notice.targetId, queue);
+        return queue.length;
+    }
+
+    /*
+     * Everything waiting for a node, gone the moment it is asked for. Synchronous, because the
+     * callers are: a shell's first screen and a hook's answer are both written before anything can
+     * be awaited. The queue leaves memory first and the file follows, so two channels asking in the
+     * same tick cannot both be handed the same message.
+     */
+    take(targetId: string): Notice[] {
+        const queue = this.waiting(targetId);
+        if (queue.length === 0) {
+            return [];
+        }
+        this.lastDrop = this.persist(targetId, []).catch((e) => console.error(`Dropping the messages of ${targetId} failed:`, errorText(e)));
+        return queue;
+    }
+
+    /* Resolves once the file the last `take` dropped is gone; `take` cannot hand that promise back itself. */
+    settled(): Promise<void> {
+        return this.lastDrop;
+    }
+
+    /*
+     * What nobody showed a person yet, marked here so it is shown once. The messages stay in the
+     * queue: this is the second reader, and only the model's copy may be taken away.
+     */
+    async show(targetId: string): Promise<Notice[]> {
+        const queue = this.waiting(targetId);
+        const unshown = queue.filter((notice) => notice.shown !== true);
+        if (unshown.length === 0) {
+            return [];
+        }
+        await this.persist(
+            targetId,
+            queue.map((notice) => ({ ...notice, shown: true }))
+        );
+        return unshown;
+    }
+
+    /* What waits for a node, without taking it; the stale ones are already gone from the answer. */
+    waiting(targetId: string): Notice[] {
+        const file = this.queues.get(targetId);
+        if (file === undefined) {
+            return [];
+        }
+        return file.notices.filter((notice) => this.fresh(notice));
+    }
+
+    /* Drops what a project was holding for ids it no longer has: the node was deleted before it read them. */
+    prune(projectId: string, ids: ReadonlySet<string>): Promise<void> {
+        return this.queues.prune((file) => file.notices[0]!.projectId === projectId && !ids.has(file.notices[0]!.targetId));
+    }
+
+    private fresh(notice: Notice): boolean {
+        return this.now() - notice.createdAt < NOTICE_MAX_AGE_MS;
+    }
+
+    /* The queue of one node, emptied here and on disk both; an empty one leaves no file behind. */
+    private async persist(targetId: string, queue: Notice[]): Promise<void> {
+        if (queue.length === 0) {
+            await this.queues.remove(targetId);
+            return;
+        }
+        await this.queues.write({ notices: queue });
+    }
+}

package/src/modes.ts

@@ -0,0 +1,38 @@
+import { RuntimeModeSchema, type RuntimeMode } from '@adecore/agent-contracts';
+import { z } from 'zod';
+import { VerbRefusal } from './context/verb.ts';
+
+/*
+ * Every CLI's flags widen in this order (its permission flags and the Codex thread options), and where
+ * two modes share a flag clamping down grants the same, never more. So one order serves every CLI.
+ */
+export const MODE_ORDER = RuntimeModeSchema.options;
+
+function rankOf(mode: RuntimeMode): number {
+    return MODE_ORDER.indexOf(mode);
+}
+
+export function narrowerMode(mode: RuntimeMode, ceiling: RuntimeMode): RuntimeMode {
+    return rankOf(mode) <= rankOf(ceiling) ? mode : ceiling;
+}
+
+function modeLines(mine: RuntimeMode): string[] {
+    return [`mode\tyou\t${mine}`, ...MODE_ORDER.filter((mode) => rankOf(mode) <= rankOf(mine)).map((mode) => `mode\t${mode}\tallowed`)];
+}
+
+/*
+ * The mode an agent the opener opens may get at most, refusing a `--mode` above it. The ceiling is
+ * the opener's own mode, so a chain of agents can only ever narrow what it may do, never widen it.
+ */
+export function ceilingForOpening(opener: RuntimeMode, requested: RuntimeMode | undefined): RuntimeMode {
+    if (requested !== undefined && rankOf(requested) > rankOf(opener)) {
+        throw new VerbRefusal(
+            'mode-above-parent',
+            `You run in ${opener} and --mode ${requested} is wider; an agent you open runs in your mode or a narrower one`,
+            modeLines(opener)
+        );
+    }
+    return opener;
+}
+
+export const modeFlag = z.enum(MODE_ORDER, { error: `--mode is one of ${MODE_ORDER.join(', ')}` }).optional();

package/src/outbox/manual-clock.ts

@@ -0,0 +1,31 @@
+import type { OutboxClock } from './outbox-worker.ts';
+
+/* A clock a test moves by hand. A timer fires only inside `advance`, never on its own. */
+export class ManualClock implements OutboxClock {
+    private time = 1_000_000;
+    private timers: Array<{ at: number; run: () => void; id: number }> = [];
+    private nextId = 1;
+
+    now(): number {
+        return this.time;
+    }
+
+    setTimeout(run: () => void, ms: number): unknown {
+        const id = this.nextId++;
+        this.timers.push({ at: this.time + ms, run, id });
+        return id;
+    }
+
+    clearTimeout(handle: unknown): void {
+        this.timers = this.timers.filter((timer) => timer.id !== handle);
+    }
+
+    advance(ms: number): void {
+        this.time += ms;
+        const due = this.timers.filter((timer) => timer.at <= this.time);
+        this.timers = this.timers.filter((timer) => timer.at > this.time);
+        for (const timer of due) {
+            timer.run();
+        }
+    }
+}

package/src/outbox/outbox-worker.ts

@@ -0,0 +1,214 @@
+import { errorText } from '../error-text.ts';
+import type { OutboxEntryOf, OutboxStore, OutboxWorkShape } from './outbox.ts';
+
+/* How long a failed entry waits before each next attempt; one more failure than there are delays parks it. */
+export const RETRY_DELAYS_MS: readonly number[] = [1_000, 5_000, 30_000];
+
+export interface OutboxClock {
+    now(): number;
+    setTimeout(run: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+
+export const systemClock: OutboxClock = {
+    now: () => Date.now(),
+    setTimeout: (run, ms) => setTimeout(run, ms),
+    clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>)
+};
+
+/*
+ * `wait` keeps the entry without counting an attempt. The work cannot happen yet (a chat is still in
+ * its turn) and runs again once `wake` names its target, never on a clock.
+ */
+export type OutboxOutcome = void | 'wait';
+
+export type OutboxHandlers<Work extends OutboxWorkShape> = {
+    [K in Work['kind']]: (entry: Extract<OutboxEntryOf<Work>, { kind: K }>) => Promise<OutboxOutcome>;
+};
+
+export interface OutboxWorkerOptions<Work extends OutboxWorkShape> {
+    store: OutboxStore<Work>;
+    handlers: OutboxHandlers<Work>;
+    clock?: OutboxClock;
+    /* An entry that failed every attempt and is given up on (and logged); the work it stood for is not done. */
+    onParked?: (entry: OutboxEntryOf<Work>, error: unknown) => void;
+}
+
+/*
+ * Works the outbox off, oldest first and one entry at a time per target, so two pieces of work
+ * about one node never overlap while nodes beside it do not wait on each other. A handler is
+ * idempotent, since a restart between the work and the removal of its file runs it again.
+ */
+export class OutboxWorker<Work extends OutboxWorkShape> {
+    private readonly store: OutboxStore<Work>;
+    private readonly handlers: OutboxHandlers<Work>;
+    private readonly clock: OutboxClock;
+    private readonly onParked: (entry: OutboxEntryOf<Work>, error: unknown) => void;
+    private readonly running = new Set<string>();
+    // Entries that said `wait`, until their target is woken; in memory only, so a restart looks again.
+    private readonly waiting = new Set<string>();
+    // Bumped by every wake of a target, so a wake that lands while its entry is still deciding to wait is not lost.
+    private readonly wakes = new Map<string, number>();
+    private timer: unknown = null;
+    private started = false;
+    private waiters: Array<() => void> = [];
+
+    constructor(options: OutboxWorkerOptions<Work>) {
+        this.store = options.store;
+        this.handlers = options.handlers;
+        this.clock = options.clock ?? systemClock;
+        this.onParked = options.onParked ?? (() => undefined);
+    }
+
+    start(): void {
+        this.started = true;
+        this.drain();
+    }
+
+    stop(): void {
+        this.started = false;
+        if (this.timer !== null) {
+            this.clock.clearTimeout(this.timer);
+            this.timer = null;
+        }
+    }
+
+    /* Owes a piece of work and starts on it; resolves once the entry is on disk, not once it is done. */
+    async enqueue(projectId: string, target: string, work: Work, notBefore?: number): Promise<void> {
+        const now = this.clock.now();
+        await this.store.put(projectId, target, work, now, notBefore ?? now);
+        this.drain();
+    }
+
+    /*
+     * Something about this target changed (a chat ended its turn), so whatever waited on it looks again.
+     * Deferred, so it never runs inside the broadcast of the chat that said so.
+     */
+    wake(target: string): void {
+        this.wakes.set(target, (this.wakes.get(target) ?? 0) + 1);
+        let woke = false;
+        for (const entry of this.store.list()) {
+            if (entry.target === target && this.waiting.delete(entry.id)) {
+                woke = true;
+            }
+        }
+        if (woke) {
+            queueMicrotask(() => this.drain());
+        }
+    }
+
+    /* Resolves once nothing is running and nothing is due; an entry waiting out a retry or a wake does not count. */
+    settled(): Promise<void> {
+        if (this.isSettled()) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+
+    private drain(): void {
+        if (!this.started) {
+            this.notifySettled();
+            return;
+        }
+        const now = this.clock.now();
+        const busy = new Set(this.running);
+        let nextDue: number | null = null;
+        for (const entry of this.store.list()) {
+            // A waiting entry holds no lane. The resume of a chat must not queue behind a wake that waits for it.
+            if (busy.has(entry.target) || this.waiting.has(entry.id)) {
+                continue;
+            }
+            // Nor does work due at a later time, which nothing owed before it has to wait for.
+            if (entry.attempts === 0 && entry.notBefore > now) {
+                nextDue = nextDue === null ? entry.notBefore : Math.min(nextDue, entry.notBefore);
+                continue;
+            }
+            const lanes = this.store.lanesOf(entry);
+            // Oldest first per target. A younger entry never overtakes one that waits out a retry.
+            for (const lane of lanes) {
+                busy.add(lane);
+            }
+            // The other lanes only wait for work that is running; work that is merely owed there is what ending takes away.
+            if (lanes.some((lane) => lane !== entry.target && this.running.has(lane))) {
+                continue;
+            }
+            if (entry.notBefore > now) {
+                nextDue = nextDue === null ? entry.notBefore : Math.min(nextDue, entry.notBefore);
+                continue;
+            }
+            void this.run(entry);
+        }
+        this.schedule(nextDue, now);
+        this.notifySettled();
+    }
+
+    private async run(entry: OutboxEntryOf<Work>): Promise<void> {
+        const lanes = this.store.lanesOf(entry);
+        for (const lane of lanes) {
+            this.running.add(lane);
+        }
+        const woken = this.wakes.get(entry.target) ?? 0;
+        try {
+            const outcome = await (this.handlers[entry.kind as Work['kind']] as (entry: OutboxEntryOf<Work>) => Promise<OutboxOutcome>)(entry);
+            if (outcome === 'wait') {
+                if ((this.wakes.get(entry.target) ?? 0) === woken && this.store.has(entry.id)) {
+                    this.waiting.add(entry.id);
+                }
+                return;
+            }
+            await this.store.remove(entry.id);
+        } catch (e) {
+            await this.failed(entry, e).catch((error: unknown) => console.error(`The outbox could not record a failed ${entry.kind}:`, errorText(error)));
+        } finally {
+            for (const lane of lanes) {
+                this.running.delete(lane);
+            }
+            this.drain();
+        }
+    }
+
+    private async failed(entry: OutboxEntryOf<Work>, error: unknown): Promise<void> {
+        const delay = RETRY_DELAYS_MS[entry.attempts];
+        if (delay === undefined) {
+            await this.store.remove(entry.id);
+            console.error(`Gave up on ${entry.kind} for ${entry.target}:`, errorText(error));
+            this.onParked(entry, error);
+            return;
+        }
+        await this.store.update({ ...entry, attempts: entry.attempts + 1, notBefore: this.clock.now() + delay });
+    }
+
+    private schedule(nextDue: number | null, now: number): void {
+        if (this.timer !== null) {
+            this.clock.clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (nextDue !== null) {
+            this.timer = this.clock.setTimeout(
+                () => {
+                    this.timer = null;
+                    this.drain();
+                },
+                Math.max(0, nextDue - now)
+            );
+        }
+    }
+
+    private isSettled(): boolean {
+        const now = this.clock.now();
+        return this.running.size === 0 && (!this.started || !this.store.list().some((entry) => entry.notBefore <= now && !this.waiting.has(entry.id)));
+    }
+
+    private notifySettled(): void {
+        if (!this.isSettled()) {
+            return;
+        }
+        const waiting = this.waiters;
+        this.waiters = [];
+        for (const resolve of waiting) {
+            resolve();
+        }
+    }
+}

package/src/outbox/outbox.ts

@@ -0,0 +1,106 @@
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { RecordDirectory } from '../record-directory.ts';
+
+/* One kind of work a host owes: its schema's `kind` is a literal, and the kinds together a discriminated union. */
+export interface OutboxWorkShape {
+    kind: string;
+    payload: unknown;
+}
+
+const OutboxEntryFieldsSchema = z.object({
+    id: z.string().min(1),
+    projectId: z.string().min(1),
+    // The node the work is about. Entries for one target run one at a time, and it goes with the node.
+    target: z.string().min(1),
+    createdAt: z.number(),
+    attempts: z.number().int().nonnegative(),
+    notBefore: z.number()
+});
+
+export type OutboxEntryFields = z.infer<typeof OutboxEntryFieldsSchema>;
+export type OutboxEntryOf<Work extends OutboxWorkShape> = Work & OutboxEntryFields;
+
+export interface OutboxStoreOptions<Work extends OutboxWorkShape> {
+    /* The entries go in `outbox` under it. */
+    dataDir: string;
+    work: z.ZodType<Work>;
+    /* The nodes an entry is about, its target first; work on any of them waits while it runs. Only the target when absent. */
+    lanesOf?(entry: OutboxEntryOf<Work>): string[];
+    /* Work owed exactly because its target is gone, which pruning therefore keeps. */
+    outlivesTarget?(entry: OutboxEntryOf<Work>): boolean;
+}
+
+/*
+ * Work a host still owes, one file per entry under `<dataDir>/outbox`, removed once it is done. On
+ * disk because the owing outlives the process: a node written a moment before a restart still has
+ * its agent started after it.
+ */
+export class OutboxStore<Work extends OutboxWorkShape> {
+    readonly dir: string;
+    private readonly entries: RecordDirectory<OutboxEntryOf<Work>>;
+    private readonly lanes: (entry: OutboxEntryOf<Work>) => string[];
+    private readonly outlivesTarget: (entry: OutboxEntryOf<Work>) => boolean;
+
+    constructor(options: OutboxStoreOptions<Work>) {
+        this.dir = join(options.dataDir, 'outbox');
+        this.entries = new RecordDirectory<OutboxEntryOf<Work>>({
+            dir: this.dir,
+            schema: z.intersection(options.work, OutboxEntryFieldsSchema),
+            idOf: (entry) => entry.id
+        });
+        this.lanes = options.lanesOf ?? ((entry) => [entry.target]);
+        this.outlivesTarget = options.outlivesTarget ?? (() => false);
+    }
+
+    /* Reads what an earlier run of the host still owed. Call before the worker starts. */
+    load(): Promise<void> {
+        return this.entries.load();
+    }
+
+    /* `notBefore` later than `now` is work due at a time, which holds no lane until then. */
+    async put(projectId: string, target: string, work: Work, now: number, notBefore = now): Promise<OutboxEntryOf<Work>> {
+        const entry: OutboxEntryOf<Work> = {
+            ...work,
+            id: `${work.kind}-${randomBytes(6).toString('hex')}`,
+            projectId,
+            target,
+            createdAt: now,
+            attempts: 0,
+            notBefore
+        };
+        await this.entries.write(entry);
+        return entry;
+    }
+
+    /* The same entry with what its last attempt left behind. */
+    async update(entry: OutboxEntryOf<Work>): Promise<void> {
+        if (!this.entries.has(entry.id)) {
+            return;
+        }
+        await this.entries.write(entry);
+    }
+
+    remove(id: string): Promise<void> {
+        return this.entries.remove(id);
+    }
+
+    /* Oldest first, which is the order the work was owed in. */
+    list(): OutboxEntryOf<Work>[] {
+        return this.entries.all().sort((a, b) => a.createdAt - b.createdAt);
+    }
+
+    has(id: string): boolean {
+        return this.entries.has(id);
+    }
+
+    lanesOf(entry: OutboxEntryOf<Work>): string[] {
+        return this.lanes(entry);
+    }
+
+    /* Drops what this project owed for ids it no longer has, since nothing is started for a node that was deleted. */
+    prune(projectId: string, ids: ReadonlySet<string>): Promise<void> {
+        return this.entries.prune((entry) => entry.projectId === projectId && !this.outlivesTarget(entry) && !ids.has(entry.target));
+    }
+}