@phnx-labs/agents-cli 1.20.33 → 1.20.35

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

@@ -0,0 +1,69 @@
+/**
+ * Ghostty backend — drives Ghostty (>= 1.3) via AppleScript (`osascript`).
+ *
+ * Ghostty's `new surface configuration` record carries the working directory and
+ * command natively, so no `cd` wrapper is needed. Tab: `new tab` (or a window
+ * when none is open). Split: `split <surface> direction right|down`, where the
+ * current surface is `focused terminal of selected tab of front window`
+ * (verified against Ghostty 1.3.1 — a surface is a "terminal" in its AS model).
+ */
+import * as fs from 'fs';
+import { appleScriptStr } from '../quote.js';
+import { execOnly, iLoginShell } from '../shell.js';
+const GHOSTTY_APP = '/Applications/Ghostty.app';
+function appExists(p) {
+    try {
+        return fs.existsSync(p);
+    }
+    catch {
+        return false;
+    }
+}
+/** Shared prologue: activate + a surface configuration carrying cwd + command. */
+function configPrologue(cwd, command) {
+    const cmd = appleScriptStr(iLoginShell(execOnly(command)));
+    return [
+        'tell application "Ghostty"',
+        '  activate',
+        '  set cfg to new surface configuration',
+        `  set initial working directory of cfg to ${appleScriptStr(cwd)}`,
+        `  set command of cfg to ${cmd}`,
+    ];
+}
+/** AppleScript that opens a Ghostty tab (a window if none is open). */
+export function ghosttyTabScript(cwd, command) {
+    return [
+        ...configPrologue(cwd, command),
+        '  if (count of windows) is 0 then',
+        '    new window with configuration cfg',
+        '  else',
+        '    new tab in front window with configuration cfg',
+        '  end if',
+        'end tell',
+    ].join('\n');
+}
+/** AppleScript that splits the current Ghostty surface (a window if none is open). */
+export function ghosttySplitScript(cwd, command, direction) {
+    return [
+        ...configPrologue(cwd, command),
+        '  if (count of windows) is 0 then',
+        '    new window with configuration cfg',
+        '  else',
+        `    split (focused terminal of selected tab of front window) direction ${direction} with configuration cfg`,
+        '  end if',
+        'end tell',
+    ].join('\n');
+}
+export const ghosttyBackend = {
+    id: 'ghostty',
+    label: 'Ghostty',
+    isAvailable(ctx) {
+        return ctx.platform === 'darwin' && appExists(GHOSTTY_APP);
+    },
+    buildTab(cwd, command) {
+        return { argv: ['osascript', '-e', ghosttyTabScript(cwd, command)] };
+    },
+    buildSplit(cwd, command, direction) {
+        return { argv: ['osascript', '-e', ghosttySplitScript(cwd, command, direction)] };
+    },
+};

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

@@ -0,0 +1,18 @@
+/**
+ * Backend registry + current-terminal detection.
+ */
+import type { Backend, EngineContext, TerminalBackend } from '../types.js';
+import { itermBackend } from './iterm.js';
+import { ghosttyBackend } from './ghostty.js';
+import { tmuxBackend } from './tmux.js';
+/** All known interactive backends, keyed by id. */
+export declare const BACKENDS: Record<Backend, TerminalBackend>;
+/**
+ * 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 declare function detectCurrentBackend(ctx: EngineContext): Backend | null;
+/** Backends that can actually be driven in this context. */
+export declare function availableBackends(ctx: EngineContext): TerminalBackend[];
+export { itermBackend, ghosttyBackend, tmuxBackend };

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

@@ -0,0 +1,29 @@
+import { itermBackend } from './iterm.js';
+import { ghosttyBackend } from './ghostty.js';
+import { tmuxBackend } from './tmux.js';
+/** All known interactive backends, keyed by id. */
+export const BACKENDS = {
+    iterm: itermBackend,
+    ghostty: ghosttyBackend,
+    tmux: tmuxBackend,
+};
+/**
+ * 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 };

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/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,14 @@
+/**
+ * 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 } from './backends/index.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';

package/dist/lib/terminal/index.js

@@ -0,0 +1,5 @@
+export { currentContext } from './types.js';
+export { BACKENDS, detectCurrentBackend, availableBackends, itermBackend, ghosttyBackend, tmuxBackend } from './backends/index.js';
+export { planLayouts } from './policy.js';
+export { specForRequest, buildRequests, openSurface, openSurfaces, } from './engine.js';
+export { runLocal, runRemote, runSpec, remoteCommand } from './transport.js';

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

@@ -0,0 +1,11 @@
+/**
+ * Layout policy — how a batch of surfaces is arranged.
+ *
+ * `two-per-tab` (default) packs sessions two-up: session 1 opens a new tab,
+ * session 2 splits it (right), session 3 opens a new tab, and so on — so each
+ * tab holds a left+right pair. `tabs` gives every session its own tab.
+ */
+import type { Layout } from './types.js';
+export type Packing = 'two-per-tab' | 'tabs';
+/** Assign a layout to each index in a batch of `count` surfaces. */
+export declare function planLayouts(count: number, packing?: Packing): Layout[];

package/dist/lib/terminal/policy.js

@@ -0,0 +1,11 @@
+/** Assign a layout to each index in a batch of `count` surfaces. */
+export function planLayouts(count, packing = 'two-per-tab') {
+    const out = [];
+    for (let i = 0; i < count; i++) {
+        if (packing === 'tabs')
+            out.push('tab');
+        else
+            out.push(i % 2 === 0 ? 'tab' : 'split-right');
+    }
+    return out;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Quoting helpers for building launch commands.
+ *
+ * `shellQuote` is the single canonical POSIX single-quoter, re-exported from the
+ * SSH transport so the local and remote legs quote identically. `appleScriptStr`
+ * is the AppleScript string-literal escaper used by the iTerm/Ghostty backends.
+ */
+import { shellQuote } from '../ssh-exec.js';
+export { shellQuote };
+/** AppleScript double-quoted string literal (escape backslash, then quote). */
+export declare function appleScriptStr(s: string): string;

package/dist/lib/terminal/quote.js

@@ -0,0 +1,13 @@
+/**
+ * Quoting helpers for building launch commands.
+ *
+ * `shellQuote` is the single canonical POSIX single-quoter, re-exported from the
+ * SSH transport so the local and remote legs quote identically. `appleScriptStr`
+ * is the AppleScript string-literal escaper used by the iTerm/Ghostty backends.
+ */
+import { shellQuote } from '../ssh-exec.js';
+export { shellQuote };
+/** AppleScript double-quoted string literal (escape backslash, then quote). */
+export function appleScriptStr(s) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}

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

@@ -0,0 +1,6 @@
+/** `cd <cwd> && exec <command>` — for backends that don't set cwd natively. */
+export declare function loginExec(cwd: string, command: string[]): string;
+/** `exec <command>` — for backends that set the working directory natively. */
+export declare function execOnly(command: string[]): string;
+/** Wrap an inner shell script in an interactive login zsh: `zsh -ilc '<inner>'`. */
+export declare function iLoginShell(inner: string): string;

package/dist/lib/terminal/shell.js

@@ -0,0 +1,23 @@
+/**
+ * Interactive-login-shell wrappers shared by every backend.
+ *
+ * `-i` is load-bearing, not cosmetic: the version-pinned shims (e.g.
+ * `claude@2.1.187`) live in `~/.agents/.cache/shims`, which `.zshrc` puts on
+ * PATH for *interactive* shells only. A plain `zsh -lc` (login, non-interactive)
+ * skips `.zshrc`, so the shim isn't found and the surface dies with "command not
+ * found". Every backend wraps its command in `zsh -ilc` for this reason — do not
+ * drop the `-i`.
+ */
+import { shellQuote } from './quote.js';
+/** `cd <cwd> && exec <command>` — for backends that don't set cwd natively. */
+export function loginExec(cwd, command) {
+    return `cd ${shellQuote(cwd)} && exec ${command.join(' ')}`;
+}
+/** `exec <command>` — for backends that set the working directory natively. */
+export function execOnly(command) {
+    return `exec ${command.join(' ')}`;
+}
+/** Wrap an inner shell script in an interactive login zsh: `zsh -ilc '<inner>'`. */
+export function iLoginShell(inner) {
+    return `zsh -ilc ${shellQuote(inner)}`;
+}

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

@@ -0,0 +1,15 @@
+import type { LaunchSpec } from './types.js';
+/** Resolve a host alias to an ssh target. Default: identity (ssh_config resolves it). */
+export type HostResolver = (alias: string) => string;
+export interface RunResult {
+    ok: boolean;
+    error?: string;
+}
+/** Run the spec on this machine: spawn the launcher, resolve when it exits. */
+export declare function runLocal(spec: LaunchSpec): Promise<RunResult>;
+/** Serialize a launch argv into a single POSIX-quoted shell command string. */
+export declare function remoteCommand(spec: LaunchSpec): string;
+/** Run the spec on a remote host over SSH. */
+export declare function runRemote(spec: LaunchSpec, target: string): RunResult;
+/** Run a spec locally (no host / 'local') or on a resolved remote host. */
+export declare function runSpec(spec: LaunchSpec, host?: string, resolveHost?: HostResolver): Promise<RunResult>;

package/dist/lib/terminal/transport.js

@@ -0,0 +1,40 @@
+/**
+ * Transport — runs a LaunchSpec locally or on a remote host.
+ *
+ * Local: spawn the launcher (osascript / tmux) and wait for it to exit — these
+ * are short-lived commands that create the surface and return, so waiting gives
+ * a real success/failure. Remote: serialize the argv into one shell string and
+ * hand it to `sshExec` — the same hardened SSH primitive `agents sessions
+ * --host` and the browser driver use (target-injection guard, POSIX quoting,
+ * connection multiplexing).
+ */
+import { spawn } from 'child_process';
+import { sshExec } from '../ssh-exec.js';
+import { shellQuote } from './quote.js';
+/** Run the spec on this machine: spawn the launcher, resolve when it exits. */
+export function runLocal(spec) {
+    return new Promise((resolve) => {
+        const child = spawn(spec.argv[0], spec.argv.slice(1), { stdio: 'ignore' });
+        child.on('error', (err) => resolve({ ok: false, error: err.message }));
+        child.on('close', (code) => resolve(code === 0 ? { ok: true } : { ok: false, error: `${spec.argv[0]} exited with code ${code}` }));
+    });
+}
+/** Serialize a launch argv into a single POSIX-quoted shell command string. */
+export function remoteCommand(spec) {
+    return spec.argv.map(shellQuote).join(' ');
+}
+/** Run the spec on a remote host over SSH. */
+export function runRemote(spec, target) {
+    const res = sshExec(target, remoteCommand(spec), { multiplex: true });
+    if (res.code === 0)
+        return { ok: true };
+    const err = (res.stderr || '').trim();
+    return { ok: false, error: err || `ssh exited with code ${res.code}` };
+}
+/** Run a spec locally (no host / 'local') or on a resolved remote host. */
+export async function runSpec(spec, host, resolveHost) {
+    if (!host || host === 'local')
+        return runLocal(spec);
+    const target = resolveHost ? resolveHost(host) : host;
+    return runRemote(spec, target);
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Core types for the terminal launch engine.
+ *
+ * The engine opens an *interactive* surface — a tab or a split pane — running a
+ * command, in a chosen terminal backend (iTerm / Ghostty / tmux), on this
+ * machine or a remote host. This is distinct from cloud providers
+ * (src/lib/cloud), which dispatch autonomous headless tasks; a terminal surface
+ * is attended and live. See docs/terminal-engine.md.
+ */
+/** An interactive terminal backend the engine can drive. */
+export type Backend = 'iterm' | 'ghostty' | 'tmux';
+/** Which way a split pane grows. `right` = side-by-side; `down` = stacked. */
+export type SplitDirection = 'right' | 'down';
+/** Where a surface lands: a new tab, or a split of the current pane. */
+export type Layout = 'tab' | 'split-right' | 'split-down';
+/** Ambient facts a backend needs to decide availability and detection. */
+export interface EngineContext {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+}
+/** Snapshot the live process context. */
+export declare function currentContext(): EngineContext;
+/** The concrete OS command that opens a surface — the pure output of a backend. */
+export interface LaunchSpec {
+    /** argv to run (e.g. `['osascript','-e',script]` or `['tmux','split-window',…]`). */
+    argv: string[];
+}
+/** A single "open this command as this surface" instruction. */
+export interface LaunchRequest {
+    backend: Backend;
+    layout: Layout;
+    /** Working directory the command runs in. */
+    cwd: string;
+    /** argv to exec in the surface (e.g. a resume command). */
+    command: string[];
+    /** undefined / 'local' = this machine; otherwise a resolvable host alias. */
+    host?: string;
+}
+/** Outcome of opening one surface. Never throws for launch failures — reports them. */
+export interface LaunchResult {
+    ok: boolean;
+    request: LaunchRequest;
+    error?: string;
+}
+/**
+ * A terminal backend: pure builders + an availability check. No side effects —
+ * building a spec never opens anything, so every backend is unit-testable
+ * without a display. The engine's transport is what actually runs the spec.
+ */
+export interface TerminalBackend {
+    readonly id: Backend;
+    readonly label: string;
+    /** Can this backend be driven here? (platform + app installed / inside tmux). */
+    isAvailable(ctx: EngineContext): boolean;
+    /** Command that opens a new tab running `command` in `cwd`. */
+    buildTab(cwd: string, command: string[]): LaunchSpec;
+    /** Command that splits the current surface, running `command` in `cwd`. */
+    buildSplit(cwd: string, command: string[], direction: SplitDirection): LaunchSpec;
+}

package/dist/lib/terminal/types.js

@@ -0,0 +1,13 @@
+/**
+ * Core types for the terminal launch engine.
+ *
+ * The engine opens an *interactive* surface — a tab or a split pane — running a
+ * command, in a chosen terminal backend (iTerm / Ghostty / tmux), on this
+ * machine or a remote host. This is distinct from cloud providers
+ * (src/lib/cloud), which dispatch autonomous headless tasks; a terminal surface
+ * is attended and live. See docs/terminal-engine.md.
+ */
+/** Snapshot the live process context. */
+export function currentContext() {
+    return { platform: process.platform, env: process.env };
+}

package/dist/lib/types.d.ts

@@ -7,7 +7,7 @@
  */
 import type { CloudProviderId } from './cloud/types.js';
 /** Unique identifier for a supported AI coding agent. */
-export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'roo' | 'antigravity' | 'grok' | 'kimi' | 'droid';
+export type AgentId = 'claude' | 'codex' | 'gemini' | 'cursor' | 'opencode' | 'openclaw' | 'copilot' | 'amp' | 'kiro' | 'goose' | 'antigravity' | 'grok' | 'kimi' | 'droid';
 /** How `agents run <agent>` chooses an installed version when none is pinned. */
 export type RunStrategy = 'pinned' | 'available' | 'balanced';
 /** Per-agent run strategy config. */
@@ -86,6 +86,13 @@ export interface AgentConfig {
      */
     nativeCommandRuntime?: boolean;
     hooksDir: string;
+    /**
+     * Directory (relative to a plugin's install dir) the agent reads its plugin
+     * manifest from, when it differs from the canonical `.claude-plugin/`. Codex
+     * uses `.codex-plugin`, Droid `.factory-plugin`. Set to `.` when the agent
+     * reads the manifest from the plugin ROOT (Copilot). syncPluginToVersion
+     * mirrors `.claude-plugin/plugin.json` into this dir.
+     */
     pluginManifestDir?: string;
     instructionsFile: string;
     format: 'markdown' | 'toml';
@@ -99,6 +106,25 @@ export interface AgentConfig {
      * cloud and falls back to the configured default.
      */
     cloudProvider?: CloudProviderId;
+    /**
+     * Set when the upstream vendor has retired this agent's CLI. Presence marks
+     * the agent deprecated (it is never blocked from use); `warnAgentDeprecated`
+     * surfaces this in yellow whenever a user installs the agent or adds it to a
+     * team. Point `replacement` at the successor agent so the warning can suggest
+     * a migration path.
+     */
+    deprecated?: {
+        /** Vendor that retired it, e.g. "Google". */
+        by: string;
+        /** Human date it stopped working / was retired, e.g. "June 18, 2026". */
+        date: string;
+        /** One-line explanation shown under the warning header. */
+        reason: string;
+        /** Successor agent id to suggest instead (e.g. 'antigravity'). */
+        replacement?: AgentId;
+        /** Announcement URL for the deprecation. */
+        url?: string;
+    };
     capabilities: {
         hooks: Capability;
         mcp: Capability;

package/dist/lib/usage.d.ts

@@ -17,6 +17,7 @@ export interface UsageSnapshot {
     sourceLabel: string;
     capturedAt: Date | null;
     windows: UsageWindow[];
+    plan?: string | null;
 }
 /** Usage data plus any error encountered while fetching. */
 export interface UsageInfo {
@@ -122,6 +123,35 @@ export declare function deriveUsageStatusFromSnapshot(snapshot: UsageSnapshot |
 export declare function formatUsageStatusBadge(usageStatus: 'available' | 'rate_limited' | 'out_of_credits' | null | undefined): string;
 /** Format a multi-line usage section for detailed agent views. */
 export declare function formatUsageSection(usage: UsageInfo): string[];
+/** Raw quota bucket from the Kimi /usages response (numbers arrive as strings). */
+interface KimiUsageQuota {
+    limit?: string | number | null;
+    used?: string | number | null;
+    remaining?: string | number | null;
+    resetTime?: string | null;
+}
+/** Response shape from the Kimi Code /usages endpoint (subset we render). */
+export interface KimiUsagesResponse {
+    user?: {
+        userId?: string | null;
+        membership?: {
+            level?: string | null;
+        } | null;
+    } | null;
+    usage?: KimiUsageQuota | null;
+    limits?: Array<{
+        window?: {
+            duration?: number | null;
+            timeUnit?: string | null;
+        } | null;
+        detail?: KimiUsageQuota | null;
+    } | null> | null;
+    subType?: string | null;
+}
+/** Normalize the Kimi /usages payload into the common UsageWindow shape. */
+export declare function normalizeKimiWindows(data: KimiUsagesResponse): UsageWindow[];
+/** Derive a display plan label from Kimi's membership tier or subscription type. */
+export declare function formatKimiPlan(data: KimiUsagesResponse): string | null;
 /** Load Claude OAuth credentials from the system keychain/keyring. */
 export declare function loadClaudeOauth(home?: string): Promise<ClaudeOauthCredentials | null>;
 /**