@jitsusama/agentic-harness.core 0.1.0

package/dist/tdd/machine.js

@@ -0,0 +1,139 @@
+/**
+ * The TDD loop domain model and its pure reducer: a single,
+ * discrete red-green-refactor loop.
+ *
+ * The agent drives the loop by attesting each transition. A
+ * transition is allowed only when the attestation supplies the
+ * justification the gate requires; otherwise the reducer refuses
+ * and hands back guidance. The reducer never inspects code, test
+ * output or file paths. It tracks the agent's own attestation,
+ * which is the one contract that stays robust across every
+ * language and every host this loop ever runs under.
+ */
+/** The resting state: no loop in play. */
+export function idleLoop() {
+    return {
+        phase: "idle",
+        assertionFailure: false,
+        behaviour: null,
+        iteration: 0,
+    };
+}
+/** Close the active loop back to idle, keeping the iteration count. */
+function rest(loop) {
+    return {
+        phase: "idle",
+        assertionFailure: false,
+        behaviour: null,
+        iteration: loop.iteration,
+    };
+}
+/** Refuse a transition, handing the agent guidance on what's missing. */
+function refuse(guidance) {
+    return { ok: false, guidance };
+}
+/** Accept a transition into a new loop state. */
+function advance(loop) {
+    return { ok: true, loop };
+}
+/** Attempt a transition, enforcing the justification each gate requires. */
+export function transition(loop, attestation) {
+    switch (attestation.action) {
+        case "plan":
+            return plan(loop, attestation);
+        case "write":
+            return write(loop, attestation);
+        case "red":
+            return red(loop, attestation);
+        case "green":
+            return green(loop, attestation);
+        case "refactor":
+            return refactor(loop);
+        case "done":
+            return done(loop, attestation);
+        case "abandon":
+            return abandon(loop, attestation);
+        default:
+            return refuse(`Unknown transition. Drive the loop with plan, write, red, ` +
+                `green, refactor, done or abandon.`);
+    }
+}
+function plan(loop, attestation) {
+    if (loop.phase !== "idle") {
+        return refuse(`Finish or abandon the current loop before planning another. You're in ${loop.phase}.`);
+    }
+    if (!attestation.behaviour) {
+        return refuse("Name the single behaviour under test: the exported thing you " +
+            "want to exist. One increment per loop.");
+    }
+    return advance({
+        phase: "plan",
+        assertionFailure: false,
+        behaviour: attestation.behaviour,
+        iteration: loop.iteration + 1,
+    });
+}
+function write(loop, attestation) {
+    if (loop.phase !== "plan") {
+        return refuse(`Writing the test follows plan. You're in ${loop.phase}, not plan. ` +
+            `Go forward, or abandon to redo.`);
+    }
+    if (!attestation.interface) {
+        return refuse("State the exported surface this test binds to before writing it. " +
+            "Tests document the interface, never the internals.");
+    }
+    return advance({ ...loop, phase: "write" });
+}
+function red(loop, attestation) {
+    if (loop.phase !== "write" && loop.phase !== "red") {
+        return refuse(`A failing test comes out of the write phase. You're in ${loop.phase}.`);
+    }
+    if (!attestation.failure) {
+        return refuse("Run the test and report the failure before moving to red.");
+    }
+    if (!attestation.failureKind) {
+        return refuse("Say whether the failure was an assertion or other (a compile or " +
+            "missing-symbol error). Only a real assertion clears the way to green.");
+    }
+    return advance({
+        ...loop,
+        phase: "red",
+        assertionFailure: attestation.failureKind === "assertion",
+    });
+}
+function green(loop, attestation) {
+    if (loop.phase !== "red" || !loop.assertionFailure) {
+        return refuse("You haven't seen a real red yet. Stub a minimal skeleton, re-run, " +
+            "and call red again with failureKind 'assertion' before green.");
+    }
+    if (!attestation.pass) {
+        return refuse("Report the passing result before moving to green.");
+    }
+    return advance({ ...loop, phase: "green", assertionFailure: false });
+}
+function refactor(loop) {
+    if (loop.phase !== "green") {
+        return refuse(`Refactoring follows a green test. You're in ${loop.phase}.`);
+    }
+    return advance({ ...loop, phase: "refactor" });
+}
+function done(loop, attestation) {
+    if (loop.phase !== "refactor") {
+        return refuse(`Close the loop from the refactor phase, not ${loop.phase}. ` +
+            `Pass through refactor first, even as a no-op.`);
+    }
+    if (!attestation.reflection) {
+        return refuse("Before you close, say what you reconsidered about the internal and " +
+            "external design now that a real consumer exists.");
+    }
+    return advance(rest(loop));
+}
+function abandon(loop, attestation) {
+    if (loop.phase === "idle") {
+        return refuse("There's no loop to abandon. Plan one when you're ready.");
+    }
+    if (!attestation.reason) {
+        return refuse("Give a reason for leaving the loop before you abandon it.");
+    }
+    return advance(rest(loop));
+}

package/dist/tdd/presentation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The visual vocabulary of a TDD scoreboard: one glyph per state
+ * of the loop. The circle fills monotonically across the five
+ * build-up states (empty, quarter, half, three-quarter, full), so
+ * every state is a distinct shape and the progression reads
+ * without colour. Green is the full circle: the test is complete.
+ * Refactor leaves the circle family for a diamond because it is a
+ * different kind of activity, not another notch of the same
+ * build-up. Fill encodes progress, colour reinforces meaning, and
+ * shape alone keeps the states apart.
+ *
+ * This is presentation, not domain: a host with no scoreboard
+ * (a Claude Code skill, a bare CLI) never needs to import it. It
+ * is a separate export specifically so it stays optional.
+ */
+import type { Loop } from "./machine.js";
+/** The seven distinct states the scoreboard can show. */
+export type VisualState = "idle" | "plan" | "write" | "red-unverified" | "red-verified" | "green" | "refactor";
+/** Collapse a loop's phase and assertion verification into one visual state. */
+export declare function visualState(loop: Loop): VisualState;
+/**
+ * The theme tokens a scoreboard paints with. A narrow, host-agnostic
+ * vocabulary an adapter maps onto its own palette: yellow for
+ * authoring, red for failing, green for passing, blue for
+ * refactoring and dim for idle.
+ */
+export type GlyphToken = "dim" | "warning" | "error" | "success" | "accent";
+/** A glyph and the colour it should be painted in. */
+export interface Glyph {
+    char: string;
+    token: GlyphToken;
+}
+/** The glyph and colour for a visual state. */
+export declare function glyph(state: VisualState): Glyph;

package/dist/tdd/presentation.js

@@ -0,0 +1,38 @@
+/**
+ * The visual vocabulary of a TDD scoreboard: one glyph per state
+ * of the loop. The circle fills monotonically across the five
+ * build-up states (empty, quarter, half, three-quarter, full), so
+ * every state is a distinct shape and the progression reads
+ * without colour. Green is the full circle: the test is complete.
+ * Refactor leaves the circle family for a diamond because it is a
+ * different kind of activity, not another notch of the same
+ * build-up. Fill encodes progress, colour reinforces meaning, and
+ * shape alone keeps the states apart.
+ *
+ * This is presentation, not domain: a host with no scoreboard
+ * (a Claude Code skill, a bare CLI) never needs to import it. It
+ * is a separate export specifically so it stays optional.
+ */
+/** Collapse a loop's phase and assertion verification into one visual state. */
+export function visualState(loop) {
+    if (loop.phase === "red") {
+        return loop.assertionFailure ? "red-verified" : "red-unverified";
+    }
+    return loop.phase;
+}
+const GLYPHS = {
+    idle: { char: "◌", token: "dim" },
+    plan: { char: "○", token: "warning" },
+    write: { char: "◔", token: "warning" },
+    "red-unverified": { char: "◑", token: "error" },
+    "red-verified": { char: "◕", token: "error" },
+    green: { char: "●", token: "success" },
+    // A circle with a centre: the same family as the phases before it,
+    // since refactoring is the last of them and not a different kind of
+    // thing.
+    refactor: { char: "◉", token: "accent" },
+};
+/** The glyph and colour for a visual state. */
+export function glyph(state) {
+    return GLYPHS[state];
+}

package/dist/tdd/queries.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Read-only queries over a loop, for an adapter to surface
+ * however its own host wants: pi via a context/message event,
+ * a CLI via a status subcommand, a Claude Code hook via whatever
+ * text it prepends. The information is host-agnostic; only the
+ * delivery mechanism differs.
+ */
+import type { Loop } from "./machine.js";
+/** The standing reminder of where the loop is, or nothing at idle. */
+export declare function standingReminder(loop: Loop): string | undefined;

package/dist/tdd/queries.js

@@ -0,0 +1,22 @@
+/**
+ * Read-only queries over a loop, for an adapter to surface
+ * however its own host wants: pi via a context/message event,
+ * a CLI via a status subcommand, a Claude Code hook via whatever
+ * text it prepends. The information is host-agnostic; only the
+ * delivery mechanism differs.
+ */
+/** Whether a loop is live: past idle, with a transition in play. */
+function isActiveLoop(loop) {
+    return loop.phase !== "idle";
+}
+/** The standing reminder of where the loop is, or nothing at idle. */
+export function standingReminder(loop) {
+    if (!isActiveLoop(loop)) {
+        return undefined;
+    }
+    const lines = [`TDD loop ${loop.iteration}, ${loop.phase} phase.`];
+    if (loop.behaviour) {
+        lines.push(`Increment under test: ${loop.behaviour}.`);
+    }
+    return lines.join("\n");
+}

package/dist/terminal/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Public surface of the terminal library.
+ *
+ * Pluggable launchers for new tabs, panes and windows. The
+ * quest extension uses it for `spawn-tab`/`spawn-pane`/
+ * `spawn-window`; other extensions can pick the same
+ * driver or register their own.
+ */
+export { clearTerminalDrivers, registerBuiltinTerminalDrivers, registerTerminalDriver, unregisterTerminalDriver, } from "./register.js";
+export { getLivenessProvider, getTerminalDriver, getTypeProvider, identifyCurrentTerminal, listTerminalDrivers, resolveDriver, spawnTerminal, spawnTerminalSurface, } from "./resolve.js";
+export type { TerminalDriver, TerminalLayout, TerminalLivenessCapability, TerminalProbe, TerminalRequest, TerminalSessionHandle, TerminalTypeCapability, } from "./types.js";
+export { terminalHandleKey } from "./types.js";

package/dist/terminal/index.js

@@ -0,0 +1,11 @@
+/**
+ * Public surface of the terminal library.
+ *
+ * Pluggable launchers for new tabs, panes and windows. The
+ * quest extension uses it for `spawn-tab`/`spawn-pane`/
+ * `spawn-window`; other extensions can pick the same
+ * driver or register their own.
+ */
+export { clearTerminalDrivers, registerBuiltinTerminalDrivers, registerTerminalDriver, unregisterTerminalDriver, } from "./register.js";
+export { getLivenessProvider, getTerminalDriver, getTypeProvider, identifyCurrentTerminal, listTerminalDrivers, resolveDriver, spawnTerminal, spawnTerminalSurface, } from "./resolve.js";
+export { terminalHandleKey } from "./types.js";

package/dist/terminal/register.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Terminal driver registration. Mirrors the refs and people
+ * libraries: explicit registration for built-ins, free
+ * functions for ad-hoc driver registration, an opt-out
+ * clear for tests.
+ */
+import type { TerminalDriver } from "./types.js";
+/**
+ * Register a terminal driver. Overwrites any previously
+ * registered driver with the same id.
+ */
+export declare function registerTerminalDriver(driver: TerminalDriver): void;
+/** Remove a driver from the registry. Idempotent. */
+export declare function unregisterTerminalDriver(id: string): void;
+/**
+ * Seed the registry with the built-in drivers: `wezterm`,
+ * `tmux` and `fallback`. Idempotent.
+ */
+export declare function registerBuiltinTerminalDrivers(): void;
+/** Empty the registry. Intended for tests. */
+export declare function clearTerminalDrivers(): void;

package/dist/terminal/register.js

@@ -0,0 +1,31 @@
+/**
+ * Terminal driver registration. Mirrors the refs and people
+ * libraries: explicit registration for built-ins, free
+ * functions for ad-hoc driver registration, an opt-out
+ * clear for tests.
+ */
+import { BUILTIN_TERMINAL_DRIVERS } from "../internal/terminal/builtins.js";
+import { clear, register, unregister } from "../internal/terminal/registry.js";
+/**
+ * Register a terminal driver. Overwrites any previously
+ * registered driver with the same id.
+ */
+export function registerTerminalDriver(driver) {
+    register(driver);
+}
+/** Remove a driver from the registry. Idempotent. */
+export function unregisterTerminalDriver(id) {
+    unregister(id);
+}
+/**
+ * Seed the registry with the built-in drivers: `wezterm`,
+ * `tmux` and `fallback`. Idempotent.
+ */
+export function registerBuiltinTerminalDrivers() {
+    for (const driver of BUILTIN_TERMINAL_DRIVERS)
+        register(driver);
+}
+/** Empty the registry. Intended for tests. */
+export function clearTerminalDrivers() {
+    clear();
+}

package/dist/terminal/resolve.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Driver resolution: pick a usable terminal driver for the
+ * current environment.
+ *
+ * Resolution order:
+ *
+ * 1. The driver named in the `preferred` argument, when its
+ *    `available()` returns true.
+ * 2. Each registered driver in registration order, the
+ *    first whose `available()` returns true wins.
+ * 3. `undefined` when no driver is available (callers fall
+ *    back to printing instructions, or refuse).
+ */
+import type { TerminalDriver, TerminalLivenessCapability, TerminalRequest, TerminalSessionHandle, TerminalTypeCapability } from "./types.js";
+/** Look up a driver by id, or `undefined`. */
+export declare function getTerminalDriver(id: string): TerminalDriver | undefined;
+/** Snapshot of every registered driver. */
+export declare function listTerminalDrivers(): TerminalDriver[];
+/**
+ * Resolve the driver that can type into an existing surface, for a
+ * recorded driver id. Undefined when that driver cannot, which a
+ * caller must treat as a refusal rather than a reason to fall back:
+ * the fallback is running the command without a login shell, and that
+ * is the failure the capability exists to avoid.
+ */
+export declare function getTypeProvider(driverId: string): (TerminalDriver & TerminalTypeCapability) | undefined;
+/**
+ * Resolve the liveness provider for a recorded driver id. Returns the
+ * registered driver only when it implements the liveness capability;
+ * undefined for an unknown id or a spawn-only driver. Keyed strictly
+ * by id so a recorded handle is probed through its own driver, never
+ * whichever terminal the reader happens to be in.
+ */
+export declare function getLivenessProvider(driverId: string): (TerminalDriver & TerminalLivenessCapability) | undefined;
+/**
+ * The terminal surface the current pi process runs in, as a
+ * probeable handle, from the first registered liveness-capable
+ * driver that recognises the environment. Undefined when no driver
+ * claims the current terminal (for example a bare shell with no
+ * supported multiplexer).
+ */
+export declare function identifyCurrentTerminal(): TerminalSessionHandle | undefined;
+/**
+ * Resolve the driver to use for a spawn. Preferred wins
+ * when available; otherwise the first registered driver
+ * whose `available()` says yes.
+ */
+export declare function resolveDriver(preferred?: string): Promise<TerminalDriver | undefined>;
+/**
+ * Convenience: resolve a driver and dispatch a request in
+ * one call. Throws when no driver is available.
+ */
+export declare function spawnTerminal(request: TerminalRequest, preferred?: string): Promise<TerminalDriver>;
+/**
+ * Spawn a surface and return both the driver and the handle it
+ * named, for a caller that means to type into what it just made.
+ * The handle is undefined when the driver cannot say what it
+ * created.
+ */
+export declare function spawnTerminalSurface(request: TerminalRequest, preferred?: string): Promise<{
+    driver: TerminalDriver;
+    handle: TerminalSessionHandle | undefined;
+}>;

package/dist/terminal/resolve.js

@@ -0,0 +1,117 @@
+/**
+ * Driver resolution: pick a usable terminal driver for the
+ * current environment.
+ *
+ * Resolution order:
+ *
+ * 1. The driver named in the `preferred` argument, when its
+ *    `available()` returns true.
+ * 2. Each registered driver in registration order, the
+ *    first whose `available()` returns true wins.
+ * 3. `undefined` when no driver is available (callers fall
+ *    back to printing instructions, or refuse).
+ */
+import { get, list } from "../internal/terminal/registry.js";
+/** Look up a driver by id, or `undefined`. */
+export function getTerminalDriver(id) {
+    return get(id);
+}
+/** Snapshot of every registered driver. */
+export function listTerminalDrivers() {
+    return list();
+}
+/** Whether a driver implements the optional liveness capability. */
+function hasLivenessCapability(driver) {
+    return (typeof driver.probe ===
+        "function" &&
+        typeof driver.identifyCurrent ===
+            "function");
+}
+function hasTypeCapability(driver) {
+    return (typeof driver.typeInto === "function");
+}
+/**
+ * Resolve the driver that can type into an existing surface, for a
+ * recorded driver id. Undefined when that driver cannot, which a
+ * caller must treat as a refusal rather than a reason to fall back:
+ * the fallback is running the command without a login shell, and that
+ * is the failure the capability exists to avoid.
+ */
+export function getTypeProvider(driverId) {
+    const driver = get(driverId);
+    if (!driver || !hasTypeCapability(driver))
+        return undefined;
+    return driver;
+}
+/**
+ * Resolve the liveness provider for a recorded driver id. Returns the
+ * registered driver only when it implements the liveness capability;
+ * undefined for an unknown id or a spawn-only driver. Keyed strictly
+ * by id so a recorded handle is probed through its own driver, never
+ * whichever terminal the reader happens to be in.
+ */
+export function getLivenessProvider(driverId) {
+    const driver = get(driverId);
+    if (!driver || !hasLivenessCapability(driver))
+        return undefined;
+    return driver;
+}
+/**
+ * The terminal surface the current pi process runs in, as a
+ * probeable handle, from the first registered liveness-capable
+ * driver that recognises the environment. Undefined when no driver
+ * claims the current terminal (for example a bare shell with no
+ * supported multiplexer).
+ */
+export function identifyCurrentTerminal() {
+    for (const driver of list()) {
+        if (!hasLivenessCapability(driver))
+            continue;
+        const handle = driver.identifyCurrent();
+        if (handle)
+            return handle;
+    }
+    return undefined;
+}
+/**
+ * Resolve the driver to use for a spawn. Preferred wins
+ * when available; otherwise the first registered driver
+ * whose `available()` says yes.
+ */
+export async function resolveDriver(preferred) {
+    if (preferred) {
+        const driver = get(preferred);
+        if (driver && (await driver.available()))
+            return driver;
+    }
+    for (const driver of list()) {
+        if (await driver.available())
+            return driver;
+    }
+    return undefined;
+}
+/**
+ * Convenience: resolve a driver and dispatch a request in
+ * one call. Throws when no driver is available.
+ */
+export async function spawnTerminal(request, preferred) {
+    const driver = await resolveDriver(preferred);
+    if (!driver) {
+        throw new Error("No terminal driver available. Register one or seed the built-ins with `registerBuiltinTerminalDrivers`.");
+    }
+    await driver.spawn(request);
+    return driver;
+}
+/**
+ * Spawn a surface and return both the driver and the handle it
+ * named, for a caller that means to type into what it just made.
+ * The handle is undefined when the driver cannot say what it
+ * created.
+ */
+export async function spawnTerminalSurface(request, preferred) {
+    const driver = await resolveDriver(preferred);
+    if (!driver) {
+        throw new Error("No terminal driver available. Register one or seed the built-ins with `registerBuiltinTerminalDrivers`.");
+    }
+    return { driver, handle: await driver.spawn(request) };
+}

package/dist/terminal/types.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Public types for the terminal library.
+ *
+ * A `TerminalDriver` knows how to spawn a new shell in a
+ * tab, a pane or a window of the user's terminal emulator
+ * or multiplexer. The library is pluggable: built-ins
+ * (wezterm, tmux, fallback) live in `lib/internal/terminal/
+ * drivers/`; consumers register their own with the same
+ * shape.
+ */
+/** Where the new shell should appear. */
+export type TerminalLayout = "tab" | "pane" | "window";
+/** A spawn request the driver fulfills. */
+export interface TerminalRequest {
+    /** Whether to open in a tab, a pane or a new window. */
+    layout: TerminalLayout;
+    /**
+     * Shell command to run. Drivers pass this through to
+     * the underlying spawn primitive; quoting is the
+     * driver's responsibility.
+     *
+     * Optional, because a caller may want the surface itself
+     * rather than a command in it: spawning a plain login
+     * shell and then typing into it is the only way to reach
+     * a shell that has run the user's own startup files.
+     */
+    command?: string;
+    /** Working directory for the new shell. */
+    cwd?: string;
+    /** Tab or window title, when the driver supports it. */
+    title?: string;
+    /**
+     * Extra environment variables. Drivers add these on
+     * top of the parent shell's environment.
+     */
+    env?: Record<string, string>;
+}
+/**
+ * A stable, probeable reference to a terminal surface a pi session
+ * was observed in. Recorded on the session so a later reader can ask
+ * the same driver whether that surface still exists. `scope` is the
+ * mux socket and host fingerprint that makes `value` (a pane id)
+ * meaningful across terminal instances and hosts.
+ */
+export interface TerminalSessionHandle {
+    /** Id of the driver that issued the handle. */
+    driverId: string;
+    /** Driver-specific kind, e.g. "wezterm-pane". */
+    kind: string;
+    /** Host the surface lives on; a foreign host is unprobeable. */
+    hostId: string;
+    /** Mux socket / server fingerprint that scopes `value`. */
+    scope?: string;
+    /** The surface id itself, e.g. a wezterm pane id. */
+    value: string;
+}
+/**
+ * A terminal probe outcome. Present and absent are only meaningful
+ * when the probe could actually observe the surface; anything else
+ * (unreachable mux, timeout, foreign scope, unsupported driver) is
+ * unknown, never a false absent.
+ */
+export type TerminalProbe = "present" | "absent" | "unknown";
+/**
+ * Optional liveness capability a terminal driver may implement in
+ * addition to spawning. Resolved by the recorded driver id, never by
+ * the reader's current terminal, and probed in one batch per scope
+ * rather than once per handle.
+ */
+export interface TerminalLivenessCapability {
+    /**
+     * The handle for the surface the current pi process runs in, read
+     * from the environment, or undefined when this driver is not the
+     * active terminal.
+     */
+    identifyCurrent(): TerminalSessionHandle | undefined;
+    /**
+     * Probe a batch of handles, returning a map keyed by
+     * {@link terminalHandleKey}. One transport call per scope. The key
+     * is host, scope and value together, not the bare pane value, since
+     * a pane id is only unique within one terminal instance.
+     */
+    probe(handles: readonly TerminalSessionHandle[], signal?: AbortSignal): Promise<ReadonlyMap<string, TerminalProbe>>;
+}
+/**
+ * The stable key a probe result is keyed by. A pane value is only
+ * unique within one terminal instance, so two instances can both hold
+ * pane "0"; keying by host, scope and value keeps their probe results
+ * from colliding when a batch spans instances.
+ */
+export declare function terminalHandleKey(handle: TerminalSessionHandle): string;
+/**
+ * Optional capability for typing into a surface that already exists.
+ *
+ * Separate from spawning because it is the only way to reach a shell
+ * that has run the user's own startup files. Handing a command to the
+ * spawn primitive runs it under a non-interactive shell, which skips
+ * the hooks that set a project's environment up, so a command that
+ * works when typed fails when spawned. Recovering by hand after a
+ * crash meant spawning bare shells and typing the resume lines in,
+ * and a driver that can do that is a driver that can do the recovery
+ * itself.
+ */
+export interface TerminalTypeCapability {
+    /**
+     * Type text into an existing surface, as though the user had. A
+     * trailing newline submits it; without one the text is left on the
+     * command line for the user to read and press enter on.
+     */
+    typeInto(handle: TerminalSessionHandle, text: string): Promise<void>;
+}
+/** A pluggable terminal driver. */
+export interface TerminalDriver {
+    /** Identifier (e.g. "wezterm", "tmux"). */
+    id: string;
+    /**
+     * Quick probe: is this driver usable in the current
+     * environment? Implementations check for the binary on
+     * PATH and any required runtime context.
+     */
+    available(): Promise<boolean> | boolean;
+    /**
+     * Dispatch the spawn. Resolves when the spawn command
+     * has been sent; the actual lifetime of the spawned
+     * process is the driver's concern.
+     *
+     * Returns a handle to the new surface when the driver can name
+     * one, so a caller that spawned a bare shell can then type into
+     * it. A driver whose spawn primitive says nothing about what it
+     * created returns undefined, which is honest rather than a
+     * guess.
+     */
+    spawn(request: TerminalRequest): Promise<TerminalSessionHandle | undefined>;
+}

package/dist/terminal/types.js

@@ -0,0 +1,19 @@
+/**
+ * Public types for the terminal library.
+ *
+ * A `TerminalDriver` knows how to spawn a new shell in a
+ * tab, a pane or a window of the user's terminal emulator
+ * or multiplexer. The library is pluggable: built-ins
+ * (wezterm, tmux, fallback) live in `lib/internal/terminal/
+ * drivers/`; consumers register their own with the same
+ * shape.
+ */
+/**
+ * The stable key a probe result is keyed by. A pane value is only
+ * unique within one terminal instance, so two instances can both hold
+ * pane "0"; keying by host, scope and value keeps their probe results
+ * from colliding when a batch spans instances.
+ */
+export function terminalHandleKey(handle) {
+    return `${handle.driverId}\u0000${handle.hostId}\u0000${handle.scope ?? ""}\u0000${handle.value}`;
+}