@adecore/agents 0.0.1 → 0.17.0-beta.1

package/dist/tasks/task-coordinator.js

@@ -0,0 +1,323 @@
+import { abortedByMachine, clipText } from '@adecore/agent-contracts';
+import { BACKGROUND_COMMAND_LIMIT_MS, commandLabel, isBackgroundWork, runningInBackground, runsInBackground } from '../chat/background-work.js';
+import { errorText } from '../error-text.js';
+// A child's answer is its last word of the turn; the thinking and the tools before it are not the result.
+function answerOf(items, turnId) {
+    for (let i = items.length - 1; i >= 0; i--) {
+        const item = items[i];
+        if (item.kind === 'assistant' && item.turnId === turnId && !item.parentToolUseId && item.text.trim() !== '') {
+            return item.text.trim();
+        }
+    }
+    return null;
+}
+function lastNote(items, turnId, levels) {
+    for (let i = items.length - 1; i >= 0; i--) {
+        const item = items[i];
+        if (item.kind === 'note' && item.turnId === turnId && levels.includes(item.level)) {
+            return item.text;
+        }
+    }
+    return null;
+}
+function commandList(commands) {
+    return commands.map((command) => `\`${command}\``).join(', ');
+}
+function outlastedNote(commands) {
+    return `The task settled after ${BACKGROUND_COMMAND_LIMIT_MS / 60_000} minutes while this still ran in the background: ${commandList(commands)}.`;
+}
+function restartedNote(commands) {
+    return `The machine restarted while this still ran in the background: ${commandList(commands)}.`;
+}
+/* What a settled turn of a child makes of its task. */
+export function resultOfTurn(turn, items, at) {
+    if (turn.state === 'done') {
+        return { status: 'done', result: { text: answerOf(items, turn.id) ?? 'It ended its turn without an answer.', source: 'turn', at } };
+    }
+    if (turn.state === 'aborted') {
+        const text = abortedByMachine(turn, items)
+            ? (lastNote(items, turn.id, ['warning']) ?? 'The machine stopped it.')
+            : 'It was stopped before it finished.';
+        return { status: 'failed', result: { text, source: 'turn', at } };
+    }
+    return { status: 'failed', result: { text: lastNote(items, turn.id, ['error']) ?? 'Its turn ended in an error.', source: 'turn', at } };
+}
+/*
+ * Settles tasks from what children do and does nothing else: it writes the task store and owes wakes
+ * in the outbox, never starts a turn, since it runs inside the broadcast of the child it heard. A chat
+ * child settles when a turn ends with none of its own tasks still open or waiting to wake it and no work
+ * of its CLI's still running in the background, or once the commands it runs there outlast their limit;
+ * an agent that is not a chat, which the host tells it about, settles only on `done`, or fails when it
+ * ends without one.
+ */
+export class TaskCoordinator {
+    deps;
+    stopped = false;
+    pending = new Set();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /* The host is going down: what dies with it did not end its task. */
+    stop() {
+        this.stopped = true;
+    }
+    async settled() {
+        while (this.pending.size > 0) {
+            await Promise.allSettled([...this.pending]);
+        }
+        await this.deps.tasks.settled();
+    }
+    /* For `chats.observe()`. */
+    chatEvent(event) {
+        if (this.stopped || event.event !== 'chat.event') {
+            return;
+        }
+        const { chatId, event: chatEvent } = event.payload;
+        if (this.deps.loading?.(chatId)) {
+            return;
+        }
+        if (chatEvent.type === 'item' && chatEvent.item.kind === 'turn' && chatEvent.item.state === 'running') {
+            this.turnStarted(chatId);
+        }
+        else if (chatEvent.type === 'item' && chatEvent.item.kind === 'turn') {
+            this.turnEnded(chatId, chatEvent.item);
+        }
+        else if (chatEvent.type === 'item' && isBackgroundWork(chatEvent.item) && !runsInBackground(chatEvent.item)) {
+            this.recheck(chatId);
+        }
+        else if (chatEvent.type === 'info' && chatEvent.info.activeTurnId === null) {
+            // A child that waited on tasks of its own may be done now that its last wake turn went.
+            this.recheck(chatId);
+        }
+    }
+    /*
+     * An agent that is not a chat ended, so no turn of it will answer its task: it fails with `text`,
+     * which says how that kind of agent reports back.
+     */
+    agentEnded(childId, text) {
+        if (this.stopped) {
+            return;
+        }
+        const task = this.deps.tasks.openFor(childId);
+        if (!task || !this.deps.placed(childId)) {
+            return;
+        }
+        this.settle(task, 'failed', { text, source: 'exit', at: this.deps.now() });
+    }
+    startFailed(childId, error) {
+        this.failed(childId, `The agent could not be started: ${errorText(error)}`);
+    }
+    /* The turn a task given to a running agent was to open never opened, so nobody is working on it. */
+    giveFailed(childId, error) {
+        this.failed(childId, `The task could not be given: ${errorText(error)}`);
+    }
+    /* `done` from the child itself, which wins over whatever else was about to settle it. */
+    async done(childId, text) {
+        const task = this.deps.tasks.openFor(childId);
+        if (!task) {
+            return null;
+        }
+        return this.settleNow(task, 'done', { text, source: 'done', at: this.deps.now() });
+    }
+    /*
+     * The limit on the commands a child ran in the background passed, or a restart took them down with
+     * its CLI: its task settles on its last turn, saying what still ran, and fails after a restart as it
+     * does when the CLI goes within one run.
+     */
+    async outlasted(childId, commands, cause = 'limit') {
+        const task = this.deps.tasks.openFor(childId);
+        const items = this.deps.chatItems(childId);
+        if (this.stopped || !task || items === null || this.delegating(childId)) {
+            return null;
+        }
+        const last = items.findLast((item) => item.kind === 'turn');
+        if (!last || last.state === 'running' || !this.answers(items, last, task)) {
+            return null;
+        }
+        const { status, result } = resultOfTurn(last, items, this.deps.now());
+        if (cause === 'restart') {
+            return this.settleNow(task, 'failed', { ...result, text: `${result.text}\n\n${restartedNote(commands)}`, source: 'exit' });
+        }
+        return this.settleNow(task, status, { ...result, text: `${result.text}\n\n${outlastedNote(commands)}` });
+    }
+    /* Tasks of children a person removed; their parent may have been waiting on nothing else. */
+    cancelled(tasks) {
+        for (const task of tasks) {
+            this.recheck(task.parentId);
+        }
+    }
+    /* An open task of this child that nothing can carry any more. */
+    failed(childId, text) {
+        const task = this.deps.tasks.openFor(childId);
+        if (!task || this.stopped) {
+            return;
+        }
+        this.settle(task, 'failed', { text, source: 'exit', at: this.deps.now() });
+    }
+    /*
+     * Whether this turn is the one the task's result comes from. A task given to an already-working agent
+     * gets a turn of its own that names it; the turn that was in its way answers the person who sent it,
+     * not the task, and nothing settles while that turn is still owed. A turn after it answers too, as the
+     * one the CLI opens about work that turn left running. A child opened with its task has no turn of that
+     * kind, so its first turn settles it, as it always did.
+     */
+    answers(items, turn, task) {
+        if ((turn.taskIds ?? []).includes(task.id)) {
+            return true;
+        }
+        if (this.deps.owedTurn(task.id)) {
+            return false;
+        }
+        const own = items.findIndex((item) => item.kind === 'turn' && (item.taskIds ?? []).includes(task.id));
+        return own === -1 ? task.requiresTaskTurn !== true && turn.createdAt >= task.createdAt : own < items.findIndex((item) => item.id === turn.id);
+    }
+    turnEnded(chatId, turn) {
+        const task = this.deps.tasks.openFor(chatId);
+        const items = this.deps.chatItems(chatId);
+        if (!task || items === null || !this.answers(items, turn, task) || this.delegating(chatId)) {
+            return;
+        }
+        const paused = this.pauseFor(chatId, turn, items);
+        if (paused !== null) {
+            this.hold(task, paused);
+            return;
+        }
+        // A turn a person stopped or that failed ends the task as it always did, whatever still runs beside it.
+        if (turn.state === 'done' && this.heldInBackground(chatId, task, items)) {
+            this.track(this.deps.tasks.holdBackground(task.id, {
+                turnId: turn.id,
+                itemIds: runningInBackground(items).map((item) => item.id),
+                commands: this.deps.commandsOf(chatId).map(commandLabel)
+            }), `Saving the background work of task ${task.id} failed`);
+            return;
+        }
+        if (task.background?.turnId === turn.id) {
+            const after = this.deps.afterBackgroundWork(chatId);
+            if (after === 'reports') {
+                return;
+            }
+            if (after === 'gone') {
+                if (task.background.itemIds.length === 0 && this.deps.limit.owed(task.id)) {
+                    return;
+                }
+                const lost = task.background.itemIds.filter((id) => {
+                    const item = items.find((item) => item.id === id);
+                    return !item || (item.kind === 'subagent' ? item.status !== 'done' : item.kind !== 'tool' || item.state !== 'done');
+                });
+                if (lost.length > 0 || task.background.commands.length > 0) {
+                    this.settle(task, 'failed', {
+                        text: `The agent ended before its background work completed: ${[
+                            ...lost.map((id) => {
+                                const row = items.find((item) => item.id === id);
+                                return row?.kind === 'subagent' ? row.description || row.toolUseId : row?.kind === 'tool' ? row.name : id;
+                            }),
+                            ...task.background.commands
+                        ].join(', ')}. This work will not send a result.`,
+                        source: 'exit',
+                        at: this.deps.now()
+                    });
+                }
+                else {
+                    const reports = task.background.itemIds.flatMap((id) => {
+                        const row = items.find((item) => item.id === id);
+                        const report = row?.kind === 'subagent' ? row.result : row?.kind === 'tool' ? row.output : null;
+                        return report ? [report] : [];
+                    });
+                    this.settle(task, 'done', {
+                        text: reports.join('\n\n') || resultOfTurn(turn, items, this.deps.now()).result.text,
+                        source: 'turn',
+                        at: this.deps.now()
+                    });
+                }
+                return;
+            }
+        }
+        else if (turn.state === 'done' && this.deps.limit.owed(task.id) && this.deps.afterBackgroundWork(chatId) === 'gone') {
+            // After a restart nothing here remembers the turn was held, but the limit it owes does, and that settles it.
+            return;
+        }
+        const { status, result } = resultOfTurn(turn, items, this.deps.now());
+        this.settle(task, status, result);
+    }
+    /*
+     * Whether work in the background keeps this task open past the turn. Commands and monitors alone hold
+     * it only until the limit, owed from the moment they are all that is left; a subagent or a workflow
+     * running beside them holds it with no limit at all.
+     */
+    heldInBackground(chatId, task, items) {
+        if (runningInBackground(items).length > 0) {
+            if (this.deps.limit.owed(task.id)) {
+                void this.deps.limit.lapse(task.id).catch((e) => console.error(`Dropping the limit of task ${task.id} failed:`, errorText(e)));
+            }
+            return true;
+        }
+        const commands = this.deps.commandsOf(chatId);
+        if (commands.length === 0) {
+            return false;
+        }
+        if (!this.deps.limit.owed(task.id)) {
+            void this.deps.limit
+                .owe(task, commands.map(commandLabel), this.deps.now() + BACKGROUND_COMMAND_LIMIT_MS)
+                .catch((e) => console.error(`Owing the limit of task ${task.id} failed:`, errorText(e)));
+        }
+        return true;
+    }
+    /*
+     * A limit is work waiting, not work that failed: the plan's limit always holds the task until the child
+     * finishes after it, an overload only while the host still owes the turn another try.
+     */
+    pauseFor(chatId, turn, items) {
+        const limit = turn.state === 'error' ? turn.limit : undefined;
+        if (limit?.kind === 'usage') {
+            return { kind: 'usage', ...(limit.resetsAt === undefined ? {} : { until: limit.resetsAt }) };
+        }
+        if (limit?.kind === 'overload') {
+            const at = this.deps.retryAt?.(chatId, turn, items) ?? null;
+            return at === null ? null : { kind: 'overload', until: at };
+        }
+        return null;
+    }
+    /* A child that took up work again is no longer waiting out a limit. */
+    turnStarted(chatId) {
+        const task = this.deps.tasks.openFor(chatId);
+        if (task?.paused !== undefined) {
+            this.hold(task, null);
+        }
+    }
+    hold(task, paused) {
+        void this.deps.tasks.pause(task.id, paused).catch((e) => console.error(`Pausing task ${task.id} failed:`, errorText(e)));
+    }
+    recheck(chatId) {
+        const task = this.deps.tasks.openFor(chatId);
+        const items = this.deps.chatItems(chatId);
+        if (!task || items === null || this.delegating(chatId)) {
+            return;
+        }
+        const last = [...items].reverse().find((item) => item.kind === 'turn');
+        if (last && last.state !== 'running' && last.createdAt >= task.createdAt) {
+            this.turnEnded(chatId, last);
+        }
+    }
+    /* A child that gave tasks of its own is not finished while one is open or has yet to wake it. */
+    delegating(chatId) {
+        return this.deps.tasks.ofParent(chatId).some((task) => task.status === 'open' || task.wake === 'pending');
+    }
+    settle(task, status, result) {
+        this.track(this.settleNow(task, status, result), `Settling task ${task.id} failed`);
+    }
+    track(work, message) {
+        this.pending.add(work);
+        void work.catch((e) => console.error(`${message}:`, errorText(e))).finally(() => this.pending.delete(work));
+    }
+    async settleNow(task, status, result) {
+        const settled = await this.deps.tasks.settle(task.id, status, result, this.deps.now());
+        if (!settled) {
+            return null;
+        }
+        await this.deps.oweWake(settled);
+        if (status === 'failed') {
+            this.deps.alert(settled.childId, `Task failed: ${settled.title}`, clipText(result.text, 500));
+        }
+        return settled;
+    }
+}

package/dist/tasks/task-store.d.ts

@@ -0,0 +1,49 @@
+import { type Task, type TaskChangedEvent, type TaskResult } from '@adecore/agent-contracts';
+export type TaskListener = (task: Task) => void;
+export interface TaskEvent {
+    event: 'task.changed';
+    payload: TaskChangedEvent;
+}
+export type TaskSink = (event: TaskEvent) => void;
+export declare class TaskStore {
+    readonly dir: string;
+    private readonly tasks;
+    private readonly listeners;
+    private readonly sinks;
+    private readonly writes;
+    constructor(dataDir: string, options?: {
+        write?: (path: string, text: string) => Promise<void>;
+    });
+    load(): Promise<void>;
+    onChange(listener: TaskListener): () => void;
+    subscribe(clientId: string, sink: TaskSink): () => void;
+    open(record: {
+        projectId: string;
+        parentId: string;
+        childId: string;
+        title: string;
+        prompt: string;
+        batchId?: string;
+        requiresTaskTurn?: boolean;
+    }, now: number): Promise<Task>;
+    all(): Task[];
+    settled(): Promise<void>;
+    holdBackground(id: string, background: NonNullable<Task['background']>): Promise<void>;
+    get(id: string): Task | undefined;
+    openFor(childId: string): Task | undefined;
+    involving(nodeId: string): Task[];
+    ofParent(parentId: string): Task[];
+    ofProject(projectId: string): Task[];
+    settle(id: string, status: 'done' | 'failed' | 'cancelled', result: TaskResult | null, now: number): Promise<Task | null>;
+    pause(id: string, paused: NonNullable<Task['paused']> | null): Promise<boolean>;
+    cancelOpen(childIds: ReadonlySet<string>, reason: string, now: number): Promise<Task[]>;
+    markWoken(ids: readonly string[]): Promise<void>;
+    pendingWake(parentId: string): Task[];
+    readyWake(parentId: string): Task[];
+    openBatches(parentId: string): string[];
+    dropWake(parentId: string): Promise<void>;
+    prune(projectId: string, ids: ReadonlySet<string>, now: number): Promise<Task[]>;
+    private sorted;
+    private write;
+    private writeNow;
+}

package/dist/tasks/task-store.js

@@ -0,0 +1,197 @@
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { TaskSchema } from '@adecore/agent-contracts';
+import { ClientSinks } from '../client-sinks.js';
+import { RecordDirectory } from '../record-directory.js';
+/*
+ * What a chat asked of the nodes it opened with `--task`, one file per task under `<dataDir>/tasks`,
+ * beside the lineage and for the same reason: an agent with a shell in the project folder can rewrite
+ * the project's files, and waking the parent is a promise the host keeps. A settled task stays until
+ * its parent leaves the project, so the parent can still list what came of it.
+ */
+export class TaskStore {
+    dir;
+    tasks;
+    listeners = new Set();
+    sinks = new ClientSinks();
+    writes = new Set();
+    constructor(dataDir, options = {}) {
+        this.dir = join(dataDir, 'tasks');
+        this.tasks = new RecordDirectory({ dir: this.dir, schema: TaskSchema, idOf: (task) => task.id, ...options });
+    }
+    /* Reads what an earlier run of the host wrote down. Call before any verb or observer can ask. */
+    load() {
+        return this.tasks.load();
+    }
+    /* Told about every task that is written, after it is on disk. */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /* Every socket hears every task: the edge and the header of a child are drawn from it. */
+    subscribe(clientId, sink) {
+        return this.sinks.subscribe(clientId, sink);
+    }
+    async open(record, now) {
+        const task = {
+            ...record,
+            id: `task-${randomBytes(6).toString('hex')}`,
+            status: 'open',
+            result: null,
+            createdAt: now,
+            settledAt: null,
+            wake: 'pending'
+        };
+        await this.write(task);
+        return task;
+    }
+    all() {
+        return this.sorted();
+    }
+    async settled() {
+        while (this.writes.size > 0) {
+            await Promise.all([...this.writes]);
+        }
+    }
+    async holdBackground(id, background) {
+        const task = this.get(id);
+        if (!task || task.status !== 'open' || JSON.stringify(task.background) === JSON.stringify(background)) {
+            return;
+        }
+        await this.write({ ...task, background });
+    }
+    get(id) {
+        return this.tasks.get(id);
+    }
+    /* The task a node is working on; a node has at most one, the one it was opened with. */
+    openFor(childId) {
+        return this.tasks.all().find((task) => task.childId === childId && task.status === 'open');
+    }
+    /* Every task this node gave or was given, oldest first. */
+    involving(nodeId) {
+        return this.sorted().filter((task) => task.parentId === nodeId || task.childId === nodeId);
+    }
+    ofParent(parentId) {
+        return this.sorted().filter((task) => task.parentId === parentId);
+    }
+    ofProject(projectId) {
+        return this.sorted().filter((task) => task.projectId === projectId);
+    }
+    /*
+     * Ends an open task with its result; false when it was not open any more, which is how the first of
+     * `done`, the end of a turn and an exit wins. A cancelled task wakes nobody.
+     */
+    async settle(id, status, result, now) {
+        const task = this.tasks.get(id);
+        if (!task || task.status !== 'open') {
+            return null;
+        }
+        const { paused: _paused, ...open } = task;
+        const settled = { ...open, status, result, settledAt: now, wake: status === 'cancelled' ? 'none' : task.wake };
+        await this.write(settled);
+        return settled;
+    }
+    /* Holds an open task while its child waits out a limit, or lets it go on with null; false when it was not open. */
+    async pause(id, paused) {
+        const task = this.tasks.get(id);
+        if (!task || task.status !== 'open') {
+            return false;
+        }
+        if (JSON.stringify(task.paused ?? null) === JSON.stringify(paused)) {
+            return true;
+        }
+        const { paused: _was, ...rest } = task;
+        await this.write(paused === null ? rest : { ...rest, paused });
+        return true;
+    }
+    /* Cancels the open tasks of these children, with the reason as the result; a cancelled task wakes nobody. */
+    async cancelOpen(childIds, reason, now) {
+        const cancelled = [];
+        for (const task of this.sorted()) {
+            if (task.status === 'open' && childIds.has(task.childId)) {
+                const settled = await this.settle(task.id, 'cancelled', { text: reason, source: 'exit', at: now }, now);
+                if (settled) {
+                    cancelled.push(settled);
+                }
+            }
+        }
+        return cancelled;
+    }
+    async markWoken(ids) {
+        for (const id of ids) {
+            const task = this.tasks.get(id);
+            if (task && task.wake === 'pending') {
+                await this.write({ ...task, wake: 'sent' });
+            }
+        }
+    }
+    pendingWake(parentId) {
+        return this.ofParent(parentId).filter((task) => task.status !== 'open' && task.wake === 'pending');
+    }
+    /*
+     * The part of `pendingWake` that may wake the parent now. A task of a `team --task` call is held back
+     * until every task of that call settled, so one team is one answer however far apart its roles finish.
+     */
+    readyWake(parentId) {
+        const open = new Set(this.openBatches(parentId));
+        return this.pendingWake(parentId).filter((task) => task.batchId === undefined || !open.has(task.batchId));
+    }
+    /* The batches of this parent with a task still open, oldest first. */
+    openBatches(parentId) {
+        const ids = this.ofParent(parentId).flatMap((task) => (task.status === 'open' && task.batchId !== undefined ? [task.batchId] : []));
+        return [...new Set(ids)];
+    }
+    /* A parent nobody can wake any more: its settled tasks stop waiting for it. */
+    async dropWake(parentId) {
+        for (const task of this.ofParent(parentId)) {
+            if (task.wake === 'pending') {
+                await this.write({ ...task, wake: 'none' });
+            }
+        }
+    }
+    /*
+     * What this project wrote down for ids it no longer has. A task whose parent is gone has nobody to
+     * report to and goes; an open task whose child is gone is cancelled and stays, so its parent sees why.
+     */
+    async prune(projectId, ids, now) {
+        const cancelled = [];
+        for (const task of this.sorted()) {
+            if (task.projectId !== projectId) {
+                continue;
+            }
+            if (!ids.has(task.parentId)) {
+                await this.tasks.remove(task.id);
+                continue;
+            }
+            if (!ids.has(task.childId) && task.status === 'open') {
+                const settled = await this.settle(task.id, 'cancelled', null, now);
+                if (settled) {
+                    cancelled.push(settled);
+                }
+            }
+        }
+        return cancelled;
+    }
+    sorted() {
+        // A stable sort: tasks made in the same millisecond keep the order they were made in.
+        return this.tasks.all().sort((a, b) => a.createdAt - b.createdAt);
+    }
+    write(task) {
+        const write = this.writeNow(task);
+        this.writes.add(write);
+        void write.finally(() => this.writes.delete(write)).catch(() => undefined);
+        return write;
+    }
+    async writeNow(task) {
+        // Only the write that is still the latest tells anyone: an older record never lands after it.
+        if (!(await this.tasks.write(task))) {
+            return;
+        }
+        for (const listener of this.listeners) {
+            listener(task);
+        }
+        this.sinks.emit({ event: 'task.changed', payload: { task } });
+    }
+}

package/dist/tasks/task-work.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import type { OutboxEntryOf, OutboxWorkShape } from '../outbox/outbox.ts';
+export declare const BackgroundLimitWorkSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"background-limit">;
+    payload: z.ZodObject<{
+        taskId: z.ZodString;
+        commands: z.ZodArray<z.ZodString>;
+        restarted: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const WakeParentWorkSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"wake-parent">;
+    payload: z.ZodObject<{
+        taskId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const GiveTaskWorkSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"give-task">;
+    payload: z.ZodObject<{
+        taskId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const DeliverWaitingWorkSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"deliver-waiting">;
+    payload: z.ZodObject<{
+        childId: z.ZodString;
+        requestId: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type BackgroundLimitWork = z.infer<typeof BackgroundLimitWorkSchema>;
+export type WakeParentWork = z.infer<typeof WakeParentWorkSchema>;
+export type GiveTaskWork = z.infer<typeof GiveTaskWorkSchema>;
+export type DeliverWaitingWork = z.infer<typeof DeliverWaitingWorkSchema>;
+export type TaskWork = BackgroundLimitWork | WakeParentWork | GiveTaskWork | DeliverWaitingWork;
+export type BackgroundLimitEntry = OutboxEntryOf<BackgroundLimitWork>;
+export type WakeParentEntry = OutboxEntryOf<WakeParentWork>;
+export type GiveTaskEntry = OutboxEntryOf<GiveTaskWork>;
+export type DeliverWaitingEntry = OutboxEntryOf<DeliverWaitingWork>;
+export type AnyOutboxEntry = OutboxEntryOf<OutboxWorkShape>;
+export interface TaskOutbox {
+    list(): readonly AnyOutboxEntry[];
+    enqueue(projectId: string, target: string, work: TaskWork, notBefore?: number): Promise<void>;
+    remove(id: string): Promise<void>;
+    wake(target: string): void;
+}
+export declare function isBackgroundLimit(entry: AnyOutboxEntry): entry is BackgroundLimitEntry;
+export declare function isGiveTask(entry: AnyOutboxEntry): entry is GiveTaskEntry;

package/dist/tasks/task-work.js

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+export const BackgroundLimitWorkSchema = z.object({
+    kind: z.literal('background-limit'),
+    // The target is the child; the task its background commands hold open, and what they were when the limit started, for a child whose process went since.
+    // `restarted` marks an entry an earlier run of the host owed, whose commands went down with it.
+    payload: z.object({ taskId: z.string().min(1), commands: z.array(z.string()), restarted: z.literal(true).optional() })
+});
+export const WakeParentWorkSchema = z.object({
+    kind: z.literal('wake-parent'),
+    // The target is the chat to wake; the task that settled is only what owed it, since a wake takes every settled task.
+    payload: z.object({ taskId: z.string().min(1) })
+});
+export const GiveTaskWorkSchema = z.object({
+    kind: z.literal('give-task'),
+    // The target is the agent the task went to; the record itself holds what it asks and who asked.
+    payload: z.object({ taskId: z.string().min(1) })
+});
+export const DeliverWaitingWorkSchema = z.object({
+    kind: z.literal('deliver-waiting'),
+    // The target is the chat that gave the child its task; the child waits on this request of its own.
+    payload: z.object({ childId: z.string().min(1), requestId: z.string().min(1) })
+});
+export function isBackgroundLimit(entry) {
+    return entry.kind === 'background-limit';
+}
+export function isGiveTask(entry) {
+    return entry.kind === 'give-task';
+}