@osdlc/agent-seat 0.0.0-stage → 0.7.1

package/dist/hosts/registry.js

@@ -0,0 +1,100 @@
+/**
+ * The shared reader for a host's registry: `<runtime>/hosts/<name>/*.json`,
+ * one file per running IDE or window, written by the extension or plugin that
+ * owns it. `<runtime>` is the caller's runtime directory (`runtimeDir`); the
+ * package picks none of its own, because the IDE companions must write to the
+ * same place.
+ */
+import { closeSync, fstatSync, openSync, readdirSync, readFileSync, statSync, } from 'node:fs';
+import { join } from 'node:path';
+import { isWithin, parseJsonOrNull, realResolve } from "../util.js";
+/** Where host `name` keeps its state under `runtimeDir`: `<runtimeDir>/hosts/<name>`. */
+export function hostRegistryDir(runtimeDir, name) {
+    return join(runtimeDir, 'hosts', name);
+}
+/** Host `name`'s state directory under `opts`. */
+export function registryDirOf(name, opts) {
+    return opts.registryDir ?? hostRegistryDir(opts.runtimeDir, name);
+}
+/** Why `stats` cannot be trusted under `uid`: owned by another user, or writable by group or others. */
+function untrusted(stats, uid) {
+    if (stats.uid !== uid)
+        return `is owned by uid ${stats.uid}, not ${uid}`;
+    if ((stats.mode & 0o022) !== 0)
+        return 'is writable by group or others';
+    return null;
+}
+/**
+ * Entries in `dir` that `parse` accepts and whose process is alive. A missing
+ * directory, an unreadable or malformed file, and a dead pid are all skipped.
+ *
+ * An entry carries an endpoint and a token, so a planted one would receive
+ * every session's argv and sent text. On POSIX the whole directory is skipped
+ * unless it belongs to the current user and is not group- or world-writable,
+ * and so is each file; `opts.onSkip` hears why. Windows has no uid to check.
+ */
+export function readHostRegistry(dir, parse, alive, opts = {}) {
+    const uid = opts.uid === undefined ? (process.getuid?.() ?? null) : opts.uid;
+    let names;
+    try {
+        if (uid !== null) {
+            const why = untrusted(statSync(dir), uid);
+            if (why !== null) {
+                opts.onSkip?.(`registry directory ${dir} ${why}`);
+                return [];
+            }
+        }
+        names = readdirSync(dir).filter((n) => n.endsWith('.json'));
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const name of names) {
+        const path = join(dir, name);
+        let text;
+        let fd = null;
+        try {
+            // Checked on the open descriptor, so the file cannot be swapped between check and read.
+            fd = openSync(path, 'r');
+            const why = uid === null ? null : untrusted(fstatSync(fd), uid);
+            if (why !== null) {
+                opts.onSkip?.(`registry file ${path} ${why}`);
+                continue;
+            }
+            text = readFileSync(fd, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        finally {
+            if (fd !== null)
+                closeSync(fd);
+        }
+        const entry = parse(parseJsonOrNull(text));
+        if (entry !== null && alive(entry.pid))
+            entries.push(entry);
+    }
+    return entries;
+}
+/**
+ * The candidate with the deepest folder containing `cwd` (depth = length of the
+ * real path), the newest `startedAt` winning a tie, then the earliest in list
+ * order. Null when no folder contains `cwd`. How both IDE hosts pick a window.
+ */
+export function deepestContaining(cwd, candidates, folders, startedAt) {
+    let best = null;
+    for (const c of candidates) {
+        for (const folder of folders(c)) {
+            if (!isWithin(cwd, folder))
+                continue;
+            const depth = realResolve(folder).length;
+            if (best === null ||
+                depth > best.depth ||
+                (depth === best.depth && startedAt(c) > startedAt(best.c))) {
+                best = { c, depth };
+            }
+        }
+    }
+    return best?.c ?? null;
+}

package/dist/hosts/session-panes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A host's memory of which pane belongs to which session:
+ * `<runtime>/hosts/<name>/sessions/<slug>.json` ({@link sessionIdSlug}), holding the session id,
+ * the host's own pane identifier (WezTerm's pane id, Orca's terminal handle, herdr's pane id)
+ * and the cwd it was opened in. The host writes it when it opens a pane for a session and resolves a
+ * later `send`/`find`/`focus`/`capture`/`close` for that session through it,
+ * so two sessions in one worktree reach two different panes.
+ *
+ * The identifier is only a hint: a host checks it against its own live
+ * listing before acting, because panes close and a restarted app reissues ids.
+ */
+/** What a host remembers about the pane it opened for a session. */
+export interface RememberedPane {
+    /** The host's own pane identifier. */
+    pane: string;
+    /** The working directory the pane was opened in, so a reissued id can be told from the original. */
+    cwd: string;
+}
+/** The pane remembered for `sessionId`, or null. A file that names another id is ignored. */
+export declare function recallSessionPane(dir: string, sessionId: string): RememberedPane | null;
+/** The pane remembered for the request's session id, or null when it carries none or none was remembered. */
+export declare function boundPane(dir: string, target: {
+    sessionId?: string | undefined;
+}): string | null;
+/**
+ * Remembers `paneId` (opened in `cwd`) for `sessionId`. A failure is reported on stderr and
+ * not thrown: the session still runs, and later requests for it resolve by `cwd`.
+ */
+export declare function rememberSessionPane(dir: string, sessionId: string, paneId: string, cwd: string): void;

package/dist/hosts/session-panes.js

@@ -0,0 +1,49 @@
+/**
+ * A host's memory of which pane belongs to which session:
+ * `<runtime>/hosts/<name>/sessions/<slug>.json` ({@link sessionIdSlug}), holding the session id,
+ * the host's own pane identifier (WezTerm's pane id, Orca's terminal handle, herdr's pane id)
+ * and the cwd it was opened in. The host writes it when it opens a pane for a session and resolves a
+ * later `send`/`find`/`focus`/`capture`/`close` for that session through it,
+ * so two sessions in one worktree reach two different panes.
+ *
+ * The identifier is only a hint: a host checks it against its own live
+ * listing before acting, because panes close and a restarted app reissues ids.
+ */
+import { join } from 'node:path';
+import { ensureDir, isRecord, readJsonOrNull, sessionIdSlug, writeJsonAtomic } from "../util.js";
+/**
+ * `<dir>/sessions/<slug>.json`: one file per session, so concurrent launches never overwrite each
+ * other. The name is a slug with a 128-bit hash, not the id itself, so it is unique on
+ * case-insensitive file systems and valid on Windows.
+ */
+function filePath(dir, sessionId) {
+    return join(dir, 'sessions', `${sessionIdSlug(sessionId, 32)}.json`);
+}
+/** The pane remembered for `sessionId`, or null. A file that names another id is ignored. */
+export function recallSessionPane(dir, sessionId) {
+    const data = readJsonOrNull(filePath(dir, sessionId));
+    if (!isRecord(data) || data['id'] !== sessionId)
+        return null;
+    const { pane, cwd } = data;
+    return typeof pane === 'string' && typeof cwd === 'string' ? { pane, cwd } : null;
+}
+/** The pane remembered for the request's session id, or null when it carries none or none was remembered. */
+export function boundPane(dir, target) {
+    return target.sessionId === undefined
+        ? null
+        : (recallSessionPane(dir, target.sessionId)?.pane ?? null);
+}
+/**
+ * Remembers `paneId` (opened in `cwd`) for `sessionId`. A failure is reported on stderr and
+ * not thrown: the session still runs, and later requests for it resolve by `cwd`.
+ */
+export function rememberSessionPane(dir, sessionId, paneId, cwd) {
+    try {
+        ensureDir(join(dir, 'sessions'));
+        writeJsonAtomic(filePath(dir, sessionId), { id: sessionId, pane: paneId, cwd });
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[host] could not remember the pane of session ${sessionId}: ${detail}\n`);
+    }
+}

package/dist/hosts/terminal.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The current terminal: run it right here and wait for it.
+ *
+ * An interactive process is the one thing that must NOT be captured — it
+ * owns the TTY until the person leaves it — so this runs through the command
+ * seam's STREAMING door (`streamRunner`; stdio fully
+ * inherited, resolves to `{exitCode}`) rather than a capture door. `req.argv`
+ * names a different binary on every call, so the injected dependency is a
+ * runner FACTORY — `(binary) => StreamRunner`, the same shape `streamRunner`
+ * itself has — not a runner bound to one binary the way `hosts/tmux.ts` and
+ * `hosts/cmux.ts` inject theirs (their binary, `tmux`/`cmux`, is fixed).
+ */
+import { type StreamRunner } from '@osdlc/command-seam';
+import type { Host } from '../contract.ts';
+/**
+ * The current-terminal host: runs the command right here with inherited stdio and waits for it.
+ * Needs no binary or app, runs on every platform, and is always available.
+ */
+export declare function makeTerminalHost(opts?: {
+    streamRunner?: ((binary: string) => StreamRunner) | undefined;
+}): Host;
+/** The production terminal host — `streamRunner` as its runner factory. */
+export declare const terminalHost: Host;

package/dist/hosts/terminal.js

@@ -0,0 +1,47 @@
+/**
+ * The current terminal: run it right here and wait for it.
+ *
+ * An interactive process is the one thing that must NOT be captured — it
+ * owns the TTY until the person leaves it — so this runs through the command
+ * seam's STREAMING door (`streamRunner`; stdio fully
+ * inherited, resolves to `{exitCode}`) rather than a capture door. `req.argv`
+ * names a different binary on every call, so the injected dependency is a
+ * runner FACTORY — `(binary) => StreamRunner`, the same shape `streamRunner`
+ * itself has — not a runner bound to one binary the way `hosts/tmux.ts` and
+ * `hosts/cmux.ts` inject theirs (their binary, `tmux`/`cmux`, is fixed).
+ */
+import { streamRunner } from '@osdlc/command-seam';
+import { onPath } from "../contract.js";
+import { wrapperSession } from "../harness.js";
+/**
+ * The current-terminal host: runs the command right here with inherited stdio and waits for it.
+ * Needs no binary or app, runs on every platform, and is always available.
+ */
+export function makeTerminalHost(opts = {}) {
+    const makeRunner = opts.streamRunner ?? streamRunner;
+    const terminal = (req) => {
+        const [bin, ...rest] = req.argv;
+        if (bin === undefined)
+            throw new Error('empty argv');
+        if (!onPath(bin))
+            throw new Error(`'${bin}' is not on PATH`);
+        return makeRunner(bin).run(rest, { cwd: req.cwd }).exitCode;
+    };
+    return {
+        name: 'terminal',
+        platforms: 'all',
+        available() {
+            return true;
+        },
+        terminal,
+        // `terminal` returns only once the agent exited, so the session-id lookup looks once. The
+        // host's own `terminal` part runs, so a host spread from this one with another
+        // `terminal` opens the session through that one.
+        session(req) {
+            const run = this.terminal ?? terminal;
+            return wrapperSession((r) => run.call(this, r), req, { hostWaited: true });
+        },
+    };
+}
+/** The production terminal host — `streamRunner` as its runner factory. */
+export const terminalHost = makeTerminalHost();

package/dist/hosts/tmux.d.ts

@@ -0,0 +1,145 @@
+/**
+ * tmux: a detached session on `cwd` running a command, found again by a name
+ * bound to the caller's session id; see `docs/planning/research/tmux.md`.
+ *
+ * Unlike orca/cmux, tmux has no app-level worktree registry and no `--name`
+ * the caller supplies — a session name is chosen here, once, and must be
+ * unique server-wide. A launch carries the caller's session id
+ * (`CommandRequest.sessionId`), so the name is derived from it
+ * ({@link tmuxIdSessionName}) and two sessions in one worktree get two tmux
+ * sessions. `send`/`find`/`focus`/`capture`/`close` take the same id and
+ * target that name; a request without an id (or a session opened before this
+ * binding existed) falls back to the name derived from `cwd`
+ * ({@link tmuxSessionName}).
+ */
+import { type CommandRunner } from '@osdlc/command-seam';
+import type { CommandRequest, Host } from '../contract.ts';
+/**
+ * The cwd-derived tmux session name: stable across repeated calls with the same
+ * `cwd`, and the name every session had before addressing by id. tmux session
+ * names must be unique server-wide and match `[A-Za-z0-9_-]` —
+ * `docs/planning/research/tmux.md`'s "Naming rules" verified that `.`/`:` are
+ * silently rewritten to `_`, which can then cause a LATER create to fail with
+ * `duplicate session` against the rewritten name instead of the one actually
+ * requested. Hashing `cwd` sidesteps that class of surprise entirely rather
+ * than trying to sanitize an arbitrary path into the safe character set.
+ *
+ * Used for a request with no session id and as the fallback for a session
+ * opened before names were bound to ids. Two launches WITHOUT an id for the
+ * SAME `cwd` still collide — the second `tmux new-session` fails with its own
+ * real "duplicate session" error, surfaced verbatim below.
+ *
+ * @experimental an `attach` part is planned to replace the tmux-specific attach helpers.
+ */
+export declare function tmuxSessionName(cwd: string): string;
+/**
+ * The tmux session name bound to a caller session id: `sd-` and {@link sessionIdSlug}, the
+ * id's first 12 characters with anything outside `[A-Za-z0-9_-]` rewritten to `_` (so tmux
+ * never rewrites it for us), then `-` and 8 hex digits of the sha256 of the whole id. The hash
+ * keeps apart ids that share their first 12 characters (`build-step-001`, `build-step-002`) or
+ * differ only in a rewritten character (`a.b`, `a_b`).
+ *
+ * The single source of the name: an attach must call this rather than rebuild it.
+ *
+ * @experimental an `attach` part is planned to replace the tmux-specific attach helpers.
+ */
+export declare function tmuxIdSessionName(sessionId: string): string;
+/**
+ * The name of a visible run's session: `sd-` and the run id (anything outside `[A-Za-z0-9_-]`
+ * rewritten to `_`), then, when there is a caller session id (a run's several agent steps each
+ * get a session), `-` and the same id part as {@link tmuxIdSessionName}. A person finds it by
+ * the run id (`tmux ls`).
+ */
+export declare function tmuxRunSessionName(runId: string, sessionId?: string): string;
+/**
+ * Argv for `tmux new-session` — pure, so a test can pin it. `-d` (detached)
+ * is what makes this hands-off, the same category as orca/cmux's own managed
+ * window: `new-session` returns almost immediately once the session exists,
+ * long before whatever it runs finishes. `--` terminates tmux's own option
+ * parsing before `req.argv` (the harness's argv, possibly under an `env` prefix —
+ * see `wrapperSession` in `../harness.ts`) starts, the same guard `harnessArgv` itself applies one
+ * level down for the harness binary's own flags.
+ */
+export declare function tmuxCreateArgv(req: CommandRequest): string[];
+/** Argv for the wait poll: prints `<pane_dead> <pane_dead_status>` for the session's pane. */
+export declare function tmuxPaneStatusArgv(name: string): string[];
+/**
+ * Argv for `load-buffer`, the first of the three invocations `send` makes, per
+ * `docs/planning/research/tmux.md`'s "Sending input" section (verified): `-`
+ * reads the buffer's content from stdin (`req.text`, passed as
+ * `CommandRunOptions.input`), so embedded newlines survive the paste instead of
+ * each arriving as an Enter, and a `text` starting with `-` is never parsed as
+ * a flag.
+ */
+export declare function tmuxLoadBufferArgv(name: string): string[];
+/**
+ * Argv for `paste-buffer`, the second invocation: `-p` pastes as if typed
+ * (bracketed paste, matching Orca's own send behavior), `-d` deletes the
+ * buffer immediately after so it never lingers for a later, unrelated send
+ * to collide with. `-t` addresses the pane by session `name`.
+ */
+export declare function tmuxPasteBufferArgv(name: string): string[];
+/** The third, separate `send-keys` call that submits what {@link tmuxPasteBufferArgv} just pasted. */
+export declare function tmuxSendEnterArgv(name: string): string[];
+/**
+ * Argv for `tmux has-session -t <name>` — per `docs/planning/research/tmux.md`'s
+ * "Presence checks" section (verified): exits 0 when the session exists, 1
+ * when it does not. Simpler than `list-panes` and sufficient here, since a
+ * session name maps 1:1 to a pane.
+ */
+export declare function tmuxHasSessionArgv(name: string): string[];
+/**
+ * Argv for `tmux attach-session -t <name>` — the real, interactive attach
+ * a caller uses for a tmux-hosted session `find` (below) confirms is still
+ * live, instead of falling through to an engine-native resume that would risk
+ * opening a SECOND, competing session on top of a still-live one. Unlike orca/cmux, tmux has a genuine
+ * interactive attach primitive of its own — this is that mechanism (`attach-
+ * session` itself is standard, well-documented tmux behavior, not something
+ * this campaign's own research docs independently verified).
+ *
+ * Only correct when the attaching process is OUTSIDE any tmux client already
+ * — a caller reaches for {@link tmuxSwitchClientArgv} instead
+ * when `$TMUX` is set, since `attach-session` refuses to nest one client
+ * inside another.
+ *
+ * @experimental an `attach` part is planned to replace the tmux-specific attach helpers.
+ */
+export declare function tmuxAttachArgv(name: string): string[];
+/**
+ * Argv for `tmux switch-client -t <name>` — what a caller uses
+ * instead of {@link tmuxAttachArgv} when the attaching process is ITSELF
+ * already inside a tmux client (`$TMUX` set, the common case for a tmux
+ * user): `attach-session` there refuses with "sessions should be nested with
+ * care, unset $TMUX to force" and exits 1 without attaching anything, while
+ * `switch-client` is tmux's own documented mechanism for moving the current
+ * client to a different session instead of nesting one inside another.
+ *
+ * @experimental an `attach` part is planned to replace the tmux-specific attach helpers.
+ */
+export declare function tmuxSwitchClientArgv(name: string): string[];
+/** Argv for `tmux list-sessions`, one session name per line. */
+export declare function tmuxListSessionsArgv(): string[];
+/** Argv for `tmux capture-pane -p -t <name>`: prints the pane's visible text to stdout. */
+export declare function tmuxCapturePaneArgv(name: string): string[];
+/** Argv for `tmux kill-session -t <name>`: ends the session and signals what runs in it. */
+export declare function tmuxKillSessionArgv(name: string): string[];
+/**
+ * Whether this process runs inside a tmux client (the `TMUX` environment variable is set).
+ *
+ * @experimental an `attach` part is planned to replace the tmux-specific attach helpers.
+ */
+export declare function insideTmux(): boolean;
+/**
+ * The tmux host: drives a detached tmux session per launch through the `tmux` binary, which must be on PATH.
+ * Runs on darwin and linux only (on Windows it is unavailable; run it inside WSL). Keeps no state of its own;
+ * sessions are found again by a name derived from the caller's session id.
+ */
+export declare function makeTmuxHost(opts: {
+    runner?: CommandRunner | undefined;
+    available?: (() => boolean) | undefined;
+    /** Defaults to {@link insideTmux}. */
+    inside?: (() => boolean) | undefined;
+    /** The wait poll's pause and clock (epoch ms); tests replace them. */
+    sleep?: ((ms: number) => void) | undefined;
+    now?: (() => number) | undefined;
+}): Host;