@xingular/harness 1.6.0-unstable → 2.0.1-unstable

package/dist/sdk/{terminal → sessions}/stallWatch.d.ts

@@ -1,3 +1,5 @@
+/** How often a live reply's progress is checked against the stall windows. */
+export declare const STALL_CHECK_MS = 30000;
 /** Silence with no tool running: the model request never came back. */
 export declare const REPLY_STALL_MS: number;
 /** One tool may run this long; past it the reply is wedged, not busy. */
@@ -11,6 +13,8 @@ export interface ReplyProgress {
 }
 /** Whether a live reply has gone too long without progress and should be ended. The oldest running tool counts. */
 export declare function replyStalled({ now, progressAt, runningTools }: ReplyProgress): boolean;
+/** Whether every tool still running only waits for subagents, which are watched by their own runs. */
+export declare function onlyWaitingForChildren(runningToolNames: readonly string[]): boolean;
 /** The tools that block a reply until its children settle. */
 export declare const CHILD_WAIT_TOOLS: ReadonlySet<string>;
 /** How long a child may stay unsettled after it was told to stop before its parent's own watch resumes. */

package/dist/sdk/{terminal → sessions}/stallWatch.js

@@ -1,10 +1,12 @@
-// A live terminal reply that produced nothing for too long is not working: the person should be
-// told instead of watching a run that never settles. This is the turn-level rule; the run-store
-// sweep (`reconcileStaleRuns`) settles a record whose owner stopped reporting, and both use the
-// same reason, `stalled` (INV-RUN-14).
+// A reply that produced nothing for too long is not working: the person should be told instead of
+// watching a run that never settles. This is the turn-level rule, applied to every harness run
+// (`runTurn`) and to the in-process terminal's reply; the run-store sweep (`reconcileStaleRuns`)
+// settles a record whose owner stopped reporting, and all use the same reason, `stalled` (INV-RUN-14).
 //
 // A reply that waits for its subagents is not silent: each child is watched on its own clock and ended
 // with the same reason when it goes quiet, so the wait returns and the parent carries on by itself.
+/** How often a live reply's progress is checked against the stall windows. */
+export const STALL_CHECK_MS = 30_000;
 /** Silence with no tool running: the model request never came back. */
 export const REPLY_STALL_MS = 15 * 60_000;
 /** One tool may run this long; past it the reply is wedged, not busy. */
@@ -17,6 +19,10 @@ export function replyStalled({ now, progressAt, runningTools }) {
         ? now - Math.min(...runningTools) >= TOOL_STALL_MS
         : now - progressAt >= REPLY_STALL_MS;
 }
+/** Whether every tool still running only waits for subagents, which are watched by their own runs. */
+export function onlyWaitingForChildren(runningToolNames) {
+    return runningToolNames.length > 0 && runningToolNames.every((name) => CHILD_WAIT_TOOLS.has(name));
+}
 /** The tools that block a reply until its children settle. */
 export const CHILD_WAIT_TOOLS = new Set(['wait_subagents', 'spawn_subagent']);
 /** How long a child may stay unsettled after it was told to stop before its parent's own watch resumes. */

package/dist/sdk/sessions/subagentService.js

@@ -69,7 +69,7 @@ export class Subagents {
         const ready = new Promise(resolve => { started = resolve; });
         if (!deferUntilPrompt)
             started();
-        this.parents.set(input.run.id, { ready, started, input: structuredClone({ ...input, text: '', images: undefined, requiresImageInput: false, preamble: null, resume: null }), accountId, capabilities: ceiling, stopped: new AbortController(), recovered: new Set(), launching: new Map() });
+        this.parents.set(input.run.id, { ready, started, input: structuredClone({ ...input, text: '', images: undefined, requiresImageInput: false, preamble: null, resume: null, live: undefined }), accountId, capabilities: ceiling, stopped: new AbortController(), recovered: new Set(), launching: new Map() });
     }
     runtimeSettings(runId) {
         return this.runtimeSettingsByRun.get(runId) ?? null;

package/dist/sdk/terminal/controller.js

@@ -7,7 +7,7 @@ import { HarnessError } from "../core/errors.js";
 import { isActiveStatus, runStatusSchema } from "../sessions/contracts.js";
 import { briefTitle } from "../sessions/subagents.js";
 import { MAIN_PROFILE, SubagentMonitor } from "./subagentMonitor.js";
-import { childStalled, replyStalled, waitingOnChildren } from "./stallWatch.js";
+import { STALL_CHECK_MS, childStalled, replyStalled, waitingOnChildren } from "../sessions/stallWatch.js";
 /** Stop codes the native extension may report for a reply it settled itself. */
 const SETTLED_CODES = new Set(['slice_budget', 'compaction_thrash', 'needs_person', 'unfinished']);
 function monitorRun(record, relation, profile, runtime) {
@@ -26,8 +26,6 @@ function monitorRun(record, relation, profile, runtime) {
 }
 const READY_TIMEOUT_MS = 90_000;
 const ACK_TIMEOUT_MS = 25_000;
-/** How often a live reply's progress is checked against the stall windows. */
-const STALL_CHECK_MS = 30_000;
 export class TerminalController {
     hooks;
     run = null;

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

@@ -0,0 +1,44 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import type { InteractiveProfile } from "../core/interactiveProfile.js";
+import { type HarnessClient } from "../server/socket.js";
+import { type StandaloneDependencies, type StandalonePaths } from "./standalone.js";
+import type { DetachedTerminal } from "./terminals.js";
+export interface DaemonFiles {
+    socket: string;
+    lock: string;
+    log: string;
+}
+export declare function daemonFiles(stateDir: string): DaemonFiles;
+interface LockRecord {
+    pid: number;
+    startedAt: string;
+    socket: string;
+}
+/** The running daemon's lock record, or null when none is running (a stale lock is not one). */
+export declare function daemonRecord(stateDir: string): LockRecord | null;
+/** Takes the state folder's lock for this process, or refuses when another daemon holds it. */
+export declare function acquireDaemonLock(stateDir: string): () => void;
+/** Runs the long-lived harness in this process until it is stopped. */
+export declare function runDaemon(paths: StandalonePaths, profile: InteractiveProfile, dependencies?: Pick<StandaloneDependencies, 'createHarness' | 'hostSecretStore'>): Promise<number>;
+/** Connects to the daemon for these folders, starting it first when `start` is set and none runs. */
+export declare function connectDaemon(paths: StandalonePaths, options?: {
+    start: boolean;
+    spawn?: typeof nodeSpawn;
+    timeoutMs?: number;
+}): Promise<HarnessClient>;
+export interface DaemonTerminalOptions {
+    paths: StandalonePaths;
+    profile: InteractiveProfile;
+    cwd: string;
+    spawn?: typeof nodeSpawn;
+    createSessionId?: () => string;
+    /** Reattach to this detached session instead of starting a new one. */
+    attach?: DetachedTerminal;
+}
+/** `xagent --daemon` and `xagent attach`: a terminal window on the long-lived harness. */
+export declare function runDaemonTerminal(options: DaemonTerminalOptions): Promise<number>;
+/** `xagent attach [session id]`: reconnects a window to a reply that kept running. */
+export declare function runAttach(paths: StandalonePaths, profile: InteractiveProfile, sessionId: string | undefined, cwd: string): Promise<number>;
+/** `xagent daemon <start | stop | status | run>`. */
+export declare function runDaemonCommand(subcommand: string | undefined, paths: StandalonePaths, profile: InteractiveProfile): Promise<number>;
+export {};

package/dist/sdk/terminal/daemon.js

@@ -0,0 +1,264 @@
+// The long-lived harness for one data root and state folder (ADR-0083, phase 3). `xagent --daemon`
+// starts it when it is not running and prepares its terminal there, so a reply keeps running when the
+// window closes; `xagent attach` reconnects a window to it. It serves the server protocol on a
+// socket in the state folder that only this user can open, and one lock keeps it the only harness
+// writing for that state folder.
+import { spawn as nodeSpawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, writeSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { log, setLogSink } from "../core/bus.js";
+import { HarnessError } from "../core/errors.js";
+import { connectHarness, serveSocket } from "../server/socket.js";
+import { REMOTE_CONTROL_ENV } from "./client.js";
+import { HARNESS_RUNTIME_ENV } from "./tui/harnessRuntime.js";
+import { createStandaloneHarness, ensureStandaloneDefaults, spawnFrontend, terminalSessionFolder } from "./standalone.js";
+export function daemonFiles(stateDir) {
+    return { socket: join(stateDir, 'harness.sock'), lock: join(stateDir, 'harness.lock'), log: join(stateDir, 'harness.log') };
+}
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/** The running daemon's lock record, or null when none is running (a stale lock is not one). */
+export function daemonRecord(stateDir) {
+    const { lock } = daemonFiles(stateDir);
+    if (!existsSync(lock))
+        return null;
+    try {
+        const record = JSON.parse(readFileSync(lock, 'utf8'));
+        return typeof record.pid === 'number' && alive(record.pid) ? record : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Takes the state folder's lock for this process, or refuses when another daemon holds it. */
+export function acquireDaemonLock(stateDir) {
+    const files = daemonFiles(stateDir);
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const descriptor = openSync(files.lock, 'wx', 0o600);
+            const record = { pid: process.pid, startedAt: new Date().toISOString(), socket: files.socket };
+            writeSync(descriptor, JSON.stringify(record));
+            closeSync(descriptor);
+            return () => {
+                try {
+                    const current = JSON.parse(readFileSync(files.lock, 'utf8'));
+                    if (current.pid === process.pid)
+                        rmSync(files.lock, { force: true });
+                }
+                catch {
+                    // Already gone.
+                }
+            };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const running = daemonRecord(stateDir);
+            if (running)
+                throw new HarnessError('daemon_running', `A harness is already running for this state folder (process ${running.pid}).`);
+            // The process that held it is gone: the lock is stale.
+            rmSync(files.lock, { force: true });
+        }
+    }
+    throw new HarnessError('daemon_running', 'The harness lock could not be taken.');
+}
+/** Runs the long-lived harness in this process until it is stopped. */
+export async function runDaemon(paths, profile, dependencies = {}) {
+    const files = daemonFiles(paths.stateDir);
+    // A first run may come before anything has made the state folder.
+    mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
+    const release = acquireDaemonLock(paths.stateDir);
+    setLogSink((text) => {
+        try {
+            appendFileSync(files.log, `${new Date().toISOString()} [daemon] ${text}\n`);
+        }
+        catch {
+            // Best effort.
+        }
+    });
+    const harness = await createStandaloneHarness(paths, profile, dependencies);
+    // Plugins run here for every window. One plugin's uncaught error is logged; it does not end every
+    // session the harness holds, as it would end a single in-process terminal.
+    const survive = (error) => { log('uncaught error in the long-lived harness', error instanceof Error ? error.stack ?? error.message : String(error)); };
+    process.on('uncaughtException', survive);
+    process.on('unhandledRejection', survive);
+    try {
+        await harness.ready;
+        const variantScope = ensureStandaloneDefaults(harness, paths, profile);
+        const startedAt = new Date().toISOString();
+        let stopping = null;
+        const stopped = new Promise((resolveStop) => { stopping = resolveStop; });
+        const server = await serveSocket(harness, files.socket, {
+            'daemon.status': () => ({ pid: process.pid, startedAt, variantScope, live: harness.sessions.liveSessions(), detached: harness.terminals.detached() }),
+            'daemon.stop': () => {
+                setImmediate(() => stopping?.());
+                return { stopping: true };
+            }
+        });
+        process.once('SIGTERM', () => stopping?.());
+        process.once('SIGINT', () => stopping?.());
+        await stopped;
+        await server.close();
+        return 0;
+    }
+    finally {
+        await Promise.race([harness.close(), new Promise((done) => setTimeout(done, 5000))]);
+        process.off('uncaughtException', survive);
+        process.off('unhandledRejection', survive);
+        release();
+        setLogSink(null);
+    }
+}
+/** The path flags that name these folders, for a daemon started in another process. */
+function pathArguments(paths) {
+    return ['--data', paths.dataRoot, '--state', paths.stateDir, ...(paths.accountState ? ['--account-state', paths.accountState] : [])];
+}
+const cliPath = () => {
+    // The bundled CLI is the file this code was bundled into; from source it is the package's `dist/cli.js`.
+    const here = fileURLToPath(import.meta.url);
+    return here.endsWith('cli.js') ? here : resolve(here, '..', '..', '..', 'dist', 'cli.js');
+};
+/** Connects to the daemon for these folders, starting it first when `start` is set and none runs. */
+export async function connectDaemon(paths, options = { start: true }) {
+    const files = daemonFiles(paths.stateDir);
+    const tryConnect = async () => {
+        if (!daemonRecord(paths.stateDir) || !existsSync(files.socket))
+            return null;
+        return connectHarness(files.socket).catch(() => null);
+    };
+    const existing = await tryConnect();
+    if (existing)
+        return existing;
+    if (!options.start)
+        throw new HarnessError('daemon_not_running', 'No harness is running for these folders. Start one with: xagent daemon start');
+    const child = (options.spawn ?? nodeSpawn)(process.execPath, [cliPath(), 'daemon', 'run', ...pathArguments(paths)], { detached: true, stdio: 'ignore', env: process.env });
+    child.unref();
+    const deadline = Date.now() + (options.timeoutMs ?? 20_000);
+    while (Date.now() < deadline) {
+        const client = await tryConnect();
+        if (client)
+            return client;
+        await new Promise((wait) => setTimeout(wait, 100));
+    }
+    throw new HarnessError('daemon_unavailable', `The harness did not start; see ${files.log}.`);
+}
+/** `xagent --daemon` and `xagent attach`: a terminal window on the long-lived harness. */
+export async function runDaemonTerminal(options) {
+    const { paths, profile } = options;
+    const client = await connectDaemon(paths, { start: !options.attach, ...(options.spawn ? { spawn: options.spawn } : {}) });
+    const newSessionId = options.createSessionId ?? randomUUID;
+    let cwd = options.attach?.cwd ?? options.cwd;
+    let current = options.attach
+        ? { sessionId: options.attach.sessionId, accountId: options.attach.accountId, nativeSessionId: null }
+        : { sessionId: newSessionId(), accountId: null, nativeSessionId: null };
+    let attach = Boolean(options.attach);
+    try {
+        const status = await client.call('daemon.status');
+        const variantScope = paths.variant ?? status.variantScope ?? profile.defaultVariantScope;
+        let variantVersion = null;
+        for (;;) {
+            const sessionFolder = options.attach && attach ? options.attach.sessionFolder : terminalSessionFolder(paths.dataRoot, cwd);
+            const launch = await client.call('terminal.prepare', {
+                ...current, cwd, sessionFolder,
+                variant: { scope: variantScope, ...(variantVersion ? { version: variantVersion } : {}) },
+                ...(attach ? { attach: true } : {})
+            }, 120_000);
+            attach = false;
+            const env = { ...launch.env, [HARNESS_RUNTIME_ENV]: 'harness', ...(paths.remoteControl ? { [REMOTE_CONTROL_ENV]: '1' } : {}) };
+            const code = await spawnFrontend({ ...launch, env }, cwd, options.spawn);
+            const next = await client.call('terminal.takeRelaunch', { sessionId: current.sessionId });
+            if (!next) {
+                const detached = await client.call('terminal.detach', { sessionId: current.sessionId });
+                if (detached.detached)
+                    process.stdout.write(`The reply is still running in the harness. Reattach with: xagent attach ${current.sessionId}\n`);
+                return code;
+            }
+            if (next.cwd) {
+                process.stdout.write(`Opening ${next.cwd}.\n`);
+                cwd = next.cwd;
+            }
+            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 another account.\n');
+            await client.call('terminal.dispose', { sessionId: current.sessionId });
+            current = { sessionId: newSessionId(), accountId: next.accountId, nativeSessionId: next.nativeSessionId };
+        }
+    }
+    finally {
+        client.close();
+    }
+}
+/** `xagent attach [session id]`: reconnects a window to a reply that kept running. */
+export async function runAttach(paths, profile, sessionId, cwd) {
+    const client = await connectDaemon(paths, { start: false });
+    let detached;
+    try {
+        detached = (await client.call('terminal.detached')).sessions;
+    }
+    finally {
+        client.close();
+    }
+    const chosen = sessionId ? detached.find((entry) => entry.sessionId === sessionId) : detached.length === 1 ? detached[0] : undefined;
+    if (!chosen) {
+        if (!detached.length)
+            process.stdout.write('No reply is running without a window.\n');
+        else {
+            process.stdout.write('Choose a session to reattach:\n');
+            for (const entry of detached)
+                process.stdout.write(`  xagent attach ${entry.sessionId}   ${entry.cwd}  (since ${entry.detachedAt})\n`);
+        }
+        return detached.length ? 2 : 1;
+    }
+    return runDaemonTerminal({ paths, profile, cwd, attach: chosen });
+}
+/** `xagent daemon <start | stop | status | run>`. */
+export async function runDaemonCommand(subcommand, paths, profile) {
+    switch (subcommand) {
+        case 'run': return runDaemon(paths, profile);
+        case 'start': {
+            const client = await connectDaemon(paths, { start: true });
+            const status = await client.call('daemon.status');
+            client.close();
+            process.stdout.write(`The harness is running (process ${status.pid}).\n`);
+            return 0;
+        }
+        case 'status': {
+            const record = daemonRecord(paths.stateDir);
+            if (!record) {
+                process.stdout.write('No harness is running for these folders.\n');
+                return 1;
+            }
+            const client = await connectDaemon(paths, { start: false });
+            const status = await client.call('daemon.status');
+            client.close();
+            process.stdout.write(`The harness is running (process ${status.pid}, since ${status.startedAt}): ${status.live.length} live session(s), ${status.detached.length} reply(ies) without a window.\n`);
+            return 0;
+        }
+        case 'stop': {
+            if (!daemonRecord(paths.stateDir)) {
+                process.stdout.write('No harness is running for these folders.\n');
+                return 0;
+            }
+            const client = await connectDaemon(paths, { start: false });
+            await client.call('daemon.stop').catch(() => undefined);
+            await Promise.race([client.closed, new Promise((done) => setTimeout(done, 10_000))]);
+            process.stdout.write('The harness stopped.\n');
+            return 0;
+        }
+        default:
+            process.stdout.write('Usage: xagent daemon <start | stop | status> [--data <dir>] [--state <dir>] [--account-state <dir>]\n');
+            return 2;
+    }
+}

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

@@ -0,0 +1,96 @@
+import type { CallerContext } from "../core/caller.js";
+import type { VariantChoice } from "../variant/materialise.js";
+import type { Launch } from "../prompt/compile.js";
+import type { RunRegistry } from "../sessions/registry.js";
+import type { SessionRunInput, Sessions } from "../sessions/sessions.js";
+/** Pi's own tools a terminal session has active, as the in-process terminal has them. */
+export declare const TERMINAL_NATIVE_TOOLS: string[];
+export interface LiveTerminalContext {
+    sessionId: string;
+    root: string;
+    accountId: string;
+    cwd: string;
+    sessionDir: string;
+    caller: CallerContext;
+    variant: VariantChoice | null;
+    launch: Launch | undefined;
+    connections: boolean;
+    readOnly: boolean;
+    /** The terminal's subagent options; null switches them off. */
+    subagents?: SessionRunInput['subagents'];
+    /** Always allow a tool for every session of this profile, as the terminal's own approvals do. */
+    allowTool(target: string): void;
+    /** The session's other tools, as terminal preparation lists them: launch and switched-on world tools. */
+    tools?(): Promise<string[]>;
+    /** The plugin commands the session's trusted extensions register, for the palette before the first turn. */
+    commands?(): Promise<LiveCommand[]>;
+}
+/** A plugin command as Pi's extension runner lists it, with what its owner prefix is derived from. */
+export interface LiveCommand {
+    name: string;
+    invocationName: string;
+    description: string;
+    sourceInfo: unknown;
+}
+/** Pi's names for the commands of loaded extensions: a name two extensions share gets `:2`, `:3`. */
+export declare function registeredCommands(extensions: ReadonlyArray<{
+    commands: Map<string, {
+        name: string;
+        description?: string;
+        sourceInfo?: unknown;
+    }>;
+    sourceInfo?: unknown;
+}>): LiveCommand[];
+export declare class LiveTerminal {
+    private readonly context;
+    private readonly sessions;
+    private readonly runs;
+    private readonly journal;
+    private seq;
+    private readonly waiters;
+    private pendingRevision;
+    private readonly pendingWaiters;
+    private activeRunId;
+    private lastRunId;
+    private readonly stops;
+    private disposed;
+    private readonly settledListeners;
+    constructor(context: LiveTerminalContext, sessions: Sessions, runs: RunRegistry);
+    /** The subagents of the active reply: their approvals and questions are this terminal's too. */
+    private children;
+    private isOwnChild;
+    private append;
+    private bumpPending;
+    private wait;
+    private known;
+    /** Pi's id of this terminal's conversation, as its harness runs record it. */
+    get nativeSessionId(): string | null;
+    /** The history file of this terminal's conversation, once it has one. */
+    get sessionFile(): string | null;
+    /** The reply running now, if one is. */
+    get activeRun(): string | null;
+    /** Called each time the terminal's replies have all settled and nothing else is queued. */
+    onSettled(listener: () => void): () => void;
+    /** The run this terminal is showing, or the last one it finished. */
+    get lastRun(): string | null;
+    call(call: string, params: Record<string, unknown>): Promise<unknown>;
+    private text;
+    private listed;
+    private state;
+    private events;
+    private started;
+    private run;
+    /** The decisions waiting; `ownDialogs` leaves out plugin dialogs the window shows itself. */
+    private pending;
+    private decision;
+    private approve;
+    private answer;
+    private answers;
+    /** A message from another surface of this terminal (remote control): a new reply, or a follow-up. */
+    send(text: string): Promise<{
+        runId: string;
+    } | {
+        queued: number;
+    }>;
+    dispose(): Promise<void>;
+}