@xingular/harness 0.1.7 → 1.1.1

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

@@ -0,0 +1,212 @@
+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 { 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";
+/** 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'>>;
+}
+/** 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[];
+    /** 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;
+}
+/** 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[]>;
+}
+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 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;
+    /** 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;
+    /** The broker's tools, then the world tools whose plugins are on for this session. */
+    private tools;
+    /** The world tools a new session will have, named in its instructions. */
+    private worldToolNames;
+    /** 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;
+    /** `/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): 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;
+    private decide;
+    private subagentsCall;
+    private componentsCall;
+    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;
+    /** The terminal process ended (or never started): its turn, tokens, and written credentials go with it. */
+    dispose(sessionId: string): Promise<void>;
+    close(): Promise<void>;
+}