@adecore/agents 0.0.1 → 0.17.0-beta.1

package/dist/chat/subagent-settlement.js

@@ -0,0 +1,103 @@
+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) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/* The report an agent handed back with `SubagentHandback` before its last message, which then only points at it. */
+function handbackBefore(lines, end) {
+    for (let i = end - 1; i >= 0; i--) {
+        let entry;
+        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) {
+    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;
+        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) {
+    let before;
+    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;
+    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/dist/chat/thread.d.ts

@@ -0,0 +1,30 @@
+import type { AgentStatus, ChatApprovalItem, ChatEvent, ChatHistoryResult, ChatInfo, ChatItem, ChatQuestionItem } from '@adecore/agent-contracts';
+export declare class ChatThread {
+    info: ChatInfo;
+    private readonly items;
+    private readonly order;
+    private historyGeneration;
+    private readonly indices;
+    constructor(info: ChatInfo, items?: ChatItem[]);
+    get(id: string): ChatItem | undefined;
+    list(): ChatItem[];
+    find<K extends ChatItem['kind']>(kind: K, match: (item: Extract<ChatItem, {
+        kind: K;
+    }>) => boolean): Extract<ChatItem, {
+        kind: K;
+    }> | undefined;
+    upsert(item: ChatItem): ChatEvent;
+    appendText(itemId: string, text: string): ChatEvent | null;
+    patchInfo(patch: Partial<ChatInfo>): ChatEvent;
+    reset(patch: Partial<ChatInfo>): ChatEvent;
+    apply(event: ChatEvent): void;
+    setStatus(status: AgentStatus): ChatEvent;
+    statusFor(activeTurnId: string | null): AgentStatus;
+    pending(): Array<ChatApprovalItem | ChatQuestionItem>;
+    private syncRequests;
+    history(limit?: number, cursor?: string): ChatHistoryResult;
+    snapshot(): {
+        info: ChatInfo;
+        items: ChatItem[];
+    };
+}

package/dist/chat/thread.js

@@ -0,0 +1,147 @@
+import { randomUUID } from 'node:crypto';
+import { ChatError } from './errors.js';
+import { requestSummaries } from './request-summary.js';
+/*
+ * 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;
+    items = new Map();
+    order = [];
+    historyGeneration = randomUUID();
+    indices = new Map();
+    constructor(info, items = []) {
+        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) {
+        return this.items.get(id);
+    }
+    list() {
+        return this.order.map((id) => this.items.get(id));
+    }
+    find(kind, match) {
+        for (let i = this.order.length - 1; i >= 0; i--) {
+            const item = this.items.get(this.order[i]);
+            if (item?.kind === kind && match(item)) {
+                return item;
+            }
+        }
+        return undefined;
+    }
+    upsert(item) {
+        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, text) {
+        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) {
+        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) {
+        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) {
+        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) {
+        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) {
+        if (this.pending().length > 0) {
+            return 'needs-you';
+        }
+        return activeTurnId === null ? 'idle' : 'running';
+    }
+    pending() {
+        return this.list().filter((item) => (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.
+     */
+    syncRequests() {
+        const { requests: _requests, ...rest } = this.info;
+        const pending = this.pending();
+        this.info = pending.length === 0 ? rest : { ...rest, requests: requestSummaries(pending) };
+    }
+    history(limit = 60, cursor) {
+        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 = [];
+        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() {
+        return { info: this.info, items: this.list() };
+    }
+}

package/dist/chat/wake-chat.d.ts

@@ -0,0 +1,20 @@
+import type { ChatItem } from '@adecore/agent-contracts';
+import type { ChatCore } from './chat-core.ts';
+import type { ChatSession } from './chat-session.ts';
+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'>;
+    placed(nodeId: string): boolean;
+}
+export declare function loadChat(deps: ChatOpenerDeps, chatId: string): Promise<ChatSession | null>;
+export declare function chatOpener(deps: ChatOpenerDeps): (chatId: string) => Promise<WakeChat | null>;

package/dist/chat/wake-chat.js

@@ -0,0 +1,27 @@
+/*
+ * 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, chatId) {
+    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) {
+    return async (chatId) => {
+        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/dist/client-sinks.d.ts

@@ -0,0 +1,9 @@
+export declare class ClientSinks<TEvent> {
+    private readonly sinks;
+    private readonly onRelease;
+    constructor(onRelease?: ((clientId: string) => void) | null);
+    subscribe(clientId: string, sink: (event: TEvent) => void): () => void;
+    emit(event: TEvent): void;
+    to(clientId: string, event: TEvent): void;
+    clientIds(): string[];
+}

package/dist/client-sinks.js

@@ -0,0 +1,34 @@
+/*
+ * 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 {
+    sinks = new Map();
+    onRelease;
+    /* What else a client leaves behind, for the parts that keep more than a sink per client. */
+    constructor(onRelease = null) {
+        this.onRelease = onRelease;
+    }
+    subscribe(clientId, sink) {
+        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) {
+        for (const sink of this.sinks.values()) {
+            sink(event);
+        }
+    }
+    to(clientId, event) {
+        this.sinks.get(clientId)?.(event);
+    }
+    clientIds() {
+        return [...this.sinks.keys()];
+    }
+}

package/dist/coded-error.d.ts

@@ -0,0 +1,5 @@
+export declare class CodedError<TCode extends string = string> extends Error {
+    readonly code: TCode;
+    readonly lines: string[];
+    constructor(code: TCode, message: string, lines?: string[]);
+}

package/dist/coded-error.js

@@ -0,0 +1,17 @@
+/*
+ * 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 extends Error {
+    code;
+    /* What the actor can do instead. Only a refusal fills this; the rest carry an empty list. */
+    lines;
+    constructor(code, message, lines = []) {
+        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/dist/context/argv.d.ts

@@ -0,0 +1,11 @@
+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;
+};
+export declare function parseArgv(argv: readonly string[], known: readonly string[], switches?: readonly string[]): ParsedArgv;

package/dist/context/argv.js

@@ -0,0 +1,58 @@
+/*
+ * 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, known, switches = []) {
+    const positionals = [];
+    const flags = {};
+    const given = new Set();
+    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;
+        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/dist/context/refusal.d.ts

@@ -0,0 +1,9 @@
+export declare function field(value: string): string;
+export declare function refusalBody(code: string, message: string, lines?: readonly string[]): string;
+export declare function refusalRows(code: string, message: string, lines?: readonly string[]): string;
+export interface ParsedRefusal {
+    code: string;
+    message: string;
+    lines: string[];
+}
+export declare function parseRefusalBody(text: string): ParsedRefusal | null;

package/dist/context/refusal.js

@@ -0,0 +1,38 @@
+/*
+ * 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) {
+    return value.replace(/[\t\r\n]+/g, ' ');
+}
+function row(line) {
+    return line.replace(/[\r\n]+/g, ' ');
+}
+function rows(code, message, lines) {
+    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, message, lines = []) {
+    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, message, lines = []) {
+    return rows(code, message, lines).join('\n');
+}
+/* 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) {
+    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 };
+}

package/dist/context/verb.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import { CodedError } from '../coded-error.ts';
+export declare class VerbRefusal extends CodedError {
+}
+export interface VerbCallBase {
+    expectedRevision?: number;
+}
+export interface VerbHelp {
+    name: string;
+    usage: string;
+    summary: string;
+    detail: readonly string[];
+}
+export interface Verb<Call extends VerbCallBase> extends VerbHelp {
+    served: 'verb';
+    flagNames: readonly string[];
+    dryRun: boolean;
+    run(argv: readonly string[], call: Call): Promise<string[]>;
+}
+export interface Action<Call extends VerbCallBase> extends Omit<Verb<Call>, 'served'> {
+    word: string;
+}
+export interface Noun<Call extends VerbCallBase> {
+    served: 'noun';
+    name: string;
+    usage: string;
+    summary: string;
+    detail: readonly string[];
+    actions: readonly Action<Call>[];
+    run(argv: readonly string[], call: Call): Promise<string[]>;
+}
+export interface ContextVerb extends VerbHelp {
+    served: 'context';
+}
+export type VerbEntry<Call extends VerbCallBase> = Verb<Call> | Noun<Call> | ContextVerb;
+export declare const DRY_RUN_FLAG = "dry-run";
+export declare const REVISION_FLAG = "revision";
+export declare const DRY_RUN_PREVIEW = "a refused call makes nothing either, so it is only a preview and never needed for safety";
+export interface ArgsSpec<Positionals extends z.ZodType, Flags extends z.ZodObject, Call extends VerbCallBase> {
+    positionals: Positionals;
+    flags: Flags;
+    switches?: readonly string[];
+    dryRun?: boolean;
+    revision?: boolean;
+    run(input: {
+        positionals: z.infer<Positionals>;
+        flags: z.infer<Flags>;
+        switches: ReadonlySet<string>;
+        dryRun: boolean;
+    }, call: Call): Promise<string[]>;
+}
+export interface VerbSpec<Positionals extends z.ZodType, Flags extends z.ZodObject, Call extends VerbCallBase> extends VerbHelp, ArgsSpec<Positionals, Flags, Call> {
+}
+export interface NounSpec<Call extends VerbCallBase> {
+    name: string;
+    summary: string;
+    detail: readonly string[];
+    actions: readonly Action<Call>[];
+}
+export interface HelpTopic {
+    name: string;
+    summary: string;
+    body: readonly string[];
+}
+export interface HelpSpec<Call extends VerbCallBase> {
+    entries(): readonly VerbEntry<Call>[];
+    root(): readonly string[];
+    refusal: string;
+    topics?: readonly HelpTopic[];
+}
+export interface VerbRegistry<Call extends VerbCallBase> {
+    defineVerb<Positionals extends z.ZodType, Flags extends z.ZodObject>(spec: VerbSpec<Positionals, Flags, Call>): Verb<Call>;
+    defineAction<Positionals extends z.ZodType, Flags extends z.ZodObject>(noun: string, spec: VerbSpec<Positionals, Flags, Call>): Action<Call>;
+    defineNoun(spec: NounSpec<Call>): Noun<Call>;
+    defineHelp(spec: HelpSpec<Call>): Verb<Call>;
+    dryRunVerbNames(): readonly string[];
+    dryRunLine(): string;
+}
+export declare function summaryLines<Call extends VerbCallBase>(entries: readonly VerbEntry<Call>[]): string[];
+export declare function createVerbRegistry<Call extends VerbCallBase>(options: {
+    cli: string;
+}): VerbRegistry<Call>;
+export declare function lengthOf(input: unknown): number;
+export declare function requiredField(needs: string): z.ZodString;
+export declare function orNote(lines: string[], note: string): string[];