@xingular/harness 0.1.7 → 1.1.1

package/dist/sdk/terminal/socket.js

@@ -0,0 +1,287 @@
+// The session socket: how a process the harness did not start in-process (the `pi` command in
+// a terminal, with its extension and the `xagent-wiki` / `xagent-mcp` commands) reaches the
+// session it belongs to. Owner-only Unix socket (a named pipe on Windows), newline-delimited JSON.
+// A connection carries one request unless the request asks to `keep` it open, in which case the
+// reply leaves it open for the next request. Each terminal session holds a random token bound to
+// its caller, its connected-apps grant, and its controller; the token stops working when the
+// terminal ends.
+import { randomBytes } from 'node:crypto';
+import { chmodSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { createServer } from 'node:net';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { log } from "../core/bus.js";
+import { HarnessError, toErrorShape } from "../core/errors.js";
+import { newId } from "../core/fs.js";
+const MAX_REQUEST_BYTES = 1024 * 1024;
+/** macOS refuses a socket path longer than 103 bytes. */
+const MAX_SOCKET_PATH = 100;
+/**
+ * Each Harness process listens on its own path. Windows has no socket files for Node's `net`: it
+ * listens on a named pipe in a machine-wide namespace, and a random name keeps another local process
+ * from guessing it. On Unix the file is named for this process, because several Harness processes
+ * may share one state folder: closing a server removes its socket file, so a shared name would let
+ * one process delete, and the next one take over, the path another's sessions still call. The token
+ * still decides what a caller may do.
+ */
+export function socketPath(stateDir) {
+    if (process.platform === 'win32')
+        return `\\\\.\\pipe\\xingular-harness-${randomBytes(12).toString('hex')}`;
+    const path = join(stateDir, 'run', `harness-${process.pid}-${randomBytes(8).toString('hex')}.sock`);
+    if (Buffer.byteLength(path) <= MAX_SOCKET_PATH)
+        return path;
+    return join(tmpdir(), `xh-${process.pid}-${randomBytes(8).toString('hex')}.sock`);
+}
+const OWN_SOCKET = /^harness-(\d+)-[0-9a-f]+\.sock$/;
+/** Removes socket files left in `folder` by Harness processes that are no longer running. */
+function pruneDeadSockets(folder) {
+    let names;
+    try {
+        names = readdirSync(folder);
+    }
+    catch {
+        return;
+    }
+    for (const name of names) {
+        const pid = Number(OWN_SOCKET.exec(name)?.[1]);
+        if (!pid || pid === process.pid || isRunning(pid))
+            continue;
+        rmSync(join(folder, name), { force: true });
+    }
+}
+function isRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+function alternateSocketPath(path) {
+    const candidate = join(dirname(path), `harness-${process.pid}-${randomBytes(8).toString('hex')}.sock`);
+    return Buffer.byteLength(candidate) <= MAX_SOCKET_PATH ? candidate : join(tmpdir(), `xh-${process.pid}-${randomBytes(8).toString('hex')}.sock`);
+}
+/** A named pipe has no folder, file mode, or owner to check or clean up. */
+const isPipePath = (path) => path.startsWith('\\\\.\\pipe\\');
+/** Names the folder and the user when the operating system refuses the socket, so the cause shows. */
+function refusedBind(path, error) {
+    const code = error?.code;
+    if (code !== 'EACCES' && code !== 'EPERM')
+        return error;
+    if (isPipePath(path)) {
+        return new HarnessError('session_socket_denied', `The session pipe ${path} could not be created (${code}).`, 'Start the harness again from your own user session. If it keeps failing, report this code and the Windows version.');
+    }
+    let folder;
+    try {
+        const stat = statSync(dirname(path));
+        folder = `${dirname(path)} is owned by uid ${stat.uid} with mode ${(stat.mode & 0o777).toString(8)}`;
+    }
+    catch {
+        folder = `${dirname(path)} could not be read`;
+    }
+    const uid = process.getuid?.() ?? 'unknown';
+    return new HarnessError('session_socket_denied', `The session socket ${path} could not be created (${code}). ${folder}; this process runs as uid ${uid}.`, 'Run the harness from your own terminal, as the user that owns its state folder, or choose a state folder you own with --state.');
+}
+export class SessionSocket {
+    handlers;
+    server = null;
+    listening = null;
+    socketPathValue;
+    grants = new Map();
+    /**
+     * A second key per token, handed out once. The token is in the session's environment, where a
+     * command the model runs can read it; this key is claimed by the session's extension as it
+     * loads, before any model turn, and kept in its memory only.
+     */
+    controls = new Map();
+    clients = new Set();
+    constructor(path, handlers) {
+        this.handlers = handlers;
+        this.socketPathValue = path;
+    }
+    get path() { return this.socketPathValue; }
+    issue(grant) {
+        const token = `${newId()}${newId()}`.replaceAll('-', '');
+        this.grants.set(token, grant);
+        return token;
+    }
+    revoke(token) {
+        this.grants.delete(token);
+        this.controls.delete(token);
+    }
+    revokeSession(sessionId) {
+        for (const [token, grant] of this.grants)
+            if (grant.sessionId === sessionId)
+                this.revoke(token);
+    }
+    /** Runs one request line and returns the reply line's object. */
+    async handle(line, connection) {
+        try {
+            let request;
+            try {
+                request = JSON.parse(line);
+            }
+            catch {
+                throw new HarnessError('invalid_request', 'The request is not JSON.');
+            }
+            connection?.keep?.(request.keep === true);
+            const token = typeof request.token === 'string' ? request.token : '';
+            const grant = this.grants.get(token);
+            if (!grant)
+                throw new HarnessError('unauthorized', 'This session token is not valid. It ends when its terminal session ends.');
+            if (typeof request.event === 'string') {
+                if (!grant.terminal)
+                    throw new HarnessError('unknown_method', 'This session has no terminal controller.');
+                connection?.waiting(grant);
+                try {
+                    return { result: (await grant.terminal.accept(request.event, (request.data ?? {}))) ?? {} };
+                }
+                finally {
+                    connection?.waiting(null);
+                }
+            }
+            const call = typeof request.call === 'string' ? request.call : '';
+            const params = (request.params && typeof request.params === 'object' ? request.params : {});
+            if (['wiki.', 'skill.', 'recall.', 'trajectory.'].some((prefix) => call.startsWith(prefix)))
+                return { result: this.handlers.memory(grant.caller(), call, params) };
+            if (call === 'tools.list' && !grant.broker)
+                return { result: { tools: [] } };
+            if (['mcp.', 'tools.'].some((prefix) => call.startsWith(prefix))) {
+                if (!grant.broker)
+                    throw new HarnessError('mcp_unauthorized', 'Connected apps are not available to this session.');
+                return { result: await this.handlers.apps(grant.broker, call, params) };
+            }
+            if (call === 'control.claim') {
+                if (this.controls.has(token))
+                    throw new HarnessError('unauthorized', "This session's control key was already claimed.");
+                const key = `${newId()}${newId()}`.replaceAll('-', '');
+                this.controls.set(token, key);
+                return { result: { key } };
+            }
+            if (call.startsWith('terminal.') && grant.terminal?.control) {
+                const key = this.controls.get(token);
+                if (!key || request.control !== key)
+                    throw new HarnessError('unauthorized', 'Only a person at this terminal can answer decisions or change its draft state.');
+                return { result: await grant.terminal.control(call, params) };
+            }
+            if ((call.startsWith('plugins.') || call.startsWith('hub.')) && this.handlers.plugins) {
+                const key = this.controls.get(token);
+                return { result: await this.handlers.plugins(grant, call, params, key !== undefined && request.control === key) };
+            }
+            if (call.startsWith('accounts.') && this.handlers.accounts) {
+                const key = this.controls.get(token);
+                return { result: await this.handlers.accounts(grant, call, params, key !== undefined && request.control === key) };
+            }
+            throw new HarnessError('unknown_method', `Unknown call ${call}.`);
+        }
+        catch (error) {
+            return { error: toErrorShape(error) };
+        }
+    }
+    serve(client) {
+        let buffer = '';
+        let busy = false;
+        let ended = false;
+        let waiting = null;
+        this.clients.add(client);
+        client.on('error', () => { });
+        client.once('close', () => {
+            this.clients.delete(client);
+            // A decision the native process was waiting on can no longer reach it.
+            waiting?.terminal?.disconnected();
+        });
+        // Requests on one connection run one at a time, in order.
+        const next = () => {
+            if (busy || ended)
+                return;
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                return;
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            busy = true;
+            client.pause();
+            let keep = false;
+            void this.handle(line, { waiting: (grant) => void (waiting = grant), keep: (value) => void (keep = value) }).then((reply) => {
+                busy = false;
+                const text = `${JSON.stringify(reply)}\n`;
+                if (!keep || client.destroyed) {
+                    ended = true;
+                    client.end(text);
+                    return;
+                }
+                client.write(text);
+                client.resume();
+                next();
+            });
+        };
+        client.on('data', (chunk) => {
+            buffer += chunk.toString('utf8');
+            if (Buffer.byteLength(buffer) > MAX_REQUEST_BYTES) {
+                client.destroy();
+                return;
+            }
+            next();
+        });
+    }
+    bind(path) {
+        return new Promise((resolve, reject) => {
+            const server = createServer((client) => this.serve(client));
+            server.once('error', reject);
+            server.listen(path, () => {
+                if (!isPipePath(path)) {
+                    try {
+                        chmodSync(path, 0o600);
+                    }
+                    catch (error) {
+                        log('session socket permissions', error instanceof Error ? error.message : String(error));
+                    }
+                }
+                this.server = server;
+                resolve();
+            });
+        });
+    }
+    /** Binds the usual path, or an instance-specific path if another Harness owns it. */
+    async bindAvailablePath() {
+        if (!isPipePath(this.path)) {
+            mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+            pruneDeadSockets(dirname(this.path));
+        }
+        try {
+            await this.bind(this.path);
+        }
+        catch (error) {
+            if (isPipePath(this.path) || error.code !== 'EADDRINUSE')
+                throw refusedBind(this.path, error);
+            this.socketPathValue = alternateSocketPath(this.path);
+            try {
+                await this.bind(this.path);
+            }
+            catch (alternateError) {
+                throw refusedBind(this.path, alternateError);
+            }
+        }
+    }
+    /** Binds the socket once; later calls wait for the same bind. */
+    listen() {
+        this.listening ??= this.bindAvailablePath().catch(error => {
+            this.listening = null;
+            throw error;
+        });
+        return this.listening;
+    }
+    async close() {
+        this.grants.clear();
+        const server = this.server;
+        this.server = null;
+        this.listening = null;
+        for (const client of this.clients)
+            client.destroy();
+        if (server)
+            await new Promise((resolve) => server.close(() => resolve()));
+        if (!isPipePath(this.path))
+            rmSync(this.path, { force: true });
+    }
+}

package/dist/sdk/terminal/standalone.d.ts

@@ -0,0 +1,20 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { type Harness, type HarnessOptions } from "../harness.js";
+export interface StandalonePaths {
+    dataRoot: string;
+    stateDir: string;
+    /** `--worktree [name]`: start in a new managed worktree (true) or the named one. */
+    worktree?: string | true | null;
+}
+export interface StandaloneDependencies {
+    home?: string;
+    cwd?: string;
+    stdinIsTTY?: boolean;
+    stdoutIsTTY?: boolean;
+    createSessionId?: () => string;
+    createHarness?: (options: HarnessOptions) => Harness;
+    spawn?: typeof nodeSpawn;
+}
+export declare function standaloneArguments(argv: string[]): string[] | null;
+export declare function parseStandaloneOptions(argv: string[], home?: string, cwd?: string): StandalonePaths;
+export declare function runStandaloneTerminal(argv: string[], dependencies?: StandaloneDependencies): Promise<number>;

package/dist/sdk/terminal/standalone.js

@@ -0,0 +1,186 @@
+// The standalone host prepares an isolated Harness terminal and supervises its frontend.
+import { spawn as nodeSpawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { setLogSink } from "../core/bus.js";
+import { DEFAULT_PRODUCT_NAME } from "../core/env.js";
+import { createHarness } from "../harness.js";
+export function standaloneArguments(argv) {
+    const command = argv[0];
+    if (!command || command.startsWith('-'))
+        return argv;
+    return command === 'terminal' ? argv.slice(1) : null;
+}
+export function parseStandaloneOptions(argv, home = homedir(), cwd = process.cwd()) {
+    const root = join(home, '.xingular-harness');
+    const paths = {
+        dataRoot: join(root, 'data'),
+        stateDir: join(root, 'state')
+    };
+    const given = new Set();
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === '--worktree' || argument === '-w') {
+            const name = argv[index + 1];
+            if (name && !name.startsWith('-')) {
+                paths.worktree = name;
+                index += 1;
+            }
+            else
+                paths.worktree = true;
+            continue;
+        }
+        if (argument !== '--data' && argument !== '--state')
+            throw new Error(`Unknown standalone option: ${argument}`);
+        const value = argv[index + 1];
+        if (!value || value.startsWith('--'))
+            throw new Error(`${argument} needs a directory path.`);
+        paths[argument === '--data' ? 'dataRoot' : 'stateDir'] = resolve(cwd, value);
+        given.add(argument);
+        index += 1;
+    }
+    // A home that is not a folder path (for example HOME set to the word "HOME") would put the
+    // defaults, and the session socket, in whatever folder the command was started from.
+    if (!isAbsolute(home) && !(given.has('--data') && given.has('--state'))) {
+        throw new Error(`The home folder "${home}" is not an absolute path, so the default data and state folders cannot be placed. Set HOME to your home folder, or pass --data and --state with absolute folders.`);
+    }
+    return paths;
+}
+function processEnvironment(overrides) {
+    const environment = { ...process.env };
+    for (const [name, value] of Object.entries(overrides)) {
+        if (value === null)
+            delete environment[name];
+        else
+            environment[name] = value;
+    }
+    return environment;
+}
+function exitCode(code, signal) {
+    if (code !== null)
+        return code;
+    if (signal === 'SIGINT')
+        return 130;
+    if (signal === 'SIGTERM')
+        return 143;
+    if (signal === 'SIGHUP')
+        return 129;
+    return 1;
+}
+function spawnError(error, launch) {
+    const code = error.code;
+    if (code !== 'ENOENT' && code !== 'EACCES' && code !== 'EPERM')
+        return error;
+    const problem = code === 'ENOENT' ? 'was not found' : `could not start (${code})`;
+    return new Error(`Could not start the Harness terminal. The Bun executable "${launch.program}" ${problem}; install Bun or set XINGULAR_HARNESS_BUN, then run npm run build:tui.`, { cause: error });
+}
+function spawnFrontend(launch, cwd, spawn = nodeSpawn) {
+    return new Promise((resolveExit, reject) => {
+        const child = spawn(launch.program, launch.args, {
+            cwd,
+            env: processEnvironment(launch.env),
+            stdio: 'inherit'
+        });
+        let settled = false;
+        const cleanup = () => {
+            process.off('SIGINT', onInterrupt);
+            process.off('SIGTERM', onTerminate);
+            process.off('SIGHUP', onHangup);
+        };
+        const finish = (action) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            action();
+        };
+        // Ctrl+C is delivered to both processes in the foreground process group. Keep this host
+        // alive while the frontend handles it so the account credentials and harness socket are cleaned up.
+        const onInterrupt = () => undefined;
+        const onTerminate = () => {
+            child.kill('SIGTERM');
+        };
+        const onHangup = () => undefined;
+        process.on('SIGINT', onInterrupt);
+        process.on('SIGTERM', onTerminate);
+        process.on('SIGHUP', onHangup);
+        child.once('error', (error) => finish(() => reject(spawnError(error, launch))));
+        child.once('exit', (code, signal) => finish(() => resolveExit(exitCode(code, signal))));
+    });
+}
+/**
+ * `--worktree`: the named worktree of the repository in `cwd`, or a new managed one. Older managed
+ * worktrees beyond the kept number are pruned (unsaved work is kept as a snapshot).
+ */
+async function enterWorktree(harness, cwd, wanted) {
+    const name = wanted === true ? undefined : wanted;
+    const existing = name ? (await harness.worktrees.list(cwd)).find((record) => record.name === name) : undefined;
+    if (existing)
+        return existing;
+    const created = await harness.worktrees.create({ repo: cwd, ...(name ? { name } : {}) });
+    process.stdout.write(`Working in worktree ${created.worktree.name} (${created.worktree.path}).\n`);
+    if (created.setup.state === 'untrusted')
+        process.stdout.write('This repository has a setup script you have not trusted; read .xharness/worktree-setup, then run: xagent worktree trust-setup\n');
+    if (created.setup.state === 'failed')
+        process.stdout.write(`The worktree setup script failed; see ${created.setup.log}.\n`);
+    await harness.worktrees.prune({ repo: cwd }).catch(() => undefined);
+    return created.worktree;
+}
+export async function runStandaloneTerminal(argv, dependencies = {}) {
+    if (!(dependencies.stdinIsTTY ?? process.stdin.isTTY) || !(dependencies.stdoutIsTTY ?? process.stdout.isTTY)) {
+        throw new Error('The interactive Harness terminal needs a TTY. Run it from a terminal, or use `xagent serve` for a host process.');
+    }
+    let cwd = resolve(dependencies.cwd ?? process.cwd());
+    const paths = parseStandaloneOptions(argv, dependencies.home, cwd);
+    const makeHarness = dependencies.createHarness ?? createHarness;
+    const harness = makeHarness({ dataRoot: paths.dataRoot, stateDir: paths.stateDir, productName: DEFAULT_PRODUCT_NAME });
+    const newSessionId = dependencies.createSessionId ?? randomUUID;
+    let current = { sessionId: newSessionId(), accountId: null, nativeSessionId: null };
+    // The frontend draws on this terminal, so the host's diagnostics go to a file the person can read instead.
+    const logFile = join(paths.stateDir, 'harness.log');
+    setLogSink((text) => {
+        try {
+            appendFileSync(logFile, `${new Date().toISOString()} ${text}\n`);
+        }
+        catch {
+            // Diagnostics are best effort; a full disk must not stop the terminal.
+        }
+    });
+    try {
+        await harness.ready;
+        if (harness.accounts.overview().accounts.length === 0)
+            harness.accounts.create('Default', 'subscription');
+        let worktreeId = null;
+        if (paths.worktree) {
+            const worktree = await enterWorktree(harness, cwd, paths.worktree);
+            cwd = worktree.path;
+            worktreeId = worktree.id;
+        }
+        for (;;) {
+            const sessionFolder = join(paths.dataRoot, 'sessions', 'terminal', createHash('sha256').update(cwd).digest('hex'));
+            const launch = await harness.terminals.prepare({ ...current, cwd, sessionFolder, ...(worktreeId ? { run: { worktreeId } } : {}) });
+            const code = await spawnFrontend(launch, cwd, dependencies.spawn);
+            // `/accounts` and `/worktree` ask for a switch and end the frontend. An account switch resumes
+            // the conversation; a folder switch starts a new one there.
+            const next = harness.terminals.takeRelaunch(current.sessionId);
+            if (!next)
+                return code;
+            if (next.cwd) {
+                process.stdout.write(`Opening ${next.cwd}.\n`);
+                cwd = next.cwd;
+                worktreeId = next.worktreeId ?? null;
+            }
+            else
+                process.stdout.write(`Switching this session to account ${harness.accounts.find(next.accountId).label}.\n`);
+            await harness.terminals.dispose(current.sessionId);
+            current = { sessionId: newSessionId(), accountId: next.accountId, nativeSessionId: next.nativeSessionId };
+        }
+    }
+    finally {
+        await harness.terminals.dispose(current.sessionId);
+        await harness.close();
+        setLogSink(null);
+    }
+}

package/dist/sdk/terminal/subagentMonitor.d.ts

@@ -0,0 +1,38 @@
+import type { RunEvent, RunStatus } from "../sessions/contracts.js";
+/** The agent profile a child started from, as the roster shows it (PROP-0029). */
+export interface TerminalSubagentProfile {
+    name: string;
+    color: string;
+}
+export interface TerminalSubagentRun {
+    id: string;
+    parentRunId: string | null;
+    relation: 'subagent';
+    /** The short name the parent gave the child (PROP-0030). */
+    title: string;
+    goal: string | null;
+    status: RunStatus;
+    startedAt: string;
+    endedAt: string | null;
+    profile?: TerminalSubagentProfile | null;
+}
+export interface TerminalSubagentActivity extends TerminalSubagentRun {
+    activity: string;
+    /** How far the child's own checklist is: counts only, never the items. */
+    checklist: {
+        done: number;
+        total: number;
+    } | null;
+}
+export declare const ACTIVE_SUBAGENT_STATUSES: Set<"queued" | "running" | "waiting_for_approval" | "waiting_for_input" | "interrupted" | "completed" | "failed">;
+export declare function terminalSubagentDuration(activity: TerminalSubagentRun, now?: number): string;
+export declare function terminalSubagentTone(status: RunStatus): 'success' | 'warning' | 'error' | 'muted';
+/** Volatile, read-only activity projection for the active terminal parent run. */
+export declare class SubagentMonitor {
+    private parentRunId;
+    private readonly activities;
+    begin(parentRunId: string): void;
+    observe(parentRunId: string, run: TerminalSubagentRun, event: RunEvent): void;
+    snapshot(parentRunId: string): TerminalSubagentActivity[];
+    clear(parentRunId?: string): void;
+}

package/dist/sdk/terminal/subagentMonitor.js

@@ -0,0 +1,121 @@
+export const ACTIVE_SUBAGENT_STATUSES = new Set(['queued', 'running', 'waiting_for_approval', 'waiting_for_input']);
+export function terminalSubagentDuration(activity, now = Date.now()) {
+    const start = Date.parse(activity.startedAt);
+    const end = activity.endedAt ? Date.parse(activity.endedAt) : now;
+    if (!Number.isFinite(start) || !Number.isFinite(end))
+        return '—';
+    const seconds = Math.max(0, Math.floor((end - start) / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}:${String(seconds % 60).padStart(2, '0')}`;
+    return `${Math.floor(minutes / 60)}h${String(minutes % 60).padStart(2, '0')}m`;
+}
+export function terminalSubagentTone(status) {
+    if (status === 'completed')
+        return 'success';
+    if (status === 'failed')
+        return 'error';
+    if (ACTIVE_SUBAGENT_STATUSES.has(status))
+        return 'warning';
+    return 'muted';
+}
+function statusActivity(status) {
+    switch (status) {
+        case 'queued': return 'Queued';
+        case 'waiting_for_approval': return 'Waiting for approval';
+        case 'waiting_for_input': return 'Waiting for input';
+        case 'completed': return 'Completed';
+        case 'failed': return 'Failed';
+        case 'interrupted': return 'Interrupted';
+        case 'running': return 'Working';
+    }
+}
+function payloadOf(event) {
+    return event.payload && typeof event.payload === 'object' ? event.payload : {};
+}
+function stringOf(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function latestTool(tools) {
+    return [...tools.values()].sort((left, right) => right.sequence - left.sequence)[0]?.text;
+}
+/** Volatile, read-only activity projection for the active terminal parent run. */
+export class SubagentMonitor {
+    parentRunId = null;
+    activities = new Map();
+    begin(parentRunId) {
+        this.parentRunId = parentRunId;
+        this.activities.clear();
+    }
+    observe(parentRunId, run, event) {
+        if (this.parentRunId !== parentRunId || run.relation !== 'subagent')
+            return;
+        const row = this.activities.get(run.id) ?? {
+            id: run.id,
+            parentRunId: run.parentRunId,
+            relation: run.relation,
+            title: run.title,
+            goal: run.goal,
+            status: run.status,
+            startedAt: run.startedAt,
+            endedAt: run.endedAt,
+            activity: statusActivity(run.status),
+            checklist: null,
+            profile: run.profile ?? null,
+            tools: new Map(),
+            lastTool: null
+        };
+        row.parentRunId = run.parentRunId;
+        if (run.profile !== undefined)
+            row.profile = run.profile;
+        row.title = run.title;
+        row.goal = run.goal;
+        row.status = run.status;
+        row.startedAt = run.startedAt;
+        row.endedAt = run.endedAt;
+        const payload = payloadOf(event);
+        if (event.type === 'tool.started') {
+            const toolCallId = stringOf(payload.toolCallId);
+            const name = stringOf(payload.name) ?? 'Tool';
+            if (toolCallId)
+                row.tools.set(toolCallId, { sequence: event.sequence, text: name });
+        }
+        else if (event.type === 'tool.completed') {
+            const toolCallId = stringOf(payload.toolCallId);
+            const tool = toolCallId ? row.tools.get(toolCallId) : undefined;
+            if (tool && (!row.lastTool || tool.sequence >= row.lastTool.sequence))
+                row.lastTool = tool;
+            if (toolCallId)
+                row.tools.delete(toolCallId);
+        }
+        else if (event.type === 'message.delta') {
+            row.lastTool = null;
+            row.activity = 'Responding';
+        }
+        else if (event.type === 'checklist.updated') {
+            const items = Array.isArray(payload.items) ? payload.items : [];
+            row.checklist = items.length ? { done: items.filter(item => item?.status === 'completed').length, total: items.length } : null;
+        }
+        if (run.status !== 'running')
+            row.tools.clear();
+        row.activity = run.status === 'running'
+            ? latestTool(row.tools) ?? row.lastTool?.text ?? (event.type === 'message.delta' ? 'Responding' : 'Working')
+            : statusActivity(run.status);
+        this.activities.set(run.id, row);
+    }
+    snapshot(parentRunId) {
+        if (this.parentRunId !== parentRunId)
+            return [];
+        return [...this.activities.values()]
+            .sort((left, right) => left.startedAt.localeCompare(right.startedAt) || left.id.localeCompare(right.id))
+            .map(({ tools: _tools, lastTool: _lastTool, ...activity }) => activity);
+    }
+    clear(parentRunId) {
+        if (parentRunId && this.parentRunId !== parentRunId)
+            return;
+        this.parentRunId = null;
+        this.activities.clear();
+    }
+}