@adecore/agents 0.0.1 → 0.17.0-beta.1

package/dist/record-directory.js

@@ -0,0 +1,114 @@
+import { mkdir, readdir, readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isNotFound, writeAtomic } from './fs.js';
+import { KeyedSerializer } from './serializer.js';
+// The id is a node id or a chat id a client chose, so it is encoded before it becomes a file name.
+export function recordFileName(id) {
+    return `${encodeURIComponent(id)}.json`;
+}
+/*
+ * One kind of record under a host's data folder, a file per record and the whole of it in memory. A file
+ * that does not parse is left alone rather than deleted: it is a record of an older or newer host,
+ * and the one thing worse than not reading it is throwing it away.
+ */
+export class RecordDirectory {
+    dir;
+    schema;
+    idOf;
+    writeFile;
+    keep;
+    records = new Map();
+    // One write at a time per record, so an older one never lands after a newer one.
+    writes = new KeyedSerializer();
+    constructor(options) {
+        this.dir = options.dir;
+        this.schema = options.schema;
+        this.idOf = options.idOf;
+        this.writeFile = options.write ?? writeAtomic;
+        this.keep = options.keep ?? null;
+    }
+    /* Reads what an earlier run of the host wrote down. Call before anything can ask. */
+    async load() {
+        let names;
+        try {
+            names = await readdir(this.dir);
+        }
+        catch (e) {
+            if (isNotFound(e)) {
+                return;
+            }
+            throw e;
+        }
+        for (const name of names) {
+            if (!name.endsWith('.json')) {
+                continue;
+            }
+            const raw = await readFile(join(this.dir, name), 'utf8').catch(() => null);
+            if (raw === null) {
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = this.schema.safeParse(JSON.parse(raw));
+            }
+            catch {
+                continue;
+            }
+            if (!parsed.success) {
+                continue;
+            }
+            const record = this.keep === null ? parsed.data : this.keep(parsed.data);
+            if (record === null) {
+                await rm(join(this.dir, name), { force: true });
+                continue;
+            }
+            this.records.set(this.idOf(record), record);
+        }
+    }
+    get(id) {
+        return this.records.get(id);
+    }
+    has(id) {
+        return this.records.has(id);
+    }
+    all() {
+        return [...this.records.values()];
+    }
+    /*
+     * Holds the record in memory at once, so the next question in the same tick already sees it, and
+     * answers whether it is still the one this directory holds by the time the file is written. A
+     * record removed while its file was being written does not come back: the rename is undone.
+     */
+    write(record) {
+        const id = this.idOf(record);
+        this.records.set(id, record);
+        return this.writes.run(id, async () => {
+            if (this.records.get(id) !== record) {
+                return false;
+            }
+            await mkdir(this.dir, { recursive: true, mode: 0o700 });
+            await this.writeFile(this.pathOf(id), JSON.stringify(record));
+            if (!this.records.has(id)) {
+                await rm(this.pathOf(id), { force: true });
+                return false;
+            }
+            return true;
+        });
+    }
+    /* Forgets a record here and now; its file follows. */
+    remove(id) {
+        this.records.delete(id);
+        return rm(this.pathOf(id), { force: true });
+    }
+    /* Drops every record the predicate says is gone. */
+    async prune(drop) {
+        for (const record of this.all()) {
+            if (drop(record)) {
+                await this.remove(this.idOf(record));
+            }
+        }
+    }
+    pathOf(id) {
+        return join(this.dir, recordFileName(id));
+    }
+}

package/dist/run-process.d.ts

@@ -0,0 +1,13 @@
+export interface ProcessResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+export interface RunProcessOptions {
+    env?: Record<string, string | undefined>;
+    cwd?: string;
+    stdin?: string;
+    timeoutMs?: number;
+    timeoutMessage?: string;
+}
+export declare function runProcess(command: readonly string[], options?: RunProcessOptions): Promise<ProcessResult>;

package/dist/run-process.js

@@ -0,0 +1,42 @@
+import { spawn } from 'node:child_process';
+/* One short command to its end, with what it printed. A command that cannot start rejects. */
+export function runProcess(command, options = {}) {
+    return new Promise((resolve, reject) => {
+        const [executable, ...args] = command;
+        if (executable === undefined) {
+            reject(new Error('No command to run'));
+            return;
+        }
+        const child = spawn(executable, args, {
+            ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+            ...(options.env === undefined ? {} : { env: options.env }),
+            stdio: [options.stdin === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe']
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout?.on('data', (chunk) => stdout.push(chunk));
+        child.stderr?.on('data', (chunk) => stderr.push(chunk));
+        const timer = options.timeoutMs === undefined
+            ? null
+            : setTimeout(() => {
+                child.kill('SIGTERM');
+                reject(new Error(options.timeoutMessage ?? `${executable} did not finish in time`));
+            }, options.timeoutMs);
+        child.on('error', (error) => {
+            if (timer !== null) {
+                clearTimeout(timer);
+            }
+            reject(error);
+        });
+        child.on('close', (exitCode) => {
+            if (timer !== null) {
+                clearTimeout(timer);
+            }
+            resolve({ exitCode, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') });
+        });
+        if (options.stdin !== undefined && child.stdin) {
+            child.stdin.on('error', () => undefined);
+            child.stdin.end(options.stdin);
+        }
+    });
+}

package/dist/serializer.d.ts

@@ -0,0 +1,9 @@
+export declare class Serializer {
+    private chain;
+    run<T>(work: () => Promise<T>): Promise<T>;
+    idle(): Promise<void>;
+}
+export declare class KeyedSerializer {
+    private readonly chains;
+    run<T>(key: string, work: () => Promise<T>): Promise<T>;
+}

package/dist/serializer.js

@@ -0,0 +1,34 @@
+/*
+ * One writer at a time: the next piece of work starts once the one before it settled, whether that
+ * one kept its promise or not, and every caller hears its own result. Two changes in a row never
+ * read the same file and drop one of them.
+ */
+export class Serializer {
+    chain = Promise.resolve();
+    run(work) {
+        const next = this.chain.then(work, work);
+        this.chain = next.catch(() => undefined);
+        return next;
+    }
+    /* Resolves once what is queued has settled, without adding work of its own. */
+    idle() {
+        return this.chain.then(() => undefined, () => undefined);
+    }
+}
+/* The same per key, for a store whose records are written one by one and never wait on each other. */
+export class KeyedSerializer {
+    chains = new Map();
+    run(key, work) {
+        const previous = this.chains.get(key) ?? Promise.resolve();
+        const next = previous.then(work, work);
+        const settled = next.catch(() => undefined);
+        this.chains.set(key, settled);
+        // A key whose chain ran out leaves nothing behind, or the map grows with every id ever written.
+        void settled.then(() => {
+            if (this.chains.get(key) === settled) {
+                this.chains.delete(key);
+            }
+        });
+        return next;
+    }
+}

package/dist/skills.d.ts

@@ -0,0 +1,21 @@
+import type { AgentKind, ChatSkill, ChatSkillSource } from '@adecore/agent-contracts';
+export interface SkillRoot {
+    dir: string;
+    source: ChatSkillSource;
+    prefix?: string;
+}
+export interface SkillRootOptions {
+    home?: string;
+    claudeConfigDir?: string;
+}
+export declare function parseFrontmatter(text: string): Record<string, string>;
+export declare function pluginSkillRoots(configDir: string): Promise<SkillRoot[]>;
+export declare function skillRootsFor(kind: AgentKind, cwd: string, options?: SkillRootOptions): Promise<SkillRoot[]>;
+export declare function scanSkillRoots(roots: SkillRoot[]): Promise<ChatSkill[]>;
+export declare function discoverSkills(kind: AgentKind, cwd: string, options?: SkillRootOptions): Promise<ChatSkill[]>;
+export declare class SkillIndex {
+    private readonly options;
+    private readonly cache;
+    constructor(options?: SkillRootOptions);
+    list(kind: AgentKind, cwd: string): Promise<ChatSkill[]>;
+}

package/dist/skills.js

@@ -0,0 +1,174 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, parse } from 'node:path';
+import { isNotFound } from './fs.js';
+const NAME = /^[A-Za-z][A-Za-z0-9_:-]*$/;
+function unquote(value) {
+    const quoted = /^(['"])([\s\S]*)\1$/.exec(value);
+    return quoted ? quoted[2] : value;
+}
+/*
+ * The `key: value` pairs of a SKILL.md front matter. Enough YAML for what a skill file holds: flat
+ * keys, quoted or bare values, and the block scalars (`>-`, `|`) a long description is written as.
+ */
+export function parseFrontmatter(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (!match) {
+        return {};
+    }
+    const fields = {};
+    const lines = match[1].split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const pair = /^([A-Za-z0-9_-]+):[ \t]*(.*)$/.exec(lines[i]);
+        if (!pair) {
+            continue;
+        }
+        let value = pair[2].trim();
+        if (value === '' || value === '>' || value === '>-' || value === '|' || value === '|-') {
+            // A block scalar puts the value on the indented lines under it; `|` keeps the newlines.
+            const keepNewlines = value.startsWith('|');
+            const parts = [];
+            while (i + 1 < lines.length && /^[ \t]+\S/.test(lines[i + 1])) {
+                parts.push(lines[++i].trim());
+            }
+            value = parts.join(keepNewlines ? '\n' : ' ');
+        }
+        fields[pair[1]] = unquote(value);
+    }
+    return fields;
+}
+/*
+ * The folders from `cwd` up to and including the repository root, closest first. The home folder
+ * itself is not one of them, since its `.claude/skills` is already the user root.
+ */
+function projectDirs(cwd, home) {
+    const dirs = [];
+    let current = cwd;
+    while (current !== '' && current !== parse(current).root && current !== home && current !== dirname(home) && dirs.length < 8) {
+        dirs.push(current);
+        // Anything above a repository root belongs to another project, so the walk ends there.
+        if (existsSync(join(current, '.git'))) {
+            break;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    return dirs;
+}
+/* The plugin folders Claude Code installed, each named the way its skills are addressed. */
+export async function pluginSkillRoots(configDir) {
+    let raw;
+    try {
+        raw = await readFile(join(configDir, 'plugins', 'installed_plugins.json'), 'utf8');
+    }
+    catch (e) {
+        if (isNotFound(e)) {
+            return [];
+        }
+        throw e;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    const plugins = typeof parsed === 'object' && parsed !== null ? parsed.plugins : undefined;
+    if (typeof plugins !== 'object' || plugins === null) {
+        return [];
+    }
+    const roots = [];
+    for (const [key, installs] of Object.entries(plugins)) {
+        const name = key.split('@')[0] ?? key;
+        for (const install of Array.isArray(installs) ? installs : []) {
+            const path = typeof install === 'object' && install !== null ? install.installPath : undefined;
+            if (typeof path === 'string' && path !== '') {
+                roots.push({ dir: join(path, 'skills'), source: 'plugin', prefix: name });
+            }
+        }
+    }
+    return roots;
+}
+/* Where a provider's CLI looks for skills, in the order a name clash is decided. */
+export async function skillRootsFor(kind, cwd, options = {}) {
+    const home = options.home ?? homedir();
+    if (kind === 'codex') {
+        return [
+            { dir: join(home, '.agents', 'skills'), source: 'user' },
+            { dir: join(home, '.codex', 'skills'), source: 'user' },
+            ...projectDirs(cwd, home).map((dir) => ({ dir: join(dir, '.agents', 'skills'), source: 'project' }))
+        ];
+    }
+    const configDir = options.claudeConfigDir ?? join(home, '.claude');
+    return [
+        { dir: join(configDir, 'skills'), source: 'user' },
+        ...projectDirs(cwd, home).map((dir) => ({ dir: join(dir, '.claude', 'skills'), source: 'project' })),
+        ...(await pluginSkillRoots(configDir))
+    ];
+}
+async function readSkill(root, folder) {
+    let text;
+    try {
+        text = await readFile(join(root.dir, folder, 'SKILL.md'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const fields = parseFrontmatter(text);
+    const own = fields.name && NAME.test(fields.name) ? fields.name : folder;
+    const name = root.prefix ? `${root.prefix}:${own}` : own;
+    if (!NAME.test(name)) {
+        return null;
+    }
+    return { name, description: fields.description ?? '', source: root.source };
+}
+/* Every skill under these roots, sorted by name; the first root that carries a name wins. */
+export async function scanSkillRoots(roots) {
+    const found = new Map();
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = await readdir(root.dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        // A skill manager links each skill in from a shared folder; a link to anything but a skill folder reads as no skill.
+        const folders = entries.filter((entry) => entry.isDirectory() || entry.isSymbolicLink());
+        const skills = await Promise.all(folders.map((entry) => readSkill(root, entry.name)));
+        for (const skill of skills) {
+            if (skill && !found.has(skill.name)) {
+                found.set(skill.name, skill);
+            }
+        }
+    }
+    return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+export async function discoverSkills(kind, cwd, options = {}) {
+    return scanSkillRoots(await skillRootsFor(kind, cwd, options));
+}
+// How long a scan stays good; a skill written mid-session shows up on the next look.
+const CACHE_TTL_MS = 30_000;
+/* The skills of one CLI in one folder, scanned at most once per half minute. There is no watcher. */
+export class SkillIndex {
+    options;
+    cache = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async list(kind, cwd) {
+        const key = `${kind}:${cwd}`;
+        const cached = this.cache.get(key);
+        if (cached && Date.now() - cached.at < CACHE_TTL_MS) {
+            return cached.skills;
+        }
+        const skills = await discoverSkills(kind, cwd, this.options);
+        this.cache.set(key, { at: Date.now(), skills });
+        return skills;
+    }
+}

package/dist/tasks/background-limit.d.ts

@@ -0,0 +1,16 @@
+import { type ChatOpenerDeps } from '../chat/wake-chat.ts';
+import type { OutboxOutcome } from '../outbox/outbox-worker.ts';
+import type { TaskCoordinator, TaskCoordinatorDeps } from './task-coordinator.ts';
+import type { TaskStore } from './task-store.ts';
+import { type AnyOutboxEntry, type BackgroundLimitEntry, type TaskOutbox } from './task-work.ts';
+export interface BackgroundLimitDeps extends ChatOpenerDeps {
+    tasks: Pick<TaskStore, 'get'>;
+    coordinator: Pick<TaskCoordinator, 'outlasted'>;
+}
+export declare function backgroundLimitHandler(deps: BackgroundLimitDeps): (entry: BackgroundLimitEntry) => Promise<OutboxOutcome>;
+export interface RestartedOutbox {
+    list(): readonly AnyOutboxEntry[];
+    update(entry: BackgroundLimitEntry): Promise<void>;
+}
+export declare function restartBackgroundLimits(outbox: RestartedOutbox, now: number): Promise<void>;
+export declare function backgroundLimits(outbox: Pick<TaskOutbox, 'list' | 'enqueue' | 'remove'>): TaskCoordinatorDeps['limit'];

package/dist/tasks/background-limit.js

@@ -0,0 +1,55 @@
+import { commandLabel, runningInBackground } from '../chat/background-work.js';
+import { loadChat } from '../chat/wake-chat.js';
+import { isBackgroundLimit } from './task-work.js';
+/*
+ * The limit on a child's background commands passed, or a restart took them down. Its task settles on
+ * the child's last turn (failed after a restart), unless something else settled it first or a subagent
+ * or a workflow now holds it, which has no limit; a turn in flight may still answer it, so the limit
+ * looks again once that turn ended.
+ */
+export function backgroundLimitHandler(deps) {
+    return async (entry) => {
+        if (deps.tasks.get(entry.payload.taskId)?.status !== 'open') {
+            return;
+        }
+        const chat = await loadChat(deps, entry.target);
+        if (chat === null) {
+            return;
+        }
+        if (chat.info.activeTurnId !== null) {
+            return 'wait';
+        }
+        if (runningInBackground(chat.thread.list()).length > 0) {
+            return;
+        }
+        // A child whose process went since the limit started runs nothing any more; what it ran then is what the parent is told.
+        const running = (chat.info.background ?? []).map(commandLabel);
+        await deps.coordinator.outlasted(entry.target, running.length > 0 ? running : entry.payload.commands, entry.payload.restarted ? 'restart' : 'limit');
+    };
+}
+/*
+ * Every limit still owed when the host starts was owed by an earlier run, and the CLI whose commands
+ * it waits on went down with that run, so nothing is left to wait for: each is due now and fails its
+ * task. Call after the outbox loaded and before its worker starts.
+ */
+export async function restartBackgroundLimits(outbox, now) {
+    for (const entry of outbox.list()) {
+        if (isBackgroundLimit(entry)) {
+            await outbox.update({ ...entry, notBefore: now, payload: { ...entry.payload, restarted: true } });
+        }
+    }
+}
+/* The `background-limit` entries of a host's outbox, one per task at most, as the coordinator owes and drops them. */
+export function backgroundLimits(outbox) {
+    return {
+        owed: (taskId) => outbox.list().some((entry) => isBackgroundLimit(entry) && entry.payload.taskId === taskId),
+        owe: (task, commands, at) => outbox.enqueue(task.projectId, task.childId, { kind: 'background-limit', payload: { taskId: task.id, commands: [...commands] } }, at),
+        lapse: async (taskId) => {
+            for (const entry of outbox.list()) {
+                if (isBackgroundLimit(entry) && entry.payload.taskId === taskId) {
+                    await outbox.remove(entry.id);
+                }
+            }
+        }
+    };
+}

package/dist/tasks/end-children.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import type { AgentLineageStore } from '../lineage.ts';
+import type { OutboxEntryOf } from '../outbox/outbox.ts';
+import type { TaskStore } from './task-store.ts';
+import type { AnyOutboxEntry } from './task-work.ts';
+export declare const EndChildrenWorkSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"end-children">;
+    payload: z.ZodObject<{
+        nodeIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type EndChildrenWork = z.infer<typeof EndChildrenWorkSchema>;
+export type EndChildrenEntry = OutboxEntryOf<EndChildrenWork>;
+export interface EndChildrenOutbox {
+    list(): readonly AnyOutboxEntry[];
+    enqueue(projectId: string, target: string, work: EndChildrenWork): Promise<void>;
+    remove(id: string): Promise<void>;
+}
+export interface EndChildrenDeps {
+    lineage: Pick<AgentLineageStore, 'descendants' | 'projectOf' | 'markEnded'>;
+    tasks: Pick<TaskStore, 'cancelOpen' | 'dropWake'>;
+    outbox: EndChildrenOutbox;
+    reviving?: readonly string[];
+    reason: string;
+    stop(nodeId: string, reason: string): Promise<void>;
+    ended?: (nodeIds: readonly string[]) => Promise<void>;
+    now?: () => number;
+}
+export interface EndChildren {
+    owe(target: string, nodeIds?: readonly string[]): Promise<number>;
+    handler(entry: EndChildrenEntry): Promise<void>;
+    end(nodeIds: readonly string[], reason: string): Promise<void>;
+}
+export declare function endChildren(deps: EndChildrenDeps): EndChildren;

package/dist/tasks/end-children.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+export const EndChildrenWorkSchema = z.object({
+    kind: z.literal('end-children'),
+    // The target is the node that was stopped or deleted; these are the agents it had opened when that was owed.
+    payload: z.object({ nodeIds: z.array(z.string().min(1)) })
+});
+/* The work of tasks that would start or wake an agent again; an agent that was ended has none of it left. */
+const TASK_REVIVING = ['wake-parent', 'give-task'];
+/*
+ * The ending of agents and the ones they opened. Marked first, so a restart halfway through finishes
+ * the same way; then the work that would bring one back goes, the open tasks are cancelled before any
+ * turn is aborted (so no parent is woken by an agent that was stopped), and the leaves stop before
+ * the nodes that opened them. Every step is safe to run twice.
+ */
+export function endChildren(deps) {
+    const { lineage, tasks, outbox } = deps;
+    const now = deps.now ?? Date.now;
+    const reviving = new Set([...TASK_REVIVING, ...(deps.reviving ?? [])]);
+    const end = async (nodeIds, reason) => {
+        await lineage.markEnded(nodeIds);
+        const ended = new Set(nodeIds);
+        for (const owed of outbox.list()) {
+            if (reviving.has(owed.kind) && ended.has(owed.target)) {
+                await outbox.remove(owed.id);
+            }
+        }
+        await tasks.cancelOpen(ended, reason, now());
+        // A stopped chat that gave tasks of its own is not woken about them either.
+        for (const nodeId of nodeIds) {
+            await tasks.dropWake(nodeId);
+        }
+        for (const nodeId of [...nodeIds].reverse()) {
+            await deps.stop(nodeId, reason);
+        }
+        await deps.ended?.(nodeIds);
+    };
+    return {
+        owe: async (target, named) => {
+            const nodeIds = named === undefined ? lineage.descendants(target) : [...named];
+            const projectId = nodeIds.map((id) => lineage.projectOf(id)).find((id) => id !== null) ?? null;
+            if (nodeIds.length === 0 || projectId === null) {
+                return 0;
+            }
+            const owed = outbox.list().some((entry) => entry.kind === 'end-children' && entry.target === target);
+            if (!owed) {
+                await outbox.enqueue(projectId, target, { kind: 'end-children', payload: { nodeIds } });
+            }
+            return nodeIds.length;
+        },
+        handler: (entry) => end([...new Set([...entry.payload.nodeIds, ...lineage.descendants(entry.target)])], deps.reason),
+        end
+    };
+}

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

@@ -0,0 +1,14 @@
+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 { GiveTaskEntry } from './task-work.ts';
+export declare function taskNote(from: string): string;
+export interface GiveTaskDeps {
+    tasks: Pick<TaskStore, 'get'>;
+    chat(chatId: string): Promise<WakeChat | null>;
+    titleFor(nodeId: string): string | null;
+    placed(nodeId: string): boolean;
+    assignment?: (task: Task) => string;
+}
+export declare function giveTaskHandler(deps: GiveTaskDeps): (entry: GiveTaskEntry) => Promise<OutboxOutcome>;

package/dist/tasks/give-task.js

@@ -0,0 +1,33 @@
+/* The note above the turn a task opens, so whoever reads the child sees who asked for it. */
+export function taskNote(from) {
+    return `Task from ${from}`;
+}
+/*
+ * Opens the turn that carries a task given to an agent already running. A turn in the way makes this
+ * `wait`, the same as a person's own message, so nothing the host owes steps on what the agent is
+ * doing. One agent holds one task at a time, so the task is never queued twice.
+ */
+export function giveTaskHandler(deps) {
+    return async (entry) => {
+        const task = deps.tasks.get(entry.payload.taskId);
+        // Settled or cancelled before the turn could open, or a node the project no longer places.
+        if (!task || task.status !== 'open' || !deps.placed(task.childId)) {
+            return;
+        }
+        const chat = await deps.chat(task.childId);
+        if (chat === null) {
+            throw new Error(`${task.childId} has no chat to open a turn in`);
+        }
+        // The turn names the task, so a restart between opening it and dropping this entry gives it once.
+        if (chat.items().some((item) => item.kind === 'turn' && (item.taskIds ?? []).includes(task.id))) {
+            await chat.persist?.();
+            return;
+        }
+        const from = deps.titleFor(task.parentId) ?? task.parentId;
+        const text = deps.assignment?.(task) ?? task.prompt;
+        if (!chat.wake({ text, label: task.title, note: taskNote(from), taskIds: [task.id] })) {
+            return 'wait';
+        }
+        await chat.persist?.();
+    };
+}

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

@@ -0,0 +1,52 @@
+import type { ChatBackgroundTask, ChatItem, ChatTurnItem, Task, TaskResult } from '@adecore/agent-contracts';
+import type { AgentEvent } from '../events.ts';
+import type { TaskStore } from './task-store.ts';
+export interface TaskCoordinatorDeps {
+    tasks: TaskStore;
+    now(): number;
+    chatItems(chatId: string): readonly ChatItem[] | null;
+    placed(nodeId: string): boolean;
+    loading?(chatId: string): boolean;
+    owedTurn(taskId: string): boolean;
+    oweWake(task: Task): Promise<void>;
+    alert(nodeId: string, title: string, body: string): void;
+    retryAt?(chatId: string, turn: ChatTurnItem, items: readonly ChatItem[]): number | null;
+    afterBackgroundWork(chatId: string): 'reports' | 'silent' | 'gone';
+    commandsOf(chatId: string): readonly ChatBackgroundTask[];
+    limit: {
+        owed(taskId: string): boolean;
+        owe(task: Task, commands: readonly string[], at: number): Promise<void>;
+        lapse(taskId: string): Promise<void>;
+    };
+}
+export declare function resultOfTurn(turn: ChatTurnItem, items: readonly ChatItem[], at: number): {
+    status: 'done' | 'failed';
+    result: TaskResult;
+};
+export declare class TaskCoordinator {
+    private readonly deps;
+    private stopped;
+    private readonly pending;
+    constructor(deps: TaskCoordinatorDeps);
+    stop(): void;
+    settled(): Promise<void>;
+    chatEvent(event: AgentEvent): void;
+    agentEnded(childId: string, text: string): void;
+    startFailed(childId: string, error: unknown): void;
+    giveFailed(childId: string, error: unknown): void;
+    done(childId: string, text: string): Promise<Task | null>;
+    outlasted(childId: string, commands: readonly string[], cause?: 'limit' | 'restart'): Promise<Task | null>;
+    cancelled(tasks: readonly Task[]): void;
+    private failed;
+    private answers;
+    private turnEnded;
+    private heldInBackground;
+    private pauseFor;
+    private turnStarted;
+    private hold;
+    private recheck;
+    private delegating;
+    private settle;
+    private track;
+    private settleNow;
+}