@zenera/server 0.0.0-stage → 1.2.1

package/dist/runLog.js

@@ -0,0 +1,153 @@
+// A run's AG-UI events, kept on disk with the user's chats, so whoever comes back to a thread -
+// after a reload, a lost connection or hours later with the pod restarted - sees the whole run.
+// One file per run: /data/users/<user>/runs/<thread>/<started ms>-<run id>.ndjson, one event a line.
+//   RunLog          - a run being written: append, follow (all so far, then live), end
+//   compact         - the deltas of each message merged into one event, which is what a replay sends
+//   threadRunLogs   - a thread's run files, oldest first
+//   readRunLog      - one file's events, ended as interrupted if the run never finished
+import { EventType } from '@ag-ui/core';
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { readdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const FILE = /^(\d+)-([\w-]+)\.ndjson$/;
+function deltaKey(e) {
+    switch (e.type) {
+        case EventType.TEXT_MESSAGE_CONTENT:
+            return `t:${e.messageId}`;
+        case EventType.REASONING_MESSAGE_CONTENT:
+            return `r:${e.messageId}`;
+        case EventType.TOOL_CALL_ARGS:
+            return `a:${e.toolCallId}`;
+        default:
+            return undefined;
+    }
+}
+// Each stream's deltas only ever concatenate, so they can all sit at the first one's place.
+export function compact(events) {
+    const out = [];
+    const at = new Map();
+    for (const e of events) {
+        const key = deltaKey(e);
+        if (key) {
+            const i = at.get(key);
+            if (i !== undefined) {
+                const first = out[i];
+                out[i] = {
+                    ...first,
+                    delta: first.delta + e.delta,
+                };
+                continue;
+            }
+            at.set(key, out.length);
+        }
+        out.push(e);
+    }
+    return out;
+}
+export function isEnd(e) {
+    return e?.type === EventType.RUN_FINISHED || e?.type === EventType.RUN_ERROR;
+}
+export class RunLog {
+    runId;
+    file;
+    #maxBytes;
+    #out;
+    #events = [];
+    #followers = new Set();
+    #bytes = 0;
+    #ended = false;
+    constructor(file, runId, maxBytes) {
+        this.file = file;
+        this.runId = runId;
+        this.#maxBytes = maxBytes;
+        this.#out = createWriteStream(file, { flags: 'a' });
+        this.#out.on('error', (err) => console.error(`run log ${file}:`, err));
+    }
+    static open(dir, runId, maxBytes) {
+        mkdirSync(dir, { recursive: true });
+        return new RunLog(join(dir, `${Date.now()}-${runId}.ndjson`), runId, maxBytes);
+    }
+    get ended() {
+        return this.#ended;
+    }
+    append(events) {
+        if (this.#ended || events.length === 0)
+            return;
+        for (const e of events) {
+            const line = `${JSON.stringify(e)}\n`;
+            // Past the cap a runaway run keeps its structure and loses its deltas.
+            if (this.#bytes + line.length > this.#maxBytes && deltaKey(e))
+                continue;
+            this.#bytes += line.length;
+            this.#events.push(e);
+            this.#out.write(line);
+        }
+        for (const f of this.#followers)
+            f.events(events);
+    }
+    /** Everything so far at once, then each batch as it comes; returns the unfollow. */
+    follow(f) {
+        f.events(compact(this.#events));
+        if (this.#ended) {
+            f.end();
+            return () => { };
+        }
+        this.#followers.add(f);
+        return () => this.#followers.delete(f);
+    }
+    /** Lets the followers go, then rewrites the file compacted. */
+    async end() {
+        if (this.#ended)
+            return;
+        this.#ended = true;
+        for (const f of this.#followers)
+            f.end();
+        this.#followers.clear();
+        await new Promise((resolve) => this.#out.end(resolve));
+        const tmp = `${this.file}.tmp`;
+        await writeFile(tmp, compact(this.#events)
+            .map((e) => `${JSON.stringify(e)}\n`)
+            .join(''));
+        await rename(tmp, this.file);
+    }
+}
+export async function threadRunLogs(dir) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    return names
+        .map((name) => FILE.exec(name))
+        .filter((m) => m !== null)
+        .sort((a, b) => Number(a[1]) - Number(b[1]))
+        .map((m) => ({ runId: m[2], file: join(dir, m[0]) }));
+}
+/** Only for a run no longer going: one without an end was cut off by a restart. */
+export async function readRunLog(file) {
+    const events = [];
+    for (const line of (await readFile(file, 'utf8')).split('\n')) {
+        if (!line)
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            // the torn last line of a run cut off mid-write
+        }
+    }
+    const out = compact(events);
+    if (!isEnd(out.at(-1))) {
+        out.push({
+            type: EventType.RUN_ERROR,
+            message: 'the run was interrupted: the project restarted',
+            code: 'interrupted',
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=runLog.js.map

package/dist/runRecords.d.ts

@@ -0,0 +1,38 @@
+import { type RunOutcome, type SessionPaths } from '@zenera/engine';
+import { type TokenUsage } from '@zenera/neo';
+export interface RunRecord {
+    runId: string;
+    startedAt: string;
+    finishedAt?: string;
+    status: 'running' | 'finished' | 'error' | 'cancelled' | 'timeout' | 'interrupted' | 'unknown';
+    engineRunId?: string;
+    durationMs?: number;
+    agent?: string;
+    stopReason?: string;
+    error?: string;
+    usage?: TokenUsage;
+    modelCalls?: number;
+    sessionModelCalls?: number;
+    /** session trajectory length before this run; absent on records written before it was kept */
+    trajectoryStart?: number;
+}
+export interface RunSummary extends RunRecord {
+    recording: 'available' | 'pending' | 'unavailable';
+    reportAvailable: boolean;
+}
+export declare function recordOutcome(record: RunRecord, outcome: RunOutcome, before: {
+    usage?: TokenUsage;
+    modelCalls: number;
+    trajectoryLength?: number;
+}): void;
+export declare function startRecord(dir: string, runId: string): RunRecord;
+export declare function saveRecord(dir: string, record: RunRecord): void;
+export declare function listRunRecords(dir: string, session: SessionPaths | null, activeRunId?: string): Promise<RunSummary[]>;
+export declare function recordedReport(dir: string, session: SessionPaths | null, runId: string): Promise<string>;
+/** The run's record and its recorded engine state file, or 404 when it was never recorded. */
+export declare function recordedRun(dir: string, session: SessionPaths | null, runId: string): {
+    record: RunRecord;
+    session: SessionPaths;
+    statePath: string;
+};
+//# sourceMappingURL=runRecords.d.ts.map

package/dist/runRecords.js

@@ -0,0 +1,154 @@
+import { isStamp, runPaths } from '@zenera/engine';
+import { turns } from '@zenera/neo';
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from 'node:fs';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { HttpError } from "./http.js";
+import { threadRunLogs } from "./runLog.js";
+const ID = /^[\w-]{1,80}$/;
+export function recordOutcome(record, outcome, before) {
+    const usage = outcome.result.usage;
+    Object.assign(record, {
+        engineRunId: outcome.run.id,
+        durationMs: outcome.durationMs,
+        agent: outcome.result.agent,
+        stopReason: outcome.result.stopReason,
+        usage: {
+            inputTokens: usage.inputTokens - (before.usage?.inputTokens ?? 0),
+            cachedInputTokens: usage.cachedInputTokens - (before.usage?.cachedInputTokens ?? 0),
+            outputTokens: usage.outputTokens - (before.usage?.outputTokens ?? 0),
+            reasoningTokens: usage.reasoningTokens - (before.usage?.reasoningTokens ?? 0),
+        },
+        modelCalls: turns(outcome.result.state) - before.modelCalls,
+        sessionModelCalls: turns(outcome.result.state),
+        trajectoryStart: before.trajectoryLength ?? 0,
+        status: outcome.result.stopReason === 'failed'
+            ? 'error'
+            : outcome.result.stopReason === 'aborted'
+                ? 'cancelled'
+                : 'finished',
+        error: outcome.result.state.error,
+    });
+}
+function recordFile(dir, runId) {
+    if (!ID.test(runId))
+        throw new HttpError(400, 'invalid run id');
+    return join(dir, `${runId}.json`);
+}
+export function startRecord(dir, runId) {
+    const file = recordFile(dir, runId);
+    mkdirSync(dir, { recursive: true });
+    if (readdirSync(dir).some((name) => new RegExp(`^\\d+-${runId}\\.ndjson$`).test(name))) {
+        throw new HttpError(409, 'this run id has already been used');
+    }
+    const record = { runId, startedAt: new Date().toISOString(), status: 'running' };
+    try {
+        writeFileSync(file, JSON.stringify(record), { flag: 'wx' });
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            throw new HttpError(409, 'this run id has already been used');
+        }
+        throw err;
+    }
+    return record;
+}
+export function saveRecord(dir, record) {
+    const file = recordFile(dir, record.runId);
+    const tmp = `${file}.tmp`;
+    writeFileSync(tmp, JSON.stringify(record));
+    renameSync(tmp, file);
+}
+function readRecord(dir, runId) {
+    const record = JSON.parse(readFileSync(recordFile(dir, runId), 'utf8'));
+    if (record.runId !== runId || (record.engineRunId && !isStamp(record.engineRunId))) {
+        throw new HttpError(500, 'invalid recorded run identity');
+    }
+    return record;
+}
+async function reportExists(session, record) {
+    if (!session || !record.engineRunId)
+        return false;
+    try {
+        return (await stat(runPaths(session, record.engineRunId).report)).isFile();
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+}
+export async function listRunRecords(dir, session, activeRunId) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const records = new Map();
+    for (const name of names) {
+        if (!name.endsWith('.json') || !ID.test(name.slice(0, -5)))
+            continue;
+        const record = readRecord(dir, name.slice(0, -5));
+        records.set(record.runId, record);
+    }
+    // Older chats have event logs but no reliable engine-run mapping.
+    for (const log of await threadRunLogs(dir)) {
+        if (!records.has(log.runId)) {
+            records.set(log.runId, {
+                runId: log.runId,
+                startedAt: new Date(Number(basename(log.file).split('-')[0])).toISOString(),
+                status: 'unknown',
+            });
+        }
+    }
+    return Promise.all([...records.values()]
+        .sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+        .map(async (record) => {
+        const active = record.runId === activeRunId;
+        const interrupted = record.status === 'running' && !active;
+        return {
+            ...record,
+            ...(interrupted
+                ? {
+                    status: 'interrupted',
+                    error: 'the run was interrupted before its recording completed',
+                }
+                : {}),
+            recording: record.engineRunId
+                ? 'available'
+                : active
+                    ? 'pending'
+                    : 'unavailable',
+            reportAvailable: await reportExists(session, record),
+        };
+    }));
+}
+export async function recordedReport(dir, session, runId) {
+    const file = recordFile(dir, runId);
+    if (!existsSync(file))
+        throw new HttpError(404, 'no recording for this run');
+    const record = readRecord(dir, runId);
+    if (!(await reportExists(session, record)) || !session || !record.engineRunId) {
+        throw new HttpError(404, 'the inspector report is unavailable for this run');
+    }
+    return readFile(runPaths(session, record.engineRunId).report, 'utf8');
+}
+/** The run's record and its recorded engine state file, or 404 when it was never recorded. */
+export function recordedRun(dir, session, runId) {
+    const file = recordFile(dir, runId);
+    if (!existsSync(file))
+        throw new HttpError(404, 'no recording for this run');
+    const record = readRecord(dir, runId);
+    if (!session || !record.engineRunId) {
+        throw new HttpError(404, 'this run has no engine recording');
+    }
+    const statePath = runPaths(session, record.engineRunId).state;
+    if (!existsSync(statePath))
+        throw new HttpError(404, 'the recorded run state is missing');
+    return { record, session, statePath };
+}
+//# sourceMappingURL=runRecords.js.map

package/dist/runs.d.ts

@@ -0,0 +1,12 @@
+import { Router } from 'express';
+import { type ChatStore, type ChatThread } from './store.ts';
+export declare function activeRuns(): number;
+export declare function currentRun(t: ChatThread): {
+    runId: string;
+} | null;
+/** Runs may start again: a new server in a process whose previous one stopped. */
+export declare function acceptRuns(): void;
+export declare function stopAllRuns(timeoutMs: number): Promise<void>;
+export declare function runsRouter(store: ChatStore): Router;
+export declare function runDebugRouter(store: ChatStore): Router;
+//# sourceMappingURL=runs.d.ts.map