@adecore/agents 0.0.1 → 0.17.0-beta.1

package/src/tasks/task-store.ts

@@ -0,0 +1,236 @@
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { TaskSchema, type Task, type TaskChangedEvent, type TaskResult } from '@adecore/agent-contracts';
+import { ClientSinks } from '../client-sinks.ts';
+import { RecordDirectory } from '../record-directory.ts';
+
+export type TaskListener = (task: Task) => void;
+
+/* What a client hears of a task: the whole of it, every time it is written. */
+export interface TaskEvent {
+    event: 'task.changed';
+    payload: TaskChangedEvent;
+}
+
+export type TaskSink = (event: TaskEvent) => void;
+
+/*
+ * 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 {
+    readonly dir: string;
+    private readonly tasks: RecordDirectory<Task>;
+    private readonly listeners = new Set<TaskListener>();
+    private readonly sinks = new ClientSinks<TaskEvent>();
+    private readonly writes = new Set<Promise<void>>();
+
+    constructor(dataDir: string, options: { write?: (path: string, text: string) => Promise<void> } = {}) {
+        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(): Promise<void> {
+        return this.tasks.load();
+    }
+
+    /* Told about every task that is written, after it is on disk. */
+    onChange(listener: TaskListener): () => void {
+        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: string, sink: TaskSink): () => void {
+        return this.sinks.subscribe(clientId, sink);
+    }
+
+    async open(
+        record: { projectId: string; parentId: string; childId: string; title: string; prompt: string; batchId?: string; requiresTaskTurn?: boolean },
+        now: number
+    ): Promise<Task> {
+        const task: 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(): Task[] {
+        return this.sorted();
+    }
+
+    async settled(): Promise<void> {
+        while (this.writes.size > 0) {
+            await Promise.all([...this.writes]);
+        }
+    }
+
+    async holdBackground(id: string, background: NonNullable<Task['background']>): Promise<void> {
+        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: string): Task | undefined {
+        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: string): Task | undefined {
+        return this.tasks.all().find((task) => task.childId === childId && task.status === 'open');
+    }
+
+    /* Every task this node gave or was given, oldest first. */
+    involving(nodeId: string): Task[] {
+        return this.sorted().filter((task) => task.parentId === nodeId || task.childId === nodeId);
+    }
+
+    ofParent(parentId: string): Task[] {
+        return this.sorted().filter((task) => task.parentId === parentId);
+    }
+
+    ofProject(projectId: string): Task[] {
+        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: string, status: 'done' | 'failed' | 'cancelled', result: TaskResult | null, now: number): Promise<Task | null> {
+        const task = this.tasks.get(id);
+        if (!task || task.status !== 'open') {
+            return null;
+        }
+        const { paused: _paused, ...open } = task;
+        const settled: Task = { ...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: string, paused: NonNullable<Task['paused']> | null): Promise<boolean> {
+        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: ReadonlySet<string>, reason: string, now: number): Promise<Task[]> {
+        const cancelled: Task[] = [];
+        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: readonly string[]): Promise<void> {
+        for (const id of ids) {
+            const task = this.tasks.get(id);
+            if (task && task.wake === 'pending') {
+                await this.write({ ...task, wake: 'sent' });
+            }
+        }
+    }
+
+    pendingWake(parentId: string): Task[] {
+        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: string): Task[] {
+        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: string): string[] {
+        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: string): Promise<void> {
+        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: string, ids: ReadonlySet<string>, now: number): Promise<Task[]> {
+        const cancelled: Task[] = [];
+        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;
+    }
+
+    private sorted(): Task[] {
+        // 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);
+    }
+
+    private write(task: Task): Promise<void> {
+        const write = this.writeNow(task);
+        this.writes.add(write);
+        void write.finally(() => this.writes.delete(write)).catch(() => undefined);
+        return write;
+    }
+
+    private async writeNow(task: Task): Promise<void> {
+        // 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/src/tasks/task-work.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import type { OutboxEntryOf, OutboxWorkShape } from '../outbox/outbox.ts';
+
+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 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>;
+
+/* The work tasks owe, which a host puts in the discriminated union of its outbox beside its own kinds. */
+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>;
+
+/* An entry of whatever kinds a host owes, as tasks read its outbox. */
+export type AnyOutboxEntry = OutboxEntryOf<OutboxWorkShape>;
+
+/* The outbox of a host as tasks use it, whatever else the host owes in it. */
+export interface TaskOutbox {
+    /* Every entry the host owes, of any kind, oldest first. */
+    list(): readonly AnyOutboxEntry[];
+    /* `notBefore` is when the work is due; now without it. */
+    enqueue(projectId: string, target: string, work: TaskWork, notBefore?: number): Promise<void>;
+    remove(id: string): Promise<void>;
+    /* The work of this target that answered `wait` may go on now. */
+    wake(target: string): void;
+}
+
+export function isBackgroundLimit(entry: AnyOutboxEntry): entry is BackgroundLimitEntry {
+    return entry.kind === 'background-limit';
+}
+
+export function isGiveTask(entry: AnyOutboxEntry): entry is GiveTaskEntry {
+    return entry.kind === 'give-task';
+}

package/src/tasks/waiting-child.ts

@@ -0,0 +1,203 @@
+import { clipText, type ChatApprovalItem, type ChatItem, type ChatQuestionItem, type Task } from '@adecore/agent-contracts';
+import type { ChatCore } from '../chat/chat-core.ts';
+import { errorText } from '../error-text.ts';
+import type { AgentEvent } from '../events.ts';
+import type { OutboxOutcome } from '../outbox/outbox-worker.ts';
+import type { DeliverWaitingEntry, TaskWork } from './task-work.ts';
+
+/* What a child waits on: an answer anyone may give, or an approval only a person gives. */
+export type WaitingRequest = ChatQuestionItem | ChatApprovalItem;
+
+export function isPendingRequest(item: ChatItem | null | undefined): item is WaitingRequest {
+    return (item?.kind === 'question' && item.state === 'pending') || (item?.kind === 'approval' && item.decision === 'pending');
+}
+
+/* What the chats of agent nodes ask and wait on, which a verb such as `answer` reaches. */
+export interface ChatRequests {
+    /* The one under this request id, in whatever state; null when the chat holds none, or nobody loaded it. */
+    request(nodeId: string, requestId: string): WaitingRequest | null;
+    /* Those it waits on now, oldest first. */
+    waiting(nodeId: string): WaitingRequest[];
+    /* Answers a pending question the way a person's `chat.answer` does; false when it no longer waits. */
+    answer(nodeId: string, requestId: string, answers: Record<string, string>): boolean;
+}
+
+/* Read off the chats the host has loaded: a chat nobody loaded since a restart waits on nothing. */
+export function chatRequests(chats: Pick<ChatCore, 'get' | 'answer'>): ChatRequests {
+    return {
+        request: (nodeId, requestId) => {
+            // The projector writes each under the kind it is.
+            const thread = chats.get(nodeId)?.thread;
+            const item = thread?.get(`question-${requestId}`) ?? thread?.get(`approval-${requestId}`);
+            return item?.kind === 'question' || item?.kind === 'approval' ? item : null;
+        },
+        waiting: (nodeId) => (chats.get(nodeId)?.thread.list() ?? []).filter(isPendingRequest),
+        answer: (nodeId, requestId, answers) => {
+            try {
+                chats.answer(nodeId, requestId, answers);
+                return true;
+            } catch {
+                return false;
+            }
+        }
+    };
+}
+
+/* The id of the note one request of one child leaves in its parent, so delivering it twice leaves one. */
+export function waitingNoteId(childId: string, requestId: string): string {
+    return `waiting-${childId}-${requestId}`;
+}
+
+/*
+ * How long a request may wait before its parent hears of it. A person watching the child settles one
+ * within seconds (1.5 to 7 seconds in a run of Claude Code 2.1.282), and a note about that is stale
+ * before the parent reads it.
+ */
+export const WAITING_GRACE_MS = 15_000;
+
+export interface WaitingObserverDeps {
+    openTask(childId: string): Task | undefined;
+    enqueue(projectId: string, target: string, work: TaskWork, notBefore: number): Promise<void>;
+    now(): number;
+    log?(message: string): void;
+}
+
+/*
+ * Notes that a child with an open task asked something, and owes its parent one note in the outbox,
+ * due once the request waited out `WAITING_GRACE_MS`. It never writes the note itself, since it runs
+ * inside the broadcast of the child it heard, and it never wakes the parent: a finished task and a
+ * message are the only things that wake a chat.
+ */
+export class WaitingObserver {
+    private readonly deps: WaitingObserverDeps;
+    // A pending item is upserted again as it changes; one entry per request is enough, and the handler is idempotent after a restart.
+    private readonly owed = new Set<string>();
+    private stopped = false;
+
+    constructor(deps: WaitingObserverDeps) {
+        this.deps = deps;
+    }
+
+    stop(): void {
+        this.stopped = true;
+    }
+
+    /* For `chats.observe()`. */
+    chatEvent(event: AgentEvent): void {
+        if (this.stopped || event.event !== 'chat.event') {
+            return;
+        }
+        const { chatId, event: chatEvent } = event.payload;
+        if (chatEvent.type !== 'item' || !isPendingRequest(chatEvent.item)) {
+            return;
+        }
+        const task = this.deps.openTask(chatId);
+        const key = `${chatId}\n${chatEvent.item.requestId}`;
+        if (task === undefined || this.owed.has(key)) {
+            return;
+        }
+        this.owed.add(key);
+        void this.deps
+            .enqueue(
+                task.projectId,
+                task.parentId,
+                { kind: 'deliver-waiting', payload: { childId: chatId, requestId: chatEvent.item.requestId } },
+                this.deps.now() + WAITING_GRACE_MS
+            )
+            .catch((e: unknown) => (this.deps.log ?? console.error)(`Owing a note about ${chatId} failed: ${errorText(e)}`));
+    }
+}
+
+function quoted(text: string): string {
+    return JSON.stringify(text.replace(/\s+/g, ' ').trim());
+}
+
+/* The one line a note shows before "Show more": a question longer than that is read in the node. */
+const NOTE_QUESTION_LENGTH = 200;
+
+function quotedShort(text: string): string {
+    const line = text.replace(/\s+/g, ' ').trim();
+    return JSON.stringify(line.length > NOTE_QUESTION_LENGTH ? `${clipText(line, NOTE_QUESTION_LENGTH - 1)}…` : line);
+}
+
+/* One question as the parent's CLI reads it, with the choices it may pick from. */
+function questionLine(question: ChatQuestionItem['questions'][number]): string {
+    const choices = question.choices.map((choice) => (choice.description === '' ? choice.label : `${choice.label} (${choice.description})`));
+    const how =
+        choices.length === 0
+            ? 'answer in your own words'
+            : `choices: ${choices.join(' | ')}; ${question.multiSelect ? 'pick one or more' : 'pick one'}, or answer in your own words`;
+    return `- question ${question.id}: ${quoted(question.question)} (${how})`;
+}
+
+/*
+ * The words a host speaks in: its name, at the head of what a parent's CLI hears, and the command an
+ * agent types, whose `answer <child> <request> --answer A` or `--answers JSON` answers a child's question.
+ */
+export interface WaitingWords {
+    app: string;
+    cli: string;
+}
+
+/* The call that answers it, in the shape the verb takes for this many questions. */
+function answerCall(cli: string, childId: string, item: ChatQuestionItem): string {
+    if (item.questions.length === 1) {
+        const multi = item.questions[0]!.multiSelect ? ', several labels in one --answer separated by a comma' : '';
+        return `${cli} answer ${childId} ${item.requestId} --answer '<a choice label as written, or your own words>'${multi}`;
+    }
+    const shape = Object.fromEntries(item.questions.map((question) => [question.id, '...']));
+    return `${cli} answer ${childId} ${item.requestId} --answers '${JSON.stringify(shape)}', one answer per question id`;
+}
+
+/*
+ * What the parent's thread shows and what its CLI hears, from one request of one child. The note's
+ * first line is what a person sees at a glance; under it, what the CLI hears in front of its next turn.
+ */
+export function waitingTexts(child: { id: string; title: string }, item: WaitingRequest, words: WaitingWords): { note: string; preamble: string } {
+    const who = `${child.title} (node ${child.id})`;
+    if (item.kind === 'approval') {
+        const what = item.description === null ? item.toolName : `${item.toolName}: ${item.description}`;
+        return {
+            note: `${who} waits for a person to approve ${what}`,
+            preamble: [
+                `${words.app}: ${who}, an agent you gave a task, waits for a person to approve ${what} (request ${item.requestId}). This did not wake you.`,
+                'Only a person answers an approval; there is no verb for it. If it holds up your plan, tell the person.'
+            ].join('\n')
+        };
+    }
+    const asked = item.questions.length === 1 ? quotedShort(item.questions[0]!.question) : `${item.questions.length} questions`;
+    const how = [
+        ...item.questions.map(questionLine),
+        `A person can answer it in that node, and this chat with ${answerCall(words.cli, child.id, item)}. Whoever answers first wins; the verb refuses a question that was answered already.`
+    ];
+    return {
+        note: [`${who} waits for an answer to ${asked}`, '', ...how].join('\n'),
+        preamble: [
+            `${words.app}: ${who}, an agent you gave a task, asked a question and waits for an answer (request ${item.requestId}). This did not wake you.`,
+            ...how
+        ].join('\n')
+    };
+}
+
+export interface DeliverWaitingDeps {
+    request: ChatRequests['request'];
+    titleFor(nodeId: string): string | null;
+    deliver(chatId: string, delivery: { noteId: string; note: string; preamble: string }): Promise<boolean>;
+    words: WaitingWords;
+}
+
+/*
+ * Leaves the note in the parent, once. A request that no longer waits (answered, allowed, taken back
+ * by its CLI, or cancelled by a restart) is news about nothing, so it says nothing.
+ */
+export function deliverWaitingHandler(deps: DeliverWaitingDeps) {
+    return async (entry: DeliverWaitingEntry): Promise<OutboxOutcome> => {
+        const { childId, requestId } = entry.payload;
+        const item = deps.request(childId, requestId);
+        if (!isPendingRequest(item)) {
+            return;
+        }
+        const texts = waitingTexts({ id: childId, title: deps.titleFor(childId) ?? childId }, item, deps.words);
+        await deps.deliver(entry.target, { noteId: waitingNoteId(childId, requestId), ...texts });
+    };
+}

package/src/tasks/wake-parent.ts

@@ -0,0 +1,142 @@
+import type { Task } from '@adecore/agent-contracts';
+import type { WakeChat } from '../chat/wake-chat.ts';
+import type { OutboxOutcome } from '../outbox/outbox-worker.ts';
+import type { TaskStore } from './task-store.ts';
+import type { TaskWork, WakeParentEntry } from './task-work.ts';
+
+/* What the parent reads of one result; the rest stays with the child, whose id is right beside it. */
+export const RESULT_PREVIEW_BYTES = 8 * 1024;
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/* The first `bytes` of a text without cutting a character in half, and whether anything was left off. */
+function cutAt(text: string, bytes: number): { text: string; cut: boolean } {
+    const encoded = encoder.encode(text);
+    if (encoded.length <= bytes) {
+        return { text, cut: false };
+    }
+    return { text: decoder.decode(encoded.slice(0, bytes)).replace(/\uFFFD$/, ''), cut: true };
+}
+
+/*
+ * The prompt a woken chat's CLI gets. Every task is named with its child's id, so the agent can go
+ * on with that node (read it, notify it) without asking which one it was. `restOf` says where the rest
+ * of a result that was cut is to be read.
+ */
+export function wakePrompt(tasks: readonly Task[], teamsOut = 0, restOf?: (childId: string) => string): string {
+    const head = tasks.length === 1 ? 'A task you gave has settled. Its result:' : `${tasks.length} tasks you gave have settled. Their results:`;
+    const sections = tasks.map((task) => {
+        const { text, cut } = cutAt(task.result?.text ?? '', RESULT_PREVIEW_BYTES);
+        const lines = [`## ${task.title} (node ${task.childId}, task ${task.id}): ${task.status}`, '', text === '' ? '(no result text)' : text];
+        if (cut) {
+            const rest = restOf === undefined ? '' : ` ${restOf(task.childId)}`;
+            lines.push('', `[The result was cut at ${RESULT_PREVIEW_BYTES / 1024} KiB.${rest}]`);
+        }
+        return lines.join('\n');
+    });
+    const together = tasks.some((task) => task.batchId !== undefined)
+        ? ['The tasks of one team call come in together, once every one of them has settled.']
+        : [];
+    const out =
+        teamsOut === 0
+            ? []
+            : [
+                  `${teamsOut === 1 ? 'A team you gave is' : `${teamsOut} teams you gave are`} still out: you are woken with all of a team's results once its last task settles.`
+              ];
+    return [head, ...sections, ...together, ...out].join('\n\n');
+}
+
+/* The label of the turn a wake opens: what a person reads above it in the thread. */
+export function wakeLabel(tasks: readonly Task[]): string {
+    return tasks.map((task) => task.title).join(', ');
+}
+
+export function wakeNote(tasks: readonly Task[]): string {
+    return `Woken by ${tasks.length} finished ${tasks.length === 1 ? 'task' : 'tasks'}`;
+}
+
+export interface WakeParentDeps {
+    tasks: Pick<TaskStore, 'pendingWake' | 'readyWake' | 'openBatches' | 'markWoken' | 'dropWake'>;
+    /* The chat as it is now, loading it from disk when nobody has; null for a chat that has no thread any more. */
+    chat(chatId: string): Promise<WakeChat | null>;
+    /* Where the rest of a result that was cut is read, after the line that says so. */
+    restOf?: (childId: string) => string;
+}
+
+/*
+ * CLI acceptance lives in the saved turn before the task store consumes its result, so a restart
+ * between those writes can finish delivery without opening another turn.
+ */
+export function wakeParentHandler(deps: WakeParentDeps) {
+    return async (entry: WakeParentEntry): Promise<OutboxOutcome> => {
+        const parentId = entry.target;
+        const pending = deps.tasks.pendingWake(parentId);
+        if (pending.length === 0) {
+            return;
+        }
+        const held = (): OutboxOutcome => (deps.tasks.readyWake(parentId).length < deps.tasks.pendingWake(parentId).length ? 'wait' : undefined);
+        // Nothing to say yet, so the chat is not loaded from disk for it.
+        if (deps.tasks.readyWake(parentId).length === 0) {
+            return held();
+        }
+        const chat = await deps.chat(parentId);
+        if (chat === null) {
+            await deps.tasks.dropWake(parentId);
+            return;
+        }
+        const items = chat.items();
+        const named = new Set(items.flatMap((item) => (item.kind === 'turn' && !item.deliveryPending ? (item.taskIds ?? []) : [])));
+        const already = deps.tasks.pendingWake(parentId).filter((task) => named.has(task.id));
+        if (already.length > 0) {
+            await chat.persist?.();
+            await deps.tasks.markWoken(already.map((task) => task.id));
+        }
+        const tasks = deps.tasks.readyWake(parentId).filter((task) => !named.has(task.id));
+        if (tasks.length === 0) {
+            return held();
+        }
+        // An unacknowledged attempt waits for a person's next turn, rather than retrying on every chat event.
+        const blocked = items.some(
+            (item, index) =>
+                item.kind === 'turn' &&
+                item.deliveryPending &&
+                item.taskIds?.some((id) => tasks.some((task) => task.id === id)) &&
+                (item.state === 'running' || !items.slice(index + 1).some((later) => later.kind === 'turn' && later.origin !== 'agent'))
+        );
+        if (blocked) {
+            return 'wait';
+        }
+        const teamsOut = deps.tasks.openBatches(parentId).length;
+        if (
+            !chat.wake({
+                text: wakePrompt(tasks, teamsOut, deps.restOf),
+                label: wakeLabel(tasks),
+                note: wakeNote(tasks),
+                taskIds: tasks.map((task) => task.id)
+            })
+        ) {
+            return 'wait';
+        }
+        await chat.persist?.();
+        if (
+            tasks.some((task) => {
+                const turn = chat.items().findLast((item) => item.kind === 'turn' && item.taskIds?.includes(task.id));
+                return turn?.kind === 'turn' && turn.deliveryPending;
+            })
+        ) {
+            return 'wait';
+        }
+        await deps.tasks.markWoken(tasks.map((task) => task.id));
+        return held();
+    };
+}
+
+export interface OweWakeDeps {
+    enqueue(projectId: string, target: string, work: TaskWork): Promise<void>;
+}
+
+/* A settled task owes its parent a wake; one entry per task, and the first to run takes every task there is. */
+export function oweWake(deps: OweWakeDeps, task: Task): Promise<void> {
+    return deps.enqueue(task.projectId, task.parentId, { kind: 'wake-parent', payload: { taskId: task.id } });
+}