@phnx-labs/agents-cli 1.20.34 → 1.20.36

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

@@ -0,0 +1,31 @@
+import { itermBackend } from './iterm.js';
+import { ghosttyBackend } from './ghostty.js';
+import { tmuxBackend } from './tmux.js';
+import { vscodiumAgentBackend } from './vscodium-agent.js';
+/** All known interactive backends, keyed by id. */
+export const BACKENDS = {
+    iterm: itermBackend,
+    ghostty: ghosttyBackend,
+    tmux: tmuxBackend,
+    'vscodium-agent': vscodiumAgentBackend,
+};
+/**
+ * The backend for the terminal the CLI is currently running in, or null if we
+ * can't open a surface into it. tmux wins (via `$TMUX`) because a tmux pane can
+ * live inside iTerm/Ghostty; otherwise fall back to `TERM_PROGRAM`.
+ */
+export function detectCurrentBackend(ctx) {
+    if (ctx.env.TMUX)
+        return 'tmux';
+    const term = (ctx.env.TERM_PROGRAM || '').toLowerCase();
+    if (term.includes('iterm'))
+        return 'iterm';
+    if (term.includes('ghostty'))
+        return 'ghostty';
+    return null;
+}
+/** Backends that can actually be driven in this context. */
+export function availableBackends(ctx) {
+    return Object.values(BACKENDS).filter((b) => b.isAvailable(ctx));
+}
+export { itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend };

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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,62 @@
+/**
+ * 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';
+const ITERM_APP = '/Applications/iTerm.app';
+function appExists(p) {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        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 [
+        'tell application "iTerm2"',
+        '  activate',
+        '  if (count of windows) is 0 then',
+        `    create window with default profile command ${cmd}`,
+        '  else',
+        `    tell current window to create tab with default profile command ${cmd}`,
+        '  end if',
+        '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"',
+        '  activate',
+        '  if (count of windows) is 0 then',
+        `    create window with default profile command ${cmd}`,
+        '  else',
+        `    tell current session of current window to ${verb} with default profile command ${cmd}`,
+        '  end if',
+        'end tell',
+    ].join('\n');
+}
+export const itermBackend = {
+    id: 'iterm',
+    label: 'iTerm',
+    isAvailable(ctx) {
+        return ctx.platform === 'darwin' && appExists(ITERM_APP);
+    },
+    buildTab(cwd, command) {
+        return { argv: ['osascript', '-e', itermTabScript(cwd, command)] };
+    },
+    buildSplit(cwd, command, direction) {
+        return { argv: ['osascript', '-e', itermSplitScript(cwd, command, direction)] };
+    },
+};

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

@@ -0,0 +1,14 @@
+/**
+ * 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

@@ -0,0 +1,23 @@
+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))];
+}
+export const tmuxBackend = {
+    id: 'tmux',
+    label: 'tmux',
+    isAvailable(ctx) {
+        return Boolean(ctx.env.TMUX);
+    },
+    buildTab(cwd, command) {
+        return { argv: tmuxTabArgv(cwd, command) };
+    },
+    buildSplit(cwd, command, direction) {
+        return { argv: tmuxSplitArgv(cwd, command, direction) };
+    },
+};

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

@@ -0,0 +1,31 @@
+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.
+ */
+export declare function spawnUri(scheme: string, cwd: string, command: string[], direction?: SplitDirection): 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

@@ -0,0 +1,72 @@
+/**
+ * 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 `--host` 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' },
+    { cli: 'code', scheme: 'vscode', app: '/Applications/Visual Studio Code.app', label: 'VS Code' },
+];
+function appExists(p) {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        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.
+ */
+export function spawnUri(scheme, cwd, command, direction) {
+    const payload = {
+        command: command.join(' '),
+        cwd,
+    };
+    if (direction)
+        payload.split = direction;
+    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',
+        label: `${variant.label} agent`,
+        isAvailable(ctx) {
+            return ctx.platform === 'darwin' && appExists(variant.app);
+        },
+        buildTab(cwd, command) {
+            return { argv: [variant.cli, '--open-url', spawnUri(variant.scheme, cwd, command)] };
+        },
+        buildSplit(cwd, command, direction) {
+            return { argv: [variant.cli, '--open-url', spawnUri(variant.scheme, cwd, command, direction)] };
+        },
+    };
+}
+/** Default backend: VSCodium (`codium` CLI, `vscodium://` scheme). */
+export const vscodiumAgentBackend = makeVscodiumAgentBackend(EDITOR_VARIANTS[0]);

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

@@ -0,0 +1,39 @@
+/**
+ * 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[];
+}
+export interface BuildRequestsOptions {
+    backend: Backend;
+    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

@@ -0,0 +1,54 @@
+import { BACKENDS } from './backends/index.js';
+import { planLayouts } from './policy.js';
+import { runSpec } from './transport.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)
+        throw new Error(`unknown backend: ${req.backend}`);
+    if (req.layout === 'tab')
+        return backend.buildTab(req.cwd, req.command);
+    return backend.buildSplit(req.cwd, req.command, req.layout === 'split-down' ? 'down' : 'right');
+}
+/** 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 --host target. Keep them inside the
+        // catch so a bad request degrades to a per-surface failure, never a throw.
+        const spec = specForRequest(req);
+        const res = await runSpec(spec, req.host, opts.resolveHost);
+        return { ok: res.ok, request: req, error: res.error };
+    }
+    catch (err) {
+        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) => ({
+        backend: opts.backend,
+        layout: layouts[i],
+        cwd: item.cwd,
+        command: item.command,
+        host: opts.host,
+    }));
+}
+/**
+ * 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;
+    const results = [];
+    for (let i = 0; i < requests.length; i++) {
+        results.push(await openSurface(requests[i], opts));
+        if (i < requests.length - 1)
+            await sleep(stagger);
+    }
+    return results;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * 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/terminal-engine.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 } from './backends/index.js';
+export { makeVscodiumAgentBackend, spawnUri, EDITOR_VARIANTS, type EditorVariant } from './backends/vscodium-agent.js';
+export { planLayouts, type Packing } from './policy.js';
+export { specForRequest, buildRequests, openSurface, openSurfaces, type OpenOptions, type OpenManyOptions, type BuildRequestsOptions, type SurfaceItem, } from './engine.js';
+export { runLocal, runRemote, runSpec, remoteCommand, type HostResolver, type RunResult } from './transport.js';
+export { injectIntoTerminal, tmuxSendKeysArgv, tmuxInjectSpecs, itermInjectScript, ghosttyInjectScript, appleScriptInjectSpec, vscodiumInjectUri, vscodiumInjectSpec, type InjectTarget, type InjectBackend, type InjectOptions, type InjectResult, } from './inject.js';
+export { resolveInjectTarget, resolveInjectTargetForSession, type InjectResolution, type InjectRail, type ResolveOptions, } from './resolve.js';

package/dist/lib/terminal/index.js

@@ -0,0 +1,8 @@
+export { currentContext } from './types.js';
+export { BACKENDS, detectCurrentBackend, availableBackends, itermBackend, ghosttyBackend, tmuxBackend, vscodiumAgentBackend } from './backends/index.js';
+export { makeVscodiumAgentBackend, spawnUri, EDITOR_VARIANTS } from './backends/vscodium-agent.js';
+export { planLayouts } from './policy.js';
+export { specForRequest, buildRequests, openSurface, openSurfaces, } from './engine.js';
+export { runLocal, runRemote, runSpec, remoteCommand } from './transport.js';
+export { injectIntoTerminal, tmuxSendKeysArgv, tmuxInjectSpecs, itermInjectScript, ghosttyInjectScript, appleScriptInjectSpec, vscodiumInjectUri, vscodiumInjectSpec, } from './inject.js';
+export { resolveInjectTarget, resolveInjectTargetForSession, } from './resolve.js';

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

@@ -0,0 +1,204 @@
+/**
+ * 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
+ * (`--host` 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 `--host` 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.
+ *   - pty   → the `agents pty write` sidecar path (ptyRequest). Local-only —
+ *             the sidecar is not an engine transport surface.
+ *
+ * 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` — it adds `pty` (the sidecar), which the engine can't launch but can
+ * be injected into.
+ */
+export type InjectTarget = {
+    backend: 'tmux';
+    pane: string;
+    socket?: string;
+} | {
+    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;
+    scheme: string;
+} | {
+    backend: 'ghostty';
+    window?: string;
+} | {
+    backend: 'pty';
+    id: string;
+};
+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;
+}
+export interface InjectResult {
+    ok: boolean;
+    backend: InjectBackend;
+    /** Discrete writes delivered: 2 for the Ink-safe text+Enter split, 1 when combined or enter=false. */
+    writes: number;
+    /** For the tmux / AppleScript backends (or any dryRun), the spec(s) that ran / would run. */
+    specs?: LaunchSpec[];
+    error?: string;
+}
+/**
+ * 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: {
+    enter: boolean;
+    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>;