@asrunjs/asrun 0.0.0-stage → 0.5.2

package/dist/ui/server/index.js

@@ -0,0 +1,33 @@
+import { serve } from '@hono/node-server';
+import { createApp } from './app.js';
+import { verifyProfiles } from './profiles.js';
+import { jobs } from './jobs.js';
+import { startFileWatcher } from './watch-files.js';
+const port = Number(process.env.ASRUN_UI_PORT ?? 4173);
+const app = createApp({ port });
+const server = serve({ fetch: app.fetch, port, hostname: '127.0.0.1' }, () => {
+    const devOrigin = process.env.ASRUN_UI_DEV_ORIGIN;
+    if (devOrigin) {
+        console.log(`asrun API (dev, no UI here): http://127.0.0.1:${port}`);
+        console.log(`asrun UI: ${devOrigin}`);
+    }
+    else {
+        console.log(`asrun UI: http://127.0.0.1:${port}`);
+    }
+    startFileWatcher();
+    void verifyProfiles();
+});
+server.on('error', (error) => {
+    if (error.code === 'EADDRINUSE') {
+        console.error(`Port ${port} is already in use. Is the UI already running? Or set ASRUN_UI_PORT.`);
+        process.exit(1);
+    }
+    throw error;
+});
+const shutdown = () => {
+    jobs.killAll();
+    server.close();
+    setTimeout(() => process.exit(0), 300).unref();
+};
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/dist/ui/server/jobs.d.ts

@@ -0,0 +1,80 @@
+import { type ChildProcess } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import type { JobChunk, JobInfo, JobKind } from '../shared/types.js';
+import type { AiCommand, AiTool } from '../shared/ai-commands.js';
+import { AiStreamFormatter } from './ai-stream.js';
+export declare class JobConflictError extends Error {
+}
+export interface JobSpec {
+    kind: JobKind;
+    profile?: string;
+    env?: string;
+    /** Shown to the user. */
+    command: string;
+    /** Executable and arguments: looked up on PATH, spawned without a shell (a Windows `.cmd` shim goes through cmd.exe). */
+    file: string;
+    args: string[];
+    /** Jobs holding the same lock cannot run at the same time. */
+    locks: string[];
+    acceptsInput: boolean;
+    /** The agent CLI whose JSON event stream on stdout is turned into readable log lines. */
+    stream?: AiTool;
+    /** Set for a test run that overwrites the baselines of these cases. */
+    baselineCases?: string[];
+    /** Set for a test run: the report folder it writes. */
+    reportId?: string;
+    /** Set for the AI run of a command on a case: what a later turn of its conversation needs. */
+    ai?: {
+        tool: AiTool;
+        command: AiCommand;
+        caseId: string;
+        env: string;
+        sessionId: string;
+        model?: string;
+        thinking?: boolean;
+    };
+    /** The job whose conversation this one continues. */
+    continuesJobId?: string;
+    /** Runs synchronously right before the final status is published. */
+    onFinish?: (job: JobInfo) => void;
+}
+interface JobRecord {
+    info: JobInfo;
+    spec: JobSpec;
+    chunks: JobChunk[];
+    bufferedChars: number;
+    nextSeq: number;
+    emitter: EventEmitter;
+    child: ChildProcess | null;
+    cancelRequested: boolean;
+    logStream: fs.WriteStream;
+    formatter: AiStreamFormatter | null;
+    heartbeat: NodeJS.Timeout | null;
+}
+declare class JobManager {
+    private jobs;
+    /** Emits `job` with a JobInfo on every status change of any job. */
+    readonly events: EventEmitter<[never]>;
+    constructor();
+    list(): JobInfo[];
+    get(id: string): JobRecord | undefined;
+    start(spec: JobSpec): JobInfo;
+    write(id: string, text: string): boolean;
+    cancel(id: string): boolean;
+    /** Stops everything; called when the server shuts down. */
+    killAll(): void;
+    /** Publishes a change of "waiting for the person" (a handoff card) like any other status change. */
+    private syncAwaiting;
+    private signalGroup;
+    /** A block of an AI run's log, with the time it was produced and how the UI should present it. */
+    private pushPart;
+    private push;
+    /** Keeps the chunk for the browser and writes it to the job's log file, which is what is left after the run. */
+    private store;
+    private finish;
+    private pruneFinished;
+    private pruneOldLogs;
+}
+export declare const jobs: JobManager;
+export {};

package/dist/ui/server/jobs.js

@@ -0,0 +1,317 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { ROOT } from '../../lib/paths.js';
+import { spawnTarget } from '../../lib/command.js';
+import { AiStreamFormatter } from './ai-stream.js';
+const LOG_DIR = path.join(ROOT, '.tmp', 'ui-jobs');
+const MAX_BUFFERED_CHARS = 4_000_000;
+const MAX_FINISHED_JOBS = 30;
+const LOG_RETENTION_MS = 7 * 24 * 3600 * 1000;
+const KILL_GRACE_MS = 5000;
+// An agent that has said nothing for this long gets a "still waiting for <tool call>" line in its log.
+const QUIET_MS = 45_000;
+const HEARTBEAT_MS = 15_000;
+export class JobConflictError extends Error {
+}
+const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
+/** The last `RESULT: ready|needs-input` line the agent said (markdown emphasis around it is fine). */
+function parseResultState(record) {
+    const text = record.chunks
+        // Only what the agent said counts: a file it read or a page it dumped may quote the same words.
+        .filter((chunk) => (chunk.kind ? chunk.kind === 'markdown' : chunk.stream !== 'system'))
+        .map((chunk) => chunk.data)
+        .join('\n')
+        .replace(ANSI, '');
+    const matches = [...text.matchAll(/^[\s*`>_-]*RESULT:\s*(ready|needs-input)\b/gm)];
+    return matches.at(-1)?.[1] ?? null;
+}
+/**
+ * A block of an AI run as the log file keeps it: the same text the UI shows, with the timestamp the UI styles written
+ * out, and the output of a call indented under the call it belongs to. The file is read in a terminal or an editor, so
+ * it has to make sense without the colors.
+ */
+function logFileText(part) {
+    const stamp = `[${new Date(part.at).toTimeString().slice(0, 8)}] `;
+    // What the agent said is separated by a blank line: it is the answer, not another line of the action above it.
+    if (part.kind === 'markdown')
+        return `\n${part.data}\n`;
+    if (part.kind === 'result' || part.kind === 'reasoning') {
+        const mark = part.kind === 'reasoning' ? '~ ' : '';
+        return part.data
+            .split('\n')
+            .map((line, index) => `    ${index === 0 ? mark : ''}${line}\n`)
+            .join('');
+    }
+    return `${stamp}${part.data}\n`;
+}
+class JobManager {
+    jobs = new Map();
+    /** Emits `job` with a JobInfo on every status change of any job. */
+    events = new EventEmitter();
+    constructor() {
+        this.events.setMaxListeners(0);
+        this.pruneOldLogs();
+    }
+    list() {
+        return [...this.jobs.values()].map((record) => record.info).reverse();
+    }
+    get(id) {
+        return this.jobs.get(id);
+    }
+    start(spec) {
+        for (const record of this.jobs.values()) {
+            if (record.info.status !== 'running')
+                continue;
+            const clash = record.spec.locks.find((lock) => spec.locks.includes(lock));
+            if (clash) {
+                throw new JobConflictError(`Cannot start: "${record.info.command}" is already running (${clash}). Wait for it to finish or cancel it.`);
+            }
+        }
+        const id = crypto.randomBytes(6).toString('hex');
+        fs.mkdirSync(LOG_DIR, { recursive: true });
+        const record = {
+            info: {
+                id,
+                kind: spec.kind,
+                profile: spec.profile,
+                env: spec.env,
+                command: spec.command,
+                status: 'running',
+                exitCode: null,
+                signal: null,
+                startedAt: new Date().toISOString(),
+                endedAt: null,
+                acceptsInput: spec.acceptsInput,
+                ...(spec.baselineCases && { baselineCases: spec.baselineCases }),
+                ...(spec.reportId && { reportId: spec.reportId }),
+                ...(spec.ai && {
+                    caseId: spec.ai.caseId,
+                    aiCommand: spec.ai.command,
+                    sessionId: spec.ai.sessionId,
+                    ...(spec.ai.model && { aiModel: spec.ai.model }),
+                    resultState: null,
+                }),
+                ...(spec.continuesJobId && { continuesJobId: spec.continuesJobId }),
+            },
+            spec,
+            chunks: [],
+            bufferedChars: 0,
+            nextSeq: 0,
+            emitter: new EventEmitter(),
+            child: null,
+            cancelRequested: false,
+            logStream: fs.createWriteStream(path.join(LOG_DIR, `${id}.log`)),
+            formatter: spec.stream ? new AiStreamFormatter(spec.stream) : null,
+            heartbeat: null,
+        };
+        record.emitter.setMaxListeners(0);
+        this.jobs.set(id, record);
+        this.push(record, 'system', `$ ${spec.command}\n`);
+        // A CLI installed globally is a `.cmd` shim on Windows, which spawn cannot start on its own (see lib/command.ts).
+        const target = spawnTarget(spec.file, spec.args);
+        if (target === null) {
+            this.finish(record, null, null, `Failed to start: "${spec.file}" was not found on PATH. Install it, or choose the other tool.`);
+            return record.info;
+        }
+        let child;
+        try {
+            child = spawn(target.file, target.args, {
+                cwd: ROOT,
+                // Off Windows the group is what `cancel` signals. On Windows a detached child loses the output of a `.cmd`
+                // shim, and the tree is ended with taskkill instead (see signalGroup).
+                detached: process.platform !== 'win32',
+                stdio: [spec.acceptsInput ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+                env: { ...process.env, FORCE_COLOR: '1', NO_COLOR: undefined },
+                windowsHide: true,
+                ...(target.throughShell && { windowsVerbatimArguments: true }),
+            });
+        }
+        catch (error) {
+            this.finish(record, null, null, `Failed to start: ${error.message}`);
+            return record.info;
+        }
+        record.child = child;
+        for (const stream of ['stdout', 'stderr']) {
+            const decoder = new StringDecoder('utf8');
+            const formatted = stream === 'stdout' ? record.formatter : null;
+            const emit = (text) => {
+                if (formatted)
+                    formatted.feed(text).forEach((part) => this.pushPart(record, part));
+                else
+                    this.push(record, stream, text);
+                this.syncAwaiting(record);
+            };
+            child[stream]?.on('data', (buffer) => {
+                const text = decoder.write(buffer);
+                if (text)
+                    emit(text);
+            });
+            child[stream]?.on('end', () => {
+                const rest = decoder.end();
+                if (rest)
+                    emit(rest);
+                formatted?.end().forEach((part) => this.pushPart(record, part));
+            });
+        }
+        if (record.formatter) {
+            const formatter = record.formatter;
+            record.heartbeat = setInterval(() => {
+                const line = formatter.waiting(QUIET_MS);
+                if (line)
+                    this.pushPart(record, line);
+            }, HEARTBEAT_MS);
+            record.heartbeat.unref();
+        }
+        child.stdin?.on('error', () => { });
+        let finished = false;
+        child.on('error', (error) => {
+            if (finished)
+                return;
+            finished = true;
+            this.finish(record, null, null, `Failed to start: ${error.message}`);
+        });
+        child.on('close', (code, signal) => {
+            if (finished)
+                return;
+            finished = true;
+            this.finish(record, code, signal);
+        });
+        this.events.emit('job', record.info);
+        return record.info;
+    }
+    write(id, text) {
+        const record = this.jobs.get(id);
+        if (!record || record.info.status !== 'running' || !record.info.acceptsInput)
+            return false;
+        return record.child?.stdin?.write(text) ?? false;
+    }
+    cancel(id) {
+        const record = this.jobs.get(id);
+        const pid = record?.child?.pid;
+        if (!record || record.info.status !== 'running' || !pid)
+            return false;
+        record.cancelRequested = true;
+        this.signalGroup(pid, 'SIGTERM');
+        setTimeout(() => {
+            if (record.info.status === 'running')
+                this.signalGroup(pid, 'SIGKILL');
+        }, KILL_GRACE_MS).unref();
+        return true;
+    }
+    /** Stops everything; called when the server shuts down. */
+    killAll() {
+        for (const record of this.jobs.values()) {
+            const pid = record.child?.pid;
+            if (record.info.status === 'running' && pid)
+                this.signalGroup(pid, 'SIGTERM');
+        }
+    }
+    /** Publishes a change of "waiting for the person" (a handoff card) like any other status change. */
+    syncAwaiting(record) {
+        const { info } = record;
+        if (info.status !== 'running' || !record.formatter)
+            return;
+        const now = record.formatter.awaiting;
+        const before = info.awaitingUser ?? null;
+        if (!now && !before)
+            return;
+        if (now && before && before.since === new Date(now.since).toISOString())
+            return;
+        info.awaitingUser = now ? { message: now.message, since: new Date(now.since).toISOString() } : null;
+        this.events.emit('job', info);
+    }
+    signalGroup(pid, signal) {
+        if (process.platform === 'win32') {
+            // Windows has no process groups (a negative pid throws ESRCH), so the whole tree is ended at once:
+            // cmd.exe, the agent CLI it started, and anything below them.
+            spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+            return;
+        }
+        try {
+            process.kill(-pid, signal);
+        }
+        catch {
+            // Already gone.
+        }
+    }
+    /** A block of an AI run's log, with the time it was produced and how the UI should present it. */
+    pushPart(record, part) {
+        const stream = part.kind === 'error' ? 'stderr' : part.kind === 'markdown' || part.kind === 'result' ? 'stdout' : 'system';
+        const chunk = {
+            seq: record.nextSeq++,
+            stream,
+            data: part.data,
+            kind: part.kind,
+            at: new Date(part.at).toISOString(),
+            ...(part.tool && { tool: part.tool }),
+        };
+        this.store(record, chunk, logFileText(part));
+    }
+    push(record, stream, data) {
+        const chunk = { seq: record.nextSeq++, stream, data };
+        this.store(record, chunk, stream === 'stderr' ? `[stderr] ${data}` : data);
+    }
+    /** Keeps the chunk for the browser and writes it to the job's log file, which is what is left after the run. */
+    store(record, chunk, fileText) {
+        record.chunks.push(chunk);
+        record.bufferedChars += chunk.data.length;
+        while (record.bufferedChars > MAX_BUFFERED_CHARS && record.chunks.length > 1) {
+            record.bufferedChars -= record.chunks.shift().data.length;
+        }
+        record.logStream.write(fileText);
+        record.emitter.emit('chunk', chunk);
+    }
+    finish(record, code, signal, note) {
+        const { info } = record;
+        if (record.heartbeat)
+            clearInterval(record.heartbeat);
+        info.awaitingUser = null;
+        info.exitCode = code;
+        info.signal = signal;
+        info.endedAt = new Date().toISOString();
+        info.status = record.cancelRequested
+            ? 'cancelled'
+            : code === 0
+                ? 'succeeded'
+                : 'failed';
+        const summary = note ??
+            (info.status === 'cancelled'
+                ? '[cancelled]'
+                : signal
+                    ? `[process killed by ${signal}]`
+                    : `[process exited with code ${code}]`);
+        if (record.spec.ai && info.status === 'succeeded')
+            info.resultState = parseResultState(record);
+        this.push(record, 'system', `\n${summary}\n`);
+        record.logStream.end();
+        try {
+            record.spec.onFinish?.(info);
+        }
+        catch (error) {
+            console.error('onFinish failed:', error);
+        }
+        record.emitter.emit('status', info);
+        this.events.emit('job', info);
+        this.pruneFinished();
+    }
+    pruneFinished() {
+        const finished = [...this.jobs.values()].filter((record) => record.info.status !== 'running');
+        for (const record of finished.slice(0, Math.max(0, finished.length - MAX_FINISHED_JOBS))) {
+            this.jobs.delete(record.info.id);
+        }
+    }
+    pruneOldLogs() {
+        if (!fs.existsSync(LOG_DIR))
+            return;
+        for (const name of fs.readdirSync(LOG_DIR)) {
+            const file = path.join(LOG_DIR, name);
+            if (Date.now() - fs.statSync(file).mtimeMs > LOG_RETENTION_MS)
+                fs.rmSync(file, { force: true });
+        }
+    }
+}
+export const jobs = new JobManager();

package/dist/ui/server/profiles.d.ts

@@ -0,0 +1,35 @@
+import type { AddProfileRequest, EditProfileRequest, EditProfileResult, ProfileInfo, ProfilesResponse } from '../shared/types.js';
+export declare function listProfileRows(): ProfilesResponse;
+/** Opens each saved session on the real site (read-only) and records whether it is still logged in. */
+export declare function verifyProfiles(only?: {
+    ids?: string[];
+    env?: string;
+}): Promise<void>;
+export declare class ProfileError extends Error {
+    readonly status: 400 | 409;
+    constructor(message: string, status: 400 | 409);
+}
+/**
+ * Appends one profile to profiles.yaml. The file is edited as a YAML document, so comments and the
+ * existing entries stay as they are.
+ */
+export declare function addProfile(request: AddProfileRequest, file?: string): ProfileInfo;
+/**
+ * Deletes the saved login of one profile, so it has to log in again. The file holds the session cookies
+ * and is never read here, only removed.
+ */
+export declare function forgetSession(id: string, file?: string): ProfileInfo;
+/**
+ * Removes one profile from profiles.yaml and deletes its saved login. Only that entry is written, so the
+ * comments and the other entries stay in the file. Screenshot baselines named after the id stay on disk:
+ * they are files of the cases, not of the profile.
+ */
+export declare function deleteProfile(id: string, file?: string): void;
+/**
+ * Changes the fields of one existing profile. Only the fields that actually changed are written, so
+ * comments on the others stay in the file. When the site address changes, the saved login belongs to
+ * the old site and is deleted: the profile has to log in again on the new one.
+ */
+export declare function editProfile(request: EditProfileRequest & {
+    id: string;
+}, file?: string): EditProfileResult;