@adecore/agents 0.0.1 → 0.17.0-beta.1

package/src/chat/chat-log.ts

@@ -0,0 +1,187 @@
+import { closeSync, fstatSync, mkdirSync, openSync, readSync, rmSync, writeSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { ChatEventSchema, type ChatEvent } from '@adecore/agent-contracts';
+import { z } from 'zod';
+import { errorText } from '../error-text.ts';
+import { writeAtomicSync } from '../fs.ts';
+
+export interface ChatLogLine {
+    seq: number;
+    at: number;
+    event: ChatEvent;
+}
+
+/* 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: string): ChatLogLine[] {
+    const lines: ChatLogLine[] = [];
+    for (const text of raw.split('\n')) {
+        if (text === '') {
+            continue;
+        }
+        let parsed: ReturnType<typeof LineSchema.safeParse>;
+        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;
+}
+
+export interface ChatLogState {
+    // The last seq anything on disk accounts for, the snapshot or the log.
+    seq: number;
+    resetSeq: number;
+    // What the log file still holds, oldest first.
+    lines: ChatLogLine[];
+}
+
+/*
+ * 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 {
+    private readonly path: string | null;
+    private lines: ChatLogLine[];
+    private bytes: number;
+    // Every event after this seq is in `lines`; anything at or before it only the snapshot still has.
+    private base: number;
+    private fd: number | null = null;
+    private seqValue: number;
+    private resetSeqValue: number;
+    // False once a line failed to reach the disk, until a fold writes the file again.
+    private written = true;
+
+    constructor(path: string | null, state: ChatLogState = { 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(): number {
+        return this.seqValue;
+    }
+
+    get resetSeq(): number {
+        return this.resetSeqValue;
+    }
+
+    /* How much the log file holds, which is what decides whether writing a snapshot folds it in. */
+    get size(): number {
+        return this.bytes;
+    }
+
+    /* Whether the file holds every line since the last fold, which is what lets a snapshot wait. */
+    get onDisk(): boolean {
+        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: ChatEvent, at: number): number {
+        this.seqValue += 1;
+        const line: ChatLogLine = { 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: number): ChatEvent[] | null {
+        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: number): void {
+        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(): void {
+        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. */
+    private open(path: string): number {
+        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/src/chat/chat-process.ts

@@ -0,0 +1,237 @@
+import { spawn } from 'node:child_process';
+import { Readable } from 'node:stream';
+
+/*
+ * The part of a child process a chat backend talks to: lines in over stdin, lines out over stdout,
+ * a signal and an exit. A test hands in a CLI that runs in the same process instead of a real one.
+ */
+export interface ChatProcess {
+    readonly pid: number;
+    readonly stdin: {
+        write(chunk: string): unknown;
+        flush(): unknown;
+        end(): unknown;
+    };
+    readonly stdout: ReadableStream<Uint8Array>;
+    // Only read for the tail a crash note carries; a fake that never writes there may leave it out.
+    readonly stderr?: ReadableStream<Uint8Array>;
+    // Reaches every process the CLI started as well, which share its process group.
+    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;
+
+// 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: ChatSpawnOptions): ChatProcess {
+    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 = (): void => {
+            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) as unknown as ReadableStream<Uint8Array>,
+        stderr: Readable.toWeb(child.stderr) as unknown as ReadableStream<Uint8Array>,
+        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 {
+    readonly done: Promise<void>;
+    private text = '';
+
+    constructor(stream: ReadableStream<Uint8Array>) {
+        this.done = this.read(stream);
+    }
+
+    /* The last lines, short enough for a note; null when nothing but whitespace came. */
+    lines(): string | null {
+        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;
+    }
+
+    private async read(stream: ReadableStream<Uint8Array>): Promise<void> {
+        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.
+        }
+    }
+}
+
+export interface ChatChildOptions extends Omit<ChatSpawnOptions, 'onExit'> {
+    spawn?: SpawnChatProcess;
+    // `stderr` is the tail of what the CLI wrote there, for an exit with an error code only.
+    onExit(exitCode: number | null, stderr: string | null): void;
+    onError?(error: Error): void;
+}
+
+/*
+ * 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 {
+    readonly process: ChatProcess;
+    // Settles when the CLI itself exited, not when its report of that was delivered.
+    readonly exited: Promise<void>;
+    private readonly tail: StreamTail | null;
+    private hasExited = false;
+    private graceTimer: ReturnType<typeof setTimeout> | null = null;
+    private ending: Promise<void> | null = null;
+
+    constructor(options: ChatChildOptions) {
+        let settle: () => void = () => 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(): number {
+        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(): void {
+        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(): Promise<void> {
+        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;
+    }
+
+    private clearGrace(): void {
+        if (this.graceTimer !== null) {
+            clearTimeout(this.graceTimer);
+            this.graceTimer = null;
+        }
+    }
+
+    private async report(exitCode: number | null, onExit: ChatChildOptions['onExit']): Promise<void> {
+        if (exitCode === null || exitCode === 0 || this.tail === null) {
+            onExit(exitCode, null);
+            return;
+        }
+        let release: () => void = () => undefined;
+        const timer = setTimeout(() => release(), STDERR_DRAIN_MS);
+        await Promise.race([
+            this.tail.done,
+            new Promise<void>((resolve) => {
+                release = resolve;
+            })
+        ]);
+        clearTimeout(timer);
+        onExit(exitCode, this.tail.lines());
+    }
+}