/**
 * 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.
 *   - 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;
    /**
     * Delivery is CONFIRMED to have reached the running agent, not merely dispatched.
     *
     * For tmux / iterm / ghostty / pty, `ok` already means delivered: `tmux
     * send-keys` errors on a missing pane, `osascript write text` errors on a bad
     * session id, and a pty write errors if the sidecar can't reach the fd — 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;
    /** For the tmux / AppleScript backends (or any dryRun), the spec(s) that ran / would run. */
    specs?: LaunchSpec[];
    error?: string;
}
/**
 * Whether a successful transport on this backend CONFIRMS delivery to the agent.
 * Everything but vscodium self-confirms (see InjectResult.confirmed); vscodium's
 * `--open-url` is fire-and-forget until the swarm-ext extension acks the verb.
 */
export declare function backendConfirmsDelivery(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: {
    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>;
