@xingular/harness 2.0.0 → 2.0.1-unstable

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/hubMenu.d.ts

@@ -0,0 +1,10 @@
+import type { HubOverview } from "../hub/schema.js";
+import type { MenuCall, MenuUi } from "./pluginMenu.js";
+type HubEntry = HubOverview['entries'][number];
+/** What the person is told before installing: the entry, who published it, and what installing does. */
+export declare function hubSummary(entry: HubEntry): string;
+/** Asks, then installs exactly this version. A refusal or a failure is reported and changes nothing. */
+export declare function installHubEntry(ui: MenuUi, call: MenuCall, entry: HubEntry): Promise<void>;
+/** The terminal's catalog uses the same exact-version installer as embedding applications. */
+export declare function runHubMenu(ui: MenuUi, call: MenuCall): Promise<void>;
+export {};

package/dist/sdk/terminal/hubMenu.js

@@ -0,0 +1,34 @@
+/** What the person is told before installing: the entry, who published it, and what installing does. */
+export function hubSummary(entry) {
+    return `${entry.description}\n\nPublisher: ${entry.publisher}\nLicense: ${entry.license}\nSource: ${entry.sourceUrl}\n\n${entry.delivery.kind === 'document' ? 'Saved as data for a compatible application. Nothing is created or enabled.' : 'Installed switched off. Code remains untrusted and approvals remain unchanged.'}`;
+}
+/** Asks, then installs exactly this version. A refusal or a failure is reported and changes nothing. */
+export async function installHubEntry(ui, call, entry) {
+    if (!await ui.confirm(`Install ${entry.title} ${entry.version}?`, hubSummary(entry)))
+        return;
+    try {
+        const receipt = await call('hub.install', { id: entry.id, version: entry.version });
+        ui.notify(receipt.document ? 'Saved in this library for a compatible application.' : 'Installed, switched off. Use /plugins to review and attach it. Changes apply after restarting the session.', 'info');
+    }
+    catch (error) {
+        ui.notify(error instanceof Error ? error.message : String(error), 'error');
+    }
+}
+/** The terminal's catalog uses the same exact-version installer as embedding applications. */
+export async function runHubMenu(ui, call) {
+    for (;;) {
+        const catalog = await call('hub.list');
+        const labels = catalog.entries.map((entry) => `${entry.title} · ${entry.category} · ${entry.id}@${entry.version}`);
+        const picked = await ui.select('Hub', [...labels, 'Refresh catalog', 'Done']);
+        if (picked === 'Refresh catalog') {
+            const refreshed = await call('hub.list', { refresh: true });
+            if (refreshed.error)
+                ui.notify(`${refreshed.error} Using ${refreshed.origin} content.`, 'warning');
+            continue;
+        }
+        const entry = catalog.entries[labels.indexOf(picked ?? '')];
+        if (!entry)
+            return;
+        await installHubEntry(ui, call, entry);
+    }
+}

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

@@ -0,0 +1,5 @@
+/** Files Pi's Git Bash shell and native Windows shells use to call Harness subcommands. */
+export declare function terminalCommandFiles(platform: NodeJS.Platform, node: string, cli: string, name: string, mode: string): Array<{
+    name: string;
+    content: string;
+}>;

package/dist/sdk/terminal/launch.js

@@ -0,0 +1,27 @@
+function bashPath(path) {
+    const drive = /^([a-z]):[\\/](.*)$/i.exec(path);
+    if (drive)
+        return `/${drive[1].toLowerCase()}/${drive[2].replaceAll('\\', '/')}`;
+    if (path.startsWith('\\\\'))
+        return `//${path.slice(2).replaceAll('\\', '/')}`;
+    return path;
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+/** Files Pi's Git Bash shell and native Windows shells use to call Harness subcommands. */
+export function terminalCommandFiles(platform, node, cli, name, mode) {
+    const shellNode = platform === 'win32' ? bashPath(node) : node;
+    const shellCli = platform === 'win32' ? bashPath(cli) : cli;
+    const files = [{
+            name,
+            content: `#!/bin/sh\nexec ${shellQuote(shellNode)} ${shellQuote(shellCli)} ${mode} "$@"\n`
+        }];
+    if (platform === 'win32') {
+        files.push({
+            name: `${name}.cmd`,
+            content: `@echo off\r\n"%XINGULAR_HARNESS_NODE%" "%XINGULAR_HARNESS_CLI%" ${mode} %*\r\nexit /b %ERRORLEVEL%\r\n`
+        });
+    }
+    return files;
+}

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>;
+}