@xingular/harness 2.0.0 → 2.0.1-unstable

package/dist/sdk/terminal/standalone.js

@@ -0,0 +1,329 @@
+// 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 { fileSecretStore } from "../accounts/secrets.js";
+import { setLogSink } from "../core/bus.js";
+import { DEFAULT_PRODUCT_NAME } from "../core/env.js";
+import { interactiveProfileSecretStore, resolveInteractiveProfile } from "../core/interactiveProfile.js";
+import { createHarness } from "../harness.js";
+import { seedVariant } from "../variant/seed.js";
+import * as variantStore from "../variant/store.js";
+import { REMOTE_CONTROL_ENV } from "./client.js";
+export function standaloneArguments(argv) {
+    const command = argv[0];
+    if (!command || command.startsWith('-'))
+        return argv;
+    return command === 'terminal' ? argv.slice(1) : null;
+}
+export function resolveStandaloneOptions(argv, home = homedir(), cwd = process.cwd()) {
+    const overrides = {};
+    const given = new Set();
+    let worktree;
+    let variant;
+    let accountState;
+    let remoteControl = false;
+    let daemon = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === '--remote-control' || argument === '--rc') {
+            remoteControl = true;
+            continue;
+        }
+        if (argument === '--daemon') {
+            daemon = true;
+            continue;
+        }
+        if (argument === '--worktree' || argument === '-w') {
+            const name = argv[index + 1];
+            if (name && !name.startsWith('-')) {
+                worktree = name;
+                index += 1;
+            }
+            else
+                worktree = true;
+            continue;
+        }
+        if (argument === '--variant') {
+            const scope = argv[index + 1];
+            if (!scope || scope.startsWith('-'))
+                throw new Error('--variant needs a variant scope.');
+            variant = scope;
+            index += 1;
+            continue;
+        }
+        if (argument === '--account-state') {
+            const value = argv[index + 1];
+            if (!value || value.startsWith('--'))
+                throw new Error('--account-state needs a state directory path.');
+            accountState = resolve(cwd, value);
+            index += 1;
+            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.`);
+        if (argument === '--data')
+            overrides.dataRoot = resolve(cwd, value);
+        else
+            overrides.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.`);
+    }
+    // `npm run dev` passes these roots explicitly. Keep its profile and credentials separate from
+    // the installed interactive profile, even when that production profile selects a host store.
+    const devRoot = isAbsolute(home) ? join(home, '.xingular-harness-dev') : null;
+    const devData = devRoot ? join(devRoot, 'data') : null;
+    const devState = devRoot ? join(devRoot, 'state') : null;
+    const development = !!devRoot && (overrides.dataRoot === devData || overrides.stateDir === devState);
+    const resolvedProfile = isAbsolute(home)
+        ? resolveInteractiveProfile({
+            home,
+            ...(development ? {
+                configPath: join(devRoot, 'profile.json'),
+                legacyDefaults: {
+                    dataRoot: devData,
+                    stateDir: devState,
+                    defaultVariantScope: 'default',
+                    secretBackend: { kind: 'file', path: join(devState, 'secrets.json') }
+                }
+            } : {}),
+            overrides
+        })
+        : {
+            version: 1,
+            dataRoot: overrides.dataRoot,
+            stateDir: overrides.stateDir,
+            defaultVariantScope: 'default',
+            secretBackend: { kind: 'file', path: join(overrides.stateDir, 'secrets.json') }
+        };
+    // The standalone development launch has no host adapter and must not use the App's Keychain.
+    const profile = development
+        ? { ...resolvedProfile, secretBackend: { kind: 'file', path: join(resolvedProfile.stateDir, 'secrets.json') } }
+        : resolvedProfile;
+    return {
+        profile,
+        paths: {
+            dataRoot: profile.dataRoot,
+            stateDir: profile.stateDir,
+            ...(accountState !== undefined ? { accountState } : {}),
+            ...(worktree !== undefined ? { worktree } : {}),
+            ...(variant !== undefined ? { variant } : {}),
+            ...(remoteControl ? { remoteControl } : {}),
+            ...(daemon ? { daemon } : {})
+        }
+    };
+}
+/** The harness a standalone launch, or the long-lived harness for the same folders, runs. */
+export async function createStandaloneHarness(paths, profile, dependencies = {}) {
+    // `--account-state` takes both halves of another state's account identity, so its credentials
+    // come from that state's own file store rather than from this launch's profile backend.
+    const secrets = paths.accountState
+        ? fileSecretStore(join(paths.accountState, 'secrets.json'))
+        : await interactiveProfileSecretStore(profile, dependencies.hostSecretStore);
+    const makeHarness = dependencies.createHarness ?? createHarness;
+    return makeHarness({
+        dataRoot: paths.dataRoot,
+        stateDir: paths.stateDir,
+        ...(paths.accountState ? { accountsDir: join(paths.accountState, 'accounts') } : {}),
+        productName: DEFAULT_PRODUCT_NAME,
+        secrets
+    });
+}
+/** What every launch needs before its first terminal: the profile's default variant and an account. */
+export function ensureStandaloneDefaults(harness, paths, profile) {
+    const variantScope = paths.variant ?? profile.defaultVariantScope;
+    if (variantScope === profile.defaultVariantScope && !variantStore.head(paths.dataRoot, variantScope)) {
+        variantStore.seed(paths.dataRoot, variantScope, seedVariant(paths.dataRoot, {}), 'interactive profile default');
+    }
+    if (harness.accounts.overview().accounts.length === 0)
+        harness.accounts.create('Default', 'subscription');
+    return variantScope;
+}
+/** Where a terminal in `cwd` keeps its compiled instructions and native history. */
+export function terminalSessionFolder(dataRoot, cwd) {
+    return join(dataRoot, 'sessions', 'terminal', createHash('sha256').update(cwd).digest('hex'));
+}
+export function parseStandaloneOptions(argv, home = homedir(), cwd = process.cwd()) {
+    return resolveStandaloneOptions(argv, home, cwd).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 });
+}
+export 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;
+        let fatal = false;
+        const cleanup = () => {
+            process.off('SIGINT', onInterrupt);
+            process.off('SIGTERM', onTerminate);
+            process.off('SIGHUP', onHangup);
+            process.off('uncaughtException', onFatal);
+            process.off('unhandledRejection', onFatal);
+        };
+        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');
+        };
+        // The window closed: its frontend gets the same hangup and should end. One that is still there
+        // after a moment has no terminal left to restore, so it is ended, and this host carries on
+        // (a detached reply keeps running in the long-lived harness).
+        const onHangup = () => {
+            setTimeout(() => {
+                if (child.exitCode === null && child.signalCode === null)
+                    child.kill('SIGKILL');
+            }, 3000).unref();
+        };
+        // A client frontend's plugins run in this process (ADR-0083). An error nothing caught ends it, as
+        // it ends an in-process frontend, but the window closes first so the terminal is left as it was.
+        const onFatal = (error) => {
+            if (fatal)
+                return;
+            fatal = true;
+            process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+            child.kill('SIGTERM');
+            setTimeout(() => process.exit(1), 5000).unref();
+        };
+        process.on('SIGINT', onInterrupt);
+        process.on('uncaughtException', onFatal);
+        process.on('unhandledRejection', onFatal);
+        process.on('SIGTERM', onTerminate);
+        process.on('SIGHUP', onHangup);
+        child.once('error', (error) => finish(() => reject(spawnError(error, launch))));
+        child.once('exit', (code, signal) => {
+            if (fatal)
+                process.exit(1);
+            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, profile } = resolveStandaloneOptions(argv, dependencies.home, cwd);
+    if (paths.daemon) {
+        const { runDaemonTerminal } = await import("./daemon.js");
+        return runDaemonTerminal({ paths, profile, cwd, ...(dependencies.spawn ? { spawn: dependencies.spawn } : {}), ...(dependencies.createSessionId ? { createSessionId: dependencies.createSessionId } : {}) });
+    }
+    const harness = await createStandaloneHarness(paths, profile, dependencies);
+    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;
+        const variantScope = ensureStandaloneDefaults(harness, paths, profile);
+        let worktreeId = null;
+        if (paths.worktree) {
+            const worktree = await enterWorktree(harness, cwd, paths.worktree);
+            cwd = worktree.path;
+            worktreeId = worktree.id;
+        }
+        // The version this conversation runs: the head at start, or one the person switched to (PROP-0052).
+        let variantVersion = null;
+        for (;;) {
+            const sessionFolder = terminalSessionFolder(paths.dataRoot, cwd);
+            const launch = await harness.terminals.prepare({ ...current, cwd, sessionFolder, variant: { scope: variantScope, ...(variantVersion ? { version: variantVersion } : {}) }, ...(worktreeId ? { run: { worktreeId } } : {}) });
+            const code = await spawnFrontend(paths.remoteControl ? { ...launch, env: { ...launch.env, [REMOTE_CONTROL_ENV]: '1' } } : 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 if (next.variantVersion) {
+                process.stdout.write(`Switching this conversation to variant version ${next.variantVersion.slice(0, 8)}.\n`);
+                variantVersion = next.variantVersion;
+            }
+            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,62 @@
+import { type RunEvent, type RunStatus, type UsagePayload } from "../sessions/contracts.js";
+import type { Effort } from "../sessions/runner.js";
+/** The agent profile a child started from, as the roster shows it (PROP-0029). */
+export interface TerminalSubagentProfile {
+    name: string;
+    color: string;
+}
+/** The main agent's row: the parent run itself, shown by name rather than by a profile. */
+export declare const MAIN_PROFILE: TerminalSubagentProfile;
+export interface TerminalSubagentRun {
+    id: string;
+    parentRunId: string | null;
+    /** `main` is the parent run itself; every other row is a child or nested child. */
+    relation: 'main' | '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;
+    /** The pinned account's display label; subagents never switch accounts. */
+    accountLabel?: string | null;
+    /** Effective launch selection, superseded by provider-reported usage when available. */
+    model?: string | null;
+    effort?: Effort | null;
+}
+export type TerminalSubagentUsage = Partial<Pick<UsagePayload, 'provider' | 'model' | 'inputTokens' | 'outputTokens' | 'cacheReadTokens' | 'cacheWriteTokens' | 'reasoningTokens' | 'costUsd' | 'costSource' | 'requests' | 'contextTokens' | 'contextWindow'>>;
+export interface TerminalSubagentActivity extends TerminalSubagentRun {
+    activity: string;
+    /** When the run last did anything but heartbeat; how long it has been quiet is what a stall is. */
+    lastEventAt?: string;
+    /** Cumulative run usage only; provider reasoning summaries and request details stay private. */
+    usage: TerminalSubagentUsage | null;
+    /** How far the child's own todo is: counts only, never the items. */
+    todo: {
+        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 latest terminal parent run. */
+export declare class SubagentMonitor {
+    private parentRunId;
+    private readonly activities;
+    begin(parentRunId: string): void;
+    /** Folds one event of the tracked parent (`main`) or one of its descendants; `null` seeds the row. */
+    observe(parentRunId: string, run: TerminalSubagentRun, event: RunEvent | null): void;
+    /**
+     * Rebuilds the rows of a parent run that is no longer live, such as the latest one of a reopened
+     * conversation, by folding each run's saved events. Rows keep their final status.
+     */
+    restore(parentRunId: string, runs: readonly {
+        run: TerminalSubagentRun;
+        events: readonly RunEvent[];
+    }[]): void;
+    /** The main row first, then children in start order. */
+    snapshot(parentRunId: string): TerminalSubagentActivity[];
+    clear(parentRunId?: string): void;
+}

package/dist/sdk/terminal/subagentMonitor.js

@@ -0,0 +1,176 @@
+import { usagePayloadSchema } from "../sessions/contracts.js";
+import { toolDisplayName } from "./toolName.js";
+/** The main agent's row: the parent run itself, shown by name rather than by a profile. */
+export const MAIN_PROFILE = { name: 'main', color: 'main' };
+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 latest terminal parent run. */
+export class SubagentMonitor {
+    parentRunId = null;
+    activities = new Map();
+    begin(parentRunId) {
+        this.parentRunId = parentRunId;
+        this.activities.clear();
+    }
+    /** Folds one event of the tracked parent (`main`) or one of its descendants; `null` seeds the row. */
+    observe(parentRunId, run, event) {
+        if (this.parentRunId !== parentRunId)
+            return;
+        if ((run.relation === 'main') !== (run.id === parentRunId))
+            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),
+            todo: null,
+            profile: run.profile ?? null,
+            accountLabel: run.accountLabel ?? null,
+            model: run.model ?? null,
+            effort: run.effort ?? null,
+            usage: null,
+            tools: new Map(),
+            lastTool: null
+        };
+        row.parentRunId = run.parentRunId;
+        if (run.profile !== undefined)
+            row.profile = run.profile;
+        if (run.accountLabel !== undefined)
+            row.accountLabel = run.accountLabel;
+        if (run.model !== undefined && !row.usage?.model)
+            row.model = run.model;
+        if (run.effort !== undefined)
+            row.effort = run.effort;
+        row.title = run.title;
+        row.goal = run.goal;
+        row.status = run.status;
+        row.startedAt = run.startedAt;
+        row.endedAt = run.endedAt;
+        const payload = event ? payloadOf(event) : {};
+        if (event && event.type !== 'heartbeat')
+            row.lastEventAt = event.timestamp;
+        if (!event) {
+            // A seeded row keeps what it already folded.
+        }
+        else if (event.type === 'tool.started') {
+            const toolCallId = stringOf(payload.toolCallId);
+            const name = toolDisplayName(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 === 'usage.updated') {
+            const parsed = usagePayloadSchema.safeParse(payload);
+            if (parsed.success) {
+                const usage = parsed.data;
+                row.usage = {
+                    ...(usage.provider === undefined ? {} : { provider: usage.provider }),
+                    ...(usage.model === undefined ? {} : { model: usage.model }),
+                    ...(usage.inputTokens === undefined ? {} : { inputTokens: usage.inputTokens }),
+                    ...(usage.outputTokens === undefined ? {} : { outputTokens: usage.outputTokens }),
+                    ...(usage.cacheReadTokens === undefined ? {} : { cacheReadTokens: usage.cacheReadTokens }),
+                    ...(usage.cacheWriteTokens === undefined ? {} : { cacheWriteTokens: usage.cacheWriteTokens }),
+                    ...(usage.reasoningTokens === undefined ? {} : { reasoningTokens: usage.reasoningTokens }),
+                    ...(usage.costUsd === undefined ? {} : { costUsd: usage.costUsd }),
+                    ...(usage.costSource === undefined ? {} : { costSource: usage.costSource }),
+                    ...(usage.requests === undefined ? {} : { requests: usage.requests }),
+                    ...(usage.contextTokens === undefined ? {} : { contextTokens: usage.contextTokens }),
+                    ...(usage.contextWindow === undefined ? {} : { contextWindow: usage.contextWindow })
+                };
+            }
+        }
+        else if (event.type === 'todo.updated' || event.type === 'checklist.updated') {
+            const items = Array.isArray(payload.items) ? payload.items : [];
+            row.todo = 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' || (!event && row.activity === 'Responding') ? 'Responding' : 'Working')
+            : statusActivity(run.status);
+        this.activities.set(run.id, row);
+    }
+    /**
+     * Rebuilds the rows of a parent run that is no longer live, such as the latest one of a reopened
+     * conversation, by folding each run's saved events. Rows keep their final status.
+     */
+    restore(parentRunId, runs) {
+        this.begin(parentRunId);
+        for (const { run, events } of runs) {
+            this.observe(parentRunId, run, null);
+            for (const event of events)
+                this.observe(parentRunId, run, event);
+        }
+    }
+    /** The main row first, then children in start order. */
+    snapshot(parentRunId) {
+        if (this.parentRunId !== parentRunId)
+            return [];
+        return [...this.activities.values()]
+            .sort((left, right) => Number(right.relation === 'main') - Number(left.relation === 'main') || 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();
+    }
+}