@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/lib/terminal/backends/iterm.d.ts

@@ -1,6 +1,4 @@
 import type { TerminalBackend, SplitDirection } from '../types.js';
-/** AppleScript that opens an iTerm tab (a window if none is open) running the command. */
 export declare function itermTabScript(cwd: string, command: string[]): string;
-/** AppleScript that splits the current iTerm session (a window if none is open). */
 export declare function itermSplitScript(cwd: string, command: string[], direction: SplitDirection): string;
 export declare const itermBackend: TerminalBackend;

package/dist/lib/terminal/backends/iterm.js

@@ -1,10 +1,3 @@
-/**
- * iTerm backend — drives iTerm2 via AppleScript (`osascript`).
- *
- * Tab: creates a tab in the current window (or a window when none is open).
- * Split: splits the current session — `split vertically` (side-by-side, a
- * vertical divider) for `right`, `split horizontally` (stacked) for `down`.
- */
 import * as fs from 'fs';
 import { appleScriptStr } from '../quote.js';
 import { loginExec, iLoginShell } from '../shell.js';
@@ -17,7 +10,6 @@ function appExists(p) {
         return false;
     }
 }
-/** AppleScript that opens an iTerm tab (a window if none is open) running the command. */
 export function itermTabScript(cwd, command) {
     const cmd = appleScriptStr(iLoginShell(loginExec(cwd, command)));
     return [
@@ -31,10 +23,8 @@ export function itermTabScript(cwd, command) {
         'end tell',
     ].join('\n');
 }
-/** AppleScript that splits the current iTerm session (a window if none is open). */
 export function itermSplitScript(cwd, command, direction) {
     const cmd = appleScriptStr(iLoginShell(loginExec(cwd, command)));
-    // iTerm: "split vertically" = a vertical divider = panes side by side (right).
     const verb = direction === 'right' ? 'split vertically' : 'split horizontally';
     return [
         'tell application "iTerm2"',

package/dist/lib/terminal/backends/terminal-app.d.ts

@@ -1,13 +1,3 @@
 import type { TerminalBackend } from '../types.js';
-/**
- * AppleScript that opens a Terminal.app tab running the command.
- *
- * `do script` with no `in` target opens a NEW window; with a front window
- * present, `tell application "System Events" to keystroke "t"` would be the only
- * way to force a tab, and that needs an Accessibility grant. So: a window when
- * none exists, otherwise `do script … in front window`, which Terminal renders
- * as a new tab of that window when its "New tabs" setting is on and a new
- * window otherwise. Either way the command runs in a fresh, visible surface.
- */
 export declare function terminalAppTabScript(cwd: string, command: string[]): string;
 export declare const terminalAppBackend: TerminalBackend;

package/dist/lib/terminal/backends/terminal-app.js

@@ -1,15 +1,3 @@
-/**
- * Terminal.app backend — drives macOS Terminal via AppleScript (`osascript`).
- *
- * This is the floor of the backend list: every Mac has Terminal.app, so a GUI
- * caller that can name no better terminal still gets a surface. It is also what
- * the menu bar's "New Session" always used before the engine took that path
- * over, so registering it keeps a Terminal-only Mac working exactly as it did.
- *
- * Terminal.app has no scriptable split — `do script` only ever makes a tab (or a
- * window). A split request therefore opens a TAB, which is stated here and in
- * `buildSplit` rather than silently pretending the pane happened.
- */
 import * as fs from 'fs';
 import { appleScriptStr } from '../quote.js';
 import { loginExec, iLoginShell } from '../shell.js';
@@ -23,16 +11,6 @@ function appExists(p) {
         return false;
     }
 }
-/**
- * AppleScript that opens a Terminal.app tab running the command.
- *
- * `do script` with no `in` target opens a NEW window; with a front window
- * present, `tell application "System Events" to keystroke "t"` would be the only
- * way to force a tab, and that needs an Accessibility grant. So: a window when
- * none exists, otherwise `do script … in front window`, which Terminal renders
- * as a new tab of that window when its "New tabs" setting is on and a new
- * window otherwise. Either way the command runs in a fresh, visible surface.
- */
 export function terminalAppTabScript(cwd, command) {
     const cmd = appleScriptStr(iLoginShell(loginExec(cwd, command)));
     return [
@@ -49,13 +27,6 @@ export function terminalAppTabScript(cwd, command) {
 export const terminalAppBackend = {
     id: 'terminal',
     label: 'Terminal',
-    /**
-     * Terminal.app is scriptable only from a session that can reach the GUI login
-     * — an `osascript` fired over plain SSH gets "Application isn't running" — so
-     * an SSH-hosted context reports it unavailable rather than launching into a
-     * window nobody can see. (A launchd GUI agent like the menu bar helper has no
-     * SSH_* vars and is available.)
-     */
     isAvailable(ctx) {
         if (ctx.platform !== 'darwin')
             return false;
@@ -66,7 +37,6 @@ export const terminalAppBackend = {
     buildTab(cwd, command) {
         return { argv: ['osascript', '-e', terminalAppTabScript(cwd, command)] };
     },
-    /** Terminal.app cannot split by script — a split request opens a tab instead. */
     buildSplit(cwd, command, _direction) {
         return { argv: ['osascript', '-e', terminalAppTabScript(cwd, command)] };
     },

package/dist/lib/terminal/backends/tmux.d.ts

@@ -1,14 +1,4 @@
-/**
- * tmux backend — opens windows and splits in the running tmux server.
- *
- * cwd is passed natively via `-c`, so the command is wrapped in `zsh -ilc` with
- * no `cd`. `split-window -h` = side-by-side (right); `-v` = stacked (down).
- * Available only when the CLI is running inside tmux (`$TMUX` set) — otherwise
- * there is no current window/pane to attach to.
- */
 import type { TerminalBackend, SplitDirection } from '../types.js';
-/** argv that opens a new tmux window running the command in cwd. */
 export declare function tmuxTabArgv(cwd: string, command: string[]): string[];
-/** argv that splits the current tmux pane, running the command in cwd. */
 export declare function tmuxSplitArgv(cwd: string, command: string[], direction: SplitDirection): string[];
 export declare const tmuxBackend: TerminalBackend;

package/dist/lib/terminal/backends/tmux.js

@@ -1,9 +1,7 @@
 import { execOnly, iLoginShell } from '../shell.js';
-/** argv that opens a new tmux window running the command in cwd. */
 export function tmuxTabArgv(cwd, command) {
     return ['tmux', 'new-window', '-c', cwd, iLoginShell(execOnly(command))];
 }
-/** argv that splits the current tmux pane, running the command in cwd. */
 export function tmuxSplitArgv(cwd, command, direction) {
     const flag = direction === 'right' ? '-h' : '-v';
     return ['tmux', 'split-window', flag, '-c', cwd, iLoginShell(execOnly(command))];

package/dist/lib/terminal/backends/vscodium-agent.d.ts

@@ -1,40 +1,15 @@
 import type { TerminalBackend, SplitDirection } from '../types.js';
-/** An editor flavour that speaks the swarm-ext URI protocol. */
 export interface EditorVariant {
-    /** CLI on PATH, invoked with `--open-url`. */
     cli: string;
-    /** URL scheme the product registers (must match the CLI's product). */
     scheme: string;
-    /** macOS app bundle, for local availability detection. */
     app: string;
     label: string;
 }
-/**
- * Known editors, in preference order. VSCodium first — the backend is named for
- * it and is the user's editor; Cursor and VS Code also ship the extension and
- * are wired here for `makeVscodiumAgentBackend` / future registration.
- */
 export declare const EDITOR_VARIANTS: EditorVariant[];
-/**
- * The `<scheme>://swarmify.swarm-ext/spawn?p=<payload>` URL the extension handles.
- *
- * The payload is base64url-encoded JSON in a single `p` param — NOT one param per
- * field. VS Code percent-*decodes* `uri.query` once before the extension parses
- * it, so a `command`/`cwd` containing `&` (or `=`) would be mis-split by a naive
- * multi-param query. base64url is `[A-Za-z0-9_-]` only (no `&`, `=`, `%`, `+`,
- * `/`), so it survives that decode untouched and round-trips exactly.
- *
- * Optional `meta.agent` / `meta.sessionId` / `meta.title` let the extension set
- * the tab chip and status bar without sniffing the local process tree — required
- * when `command` is a remote attach (`ssh … tmux attach`) with no agent binary
- * on this box (#2478).
- */
 export declare function spawnUri(scheme: string, cwd: string, command: string[], direction?: SplitDirection, meta?: {
     agent?: string;
     sessionId?: string;
     title?: string;
 }): string;
-/** Build a backend bound to one editor variant. */
 export declare function makeVscodiumAgentBackend(variant: EditorVariant): TerminalBackend;
-/** Default backend: VSCodium (`codium` CLI, `vscodium://` scheme). */
 export declare const vscodiumAgentBackend: TerminalBackend;

package/dist/lib/terminal/backends/vscodium-agent.js

@@ -1,25 +1,5 @@
-/**
- * VSCodium agent-terminal backend — opens an agent terminal in a VSCodium /
- * Cursor / VS Code window via the swarmify `swarm-ext` extension's URI handler.
- *
- * Unlike iTerm/Ghostty (GUI terminal apps driven by AppleScript), the editor is
- * already running; we hand it a `<scheme>://swarmify.swarm-ext/spawn?…` URL via
- * the editor CLI's `--open-url` flag. The extension opens an editor-tab terminal
- * in `cwd`, runs `command`, and its shell-adoption promotes a resume command
- * (e.g. `claude --resume <id>`) to the matching agent chip. Driving the editor
- * CLI (not macOS `open`) means this works over `--device` SSH and on Linux, needs
- * no OS URL-scheme handler registration, and sends the command into an
- * already-interactive login shell — so no `zsh -ilc` wrap (the other backends'
- * wrapper) is applied here.
- */
 import * as fs from 'fs';
-/** The swarmify extension identifier that owns the `/spawn` URI verb. */
 const EXTENSION_AUTHORITY = 'swarmify.swarm-ext';
-/**
- * Known editors, in preference order. VSCodium first — the backend is named for
- * it and is the user's editor; Cursor and VS Code also ship the extension and
- * are wired here for `makeVscodiumAgentBackend` / future registration.
- */
 export const EDITOR_VARIANTS = [
     { cli: 'codium', scheme: 'vscodium', app: '/Applications/VSCodium.app', label: 'VSCodium' },
     { cli: 'cursor', scheme: 'cursor', app: '/Applications/Cursor.app', label: 'Cursor' },
@@ -33,20 +13,6 @@ function appExists(p) {
         return false;
     }
 }
-/**
- * The `<scheme>://swarmify.swarm-ext/spawn?p=<payload>` URL the extension handles.
- *
- * The payload is base64url-encoded JSON in a single `p` param — NOT one param per
- * field. VS Code percent-*decodes* `uri.query` once before the extension parses
- * it, so a `command`/`cwd` containing `&` (or `=`) would be mis-split by a naive
- * multi-param query. base64url is `[A-Za-z0-9_-]` only (no `&`, `=`, `%`, `+`,
- * `/`), so it survives that decode untouched and round-trips exactly.
- *
- * Optional `meta.agent` / `meta.sessionId` / `meta.title` let the extension set
- * the tab chip and status bar without sniffing the local process tree — required
- * when `command` is a remote attach (`ssh … tmux attach`) with no agent binary
- * on this box (#2478).
- */
 export function spawnUri(scheme, cwd, command, direction, meta) {
     const payload = {
         command: command.join(' '),
@@ -63,7 +29,6 @@ export function spawnUri(scheme, cwd, command, direction, meta) {
     const p = Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
     return `${scheme}://${EXTENSION_AUTHORITY}/spawn?p=${p}`;
 }
-/** Build a backend bound to one editor variant. */
 export function makeVscodiumAgentBackend(variant) {
     return {
         id: 'vscodium-agent',
@@ -79,5 +44,4 @@ export function makeVscodiumAgentBackend(variant) {
         },
     };
 }
-/** Default backend: VSCodium (`codium` CLI, `vscodium://` scheme). */
 export const vscodiumAgentBackend = makeVscodiumAgentBackend(EDITOR_VARIANTS[0]);

package/dist/lib/terminal/engine.d.ts

@@ -1,27 +1,15 @@
-/**
- * The engine — turns requests into open surfaces.
- *
- * `specForRequest` and `buildRequests` are pure (planning); `openSurface` and
- * `openSurfaces` add the side-effecting transport. A batch runs sequentially and
- * staggered so a `split-right` lands in the tab that was just opened (the split
- * targets the front pane).
- */
 import type { Backend, EngineContext, LaunchRequest, LaunchResult, LaunchSpec } from './types.js';
 import { type Packing } from './policy.js';
 import { type HostResolver } from './transport.js';
-/** The concrete launch command for a request (pure — no side effects). */
 export declare function specForRequest(req: LaunchRequest): LaunchSpec;
 export interface OpenOptions {
     resolveHost?: HostResolver;
     ctx?: EngineContext;
 }
-/** Open a single surface for one request. Never throws — failures come back in the result. */
 export declare function openSurface(req: LaunchRequest, opts?: OpenOptions): Promise<LaunchResult>;
-/** One command to run as a surface. */
 export interface SurfaceItem {
     cwd: string;
     command: string[];
-    /** Optional harness identity for editor-backed backends (vscodium-agent). */
     agent?: string;
     sessionId?: string;
     title?: string;
@@ -31,13 +19,8 @@ export interface BuildRequestsOptions {
     host?: string;
     packing?: Packing;
 }
-/** Turn a list of commands into layout-assigned requests (pure — the planning step). */
 export declare function buildRequests(items: SurfaceItem[], opts: BuildRequestsOptions): LaunchRequest[];
 export interface OpenManyOptions extends OpenOptions, BuildRequestsOptions {
     staggerMs?: number;
 }
-/**
- * Open many surfaces, applying the layout policy (default: two-per-tab).
- * Sequential + staggered so each split follows the tab it splits.
- */
 export declare function openSurfaces(items: SurfaceItem[], opts: OpenManyOptions): Promise<LaunchResult[]>;

package/dist/lib/terminal/engine.js

@@ -5,7 +5,6 @@ import { homeRemainder, remoteCdPrefix } from '../project-root.js';
 import { sshExec } from '../ssh-exec.js';
 const DEFAULT_STAGGER_MS = 400;
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-/** The concrete launch command for a request (pure — no side effects). */
 export function specForRequest(req) {
     const backend = BACKENDS[req.backend];
     if (!backend)
@@ -17,12 +16,8 @@ export function specForRequest(req) {
         return backend.buildTab(req.cwd, req.command, meta);
     return backend.buildSplit(req.cwd, req.command, req.layout === 'split-down' ? 'down' : 'right', meta);
 }
-/** Open a single surface for one request. Never throws — failures come back in the result. */
 export async function openSurface(req, opts = {}) {
     try {
-        // Both can throw: specForRequest on an unknown backend, runSpec when the
-        // SSH transport rejects an invalid --device target. Keep them inside the
-        // catch so a bad request degrades to a per-surface failure, never a throw.
         let resolved = req;
         if (req.host && req.host !== 'local' && homeRemainder(req.cwd) !== null) {
             const target = opts.resolveHost ? opts.resolveHost(req.host) : req.host;
@@ -41,7 +36,6 @@ export async function openSurface(req, opts = {}) {
         return { ok: false, request: req, error: err?.message ?? String(err) };
     }
 }
-/** Turn a list of commands into layout-assigned requests (pure — the planning step). */
 export function buildRequests(items, opts) {
     const layouts = planLayouts(items.length, opts.packing ?? 'two-per-tab');
     return items.map((item, i) => ({
@@ -55,10 +49,6 @@ export function buildRequests(items, opts) {
         title: item.title,
     }));
 }
-/**
- * Open many surfaces, applying the layout policy (default: two-per-tab).
- * Sequential + staggered so each split follows the tab it splits.
- */
 export async function openSurfaces(items, opts) {
     const requests = buildRequests(items, opts);
     const stagger = opts.staggerMs ?? DEFAULT_STAGGER_MS;

package/dist/lib/terminal/index.d.ts

@@ -1,11 +1,3 @@
-/**
- * Terminal launch engine — open an interactive command as a tab or split pane
- * in iTerm / Ghostty / tmux, on this machine or a remote host.
- *
- * Public entry point. Callers typically use `openSurfaces` (a batch with a
- * layout policy) or `openSurface` (a single request), and `availableBackends` /
- * `detectCurrentBackend` to pick a target. See docs/interfaces.md.
- */
 export type { Backend, SplitDirection, Layout, EngineContext, LaunchSpec, LaunchRequest, LaunchResult, TerminalBackend, } from './types.js';
 export { currentContext } from './types.js';
 export { BACKENDS, detectCurrentBackend, availableBackends, itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend, terminalAppBackend } from './backends/index.js';

package/dist/lib/terminal/inject.d.ts

@@ -1,50 +1,5 @@
-/**
- * Terminal injection — Gap 2 of the Terminal Engine.
- *
- * Where the rest of the engine OPENS a surface (a tab / split running a
- * command), injection types into an ALREADY-running surface. It's the primitive
- * a native watchdog (RUSH-1415) needs to nudge a stalled agent with "continue"
- * delivered into the exact terminal that agent lives in — the gap flagged in
- * src/lib/session/provenance.ts:20:
- *
- *   > Actually delivering the keystrokes is Gap 2 (pty/tmux send-keys).
- *
- * It mirrors the engine's shape exactly: pure per-backend spec builders (like
- * `tmuxTabArgv` / `itermTabScript`) produce a `LaunchSpec` (argv), and the same
- * `runSpec` transport runs it — so injection inherits the engine's local/remote
- * (`--device` over SSH) execution for free. A `LaunchSpec` never opens anything;
- * building one is side-effect-free and unit-testable without a display.
- *
- * Backends (each addresses the EXACT split, not the frontmost surface):
- *   - tmux  → `tmux send-keys -t <pane>` — the send-keys primitive addressed by
- *             pane id + socket (the exact rail provenance.ts identifies).
- *   - iterm (macOS) → AppleScript `tell session id "<uuid>" to write text` —
- *             addresses the precise iTerm2 split by its session UUID WITHOUT
- *             `activate`, so it never steals focus or types into the wrong split.
- *             Uses the engine's `appleScriptStr` escaper; guarded by the iterm
- *             backend's `isAvailable` (platform + app installed).
- *   - vscodium (VSCodium / Cursor / VS Code) → the editor CLI's `--open-url`
- *             into the swarmify `swarm-ext` extension's `/inject` verb, targeting
- *             a live-terminals.json terminal by id. Focus-independent, exact
- *             terminal, and (like the launch backend, src/lib/terminal/backends/
- *             vscodium-agent.ts) works over `--device` SSH and on Linux.
- *   - ghostty (macOS) → COARSE only: Ghostty has no scripting dictionary, so
- *             there is no per-split addressing — this raises a window and types
- *             via System Events keystrokes, stealing focus. The resolver refuses
- *             to route here by default (see resolve.ts); it stays behind an
- *             explicit opt-in.
- *
- * Ink-TUI Enter semantics: Claude's Ink TUI swallows an Enter fused to the text,
- * so the default path delivers the text and the Enter as TWO SEPARATE writes
- * (swarmify's `sendText(text,false)` then `sendText('\r',false)`). `combined`
- * opts into one fused write for plain shells / REPLs.
- */
 import { type HostResolver } from './transport.js';
 import { type LaunchSpec, type EngineContext } from './types.js';
-/**
- * An already-running surface to type into. A superset of the engine's launch
- * `Backend`.
- */
 export type InjectTarget = {
     backend: 'tmux';
     pane: string;
@@ -52,14 +7,7 @@ export type InjectTarget = {
 } | {
     backend: 'iterm';
     session?: string;
-}
-/**
- * A VSCodium / Cursor / VS Code integrated terminal, addressed by the id the
- * swarm-ext extension keys `live-terminals.json` on (the session UUID). `cli`
- * is the editor CLI on PATH (`codium` / `cursor` / `code`); `scheme` is its
- * URL scheme (`vscodium` / `cursor` / `vscode`) — the resolver fills both.
- */
- | {
+} | {
     backend: 'vscodium';
     terminalId: string;
     cli: string;
@@ -70,100 +18,32 @@ export type InjectTarget = {
 };
 export type InjectBackend = InjectTarget['backend'];
 export interface InjectOptions {
-    /** Append Enter after the text. Default true. */
     enter?: boolean;
-    /**
-     * Fuse the text and its Enter into a SINGLE write. Default false — the safe
-     * default sends the text, then the Enter, as two separate writes (Ink-TUI
-     * safe). Set true for plain shells / REPLs that want one atomic line.
-     */
     combined?: boolean;
-    /** tmux socket override (defaults to `target.socket`, then tmux's default socket). */
     socket?: string;
-    /** Remote host for the tmux / AppleScript backends (runs the spec over SSH). Local by default. */
     host?: string;
-    /** Resolve a host alias to an ssh target (see the engine's transport). */
     resolveHost?: HostResolver;
-    /** Ambient context for the availability check (defaults to the live process context). */
     ctx?: EngineContext;
-    /** Don't execute — return the spec(s) that WOULD run. Lets the macOS paths be asserted on Linux. */
     dryRun?: boolean;
-    /**
-     * Hard bound for the WHOLE injection, in ms. Each spec is run under the
-     * remaining budget with process-group cancellation, and a spec is never
-     * STARTED once the budget is gone — an operator-facing caller must be able to
-     * return a verdict on time without leaving a launcher running behind it
-     * (PHNX-3999). Omitted keeps the historical unbounded behaviour.
-     */
     deadlineMs?: number;
-    /**
-     * Frame the text in bracketed-paste markers so a TUI inserts it verbatim
-     * instead of reading each embedded newline as a submit. Required for a
-     * multiline free-text answer. Only the tmux rail can carry it (see
-     * {@link backendCarriesPaste}); every other backend refuses with an error.
-     */
     paste?: boolean;
 }
 export interface InjectResult {
     ok: boolean;
     backend: InjectBackend;
-    /**
-     * Delivery is CONFIRMED to have reached the running agent, not merely dispatched.
-     *
-     * For tmux / iterm / ghostty, `ok` already means delivered: `tmux
-     * send-keys` errors on a missing pane, `osascript write text` errors on a bad
-     * session id — so a successful transport IS the confirmation. For **vscodium**, `ok` only means the
-     * editor CLI accepted the `--open-url` hand-off; whether the swarm-ext extension
-     * actually parsed the verb and typed anything is unknown from the CLI side (the
-     * ext must ack — RUSH follow-up). So vscodium is delivered-but-UNCONFIRMED, and
-     * the watchdog must not book a nudge as landed on that alone.
-     */
     confirmed: boolean;
-    /** Discrete writes delivered: 2 for the Ink-safe text+Enter split, 1 when combined or enter=false. */
     writes: number;
-    /**
-     * How many specs were STARTED. This -- not `writes` -- is what says whether
-     * anything may have reached the terminal: a spec that failed or timed out may
-     * still have written bytes before dying, so only `started === 0` proves
-     * nothing landed and the answer is cleanly retryable (PHNX-3999).
-     */
     started: number;
-    /** For the tmux / AppleScript backends (or any dryRun), the spec(s) that ran / would run. */
     specs?: LaunchSpec[];
     error?: string;
 }
-/**
- * Bracketed-paste framing (DEC mode 2004) — the pty contract for "insert this
- * verbatim, do not submit". A readline/Ink composer that sees the start marker
- * buffers every byte up to the end marker, so an embedded newline lands as a
- * literal newline in the draft instead of submitting the partial line.
- */
 export declare const BRACKETED_PASTE_START = "\u001B[200~";
 export declare const BRACKETED_PASTE_END = "\u001B[201~";
-/**
- * Only tmux can carry the framing: `send-keys -l` writes the marker bytes
- * straight to the pty. ghostty simulates keystrokes, vscodium hands a JSON
- * payload to the extension, and iTerm's AppleScript `write text` cannot encode
- * a raw ESC byte — so a paste request on those is refused rather than
- * half-delivered as one submit per line.
- */
 export declare function backendCarriesPaste(backend: InjectBackend): boolean;
-/**
- * argv for `tmux send-keys` targeting a pane by id. Starts with `tmux` (like the
- * engine's `tmuxTabArgv`) so the same transport runs it locally or over SSH. The
- * socket, when set, is positioned before the subcommand (`-S` must lead). `-l`
- * sends the keys literally; without it tmux interprets a key name like `Enter`.
- *
- * NOTE: distinct from `sendKeys()` in src/lib/tmux/session.ts — that one
- * addresses by session *name* on the default socket (the `agents tmux` surface)
- * and shells out directly; this one addresses by *pane id* + arbitrary socket and
- * returns an SSH-capable `LaunchSpec` for the engine transport. Don't collapse them.
- */
 export declare function tmuxSendKeysArgv(pane: string, keys: string, opts?: {
     literal?: boolean;
     socket?: string;
 }): string[];
-/** The one-or-two send-keys specs for a tmux injection (Ink-safe split by default). */
 export declare function tmuxInjectSpecs(target: Extract<InjectTarget, {
     backend: 'tmux';
 }>, text: string, o: {
@@ -171,78 +51,26 @@ export declare function tmuxInjectSpecs(target: Extract<InjectTarget, {
     combined: boolean;
     socket?: string;
 }): LaunchSpec[];
-/**
- * AppleScript that types into a SPECIFIC iTerm2 split via `tell session id
- * "<uuid>" to write text` — the exact split provenance's iterm rail identifies,
- * addressed by its session UUID. Crucially there is NO `activate`: `write text`
- * delivers to that session directly, so injection never brings iTerm forward or
- * types into whatever split happens to be focused. Omitting `session` targets
- * the current session (a direct-call convenience; the resolver always supplies
- * one).
- *
- * Enter semantics — iTerm's `write text` appends a trailing newline, which fuses
- * text+Enter into ONE write and Claude's Ink TUI swallows it. So the Ink-safe
- * default (enter, not combined) suppresses that newline (`write text … newline
- * no`) and sends the Return as a SEPARATE `write text` of a lone CR (`character
- * id 13`) — two distinct pty writes, Enter seen on its own. `combined` opts into
- * the single fused `write text` (auto-newline) for plain shells / REPLs.
- *
- * NOTE (macOS-only verification pending): the two-write CR path is the safe
- * choice because it mirrors the tmux/pty Ink-safe split that IS verified here on
- * Linux; whether a single `write text T` would also submit under Ink can only be
- * confirmed on a Mac running iTerm (see the PR body).
- */
 export declare function itermInjectScript(text: string, opts: {
     session?: string;
     enter: boolean;
     combined?: boolean;
 }): string;
-/**
- * AppleScript for Ghostty (no scripting dictionary): raise the target window via
- * System Events, then keystroke the text and a separate Return. `window` matches
- * a window whose title contains the string; omitted → the frontmost Ghostty window.
- */
 export declare function ghosttyInjectScript(text: string, opts: {
     window?: string;
     enter: boolean;
 }): string;
-/** The osascript spec for a macOS injection. One invocation delivers the text + Return. */
 export declare function appleScriptInjectSpec(target: Extract<InjectTarget, {
     backend: 'iterm' | 'ghostty';
 }>, text: string, enter: boolean, combined?: boolean): LaunchSpec;
-/**
- * The `<scheme>://swarmify.swarm-ext/inject?p=<payload>` URL the extension
- * handles to type into an ALREADY-open integrated terminal (the inject sibling
- * of the launch backend's `/spawn`, src/lib/terminal/backends/vscodium-agent.ts).
- *
- * Payload is base64url-encoded JSON in a single `p` param — identical encoding
- * to `spawnUri`, and for the same reason: VS Code percent-decodes `uri.query`
- * once before the extension parses it, so a naive multi-param query would
- * mis-split a text containing `&`/`=`; base64url (`[A-Za-z0-9_-]`) survives that
- * decode untouched. `terminalId` is the id the extension keys live-terminals.json
- * on (the session UUID); `enter` tells the extension to submit; `combined` asks
- * it to fuse text+Enter into one write (default is the Ink-safe two-write split,
- * mirroring the tmux/iterm paths — the extension owns that split on its side).
- *
- * DEPENDENCY: the `/inject` verb ships in the swarm-ext extension via PR #608's
- * successor (PR #608 introduces `/spawn`; the inject verb + `write`/`enter`
- * handling is its follow-up). Until that lands, this routes correctly on the CLI
- * side but the extension will no-op the unknown verb. See the PR body.
- */
 export declare function vscodiumInjectUri(scheme: string, terminalId: string, text: string, opts: {
     enter: boolean;
     combined: boolean;
 }): string;
-/** The editor-CLI spec for a VSCodium/Cursor/VS Code injection (one `--open-url` invocation). */
 export declare function vscodiumInjectSpec(target: Extract<InjectTarget, {
     backend: 'vscodium';
 }>, text: string, opts: {
     enter: boolean;
     combined: boolean;
 }): LaunchSpec;
-/**
- * Deliver `text` (+ Enter) into an existing terminal surface. Resolves the
- * target's backend and routes to the matching primitive. Never throws — launch
- * failures come back in the result, like the engine's `openSurface`.
- */
 export declare function injectIntoTerminal(target: InjectTarget, text: string, opts?: InjectOptions): Promise<InjectResult>;