@xingular/harness 1.0.0 → 1.1.1

package/dist/sdk/terminal/socket.js

@@ -5,8 +5,8 @@
 // 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 { createHash, randomBytes } from 'node:crypto';
-import { chmodSync, mkdirSync, rmSync, statSync } from 'node:fs';
+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';
@@ -17,21 +17,50 @@ const MAX_REQUEST_BYTES = 1024 * 1024;
 /** macOS refuses a socket path longer than 103 bytes. */
 const MAX_SOCKET_PATH = 100;
 /**
- * Windows has no socket files for Node's `net`: it listens on a named pipe, which lives in a
- * machine-wide namespace. A random name keeps another local process from guessing it and standing
- * in front of the session; the token still decides what a caller may do.
+ * 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.sock');
+    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-${createHash('sha256').update(path).digest('hex').slice(0, 16)}.sock`);
+    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-${randomBytes(16).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\\');
@@ -216,8 +245,10 @@ export class SessionSocket {
     }
     /** Binds the usual path, or an instance-specific path if another Harness owns it. */
     async bindAvailablePath() {
-        if (!isPipePath(this.path))
+        if (!isPipePath(this.path)) {
             mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
+            pruneDeadSockets(dirname(this.path));
+        }
         try {
             await this.bind(this.path);
         }

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

@@ -3,6 +3,8 @@ 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;

package/dist/sdk/terminal/standalone.js

@@ -5,10 +5,11 @@ 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('--') || command === '-h')
+    if (!command || command.startsWith('-'))
         return argv;
     return command === 'terminal' ? argv.slice(1) : null;
 }
@@ -21,6 +22,16 @@ export function parseStandaloneOptions(argv, home = homedir(), cwd = process.cwd
     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];
@@ -99,14 +110,32 @@ function spawnFrontend(launch, cwd, spawn = nodeSpawn) {
         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 `xharness serve` for a host process.');
+        throw new Error('The interactive Harness terminal needs a TTY. Run it from a terminal, or use `xagent serve` for a host process.');
     }
-    const cwd = resolve(dependencies.cwd ?? process.cwd());
+    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: 'Xingular Harness' });
+    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.
@@ -123,17 +152,28 @@ export async function runStandaloneTerminal(argv, dependencies = {}) {
         await harness.ready;
         if (harness.accounts.overview().accounts.length === 0)
             harness.accounts.create('Default', 'subscription');
-        const cwdHash = createHash('sha256').update(cwd).digest('hex');
-        const sessionFolder = join(paths.dataRoot, 'sessions', 'terminal', cwdHash);
+        let worktreeId = null;
+        if (paths.worktree) {
+            const worktree = await enterWorktree(harness, cwd, paths.worktree);
+            cwd = worktree.path;
+            worktreeId = worktree.id;
+        }
         for (;;) {
-            const launch = await harness.terminals.prepare({ ...current, cwd, sessionFolder });
+            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` asks for a switch and ends the frontend. The conversation resumes on the chosen account.
+            // `/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;
-            const label = harness.accounts.find(next.accountId).label;
-            process.stdout.write(`Switching this session to account ${label}.\n`);
+            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 };
         }

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

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

@@ -1,5 +1,6 @@
 import type { CapabilitySet } from "../capabilities/types.js";
 import type { Subagents } from "../sessions/subagentService.js";
+import type { SideQuestions } from "../sessions/sideQuestions.js";
 import { type SubagentOptions } from "../sessions/subagents.js";
 import type { Accounts } from "../accounts/accounts.js";
 import type { Approvals } from "../sessions/approvals.js";
@@ -18,11 +19,14 @@ import type { RunRecord } from "../sessions/contracts.js";
 import type { ToolPolicy } from "../sessions/policy.js";
 import type { RunRegistry } from "../sessions/registry.js";
 import type { World } from "../world/world.js";
+import type { Worktrees } from "../worktrees/service.js";
+import type { AnnotationCapture } from "../annotations/capture.js";
+import type { NoteDeliveries } from "../annotations/delivery.js";
 /** The files a terminal session needs on disk, outside this process. */
 export interface TerminalAssets {
     /** The Node binary that runs the commands. */
     node: string;
-    /** The built `xharness` command (`dist/cli.js`). */
+    /** The built `xagent` command (`dist/cli.js`). */
     cli: string;
     /** The built Pi extension (`dist/terminal-pi.js`). */
     piExtension: string;
@@ -52,6 +56,15 @@ export interface TerminalPrepareInput {
     /** Fields copied onto each run this session records. */
     run?: Partial<Pick<RunRecord, 'mode' | 'worktreeId'>>;
 }
+/** What a session asked to restart as: another account, or another folder (a worktree or the main checkout). */
+export interface TerminalRelaunch {
+    accountId: string;
+    nativeSessionId: string | null;
+    /** Restart in this folder, as a new conversation there. */
+    cwd?: string;
+    /** The managed worktree the new folder belongs to; null for the main checkout. */
+    worktreeId?: string | null;
+}
 export interface TerminalLaunch {
     program: string;
     args: string[];
@@ -65,6 +78,8 @@ export interface TerminalsOptions {
     /** Which plugin code in variants a person trusted. */
     trust?: VariantTrust | null;
     subagents?: Subagents;
+    /** Shared tool-free side-question runs. */
+    sideQuestions?: SideQuestions;
     resolveCapabilities?: (caller: CallerContext, tools: readonly string[], cwd: string) => Promise<CapabilitySet>;
     env: HarnessEnv;
     stateDir: string;
@@ -82,6 +97,12 @@ export interface TerminalsOptions {
     assets?: TerminalAssets;
     /** Web, browser and computer tools, offered when their plugins are on. */
     world?: World;
+    /** Managed worktrees: a session naming one works in it and holds it while it lives. */
+    worktrees?: Worktrees;
+    /** The visible browser a person captures page notes in. */
+    noteCapture?: AnnotationCapture;
+    /** Page notes on their way to a session (PROP-0018). */
+    pageNotes?: NoteDeliveries;
 }
 /** What `/plugins` in a terminal can do. Each takes the session's folder, account and project. */
 export interface PluginControl {
@@ -98,6 +119,12 @@ export interface PluginControl {
         pluginId: string;
         settings: Record<string, unknown>;
     }): Promise<Plugin[]>;
+    install?(params: PluginScope & {
+        source: string;
+    }): Promise<Plugin[]>;
+    remove?(params: PluginScope & {
+        pluginId: string;
+    }): Promise<Plugin[]>;
 }
 export declare class Terminals {
     private readonly options;
@@ -110,8 +137,13 @@ export declare class Terminals {
     private readonly worldReadOnly;
     private readonly socket;
     private readonly assets;
-    /** A session's `/accounts` switch, taken once its Pi process has ended. */
+    /** A session's `/accounts` or `/worktree` switch, taken once its Pi process has ended. */
     private readonly relaunches;
+    /** The managed worktree each live session holds. */
+    private readonly worktreeLeases;
+    /** Each child's profile name and colour, looked up once per child run. */
+    private readonly childProfiles;
+    private subagentProfile;
     constructor(options: TerminalsOptions);
     /** The commands a terminal session finds on PATH. Rewritten only when they change. */
     private ensureCommands;
@@ -133,11 +165,14 @@ export declare class Terminals {
      * or removing an account is a person's choice, never the model's shell command.
      */
     private accountsCall;
+    /** `/agents`: the agent profiles this session's folder can use (PROP-0029). */
+    private agentsCall;
+    /** `/worktree`: the managed worktrees of the repository this session works in. */
+    private worktreesCall;
+    /** `/plugin:notes` and `/plugin:annotate`: the page notes a person keeps, and the visible browser they capture them in. */
+    private annotationsCall;
     /** The account a session asked to switch to. Taken once, after its Pi process has ended and before `dispose`. */
-    takeRelaunch(sessionId: string): {
-        accountId: string;
-        nativeSessionId: string | null;
-    } | null;
+    takeRelaunch(sessionId: string): TerminalRelaunch | null;
     private live;
     private historyDir;
     private runRecord;
@@ -147,6 +182,7 @@ export declare class Terminals {
     private subagentsCall;
     private componentsCall;
     private trajectoryCall;
+    private sideQuestionCall;
     /** The only terminal frontend: the Bun-run OpenTUI application. */
     private frontendCommand;
     /**