@adecore/agents 0.0.1 → 0.17.0-beta.2

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

@@ -0,0 +1,33 @@
+import { type ChatEvent } from '@adecore/agent-contracts';
+export interface ChatLogLine {
+    seq: number;
+    at: number;
+    event: ChatEvent;
+}
+export declare const COMPACT_ABOVE_BYTES: number;
+export declare function parseLog(raw: string): ChatLogLine[];
+export interface ChatLogState {
+    seq: number;
+    resetSeq: number;
+    lines: ChatLogLine[];
+}
+export declare class ChatLog {
+    private readonly path;
+    private lines;
+    private bytes;
+    private base;
+    private fd;
+    private seqValue;
+    private resetSeqValue;
+    private written;
+    constructor(path: string | null, state?: ChatLogState);
+    get seq(): number;
+    get resetSeq(): number;
+    get size(): number;
+    get onDisk(): boolean;
+    append(event: ChatEvent, at: number): number;
+    after(since: number): ChatEvent[] | null;
+    compact(seq: number): void;
+    close(): void;
+    private open;
+}

package/dist/chat/chat-log.js

@@ -0,0 +1,163 @@
+import { closeSync, fstatSync, mkdirSync, openSync, readSync, rmSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { ChatEventSchema } from '@adecore/agent-contracts';
+import { z } from 'zod';
+import { errorText } from '../error-text.js';
+import { writeAtomicSync } from '../fs.js';
+/* Past this the next write of the record folds the log into it. */
+export const COMPACT_ABOVE_BYTES = 1024 * 1024;
+const LineSchema = z.object({ seq: z.number().int().positive(), at: z.number(), event: ChatEventSchema });
+/*
+ * The lines of a log as they were written. A line that does not parse is left out: a crash in the
+ * middle of an append leaves a torn last line, and what came before it is still good.
+ */
+export function parseLog(raw) {
+    const lines = [];
+    for (const text of raw.split('\n')) {
+        if (text === '') {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = LineSchema.safeParse(JSON.parse(text));
+        }
+        catch {
+            continue;
+        }
+        if (parsed.success && parsed.data.seq > (lines.at(-1)?.seq ?? 0)) {
+            lines.push(parsed.data);
+        }
+    }
+    return lines;
+}
+/*
+ * Number and synchronously append each broadcast event so disk, memory and snapshot boundaries keep
+ * one order. Recent lines stay in memory for immediate `since` attachment.
+ */
+export class ChatLog {
+    path;
+    lines;
+    bytes;
+    // Every event after this seq is in `lines`; anything at or before it only the snapshot still has.
+    base;
+    fd = null;
+    seqValue;
+    resetSeqValue;
+    // False once a line failed to reach the disk, until a fold writes the file again.
+    written = true;
+    constructor(path, state = { seq: 0, resetSeq: 0, lines: [] }) {
+        this.path = path;
+        this.lines = state.lines;
+        this.bytes = state.lines.reduce((sum, line) => sum + JSON.stringify(line).length + 1, 0);
+        this.seqValue = Math.max(state.seq, state.lines.at(-1)?.seq ?? 0);
+        this.resetSeqValue = state.resetSeq;
+        const first = state.lines[0];
+        // A log with a hole in front of it only answers from after the hole.
+        this.base = first === undefined ? this.seqValue : first.seq - 1;
+        for (let i = 1; i < state.lines.length; i++) {
+            if (state.lines[i].seq !== state.lines[i - 1].seq + 1) {
+                this.base = state.lines[i - 1].seq;
+                this.lines = state.lines.slice(i);
+            }
+        }
+    }
+    get seq() {
+        return this.seqValue;
+    }
+    get resetSeq() {
+        return this.resetSeqValue;
+    }
+    /* How much the log file holds, which is what decides whether writing a snapshot folds it in. */
+    get size() {
+        return this.bytes;
+    }
+    /* Whether the file holds every line since the last fold, which is what lets a snapshot wait. */
+    get onDisk() {
+        return this.written;
+    }
+    /* Numbers an event and writes it down; answers its seq. The seq holds even when the disk refused the line. */
+    append(event, at) {
+        this.seqValue += 1;
+        const line = { seq: this.seqValue, at, event };
+        if (event.type === 'reset') {
+            this.resetSeqValue = line.seq;
+        }
+        const text = `${JSON.stringify(line)}\n`;
+        this.lines.push(line);
+        this.bytes += text.length;
+        if (this.path !== null) {
+            try {
+                this.fd ??= this.open(this.path);
+                writeSync(this.fd, text);
+            }
+            catch (e) {
+                this.written = false;
+                // The event still reaches every client; only a restart before the next snapshot loses it.
+                console.error(`Appending to ${this.path} failed:`, errorText(e));
+            }
+        }
+        return line.seq;
+    }
+    /*
+     * What came after `since`, when all of it is still here: null for a seq from before a reset (the
+     * thread it built on is gone), from before the lines held (folded into the snapshot) or from a
+     * stream this chat never reached.
+     */
+    after(since) {
+        if (since < this.resetSeqValue || since < this.base || since > this.seqValue) {
+            return null;
+        }
+        return this.lines.filter((line) => line.seq > since).map((line) => line.event);
+    }
+    /*
+     * Folds the log into a snapshot that holds everything up to `seq`. What came after it (events
+     * broadcast while that snapshot was on its way to disk) is written again as the whole log, in
+     * one synchronous step, so no append can land between the two. A snapshot older than the last
+     * fold changes nothing.
+     */
+    compact(seq) {
+        if (seq <= this.base) {
+            return;
+        }
+        this.lines = this.lines.filter((line) => line.seq > seq);
+        this.base = seq;
+        const text = this.lines.map((line) => `${JSON.stringify(line)}\n`).join('');
+        this.bytes = text.length;
+        if (this.path === null) {
+            return;
+        }
+        this.close();
+        try {
+            if (text === '') {
+                rmSync(this.path, { force: true });
+            }
+            else {
+                writeAtomicSync(this.path, text);
+            }
+            this.written = true;
+        }
+        catch (e) {
+            console.error(`Compacting ${this.path} failed:`, errorText(e));
+        }
+    }
+    close() {
+        if (this.fd !== null) {
+            closeSync(this.fd);
+            this.fd = null;
+        }
+    }
+    /* A torn last line from a crash gets its newline first, so the next line does not run into it and get lost with it. */
+    open(path) {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        const fd = openSync(path, 'a+', 0o600);
+        const { size } = fstatSync(fd);
+        if (size > 0) {
+            const last = Buffer.alloc(1);
+            readSync(fd, last, 0, 1, size - 1);
+            if (last[0] !== 0x0a) {
+                writeSync(fd, '\n');
+            }
+        }
+        return fd;
+    }
+}

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

@@ -0,0 +1,46 @@
+export interface ChatProcess {
+    readonly pid: number;
+    readonly stdin: {
+        write(chunk: string): unknown;
+        flush(): unknown;
+        end(): unknown;
+    };
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly stderr?: ReadableStream<Uint8Array>;
+    kill(signal: 'SIGTERM' | 'SIGKILL'): void;
+}
+export interface ChatSpawnOptions {
+    command: string[];
+    cwd: string;
+    env: Record<string, string>;
+    onExit(exitCode: number | null): void;
+    onError?(error: Error): void;
+}
+export type SpawnChatProcess = (options: ChatSpawnOptions) => ChatProcess;
+export declare function spawnChatProcess(options: ChatSpawnOptions): ChatProcess;
+export declare class StreamTail {
+    readonly done: Promise<void>;
+    private text;
+    constructor(stream: ReadableStream<Uint8Array>);
+    lines(): string | null;
+    private read;
+}
+export interface ChatChildOptions extends Omit<ChatSpawnOptions, 'onExit'> {
+    spawn?: SpawnChatProcess;
+    onExit(exitCode: number | null, stderr: string | null): void;
+    onError?(error: Error): void;
+}
+export declare class ChatChild {
+    readonly process: ChatProcess;
+    readonly exited: Promise<void>;
+    private readonly tail;
+    private hasExited;
+    private graceTimer;
+    private ending;
+    constructor(options: ChatChildOptions);
+    get pid(): number;
+    endAfterGrace(): void;
+    end(): Promise<void>;
+    private clearGrace;
+    private report;
+}

package/dist/chat/chat-process.js

@@ -0,0 +1,190 @@
+import { spawn } from 'node:child_process';
+import { Readable } from 'node:stream';
+// How long an exit waits for the rest of stdout; a process the CLI started may hold the pipe open.
+const STDOUT_DRAIN_MS = 250;
+export function spawnChatProcess(options) {
+    const [command, ...args] = options.command;
+    if (command === undefined) {
+        throw new Error('No command to start');
+    }
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        // A group of its own, so ending the chat also ends what its agent started (a dev server, a watcher).
+        detached: true
+    });
+    // Node reports a missing executable as an event after the call; a start that failed says so on the spot.
+    child.on('error', () => undefined);
+    const pid = child.pid;
+    if (pid === undefined) {
+        throw new Error(`Could not start ${command}: no such executable`);
+    }
+    child.stdin.on('error', (error) => options.onError?.(error));
+    child.on('exit', (exitCode) => {
+        // The last lines may still be on their way through the pipe; they belong before the exit.
+        const report = () => {
+            clearTimeout(timer);
+            child.stdout.off('end', report);
+            setImmediate(() => options.onExit(exitCode));
+        };
+        const timer = setTimeout(report, STDOUT_DRAIN_MS);
+        if (child.stdout.readableEnded) {
+            report();
+            return;
+        }
+        child.stdout.once('end', report);
+    });
+    return {
+        pid,
+        stdin: {
+            write: (chunk) => child.stdin.write(chunk),
+            flush: () => undefined,
+            end: () => child.stdin.end()
+        },
+        stdout: Readable.toWeb(child.stdout),
+        stderr: Readable.toWeb(child.stderr),
+        kill: (signal) => {
+            try {
+                process.kill(-pid, signal);
+            }
+            catch {
+                // Nothing of the group is left to signal.
+            }
+        }
+    };
+}
+// After stdin closed, a CLI that is still around is not going to say more.
+const EXIT_GRACE_MS = 3000;
+// What a CLI and everything it started get between the SIGTERM and the SIGKILL.
+const KILL_GRACE_MS = 2000;
+// How long a crash note waits for the last of stderr; a process the CLI started may hold the pipe open.
+const STDERR_DRAIN_MS = 250;
+// A pipe nobody reads is buffered in memory for as long as the CLI lives, so stderr is read into this much and no more.
+const STDERR_TAIL_CHARS = 8 * 1024;
+// What of that tail goes into the note, which the log and every client carry.
+const NOTE_TAIL_LINES = 10;
+const NOTE_TAIL_CHARS = 2000;
+/* The last few kilobytes a stream carried. */
+export class StreamTail {
+    done;
+    text = '';
+    constructor(stream) {
+        this.done = this.read(stream);
+    }
+    /* The last lines, short enough for a note; null when nothing but whitespace came. */
+    lines() {
+        const lines = this.text
+            .split('\n')
+            .map((line) => line.trimEnd())
+            .filter((line) => line.trim() !== '')
+            .slice(-NOTE_TAIL_LINES);
+        const tail = lines.join('\n').slice(-NOTE_TAIL_CHARS);
+        return tail === '' ? null : tail;
+    }
+    async read(stream) {
+        const reader = stream.getReader();
+        const decoder = new TextDecoder();
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done) {
+                    break;
+                }
+                this.text = (this.text + decoder.decode(value, { stream: true })).slice(-STDERR_TAIL_CHARS);
+            }
+        }
+        catch {
+            // The pipe went with the process; what came before it is still the tail.
+        }
+    }
+}
+/*
+ * A spawned CLI and how it ends. Every signal goes to its process group, SIGTERM first and SIGKILL
+ * after a grace, and only ever because a person stopped, removed or restarted something.
+ */
+export class ChatChild {
+    process;
+    // Settles when the CLI itself exited, not when its report of that was delivered.
+    exited;
+    tail;
+    hasExited = false;
+    graceTimer = null;
+    ending = null;
+    constructor(options) {
+        let settle = () => undefined;
+        this.exited = new Promise((resolve) => {
+            settle = resolve;
+        });
+        const spawn = options.spawn ?? spawnChatProcess;
+        this.process = spawn({
+            command: options.command,
+            cwd: options.cwd,
+            env: options.env,
+            ...(options.onError ? { onError: options.onError } : {}),
+            onExit: (exitCode) => {
+                this.hasExited = true;
+                this.clearGrace();
+                settle();
+                void this.report(exitCode, options.onExit);
+            }
+        });
+        this.tail = this.process.stderr ? new StreamTail(this.process.stderr) : null;
+    }
+    get pid() {
+        return this.process.pid;
+    }
+    /* Ends the CLI once the grace is over and it has not left on its own; the caller closed its input. */
+    endAfterGrace() {
+        if (this.hasExited || this.graceTimer !== null || this.ending !== null) {
+            return;
+        }
+        this.graceTimer = setTimeout(() => {
+            this.graceTimer = null;
+            void this.end();
+        }, EXIT_GRACE_MS);
+        this.graceTimer.unref?.();
+    }
+    /* SIGTERM to the group now and SIGKILL after the grace; settles once the CLI exited or was sent the SIGKILL. */
+    end() {
+        this.clearGrace();
+        if (this.hasExited) {
+            return Promise.resolve();
+        }
+        if (this.ending === null) {
+            this.process.kill('SIGTERM');
+            this.ending = new Promise((resolve) => {
+                // Sent even when the CLI left in time: what it started may still be shutting down, or ignoring the SIGTERM.
+                const timer = setTimeout(() => {
+                    this.process.kill('SIGKILL');
+                    resolve();
+                }, KILL_GRACE_MS);
+                timer.unref?.();
+                void this.exited.then(resolve);
+            });
+        }
+        return this.ending;
+    }
+    clearGrace() {
+        if (this.graceTimer !== null) {
+            clearTimeout(this.graceTimer);
+            this.graceTimer = null;
+        }
+    }
+    async report(exitCode, onExit) {
+        if (exitCode === null || exitCode === 0 || this.tail === null) {
+            onExit(exitCode, null);
+            return;
+        }
+        let release = () => undefined;
+        const timer = setTimeout(() => release(), STDERR_DRAIN_MS);
+        await Promise.race([
+            this.tail.done,
+            new Promise((resolve) => {
+                release = resolve;
+            })
+        ]);
+        clearTimeout(timer);
+        onExit(exitCode, this.tail.lines());
+    }
+}

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

@@ -0,0 +1,209 @@
+import type { ChatAttachment, ChatCheckpointDiff, ChatEvent, ChatInfo, ChatItem, ChatQueuedMessage, ChatSkill, ModelSelection, RuntimeMode } from '@adecore/agent-contracts';
+import type { ChatProvider } from '../providers/provider.ts';
+import type { LimitsUpdate } from '../usage/limits/normalize.ts';
+import type { SpawnChatProcess } from './chat-process.ts';
+import type { ChatTitleInput } from './chat-title.ts';
+import type { SubagentSettlement } from './subagent-settlement.ts';
+import { ChatThread } from './thread.ts';
+import { type OutboxClock } from '../outbox/outbox-worker.ts';
+export interface TurnCheckpoints {
+    take(cwd: string): Promise<string | null>;
+    diff(cwd: string, tree: string): Promise<ChatCheckpointDiff | null>;
+    settle(cwd: string, tree: string): Promise<{
+        diff: ChatCheckpointDiff;
+        after: string;
+    } | null>;
+}
+export interface PromptNotes {
+    next(): {
+        shown: string[];
+        heard: string[];
+    };
+    reset(): void;
+}
+export type ChatReferences = (ids: readonly string[] | undefined) => {
+    ids: string[];
+    note: string | null;
+};
+export interface ChatSessionOptions {
+    info: ChatInfo;
+    clock?: OutboxClock;
+    items?: ChatItem[];
+    preambles?: string[];
+    provider: ChatProvider;
+    command: string[];
+    env(account: string | undefined): Record<string, string>;
+    spawn?: SpawnChatProcess;
+    instructions?(): string | null;
+    resumeNote?(): string | null;
+    folders?(): readonly string[];
+    promptNotes?: PromptNotes;
+    references?: ChatReferences;
+    checkpoints?: TurnCheckpoints;
+    emit(event: ChatEvent): void;
+    onLimits?(update: LimitsUpdate): void;
+    persist(): void;
+    save?(): Promise<void>;
+    persistSoon(): void;
+    readTitle?(agentSessionId: string): Promise<string | null>;
+    nameThread?(input: ChatTitleInput): Promise<string | null>;
+    subagentSettlement?(toolUseId: string): Promise<SubagentSettlement | null>;
+    limitResume?: LimitResumeHooks;
+}
+export interface LimitResumeHooks {
+    allowed(): boolean;
+    now(): number;
+    owe(turnId: string, at: number): Promise<void>;
+    lapse(): Promise<void>;
+    owed(): boolean;
+}
+export interface ChatSendExtras {
+    mentions?: string[];
+    skills?: string[];
+    chats?: string[];
+    attachments?: ChatAttachment[];
+}
+export interface ResumeWords {
+    prompt: string;
+    note: string;
+    preamble: string | null;
+}
+export declare class ChatSession {
+    readonly thread: ChatThread;
+    private readonly options;
+    private readonly projector;
+    private backend;
+    private starting;
+    private pendingStart;
+    private sendAfterStop;
+    private sendAfterReplacement;
+    private readonly workflowWarnings;
+    private generation;
+    private awaitingBackgroundReport;
+    private launchedSelection;
+    private launchedAccount;
+    private launchedRuntimeMode;
+    private launchedFolders;
+    private turnReady;
+    private staleResults;
+    private spokenTurnId;
+    private titleTimer;
+    private naming;
+    private frozen;
+    private readonly orphans;
+    private pendingPreambles;
+    private submission;
+    constructor(options: ChatSessionOptions);
+    get id(): string;
+    get info(): ChatInfo;
+    get running(): boolean;
+    get preambles(): readonly string[];
+    get pid(): number | null;
+    get busy(): boolean;
+    configure(patch: {
+        selection?: ModelSelection;
+        runtimeMode?: RuntimeMode;
+        resumeAtReset?: boolean;
+    }): ChatInfo;
+    setAccount(account: string | undefined): ChatInfo;
+    send(text: string, extras?: ChatSendExtras): {
+        queued: boolean;
+        turnId: string;
+    };
+    unqueue(messageId: string): ChatQueuedMessage | null;
+    sendNow(messageId: string): boolean;
+    private get queue();
+    private setQueue;
+    private drainQueue;
+    private dispatch;
+    compact(): void;
+    cancel(advanceQueue?: boolean): void;
+    stopTask(taskId: string): void;
+    approve(requestId: string, decision: 'allow' | 'allow-always' | 'deny', message?: string): boolean;
+    answer(requestId: string, answers: Record<string, string>): boolean;
+    dismiss(itemId: string): boolean;
+    clear(force: boolean): void;
+    settleStored(selection: ModelSelection, resume: ResumeDecision): void;
+    resume(turnId: string, attempt: number, words: ResumeWords): Promise<void>;
+    abandon(turnId: string, reason: string | null): void;
+    wake(wake: {
+        text: string;
+        label: string;
+        note?: string;
+        taskIds: string[];
+        summaryFor?: string;
+        messageFrom?: string[];
+    }): string | null;
+    resumeSettingChanged(): void;
+    takeUpAfterLimit(turnId: string): 'opened' | 'wait' | 'lapsed';
+    get replacementWouldWait(): boolean;
+    private wentOn;
+    private resumeAllowed;
+    private oweResume;
+    settleOwedResume(): void;
+    private turnOpened;
+    continuedElsewhere(note: string): void;
+    lapseResume(): void;
+    deliverNote(delivery: {
+        noteId: string;
+        note: string;
+        from?: string;
+        preamble: string;
+    }): boolean;
+    upsertItems(items: readonly ChatItem[]): void;
+    addNote(level: 'info' | 'warning' | 'error', text: string): void;
+    end(reason: string): void;
+    freeze(): void;
+    dispose(): Promise<void>;
+    turnDiff(turnId: string): Promise<ChatCheckpointDiff | null>;
+    listThreadItems(params: {
+        threadId: string;
+        cursor?: string;
+        limit: number;
+        sortDirection: 'asc' | 'desc';
+    }): Promise<unknown> | null;
+    settleOrphanedSubagents(): Promise<void>;
+    private recordLostBackground;
+    markSubagentStopped(toolUseId: string): void;
+    markSubagentsStopped(): void;
+    private markStopped;
+    recheckOrphan(toolUseId: string): Promise<void>;
+    noteSubagentNative(toolUseId: string, native: {
+        agentId?: string;
+        threadId?: string;
+    }): void;
+    skills(scan: () => Promise<ChatSkill[]>): Promise<ChatSkill[]>;
+    private openTurn;
+    private settleAgentTurn;
+    private checkpoint;
+    private settleCheckpoint;
+    private contextNote;
+    private submit;
+    private acceptPrompt;
+    private run;
+    private watchStart;
+    private clearStartWarning;
+    private requiresReplacement;
+    private hasNativeWork;
+    private processInUse;
+    private replacementWaits;
+    private ensureBackend;
+    private awaitsResume;
+    private receive;
+    private pauseQueue;
+    private clearWorkflowWarnings;
+    private watchWorkflows;
+    private reportsCurrentWindow;
+    private refreshTitle;
+    private applyTitle;
+    private nameThread;
+    private runningBackgroundRows;
+    private settleFromTranscripts;
+    private settleRows;
+    private emit;
+    private delegatingChange;
+}
+export interface ResumeDecision {
+    resumeTurnId: string | null;
+    reason: string | null;
+}