@xingular/harness 1.6.0-unstable → 2.0.1-unstable

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

@@ -60,6 +60,18 @@ export interface TerminalPrepareInput {
     connections?: boolean;
     /** Fields copied onto each run this session records. */
     run?: Partial<Pick<RunRecord, 'mode' | 'worktreeId'>>;
+    /** Reattach to this session id's detached client terminal, whose reply kept running (ADR-0083). */
+    attach?: boolean;
+}
+/** A client terminal whose window closed while its reply was running (ADR-0083, phase 3). */
+export interface DetachedTerminal {
+    sessionId: string;
+    cwd: string;
+    sessionFolder: string;
+    accountId: string;
+    activeRunId: string | null;
+    sessionFile: string | null;
+    detachedAt: string;
 }
 /** What a session asked to restart as: another account, or another folder (a worktree or the main checkout). */
 export interface TerminalRelaunch {
@@ -118,6 +130,8 @@ export interface TerminalsOptions {
     remoteControl?: RemoteControlOptions;
     /** Refinements, for `/refine` (PROP-0052). */
     refine?: Refinements;
+    /** The harness's sessions: a terminal frontend that is a client of the harness runs its turns here (ADR-0083). */
+    sessionService?: import("../sessions/sessions.js").Sessions;
 }
 /** What `/plugins` in a terminal can do. Each takes the session's folder, account and project. */
 export interface PluginControl {
@@ -168,6 +182,10 @@ export declare class Terminals {
     private readonly worktreeLeases;
     /** `/remote-control` for each live session that opened it. */
     private readonly remotes;
+    /** Terminals whose frontend is a client of the harness (ADR-0083). */
+    private readonly clients;
+    /** Client terminals whose window closed while a reply ran; they end when it settles. */
+    private readonly detachedClients;
     /** Each child's profile name and colour, looked up once per child run. */
     private readonly childProfiles;
     private subagentProfile;
@@ -264,6 +282,31 @@ export declare class Terminals {
     private remotePort;
     private remoteCall;
     /** The terminal process ended (or never started): its turn, tokens, and written credentials go with it. */
+    /**
+     * The native conversation a terminal's runs carry. A client terminal's runs are harness runs, which
+     * record Pi's session id; an in-process terminal's record its history file (ADR-0083).
+     */
+    private nativeOf;
+    /** The history file a relaunch of this terminal resumes. */
+    private historyFileOf;
+    /**
+     * Where a terminal's decision and stop calls go: its controller, or, once the frontend is a client
+     * of the harness, the live session's run (ADR-0083).
+     */
+    private controlFor;
+    /** The client half of a terminal whose frontend runs no Pi of its own (ADR-0083). */
+    private liveTerminal;
+    /**
+     * The terminal's window closed. A client terminal whose reply is still running keeps it running in
+     * the harness, without the window, until it settles; `prepare({ attach: true })` reconnects to it.
+     * Anything else ends now, as `dispose` does.
+     */
+    detach(sessionId: string): Promise<{
+        detached: boolean;
+        activeRunId: string | null;
+    }>;
+    /** Client terminals whose reply is running without a window. */
+    detached(): DetachedTerminal[];
     dispose(sessionId: string): Promise<void>;
     close(): Promise<void>;
 }

package/dist/sdk/terminal/terminals.js

@@ -17,6 +17,18 @@ import { newId, now } from "../core/fs.js";
 import { formatBashCommandForApproval } from "../core/workspaceBashTool.js";
 import { resolveWorkspaceRoot } from "../core/workspace.js";
 import { prependSearchPath, searchPath } from "../core/path.js";
+import { LiveTerminal, registeredCommands } from "./liveTerminal.js";
+import { loadResources } from "../sessions/runner.js";
+import { loadPi } from "../pi/runtime.js";
+/** A client terminal's decision and stop calls, and the live-session routes that answer them. */
+const LIVE_DECISION_CALLS = {
+    'terminal.pending': 'terminal.live.pending',
+    'terminal.pending.wait': 'terminal.live.pending.wait',
+    'terminal.approve': 'terminal.live.approve',
+    'terminal.answer': 'terminal.live.answer',
+    'terminal.answers': 'terminal.live.answers',
+    'terminal.interrupt': 'terminal.live.interrupt'
+};
 import { dispatch } from "../tools/dispatch.js";
 import { defaultSkillPaths } from "../tools/defaultSkills.js";
 import { materialise } from "../variant/materialise.js";
@@ -94,6 +106,10 @@ export class Terminals {
     worktreeLeases = new Map();
     /** `/remote-control` for each live session that opened it. */
     remotes = new Map();
+    /** Terminals whose frontend is a client of the harness (ADR-0083). */
+    clients = new Map();
+    /** Client terminals whose window closed while a reply ran; they end when it settles. */
+    detachedClients = new Map();
     /** Each child's profile name and colour, looked up once per child run. */
     childProfiles = new Map();
     subagentProfile(record) {
@@ -128,7 +144,7 @@ export class Terminals {
      */
     hydrateMonitor(live, owners) {
         const { root } = this.options.env;
-        const native = live.controller.nativeSessionId;
+        const native = this.nativeOf(live);
         if (!native)
             return;
         for (const id of [...owners].reverse()) {
@@ -504,7 +520,7 @@ export class Terminals {
             case 'accounts.relaunch': {
                 // Checked here so a bad choice is refused before the session is asked to end.
                 const target = accounts.resolve(text('accountId'));
-                this.relaunches.set(sessionId, { accountId: target.id, nativeSessionId: live.controller.nativeSessionId });
+                this.relaunches.set(sessionId, { accountId: target.id, nativeSessionId: this.historyFileOf(live) });
                 return { accountId: target.id, label: target.label };
             }
             default:
@@ -612,7 +628,7 @@ export class Terminals {
         if (!runId)
             return { attribution: null, text: null };
         if (params.runId !== undefined)
-            readTerminalTrajectory(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId, runId);
+            readTerminalTrajectory(this.options.env.root, live.input.sessionId, this.nativeOf(live), runId);
         const text = typeof params.section === 'string' && params.section ? rowText(this.options.env, runId, params.section) : null;
         return { attribution: attribution(this.options.env, runId), text };
     }
@@ -1090,23 +1106,23 @@ export class Terminals {
             root: this.options.env.root,
             bus: this.options.bus,
             sessionId,
-            nativeSessionId: live.controller.nativeSessionId,
+            nativeSessionId: this.nativeOf(live),
             scope,
             pinned: live.variant?.fingerprint ?? null,
             active: () => Boolean(this.options.runs.activeForSession(sessionId)) || live.controller.state().active,
-            relaunchOn: (version) => this.relaunches.set(sessionId, { accountId: live.account.id, nativeSessionId: live.controller.nativeSessionId, variantVersion: version }),
+            relaunchOn: (version) => this.relaunches.set(sessionId, { accountId: live.account.id, nativeSessionId: this.historyFileOf(live), variantVersion: version }),
             refine: this.options.refine ?? null,
             started
         };
     }
     trajectoryCall(live, call, params) {
         if (call === 'terminal.trajectory.list') {
-            return { runs: listTerminalTrajectoryRuns(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId) };
+            return { runs: listTerminalTrajectoryRuns(this.options.env.root, live.input.sessionId, this.nativeOf(live)) };
         }
         if (call === 'terminal.trajectory.details') {
             if (typeof params.runId !== 'string' || !params.runId)
                 throw invalid('A run id is required.');
-            readTerminalTrajectory(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId, params.runId);
+            readTerminalTrajectory(this.options.env.root, live.input.sessionId, this.nativeOf(live), params.runId);
             return runDetails(this.options.env.root, params.runId);
         }
         if (call === 'terminal.trajectory.events') {
@@ -1115,7 +1131,7 @@ export class Terminals {
             const afterSequence = params.afterSequence;
             if (afterSequence !== undefined && typeof afterSequence !== 'number')
                 throw invalid('The event sequence must be a number.');
-            return readTerminalTrajectory(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId, params.runId, afterSequence);
+            return readTerminalTrajectory(this.options.env.root, live.input.sessionId, this.nativeOf(live), params.runId, afterSequence);
         }
         throw new HarnessError('unknown_method', `Unknown call ${call}.`);
     }
@@ -1129,7 +1145,7 @@ export class Terminals {
             const context = params.context && typeof params.context === 'object' && !Array.isArray(params.context)
                 ? params.context
                 : undefined;
-            const latest = listTerminalTrajectoryRuns(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId)
+            const latest = listTerminalTrajectoryRuns(this.options.env.root, live.input.sessionId, this.nativeOf(live))
                 .find(run => findRun(this.options.env.root, run.id)?.trigger !== 'side-question');
             return service.start({
                 sessionId: live.input.sessionId,
@@ -1174,6 +1190,18 @@ export class Terminals {
         const { root } = env;
         if (!input?.sessionId || !input.cwd || !input.sessionFolder)
             throw invalid('A terminal session needs an id, a working folder, and its own folder.');
+        const carried = input.attach ? this.detachedClients.get(input.sessionId) ?? null : null;
+        if (input.attach) {
+            if (!carried)
+                throw new HarnessError('not_found', 'There is no detached terminal session with this id.');
+            if (carried.info.cwd !== input.cwd || carried.info.sessionFolder !== input.sessionFolder || (input.accountId && input.accountId !== carried.info.accountId)) {
+                throw invalid('Reattach a terminal session in its own folder, on its own account.');
+            }
+            this.detachedClients.delete(input.sessionId);
+            carried.stop();
+            input.accountId = carried.info.accountId;
+            input.nativeSessionId = carried.client.sessionFile ?? input.nativeSessionId ?? null;
+        }
         await this.dispose(input.sessionId);
         const sessionId = input.sessionId;
         let acquiredWorktreeId = null;
@@ -1250,6 +1278,8 @@ export class Terminals {
                     answerQuestions: (runId, batchId, answers) => this.options.runs.answerQuestions(runId, batchId, answers)
                 })
             };
+            if (carried)
+                this.clients.set(sessionId, carried.client);
             token = this.socket.issue({
                 sessionId,
                 caller: () => ({ ...caller, runId: live.controller.activeRun?.runId ?? null }),
@@ -1356,6 +1386,8 @@ export class Terminals {
                                 return doctor.cancel(id);
                             throw invalid('Unknown diagnostic operation.');
                         }
+                        if (call.startsWith('terminal.live.'))
+                            return this.liveTerminal(live).call(call, params);
                         if (call.startsWith('terminal.agents.'))
                             return this.agentsCall(live, call, params);
                         if (call.startsWith('terminal.subagents.'))
@@ -1387,7 +1419,7 @@ export class Terminals {
                         if (call.startsWith('terminal.trajectory.'))
                             return this.trajectoryCall(live, call, params);
                         if (call === 'terminal.todo')
-                            return latestTerminalTodo(this.options.env.root, live.input.sessionId, live.controller.nativeSessionId);
+                            return latestTerminalTodo(this.options.env.root, live.input.sessionId, this.nativeOf(live));
                         if (call === 'terminal.permissions.get') {
                             const policy = this.options.approvals.read();
                             return { full: this.options.approvals.isAuto('pi'), globalTools: policy.globalTools.pi ?? [] };
@@ -1412,7 +1444,7 @@ export class Terminals {
                         if (call.startsWith('terminal.remoteControl.'))
                             return this.remoteCall(live, call, params);
                         if (call !== 'terminal.resources')
-                            return live.controller.control(call, params);
+                            return this.controlFor(live)(call, params);
                         const current = await this.options.plugins?.loading({ cwd: input.cwd, agentDir: configDir(accounts.dir, preparedAccount), install: false, caller: { projectId: input.projectId ?? null } }) ?? null;
                         const currentVariant = variant ? materialise(root, { dir: variant.dir, scope: variant.scope }, { trust: this.options.trust ?? null }) : null;
                         if (resourceIdentity(current) !== resourceIdentity(loading) || (variant && (currentVariant?.fingerprint !== variant.fingerprint || JSON.stringify(currentVariant.extensionPaths) !== JSON.stringify(variant.extensionPaths)))) {
@@ -1473,6 +1505,19 @@ export class Terminals {
                 await accounts.terminalEnd(account).catch(() => undefined);
             if (acquiredWorktreeId)
                 await this.options.worktrees?.release(acquiredWorktreeId, sessionId).catch(() => undefined);
+            // A reattach that failed leaves the reply running without a window, as before.
+            if (carried) {
+                if (this.clients.get(sessionId) === carried.client)
+                    this.clients.delete(sessionId);
+                const stop = carried.client.onSettled(() => {
+                    if (this.detachedClients.get(sessionId)?.client !== carried.client)
+                        return;
+                    this.detachedClients.delete(sessionId);
+                    stop();
+                    void carried.client.dispose().catch(() => undefined);
+                });
+                this.detachedClients.set(sessionId, { client: carried.client, info: carried.info, stop });
+            }
             throw error;
         }
     }
@@ -1546,10 +1591,13 @@ export class Terminals {
         return {
             sessionId,
             title: () => basename(live.input.cwd) || this.options.env.productName,
-            send: (text) => this.send({ sessionId, text }),
-            control: (call, params) => live.controller.control(call, params),
+            send: (text) => {
+                const client = this.clients.get(sessionId);
+                return client ? client.send(text).then((result) => ({ runId: 'runId' in result ? result.runId : client.lastRun ?? '' })) : this.send({ sessionId, text });
+            },
+            control: (call, params) => this.controlFor(live)(call, params),
             history: () => {
-                const native = live.controller.nativeSessionId;
+                const native = this.nativeOf(live);
                 if (!native)
                     return [];
                 const runs = listRuns(root, { sessionId })
@@ -1592,10 +1640,116 @@ export class Terminals {
         throw new HarnessError('unknown_method', `Unknown terminal control ${call}.`);
     }
     /** The terminal process ended (or never started): its turn, tokens, and written credentials go with it. */
+    /**
+     * The native conversation a terminal's runs carry. A client terminal's runs are harness runs, which
+     * record Pi's session id; an in-process terminal's record its history file (ADR-0083).
+     */
+    nativeOf(live) {
+        const client = this.clients.get(live.input.sessionId);
+        return client ? client.nativeSessionId : live.controller.nativeSessionId;
+    }
+    /** The history file a relaunch of this terminal resumes. */
+    historyFileOf(live) {
+        const client = this.clients.get(live.input.sessionId);
+        return client ? client.sessionFile : live.controller.nativeSessionId;
+    }
+    /**
+     * Where a terminal's decision and stop calls go: its controller, or, once the frontend is a client
+     * of the harness, the live session's run (ADR-0083).
+     */
+    controlFor(live) {
+        return (call, params) => {
+            const client = this.clients.get(live.input.sessionId);
+            const routed = client ? LIVE_DECISION_CALLS[call] : undefined;
+            return routed ? client.call(routed, params) : live.controller.control(call, params);
+        };
+    }
+    /** The client half of a terminal whose frontend runs no Pi of its own (ADR-0083). */
+    liveTerminal(live) {
+        const existing = this.clients.get(live.input.sessionId);
+        if (existing)
+            return existing;
+        const sessions = this.options.sessionService;
+        if (!sessions)
+            throw invalid('This host does not run terminal turns in the harness.');
+        const { input } = live;
+        const client = new LiveTerminal({
+            sessionId: input.sessionId,
+            root: this.options.env.root,
+            accountId: live.account.id,
+            cwd: input.cwd,
+            sessionDir: this.historyDir(input),
+            caller: live.caller,
+            // The version this terminal was prepared on stays pinned; a switch restarts the frontend (ADR-0065).
+            variant: live.variant ? { dir: live.variant.dir, scope: live.variant.scope ?? undefined } : null,
+            launch: { ...input.launch, standard: input.launch?.standard === null ? null : input.launch?.standard ?? { cwd: input.cwd } },
+            connections: input.connections !== false,
+            readOnly: !!input.readOnly,
+            ...(input.subagents === null ? { subagents: null } : {}),
+            allowTool: (target) => { this.options.approvals.allowTool('pi', target); },
+            tools: async () => [...(input.launch?.tools ?? []), ...await this.worldToolNames(input, live.account)],
+            commands: async () => {
+                // The trusted extensions a turn would load, loaded only to read what they register.
+                const pi = await loadPi();
+                const account = this.options.accounts.context(live.account);
+                const plugins = this.options.plugins;
+                const loader = await loadResources(pi, {
+                    cwd: input.cwd, account, system: '', inline: [], variantExtensions: live.variant?.extensionPaths ?? [],
+                    resources: { ids: [], skillPaths: [], promptPaths: [] },
+                    ...(plugins ? { plugins: { loading: () => plugins.loading({ cwd: input.cwd, agentDir: account.configDir, install: false, caller: { projectId: input.projectId ?? null } }), loaded: () => undefined } } : {})
+                }, () => undefined);
+                // A plugin that cannot load stops the window, as it stops an in-process terminal's start.
+                const { errors } = loader.getExtensions();
+                if (errors.length)
+                    throw new Error(errors.map((error) => `${error.path}: ${error.error}`).join('\n'));
+                return registeredCommands(loader.getExtensions().extensions);
+            }
+        }, sessions, this.options.runs);
+        this.clients.set(input.sessionId, client);
+        return client;
+    }
+    /**
+     * The terminal's window closed. A client terminal whose reply is still running keeps it running in
+     * the harness, without the window, until it settles; `prepare({ attach: true })` reconnects to it.
+     * Anything else ends now, as `dispose` does.
+     */
+    async detach(sessionId) {
+        const live = this.sessions.get(sessionId);
+        const client = this.clients.get(sessionId);
+        const activeRunId = client?.activeRun ?? null;
+        if (!live || !client || !activeRunId) {
+            await this.dispose(sessionId);
+            return { detached: false, activeRunId: null };
+        }
+        // The window's binding goes; the client and its live session stay.
+        this.clients.delete(sessionId);
+        await this.dispose(sessionId);
+        const info = {
+            sessionId, cwd: live.input.cwd, sessionFolder: live.input.sessionFolder, accountId: live.account.id,
+            activeRunId, sessionFile: client.sessionFile, detachedAt: new Date().toISOString()
+        };
+        const stop = client.onSettled(() => {
+            const entry = this.detachedClients.get(sessionId);
+            if (entry?.client !== client)
+                return;
+            this.detachedClients.delete(sessionId);
+            entry.stop();
+            void client.dispose().catch(() => undefined);
+        });
+        this.detachedClients.set(sessionId, { client, info, stop });
+        return { detached: true, activeRunId };
+    }
+    /** Client terminals whose reply is running without a window. */
+    detached() {
+        return [...this.detachedClients.values()].map(({ client, info }) => ({ ...info, activeRunId: client.activeRun, sessionFile: client.sessionFile }));
+    }
     async dispose(sessionId) {
         const live = this.sessions.get(sessionId);
         if (!live)
             return;
+        const client = this.clients.get(sessionId);
+        this.clients.delete(sessionId);
+        await client?.dispose().catch(() => undefined);
         for (const [id, owner] of this.diagnosticOwners)
             if (owner === sessionId) {
                 this.options.doctor?.cancel(id);
@@ -1619,6 +1773,9 @@ export class Terminals {
         await this.options.accounts.terminalEnd(live.account).catch((error) => log('terminal credentials', error instanceof Error ? error.message : String(error)));
     }
     async close() {
+        const detached = [...this.detachedClients.values()];
+        this.detachedClients.clear();
+        await Promise.allSettled(detached.map(({ client, stop }) => { stop(); return client.dispose(); }));
         await Promise.allSettled([...this.sessions.keys()].map((sessionId) => this.dispose(sessionId)));
         await this.socket.close();
     }

package/dist/sdk/terminal/tui/commands.d.ts

@@ -67,3 +67,5 @@ export declare function createTerminalCommands(host: TerminalCommandHost): {
     skills: () => SkillEntry[];
     legacyAliases: () => string[];
 };
+/** The history file a `/session` argument names: a path, or the session id in a file's header. */
+export declare function sessionFileFor(argument: string, cwd: string, sessionDirectory: string): string;

package/dist/sdk/terminal/tui/commands.js

@@ -1,4 +1,5 @@
-import { isAbsolute, relative, resolve } from 'node:path';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
 import { SessionManager } from '@earendil-works/pi-coding-agent';
 import { CORE_COMMANDS, coreCommand } from "../../commands/registry.js";
 import { commandRoutes, promptCommandAvailable } from "../../commands/routes.js";
@@ -264,7 +265,8 @@ export function createTerminalCommands(host) {
                             break;
                         path = selected;
                     }
-                    const target = resolve(host.cwd(), path);
+                    // A conversation by its file, or by the session id its runs record (ADR-0083).
+                    const target = sessionFileFor(path, host.cwd(), host.sessionDirectory());
                     const within = relative(host.sessionDirectory(), target);
                     if (within === '..' || within.startsWith('../') || within.startsWith('..\\') || isAbsolute(within)) {
                         throw new Error('Resume sessions from this account history folder.');
@@ -472,3 +474,23 @@ export function createTerminalCommands(host) {
     }
     return { execute, completions, skills, legacyAliases };
 }
+/** The history file a `/session` argument names: a path, or the session id in a file's header. */
+export function sessionFileFor(argument, cwd, sessionDirectory) {
+    const named = resolve(cwd, argument);
+    if (existsSync(named) || /[\\/]|\.jsonl$/u.test(argument))
+        return named;
+    try {
+        for (const name of readdirSync(sessionDirectory)) {
+            if (!name.endsWith('.jsonl'))
+                continue;
+            const file = join(sessionDirectory, name);
+            const header = JSON.parse(readFileSync(file, 'utf8').split('\n', 1)[0]);
+            if (header.type === 'session' && header.id === argument)
+                return file;
+        }
+    }
+    catch {
+        // An unreadable folder or header names nothing.
+    }
+    return named;
+}

package/dist/sdk/terminal/tui/harnessRuntime.d.ts

@@ -0,0 +1,8 @@
+import { type TerminalRuntime, type TerminalRuntimeHost } from "./runtime.js";
+/**
+ * The terminal's runtime (ADR-0083): this client of the harness by default; `inprocess` runs the
+ * previous in-process Pi runtime, which keeps plugins' own terminal components.
+ */
+export declare const HARNESS_RUNTIME_ENV = "XINGULAR_TERMINAL_RUNTIME";
+export declare const harnessRuntimeSelected: (env?: NodeJS.ProcessEnv) => boolean;
+export declare function createHarnessTerminalRuntime(args: string[], host: TerminalRuntimeHost): Promise<TerminalRuntime>;