@xingular/harness 2.0.0 → 2.0.1-unstable

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

@@ -0,0 +1,312 @@
+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";
+import type { Bus } from "../core/bus.js";
+import type { HarnessEnv } from "../core/env.js";
+import type { ConnectedApps } from "../mcp/service.js";
+import type { CallerContext } from "../core/caller.js";
+import { type VariantChoice } from "../variant/materialise.js";
+import type { VariantTrust } from "../variant/trust.js";
+import type { AttachParams, PluginScope } from "../plugins/api.js";
+import type { Proposal } from "../plugins/proposals.js";
+import type { Plugins } from "../plugins/plugins.js";
+import type { Plugin } from "../plugins/types.js";
+import type { Hub } from "../hub/hub.js";
+import { type Launch } from "../prompt/compile.js";
+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";
+import type { Usage } from "../usage/service.js";
+import type { UsageLimits } from "../usage/limits/service.js";
+import { type RemoteControlOptions } from "../remote/service.js";
+import type { Refinements } from "../refine/service.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 `xagent` command (`dist/cli.js`). */
+    cli: string;
+    /** The built Pi extension (`dist/terminal-pi.js`). */
+    piExtension: string;
+    /** The built OpenTUI frontend (`dist/terminal-opentui.js`). */
+    openTui: string;
+}
+/** Where the package's own build puts them. An application that bundles the harness passes its own. */
+export declare function defaultAssets(): TerminalAssets;
+export interface TerminalPrepareInput {
+    subagents?: SubagentOptions | null;
+    sessionId: string;
+    /** The account the session is pinned to. Omitted only for a session that has none yet; it then takes the default and keeps it. */
+    accountId?: string | null;
+    projectId?: string | null;
+    cwd: string;
+    /** The session's own folder. Its compiled instructions and native history are kept under it. */
+    sessionFolder: string;
+    nativeSessionId?: string | null;
+    model?: string | null;
+    readOnly?: boolean;
+    /** What the application adds to the instructions, and which of its tools it describes. */
+    launch?: Launch;
+    /** The variant the session runs; its version is pinned for the session. */
+    variant?: VariantChoice | null;
+    /** Give the session the connected-apps broker. Defaults to yes. */
+    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 {
+    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;
+    /** Resume the conversation on this version of the session's variant scope (PROP-0052). */
+    variantVersion?: string;
+}
+export interface TerminalLaunch {
+    program: string;
+    args: string[];
+    /** Variables to set; `null` removes an inherited one. */
+    env: Record<string, string | null>;
+    accountId: string;
+    nativeSessionId: string | null;
+}
+export interface TerminalsOptions {
+    doctor?: import("../doctor/service.js").Doctor;
+    /** 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;
+    accounts: Accounts;
+    runs: RunRegistry;
+    approvals: Approvals;
+    apps: ConnectedApps;
+    policy: ToolPolicy;
+    bus: Bus;
+    /** Chooses what a terminal loads. Without it Pi discovers extensions and skills on its own. */
+    plugins?: Plugins;
+    /** Lists plugins and applies a person's choices, for the session's `/plugins` command. */
+    pluginControl?: PluginControl;
+    hub?: Hub;
+    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;
+    /** Usage analytics over the derived ledger (`/usage:analysis`). */
+    usage?: Usage;
+    /** Provider plan windows, balances and rate limits (`/usage:limit`). */
+    usageLimits?: UsageLimits;
+    /** Where `/remote-control` listens; tests bind loopback here. */
+    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 {
+    list(scope: PluginScope): Promise<Plugin[]>;
+    attach(params: AttachParams, on: boolean): Promise<Plugin[]>;
+    trust(scope: PluginScope & {
+        hash: string;
+    }): Promise<Plugin[]>;
+    untrust(scope: PluginScope & {
+        hash: string;
+    }): Promise<Plugin[]>;
+    /** Saves numbers a person set on a plugin; each is checked against the plugin's settings. */
+    configure(params: PluginScope & {
+        pluginId: string;
+        settings: Record<string, unknown>;
+    }): Promise<Plugin[]>;
+    install?(params: PluginScope & {
+        source: string;
+    }): Promise<Plugin[]>;
+    remove?(params: PluginScope & {
+        pluginId: string;
+    }): Promise<Plugin[]>;
+    proposals?: {
+        list(): Proposal[] | Promise<Proposal[]>;
+        preview(id: string): Proposal | Promise<Proposal>;
+        accept(id: string, hash: string): Proposal | Promise<Proposal>;
+        reject(id: string, hash: string): Proposal | Promise<Proposal>;
+    };
+}
+export declare class Terminals {
+    private readonly options;
+    private readonly sessions;
+    private readonly diagnosticOwners;
+    /** The variant each live session runs, for loading its skills. */
+    private readonly variantDirs;
+    /** The subagent profile files each live session's packages bring, chosen when it started. */
+    private readonly packageProfiles;
+    /** The world tools each session was given, so a call can only reach one of them. */
+    private readonly worldNames;
+    private readonly worldReadOnly;
+    private readonly socket;
+    private readonly assets;
+    /** A session's `/accounts` or `/worktree` switch, taken once its Pi process has ended. */
+    private readonly relaunches;
+    /** Refinements each session started with `/refine`. */
+    private readonly refinements;
+    /** The managed worktree each live session holds. */
+    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;
+    /** Account, model and effort for a monitor row, from the run record. */
+    private monitorRuntime;
+    /**
+     * Shows the reopened conversation's latest parent run again: the last owner on its native branch
+     * that ran in this folder, with every descendant flat, as each ended.
+     */
+    private hydrateMonitor;
+    constructor(options: TerminalsOptions);
+    /** The commands a terminal session finds on PATH. Rewritten only when they change. */
+    private ensureCommands;
+    /**
+     * The harness's own History, Wiki and skill tools, then the broker's, then the world tools whose
+     * plugins are on for this session: the same tools a structured session has (INV-PAR-1).
+     */
+    private tools;
+    private readonly ownNames;
+    private ownTools;
+    /** The world tools a new session will have, named in its instructions. */
+    private worldToolNames;
+    /** The harness's own History, Wiki and skill tools a new session will have. */
+    private ownToolNames;
+    /** Whether a world tool's plugin is switched on for a session's folder, account and project. */
+    private worldOn;
+    private appsCall;
+    /**
+     * `/plugins` in a terminal. Listing is open to the session. A change is taken only from the
+     * session's own extension, which asks the person in the terminal first: the model can reach
+     * this socket from a shell command, and must not be able to trust code or switch it on.
+     */
+    private pluginsCall;
+    /**
+     * `/accounts` in a terminal. Every call needs the session's control key: adding, signing in,
+     * 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;
+    /** `/context`: the selected run's request, and one row's text on request. */
+    private contextCall;
+    /** `/usage:analysis` and `/usage:limit`: usage for this session's own account, project or session. */
+    private usageCall;
+    /** `/annotate:notes` and `/annotate:`: Web annotations and their visible capture browser. */
+    private annotationsCall;
+    /** The account a session asked to switch to. Taken once, after its Pi process has ended and before `dispose`. */
+    takeRelaunch(sessionId: string): TerminalRelaunch | null;
+    private live;
+    private historyDir;
+    private runRecord;
+    /** The run a native turn reports into: the one reserved by `send`, or a new one for what the person typed. */
+    private begin;
+    /** Records the working tree as a typed turn found it, before the agent acts (refinement replays from it). */
+    private snapshotTurn;
+    private decide;
+    private workspaceEscape;
+    private workspaceBoundaryBypass;
+    private subagentsCall;
+    private componentsCall;
+    private variantContext;
+    private trajectoryCall;
+    private sideQuestionCall;
+    /** The only terminal frontend: the Bun-run OpenTUI application. */
+    private frontendCommand;
+    /**
+     * Prepares an OpenTUI terminal session and returns what to spawn. The caller must report the
+     * process's end with `dispose`, also when it never starts.
+     */
+    prepare(input: TerminalPrepareInput): Promise<TerminalLaunch>;
+    /** Hands the terminal an instruction as a new run. Resolves once the native session has taken it. */
+    send(input: {
+        sessionId: string;
+        runId?: string | null;
+        text: string;
+    }): Promise<{
+        runId: string;
+    }>;
+    /** What the person typed into the terminal. */
+    input(sessionId: string, data: string): void;
+    state(sessionId: string): {
+        ready: boolean;
+        dirty: boolean;
+        active: boolean;
+    };
+    has(sessionId: string): boolean;
+    private remote;
+    /**
+     * What a paired phone reaches: this session's own runs and the same send, interrupt and
+     * decision calls the terminal makes (INV-RC-3).
+     */
+    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>;
+}