@adecore/agents 0.0.1 → 0.17.0-beta.1

package/dist/tasks/waiting-child.d.ts

@@ -0,0 +1,51 @@
+import { type ChatApprovalItem, type ChatItem, type ChatQuestionItem, type Task } from '@adecore/agent-contracts';
+import type { ChatCore } from '../chat/chat-core.ts';
+import type { AgentEvent } from '../events.ts';
+import type { OutboxOutcome } from '../outbox/outbox-worker.ts';
+import type { DeliverWaitingEntry, TaskWork } from './task-work.ts';
+export type WaitingRequest = ChatQuestionItem | ChatApprovalItem;
+export declare function isPendingRequest(item: ChatItem | null | undefined): item is WaitingRequest;
+export interface ChatRequests {
+    request(nodeId: string, requestId: string): WaitingRequest | null;
+    waiting(nodeId: string): WaitingRequest[];
+    answer(nodeId: string, requestId: string, answers: Record<string, string>): boolean;
+}
+export declare function chatRequests(chats: Pick<ChatCore, 'get' | 'answer'>): ChatRequests;
+export declare function waitingNoteId(childId: string, requestId: string): string;
+export declare const WAITING_GRACE_MS = 15000;
+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;
+}
+export declare class WaitingObserver {
+    private readonly deps;
+    private readonly owed;
+    private stopped;
+    constructor(deps: WaitingObserverDeps);
+    stop(): void;
+    chatEvent(event: AgentEvent): void;
+}
+export interface WaitingWords {
+    app: string;
+    cli: string;
+}
+export declare function waitingTexts(child: {
+    id: string;
+    title: string;
+}, item: WaitingRequest, words: WaitingWords): {
+    note: string;
+    preamble: string;
+};
+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;
+}
+export declare function deliverWaitingHandler(deps: DeliverWaitingDeps): (entry: DeliverWaitingEntry) => Promise<OutboxOutcome>;

package/dist/tasks/waiting-child.js

@@ -0,0 +1,143 @@
+import { clipText } from '@adecore/agent-contracts';
+import { errorText } from '../error-text.js';
+export function isPendingRequest(item) {
+    return (item?.kind === 'question' && item.state === 'pending') || (item?.kind === 'approval' && item.decision === 'pending');
+}
+/* Read off the chats the host has loaded: a chat nobody loaded since a restart waits on nothing. */
+export function chatRequests(chats) {
+    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, requestId) {
+    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;
+/*
+ * 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 {
+    deps;
+    // A pending item is upserted again as it changes; one entry per request is enough, and the handler is idempotent after a restart.
+    owed = new Set();
+    stopped = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    stop() {
+        this.stopped = true;
+    }
+    /* For `chats.observe()`. */
+    chatEvent(event) {
+        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) => (this.deps.log ?? console.error)(`Owing a note about ${chatId} failed: ${errorText(e)}`));
+    }
+}
+function quoted(text) {
+    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) {
+    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) {
+    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 call that answers it, in the shape the verb takes for this many questions. */
+function answerCall(cli, childId, item) {
+    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, item, words) {
+    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')
+    };
+}
+/*
+ * 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) {
+    return async (entry) => {
+        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/dist/tasks/wake-parent.d.ts

@@ -0,0 +1,19 @@
+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';
+export declare const RESULT_PREVIEW_BYTES: number;
+export declare function wakePrompt(tasks: readonly Task[], teamsOut?: number, restOf?: (childId: string) => string): string;
+export declare function wakeLabel(tasks: readonly Task[]): string;
+export declare function wakeNote(tasks: readonly Task[]): string;
+export interface WakeParentDeps {
+    tasks: Pick<TaskStore, 'pendingWake' | 'readyWake' | 'openBatches' | 'markWoken' | 'dropWake'>;
+    chat(chatId: string): Promise<WakeChat | null>;
+    restOf?: (childId: string) => string;
+}
+export declare function wakeParentHandler(deps: WakeParentDeps): (entry: WakeParentEntry) => Promise<OutboxOutcome>;
+export interface OweWakeDeps {
+    enqueue(projectId: string, target: string, work: TaskWork): Promise<void>;
+}
+export declare function oweWake(deps: OweWakeDeps, task: Task): Promise<void>;

package/dist/tasks/wake-parent.js

@@ -0,0 +1,109 @@
+/* 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, bytes) {
+    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, teamsOut = 0, restOf) {
+    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) {
+    return tasks.map((task) => task.title).join(', ');
+}
+export function wakeNote(tasks) {
+    return `Woken by ${tasks.length} finished ${tasks.length === 1 ? 'task' : 'tasks'}`;
+}
+/*
+ * 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) {
+    return async (entry) => {
+        const parentId = entry.target;
+        const pending = deps.tasks.pendingWake(parentId);
+        if (pending.length === 0) {
+            return;
+        }
+        const held = () => (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();
+    };
+}
+/* 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, task) {
+    return deps.enqueue(task.projectId, task.parentId, { kind: 'wake-parent', payload: { taskId: task.id } });
+}

package/dist/tasks/wiring.d.ts

@@ -0,0 +1,51 @@
+import type { Task } from '@adecore/agent-contracts';
+import type { ChatCore } from '../chat/chat-core.ts';
+import type { OutboxHandlers } from '../outbox/outbox-worker.ts';
+import { TaskCoordinator, type TaskCoordinatorDeps } from './task-coordinator.ts';
+import type { TaskStore } from './task-store.ts';
+import { type AnyOutboxEntry, type TaskOutbox, type TaskWork } from './task-work.ts';
+import { WaitingObserver, type ChatRequests, type WaitingWords } from './waiting-child.ts';
+export type TaskChats = Pick<ChatCore, 'get' | 'observe' | 'hasStored' | 'create' | 'answer' | 'deliverNote' | 'isLoading' | 'storedBackground' | 'save'>;
+export interface TaskRecord {
+    projectId: string;
+    parentId: string;
+    childId: string;
+    title: string;
+    prompt: string;
+}
+export interface TaskVerbs {
+    open(record: TaskRecord & {
+        batchId?: string;
+    }): Promise<Task>;
+    give(record: TaskRecord): Promise<Task>;
+    chatState(nodeId: string): Promise<'none' | 'idle' | 'running'>;
+    done(childId: string, text: string): Promise<Task | null>;
+    involving(nodeId: string): Task[];
+}
+export interface TaskWords extends WaitingWords {
+    assignment?: (task: Task) => string;
+    restOf?: (childId: string) => string;
+}
+export interface TaskWiringDeps {
+    tasks: TaskStore;
+    chats: TaskChats;
+    outbox: TaskOutbox;
+    placed(nodeId: string): boolean;
+    titleFor(nodeId: string): string | null;
+    alert(nodeId: string, title: string, body: string): void;
+    changed?: (task: Task) => void;
+    retryAt?: TaskCoordinatorDeps['retryAt'];
+    words: TaskWords;
+    now?: () => number;
+}
+export interface TaskWiring {
+    coordinator: TaskCoordinator;
+    recover(): Promise<void>;
+    waiting: WaitingObserver;
+    verbs: TaskVerbs;
+    requests: ChatRequests;
+    handlers: OutboxHandlers<TaskWork>;
+    onParked(entry: AnyOutboxEntry, error: unknown): void;
+    prune(projectId: string, ids: ReadonlySet<string>): Promise<void>;
+}
+export declare function wireTasks(deps: TaskWiringDeps): TaskWiring;

package/dist/tasks/wiring.js

@@ -0,0 +1,151 @@
+import { reportsOnBackgroundWork } from '../chat/background-work.js';
+import { chatOpener, loadChat } from '../chat/wake-chat.js';
+import { errorText } from '../error-text.js';
+import { backgroundLimitHandler, backgroundLimits } from './background-limit.js';
+import { giveTaskHandler } from './give-task.js';
+import { TaskCoordinator } from './task-coordinator.js';
+import { isGiveTask } from './task-work.js';
+import { chatRequests, deliverWaitingHandler, WaitingObserver } from './waiting-child.js';
+import { oweWake, wakeParentHandler } from './wake-parent.js';
+/*
+ * The tasks of a host in one place, so the host only hands in what it has: the coordinator that
+ * settles, the work the outbox runs, the notes in a parent's thread and what the verbs reach.
+ */
+export function wireTasks(deps) {
+    const now = deps.now ?? Date.now;
+    const { chats, outbox } = deps;
+    const enqueue = (projectId, target, work, notBefore) => outbox.enqueue(projectId, target, work, notBefore);
+    const limit = backgroundLimits(outbox);
+    const coordinator = new TaskCoordinator({
+        tasks: deps.tasks,
+        now,
+        chatItems: (chatId) => chats.get(chatId)?.thread.list() ?? null,
+        placed: (nodeId) => deps.placed(nodeId),
+        loading: (chatId) => chats.isLoading(chatId),
+        // Until the turn that carries a task ran, no turn of the child is its answer.
+        owedTurn: (taskId) => outbox.list().some((entry) => isGiveTask(entry) && entry.payload.taskId === taskId),
+        oweWake: (task) => oweWake({ enqueue }, task),
+        alert: (nodeId, title, body) => deps.alert(nodeId, title, body),
+        ...(deps.retryAt ? { retryAt: deps.retryAt } : {}),
+        afterBackgroundWork: (chatId) => {
+            const chat = chats.get(chatId);
+            if (!chat?.running) {
+                return 'gone';
+            }
+            return reportsOnBackgroundWork(chat.info.provider) ? 'reports' : 'silent';
+        },
+        commandsOf: (chatId) => chats.get(chatId)?.info.background ?? [],
+        limit
+    });
+    deps.tasks.onChange((task) => {
+        deps.changed?.(task);
+        // A cancelled task owes no wake of its own, but it may be the last of a team whose held results now go out.
+        if (task.status === 'cancelled' && task.batchId !== undefined) {
+            outbox.wake(task.parentId);
+        }
+        // However a task ended, the limit on its child's background commands has nothing left to settle.
+        if (task.status !== 'open' && limit.owed(task.id)) {
+            void limit.lapse(task.id).catch((e) => console.error(`Dropping the limit of task ${task.id} failed:`, errorText(e)));
+        }
+    });
+    const requests = chatRequests(chats);
+    const waiting = new WaitingObserver({ openTask: (childId) => deps.tasks.openFor(childId), enqueue, now });
+    chats.observe((event) => {
+        coordinator.chatEvent(event);
+        waiting.chatEvent(event);
+        if (event.event === 'chat.event' && chats.get(event.payload.chatId)?.info.activeTurnId === null) {
+            outbox.wake(event.payload.chatId);
+        }
+    });
+    const chatFor = chatOpener({ chats, placed: deps.placed });
+    return {
+        coordinator,
+        recover: async () => {
+            for (const task of deps.tasks.all()) {
+                if (task.status === 'open' && task.requiresTaskTurn === true && deps.placed(task.childId)) {
+                    if (!outbox.list().some((entry) => isGiveTask(entry) && entry.payload.taskId === task.id)) {
+                        await enqueue(task.projectId, task.childId, { kind: 'give-task', payload: { taskId: task.id } });
+                    }
+                }
+                const storedBackground = task.status === 'open' ? await chats.storedBackground(task.childId) : { turnId: null, items: [], commands: [] };
+                if (task.status === 'open' &&
+                    deps.placed(task.childId) &&
+                    (task.background !== undefined ||
+                        task.requiresTaskTurn === true ||
+                        storedBackground.items.length > 0 ||
+                        storedBackground.commands.length > 0)) {
+                    if (task.background === undefined &&
+                        storedBackground.turnId !== null &&
+                        (storedBackground.items.length > 0 || storedBackground.commands.length > 0)) {
+                        await deps.tasks.holdBackground(task.id, {
+                            turnId: storedBackground.turnId,
+                            itemIds: storedBackground.items.map((item) => item.id),
+                            commands: storedBackground.commands
+                        });
+                    }
+                    const chat = await loadChat({ chats, placed: deps.placed }, task.childId);
+                    if (chat && chat.info.activeTurnId === null) {
+                        const last = chat.thread.list().findLast((item) => item.kind === 'turn');
+                        if (last?.kind === 'turn') {
+                            coordinator.chatEvent({ event: 'chat.event', payload: { chatId: task.childId, event: { type: 'item', item: last } } });
+                        }
+                    }
+                }
+            }
+            await coordinator.settled();
+            for (const task of deps.tasks.all()) {
+                if (task.status !== 'open' &&
+                    task.wake === 'pending' &&
+                    !outbox.list().some((entry) => entry.kind === 'wake-parent' && entry.payload.taskId === task.id)) {
+                    await oweWake({ enqueue }, task);
+                }
+            }
+        },
+        waiting,
+        verbs: {
+            open: (record) => deps.tasks.open(record, now()),
+            give: async (record) => {
+                // The record first: the handler reads what the task asks from it, and a restart in between still owes the turn.
+                const task = await deps.tasks.open({ ...record, requiresTaskTurn: true }, now());
+                await enqueue(task.projectId, task.childId, { kind: 'give-task', payload: { taskId: task.id } });
+                return task;
+            },
+            chatState: async (nodeId) => {
+                const session = chats.get(nodeId);
+                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(nodeId)) ? 'idle' : 'none';
+            },
+            done: (childId, text) => coordinator.done(childId, text),
+            involving: (nodeId) => deps.tasks.involving(nodeId)
+        },
+        requests,
+        handlers: {
+            'wake-parent': wakeParentHandler({ tasks: deps.tasks, chat: chatFor, ...(deps.words.restOf ? { restOf: deps.words.restOf } : {}) }),
+            'background-limit': backgroundLimitHandler({ tasks: deps.tasks, coordinator, chats, placed: deps.placed }),
+            'give-task': giveTaskHandler({
+                tasks: deps.tasks,
+                chat: chatFor,
+                titleFor: deps.titleFor,
+                placed: deps.placed,
+                ...(deps.words.assignment ? { assignment: deps.words.assignment } : {})
+            }),
+            'deliver-waiting': deliverWaitingHandler({
+                request: requests.request,
+                titleFor: deps.titleFor,
+                deliver: (chatId, delivery) => chats.deliverNote(chatId, delivery),
+                words: { app: deps.words.app, cli: deps.words.cli }
+            })
+        },
+        onParked: (entry, error) => {
+            if (isGiveTask(entry)) {
+                coordinator.giveFailed(entry.target, error);
+            }
+        },
+        prune: async (projectId, ids) => {
+            coordinator.cancelled(await deps.tasks.prune(projectId, ids, now()));
+        }
+    };
+}

package/dist/title-file.d.ts

@@ -0,0 +1,2 @@
+export declare function cleanTitle(raw: unknown): string | null;
+export declare function readLines(path: string, from: number, size: number, chunkBytes: number, onLine: (line: string) => void): Promise<number>;

package/dist/title-file.js

@@ -0,0 +1,55 @@
+import { open } from 'node:fs/promises';
+import { clipText, SUGGESTED_TITLE_LIMIT } from '@adecore/agent-contracts';
+// oxlint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u001f\u007f]+/g;
+/*
+ * A model wrote this, so it is text and nothing else: no control characters, no line breaks, one
+ * space between words and a length a header can hold.
+ */
+export function cleanTitle(raw) {
+    if (typeof raw !== 'string') {
+        return null;
+    }
+    const text = raw.replace(CONTROL, ' ').replace(/\s+/g, ' ').trim();
+    if (text === '') {
+        return null;
+    }
+    return text.length <= SUGGESTED_TITLE_LIMIT ? text : `${clipText(text, SUGGESTED_TITLE_LIMIT - 1).trimEnd()}…`;
+}
+/*
+ * Hands every whole line between `from` and `size` of a file that only grows to `onLine`, and
+ * answers where the next read starts: just past the last whole line, so a line still being written
+ * is read once it is done. In pieces, so a file of hundreds of megabytes is never one buffer, and cut
+ * on bytes, since a piece may end halfway into a character.
+ */
+export async function readLines(path, from, size, chunkBytes, onLine) {
+    const handle = await open(path, 'r');
+    let offset = from;
+    try {
+        let carry = Buffer.alloc(0);
+        let position = from;
+        while (position < size) {
+            const piece = Buffer.alloc(Math.min(chunkBytes, size - position));
+            const { bytesRead } = await handle.read(piece, 0, piece.length, position);
+            if (bytesRead === 0) {
+                break;
+            }
+            position += bytesRead;
+            const bytes = Buffer.concat([carry, piece.subarray(0, bytesRead)]);
+            const end = bytes.lastIndexOf(0x0a);
+            if (end < 0) {
+                carry = bytes;
+                continue;
+            }
+            for (const line of bytes.subarray(0, end).toString('utf8').split('\n')) {
+                onLine(line);
+            }
+            carry = bytes.subarray(end + 1);
+            offset = position - carry.length;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    return offset;
+}

package/dist/usage/accounts.d.ts

@@ -0,0 +1,15 @@
+import { type ChatInfo, type ProviderAccounts, type UsageAccount, type UsageProvider } from '@adecore/agent-contracts';
+import type { ProviderAccountsService } from '../providers/accounts/service.ts';
+import type { LimitAccounts } from './limits/monitor.ts';
+import { type UsageRootPath } from './roots.ts';
+interface MachineAccount extends UsageAccount {
+    isDefault: boolean;
+    enabled: boolean;
+    signedIn: boolean;
+}
+export declare function machineAccounts(snapshot: ProviderAccounts, nameOf: (kind: UsageProvider) => string): MachineAccount[];
+export declare function usageAccountsOf(service: ProviderAccountsService, nameOf: (kind: UsageProvider) => string): UsageAccount[];
+export declare function usageRootsOf(service: ProviderAccountsService): UsageRootPath[];
+export declare function limitAccountsOf(service: ProviderAccountsService, nameOf: (kind: UsageProvider) => string, baseEnv: Record<string, string | undefined>): LimitAccounts;
+export declare function chatSessionAccounts(chats: ReadonlyArray<Pick<ChatInfo, 'provider' | 'agentSessionId' | 'account'>>): Map<string, string>;
+export {};

package/dist/usage/accounts.js

@@ -0,0 +1,64 @@
+import { USAGE_PROVIDERS } from '@adecore/agent-contracts';
+import { definedEnv } from '../providers/accounts/launch.js';
+import { accountRoots } from './roots.js';
+function isUsageProvider(kind) {
+    return USAGE_PROVIDERS.includes(kind);
+}
+/* The accounts of the CLIs whose usage the host reads; a default account nobody named is called after its CLI. */
+export function machineAccounts(snapshot, nameOf) {
+    return Object.entries(snapshot.accounts).flatMap(([id, account]) => {
+        if (!isUsageProvider(account.kind)) {
+            return [];
+        }
+        const isDefault = id === account.kind;
+        const state = snapshot.statuses.find((status) => status.id === id)?.state;
+        return [
+            {
+                id,
+                kind: account.kind,
+                label: account.label ?? (isDefault ? nameOf(account.kind) : id),
+                ...(account.color === undefined ? {} : { color: account.color }),
+                isDefault,
+                enabled: account.enabled !== false,
+                signedIn: state === 'ready'
+            }
+        ];
+    });
+}
+function usageAccount({ id, kind, label, color }) {
+    return { id, kind, label, ...(color === undefined ? {} : { color }) };
+}
+/* What the usage page may filter by: every account, whether it is on or signed in or not, since what it spent still counts. */
+export function usageAccountsOf(service, nameOf) {
+    return machineAccounts(service.snapshot(), nameOf).map(usageAccount);
+}
+/* The transcripts of every account the machine has. */
+export function usageRootsOf(service) {
+    return accountRoots(Object.entries(service.snapshot().accounts).flatMap(([id, { kind }]) => {
+        if (!isUsageProvider(kind)) {
+            return [];
+        }
+        const folder = service.transcriptFolder(kind, id);
+        return folder === null || folder === '' ? [] : [{ id, kind, folder }];
+    }));
+}
+/* The plans the limits monitor reads: the default account of every CLI, and every other one that is on and signed in. */
+export function limitAccountsOf(service, nameOf, baseEnv) {
+    return {
+        list: () => machineAccounts(service.snapshot(), nameOf)
+            .filter((account) => account.isDefault || (account.enabled && account.signedIn))
+            .map((account) => ({ ...usageAccount(account), isDefault: account.isDefault })),
+        envFor: (kind, id) => definedEnv(service.envFor(kind, id, baseEnv)),
+        lastUsedAt: (id) => service.lastLaunchAt(id)
+    };
+}
+/* The account every CLI session a chat here ran was under, by `<provider>\0<sessionId>`, for the transcripts accounts share. */
+export function chatSessionAccounts(chats) {
+    const known = new Map();
+    for (const chat of chats) {
+        if (chat.agentSessionId !== null) {
+            known.set(`${chat.provider}\0${chat.agentSessionId}`, chat.account ?? chat.provider);
+        }
+    }
+    return known;
+}