@adecore/agents 0.0.1 → 0.17.0-beta.1

package/src/chat/subagent-settlement.ts

@@ -0,0 +1,111 @@
+import { open, stat } from 'node:fs/promises';
+
+// The end of a transcript is all the question needs; a final line longer than this reads as undecided.
+const TAIL_BYTES = 1024 * 1024;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/* How a subagent's own transcript says it ended: when, and the text of its last message. */
+export interface SubagentSettlement {
+    finishedAt: number | null;
+    report: string | null;
+}
+
+/* The report an agent handed back with `SubagentHandback` before its last message, which then only points at it. */
+function handbackBefore(lines: string[], end: number): string | null {
+    for (let i = end - 1; i >= 0; i--) {
+        let entry: unknown;
+        try {
+            entry = JSON.parse(lines[i]!);
+        } catch {
+            continue;
+        }
+        const message = isRecord(entry) && entry.type === 'assistant' && isRecord(entry.message) ? entry.message : null;
+        const content = message && Array.isArray(message.content) ? message.content.filter(isRecord) : [];
+        for (const block of content) {
+            const input = block.type === 'tool_use' && block.name === 'SubagentHandback' && isRecord(block.input) ? block.input : null;
+            if (input && typeof input.message === 'string' && input.message.trim() !== '') {
+                return input.message;
+            }
+        }
+    }
+    return null;
+}
+
+/*
+ * Whether the end of a Claude subagent transcript shows an agent that finished: the last line that
+ * is a message is the assistant's, it ended its turn (`stop_reason: end_turn`) and it asked for no
+ * tool. Anything else (a tool call still out, a tool result the model has not answered yet, a line
+ * still being written, a file cut off in the middle of a line) is not an answer, and null leaves the
+ * row as it was. `text` starts on a line boundary.
+ */
+export function settlementOf(text: string): SubagentSettlement | null {
+    if (!text.endsWith('\n')) {
+        return null;
+    }
+    const lines = text.split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i]!.trim();
+        if (line === '') {
+            continue;
+        }
+        let entry: unknown;
+        try {
+            entry = JSON.parse(line);
+        } catch {
+            return null;
+        }
+        if (!isRecord(entry) || (entry.type !== 'user' && entry.type !== 'assistant')) {
+            continue;
+        }
+        const message = isRecord(entry.message) ? entry.message : {};
+        const content = Array.isArray(message.content) ? message.content.filter(isRecord) : [];
+        if (entry.type !== 'assistant' || message.stop_reason !== 'end_turn' || content.some((block) => block.type === 'tool_use')) {
+            return null;
+        }
+        const time = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN;
+        const handedBack = handbackBefore(lines, i);
+        const report =
+            handedBack ??
+            content
+                .map((block) => (block.type === 'text' && typeof block.text === 'string' ? block.text : ''))
+                .filter((part) => part.trim() !== '')
+                .join('\n');
+        return { finishedAt: Number.isFinite(time) ? time : null, report: report === '' ? null : report };
+    }
+    return null;
+}
+
+/*
+ * Reads the end of a transcript and asks `settlementOf`. The file has to be the same size and age
+ * after the read as before it: a transcript that grew in between belongs to an agent still writing.
+ */
+export async function readSubagentSettlement(path: string): Promise<SubagentSettlement | null> {
+    let before: { size: number; mtimeMs: number };
+    try {
+        before = await stat(path);
+    } catch {
+        return null;
+    }
+    const from = Math.max(0, before.size - TAIL_BYTES);
+    const handle = await open(path, 'r');
+    let text: string;
+    try {
+        const bytes = Buffer.alloc(before.size - from);
+        const { bytesRead } = await handle.read(bytes, 0, bytes.length, from);
+        text = bytes.subarray(0, bytesRead).toString('utf8');
+    } finally {
+        await handle.close();
+    }
+    const after = await stat(path).catch(() => null);
+    if (after === null || after.size !== before.size || after.mtimeMs !== before.mtimeMs) {
+        return null;
+    }
+    if (from > 0) {
+        const start = text.indexOf('\n');
+        text = start < 0 ? '' : text.slice(start + 1);
+    }
+    return text === '' ? null : settlementOf(text);
+}

package/src/chat/thread.ts

@@ -0,0 +1,167 @@
+import { randomUUID } from 'node:crypto';
+import { ChatError } from './errors.ts';
+import { requestSummaries } from './request-summary.ts';
+import type { AgentStatus, ChatApprovalItem, ChatEvent, ChatHistoryResult, ChatInfo, ChatItem, ChatQuestionItem } from '@adecore/agent-contracts';
+
+/*
+ * The state of one chat as the client sees it. Every mutation answers the event that describes
+ * it, so the host broadcasts exactly what it applied and a reload can rebuild from `snapshot`.
+ */
+export class ChatThread {
+    info: ChatInfo;
+    private readonly items = new Map<string, ChatItem>();
+    private readonly order: string[] = [];
+    private historyGeneration = randomUUID();
+    private readonly indices = new Map<string, number>();
+
+    constructor(info: ChatInfo, items: ChatItem[] = []) {
+        this.info = info;
+        for (const item of items) {
+            this.items.set(item.id, item);
+            this.indices.set(item.id, this.order.length);
+            this.order.push(item.id);
+        }
+        this.syncRequests();
+    }
+
+    get(id: string): ChatItem | undefined {
+        return this.items.get(id);
+    }
+
+    list(): ChatItem[] {
+        return this.order.map((id) => this.items.get(id)!);
+    }
+
+    find<K extends ChatItem['kind']>(kind: K, match: (item: Extract<ChatItem, { kind: K }>) => boolean): Extract<ChatItem, { kind: K }> | undefined {
+        for (let i = this.order.length - 1; i >= 0; i--) {
+            const item = this.items.get(this.order[i]!);
+            if (item?.kind === kind && match(item as Extract<ChatItem, { kind: K }>)) {
+                return item as Extract<ChatItem, { kind: K }>;
+            }
+        }
+        return undefined;
+    }
+
+    upsert(item: ChatItem): ChatEvent {
+        if (!this.items.has(item.id)) {
+            this.indices.set(item.id, this.order.length);
+            this.order.push(item.id);
+        }
+        this.items.set(item.id, item);
+        if (item.kind === 'approval' || item.kind === 'question') {
+            this.syncRequests();
+        }
+        return { type: 'item', item, historyIndex: this.indices.get(item.id)! };
+    }
+
+    /* Streams text into an assistant or thinking item, or partial output into a tool call that is still running. */
+    appendText(itemId: string, text: string): ChatEvent | null {
+        const item = this.items.get(itemId);
+        if (item?.kind === 'assistant' || item?.kind === 'thinking') {
+            this.items.set(itemId, { ...item, text: item.text + text });
+            return { type: 'delta', itemId, text };
+        }
+        if (item?.kind === 'tool' && item.state === 'running') {
+            const progress = item.progress ?? { startedAt: null, description: null, output: null };
+            this.items.set(itemId, { ...item, progress: { ...progress, output: (progress.output ?? '') + text } });
+            return { type: 'delta', itemId, text };
+        }
+        return null;
+    }
+
+    patchInfo(patch: Partial<ChatInfo>): ChatEvent {
+        this.info = { ...this.info, ...patch };
+        return { type: 'info', info: this.info };
+    }
+
+    /* Empties the thread; the info carries on with the patch on top. */
+    reset(patch: Partial<ChatInfo>): ChatEvent {
+        this.items.clear();
+        this.indices.clear();
+        this.historyGeneration = randomUUID();
+        this.order.length = 0;
+        this.info = { ...this.info, ...patch };
+        this.syncRequests();
+        return { type: 'reset', info: this.info, items: [] };
+    }
+
+    /* Applies an event this thread answered before, as a log read back after a restart hands it in. */
+    apply(event: ChatEvent): void {
+        switch (event.type) {
+            case 'item':
+                this.upsert(event.item);
+                break;
+            case 'delta':
+                this.appendText(event.itemId, event.text);
+                break;
+            case 'info':
+                this.info = event.info;
+                break;
+            case 'reset':
+                this.reset(event.info);
+                for (const item of event.items) {
+                    this.upsert(item);
+                }
+                break;
+        }
+    }
+
+    setStatus(status: AgentStatus): ChatEvent {
+        return this.patchInfo({ status });
+    }
+
+    /* A request can outlive the turn it came in, when work the CLI runs beside its turns asked it. */
+    statusFor(activeTurnId: string | null): AgentStatus {
+        if (this.pending().length > 0) {
+            return 'needs-you';
+        }
+        return activeTurnId === null ? 'idle' : 'running';
+    }
+
+    pending(): Array<ChatApprovalItem | ChatQuestionItem> {
+        return this.list().filter(
+            (item): item is ChatApprovalItem | ChatQuestionItem =>
+                (item.kind === 'approval' && item.decision === 'pending') || (item.kind === 'question' && item.state === 'pending')
+        );
+    }
+
+    /*
+     * `info.requests` follows the request items, so whatever event comes next carries what the chat waits on,
+     * and a log read back rebuilds it the same way.
+     */
+    private syncRequests(): void {
+        const { requests: _requests, ...rest } = this.info;
+        const pending = this.pending();
+        this.info = pending.length === 0 ? rest : { ...rest, requests: requestSummaries(pending) };
+    }
+
+    history(limit = 60, cursor?: string): ChatHistoryResult {
+        let end = this.order.length;
+        if (cursor) {
+            const [generation, offset] = cursor.split(':');
+            end = Number(offset);
+            if (generation !== this.historyGeneration || !/^\d+$/.test(offset ?? '') || !Number.isSafeInteger(end) || end < 0 || end > this.order.length) {
+                throw new ChatError('history-expired', 'The conversation changed. Reload its history.');
+            }
+        }
+        const items: ChatItem[] = [];
+        let bytes = 0;
+        let start = end;
+        while (start > 0 && items.length < Math.min(100, Math.max(1, limit))) {
+            const item = this.items.get(this.order[start - 1]!)!;
+            const size = Buffer.byteLength(JSON.stringify(item));
+            // An atomic item is never cut; an oversized item travels alone.
+            if (items.length && bytes + size > 512 * 1024) {
+                break;
+            }
+            items.unshift(item);
+            bytes += size;
+            start--;
+        }
+        return { items, history: { start, cursor: start ? `${this.historyGeneration}:${start}` : null } };
+    }
+
+    snapshot(): { info: ChatInfo; items: ChatItem[] } {
+        return { info: this.info, items: this.list() };
+    }
+}

package/src/chat/wake-chat.ts

@@ -0,0 +1,45 @@
+import type { ChatItem } from '@adecore/agent-contracts';
+import type { ChatCore } from './chat-core.ts';
+import type { ChatSession } from './chat-session.ts';
+
+/* A chat the host may open a turn in, as the outbox handlers see it: what its thread holds, and the one call that opens one, false while a turn or an owed resume is in the way. */
+export interface WakeChat {
+    items(): ChatItem[];
+    persist?(): Promise<void>;
+    wake(wake: { text: string; label: string; note?: string; taskIds: string[]; messageFrom?: string[] }): boolean;
+}
+
+export interface ChatOpenerDeps {
+    chats: Pick<ChatCore, 'get' | 'hasStored' | 'create' | 'save'>;
+    /* Whether a project still places the node; one that left the document is nobody's to open a turn in. */
+    placed(nodeId: string): boolean;
+}
+
+/*
+ * A chat, loaded from disk when nobody has it, so work owed to a chat nobody mounted since the restart
+ * still lands. Null for a node with no thread at all.
+ */
+export async function loadChat(deps: ChatOpenerDeps, chatId: string): Promise<ChatSession | null> {
+    if (!deps.chats.get(chatId)) {
+        if (!deps.placed(chatId) || !(await deps.chats.hasStored(chatId))) {
+            return null;
+        }
+        await deps.chats.create({ chatId });
+    }
+    return deps.chats.get(chatId) ?? null;
+}
+
+/* The chat a turn is to be opened in. */
+export function chatOpener(deps: ChatOpenerDeps) {
+    return async (chatId: string): Promise<WakeChat | null> => {
+        const session = await loadChat(deps, chatId);
+        return session
+            ? {
+                  items: () => session.thread.list(),
+                  persist: () => deps.chats.save(chatId),
+                  // A turn before the reset would stop on the same limit and spend one of the resume's tries, so it waits for the resume turn.
+                  wake: (wake) => session.info.resumeAt === undefined && session.wake(wake) !== null
+              }
+            : null;
+    };
+}

package/src/client-sinks.ts

@@ -0,0 +1,39 @@
+/*
+ * The clients listening to one part of a host. A client is one sink at a time; a client that
+ * connects again replaces the one before it.
+ */
+export class ClientSinks<TEvent> {
+    private readonly sinks = new Map<string, (event: TEvent) => void>();
+    private readonly onRelease: ((clientId: string) => void) | null;
+
+    /* What else a client leaves behind, for the parts that keep more than a sink per client. */
+    constructor(onRelease: ((clientId: string) => void) | null = null) {
+        this.onRelease = onRelease;
+    }
+
+    subscribe(clientId: string, sink: (event: TEvent) => void): () => void {
+        this.sinks.set(clientId, sink);
+        return () => {
+            // A client that subscribes again before it unsubscribes keeps its newer sink.
+            if (this.sinks.get(clientId) !== sink) {
+                return;
+            }
+            this.sinks.delete(clientId);
+            this.onRelease?.(clientId);
+        };
+    }
+
+    emit(event: TEvent): void {
+        for (const sink of this.sinks.values()) {
+            sink(event);
+        }
+    }
+
+    to(clientId: string, event: TEvent): void {
+        this.sinks.get(clientId)?.(event);
+    }
+
+    clientIds(): string[] {
+        return [...this.sinks.keys()];
+    }
+}

package/src/coded-error.ts

@@ -0,0 +1,18 @@
+/*
+ * The shape every failure on the wire has: a code a client can branch on and a message a person reads.
+ * A domain gives it a union of its own codes, so a typo in a code is a compile error instead of a
+ * string the other end never matches.
+ */
+export class CodedError<TCode extends string = string> extends Error {
+    readonly code: TCode;
+    /* What the actor can do instead. Only a refusal fills this; the rest carry an empty list. */
+    readonly lines: string[];
+
+    constructor(code: TCode, message: string, lines: string[] = []) {
+        super(message);
+        // The subclass names itself, so a stack reads `GitError:` and not `Error:`.
+        this.name = new.target.name;
+        this.code = code;
+        this.lines = lines;
+    }
+}

package/src/context/argv.ts

@@ -0,0 +1,61 @@
+export type ParsedArgv =
+    | { ok: true; positionals: string[]; flags: Record<string, string>; switches: Set<string> }
+    | { ok: false; code: 'unknown-flag' | 'missing-value' | 'duplicate-flag' | 'unexpected-value'; message: string };
+
+/*
+ * Splits the words after a verb into positionals, `--flag value` pairs (`--flag=value` too, for a
+ * value that itself starts with `--`) and the switches the verb declared. Anything not declared a
+ * switch takes a value, so a flag that lost its argument is refused instead of swallowing the next
+ * word, and a flag given twice is refused rather than one of the two silently winning. A name that is
+ * both a switch and a flag is on when written bare and takes a value only after `=` (`--state=full`).
+ */
+export function parseArgv(argv: readonly string[], known: readonly string[], switches: readonly string[] = []): ParsedArgv {
+    const positionals: string[] = [];
+    const flags: Record<string, string> = {};
+    const given = new Set<string>();
+    const all = [...new Set([...known, ...switches])];
+    for (let i = 0; i < argv.length; i++) {
+        const word = argv[i]!;
+        if (!word.startsWith('--')) {
+            positionals.push(word);
+            continue;
+        }
+        const equals = word.indexOf('=');
+        const name = word.slice(2, equals === -1 ? undefined : equals);
+        if (!all.includes(name)) {
+            return {
+                ok: false,
+                code: 'unknown-flag',
+                message: all.length === 0 ? `--${name} is not a flag here; this verb takes none` : `--${name} is not one of --${all.join(', --')}`
+            };
+        }
+        if (Object.hasOwn(flags, name) || given.has(name)) {
+            return { ok: false, code: 'duplicate-flag', message: `--${name} is given twice` };
+        }
+        if (switches.includes(name)) {
+            if (equals !== -1 && known.includes(name)) {
+                flags[name] = word.slice(equals + 1);
+                given.add(name);
+                continue;
+            }
+            if (equals !== -1) {
+                return { ok: false, code: 'unexpected-value', message: `--${name} takes no value; it is on when you write it and off when you do not` };
+            }
+            given.add(name);
+            continue;
+        }
+        let value: string;
+        if (equals !== -1) {
+            value = word.slice(equals + 1);
+        } else {
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                return { ok: false, code: 'missing-value', message: `--${name} needs a value (write --${name}=<value> for one that starts with --)` };
+            }
+            value = next;
+            i++;
+        }
+        flags[name] = value;
+    }
+    return { ok: true, positionals, flags, switches: given };
+}

package/src/context/refusal.ts

@@ -0,0 +1,50 @@
+/*
+ * How every no reads: `refused`, the code a script branches on and the sentence a model reads, and
+ * under it a line per thing the actor can do instead. One row per line, and a line is a row of
+ * tab-separated fields of its own, so only a newline is taken out of it: that would split the row in
+ * two, and everything under the first row is read as advice.
+ */
+
+/* A field that goes into a tab-separated line; a tab or a newline in a title would split the row. */
+export function field(value: string): string {
+    return value.replace(/[\t\r\n]+/g, ' ');
+}
+
+function row(line: string): string {
+    return line.replace(/[\r\n]+/g, ' ');
+}
+
+function rows(code: string, message: string, lines: readonly string[]): string[] {
+    return [`${field(code)}\t${field(message)}`, ...lines.map(row)];
+}
+
+/* What a verb is refused with, whole: the `refused` row and what to do instead under it. */
+export function refusalBody(code: string, message: string, lines: readonly string[] = []): string {
+    const [first, ...rest] = rows(code, message, lines);
+    return [`refused\t${first}`, ...rest].join('\n');
+}
+
+/*
+ * The same without the word that names it, for a host that adds the prefix in its CLI:
+ * The context CLI puts the prefix on, so a CLI of an older build still prints one refusal.
+ */
+export function refusalRows(code: string, message: string, lines: readonly string[] = []): string {
+    return rows(code, message, lines).join('\n');
+}
+
+export interface ParsedRefusal {
+    code: string;
+    message: string;
+    lines: string[];
+}
+
+/* Reads either form back. Null when the text is no refusal at all, which is not the same as one without advice. */
+export function parseRefusalBody(text: string): ParsedRefusal | null {
+    const [first = '', ...lines] = text.split('\n').filter((line) => line.trim() !== '');
+    const parts = first.split('\t');
+    const [code, message] = parts[0] === 'refused' ? parts.slice(1) : parts;
+    if (!code || !message) {
+        return null;
+    }
+    return { code, message, lines };
+}