@phnx-labs/agents-cli 1.20.34 → 1.20.36

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

@@ -0,0 +1,18 @@
+/**
+ * Session → Terminal-Engine injection adapter.
+ *
+ * The Terminal Engine owns the injection primitive (`injectIntoTerminal`,
+ * src/lib/terminal/inject.ts). This thin adapter maps a session's provenance
+ * `ReplyRail` (the addressable terminal the feed already derives — provenance.ts:47)
+ * to the engine's `InjectTarget`, so a caller can go session → keystrokes in one
+ * hop. Kept on the session side because `ReplyRail` is a session concept; the
+ * engine stays agnostic of how a target was discovered.
+ */
+import type { ReplyRail } from './provenance.js';
+import type { InjectTarget } from '../terminal/inject.js';
+/**
+ * Map a session's `ReplyRail` to an engine `InjectTarget`. Today only tmux rails
+ * are externally addressable (provenance.ts:143-149); a null rail yields null and
+ * the caller must supply a target another way (a pty id, a macOS window).
+ */
+export declare function injectTargetFromReplyRail(rail: ReplyRail): InjectTarget | null;

package/dist/lib/session/inject.js

@@ -0,0 +1,21 @@
+/**
+ * Session → Terminal-Engine injection adapter.
+ *
+ * The Terminal Engine owns the injection primitive (`injectIntoTerminal`,
+ * src/lib/terminal/inject.ts). This thin adapter maps a session's provenance
+ * `ReplyRail` (the addressable terminal the feed already derives — provenance.ts:47)
+ * to the engine's `InjectTarget`, so a caller can go session → keystrokes in one
+ * hop. Kept on the session side because `ReplyRail` is a session concept; the
+ * engine stays agnostic of how a target was discovered.
+ */
+/**
+ * Map a session's `ReplyRail` to an engine `InjectTarget`. Today only tmux rails
+ * are externally addressable (provenance.ts:143-149); a null rail yields null and
+ * the caller must supply a target another way (a pty id, a macOS window).
+ */
+export function injectTargetFromReplyRail(rail) {
+    if (rail && rail.rail === 'tmux') {
+        return { backend: 'tmux', pane: rail.target, socket: rail.socket };
+    }
+    return null;
+}

package/dist/lib/session/parse.d.ts

@@ -50,6 +50,12 @@ export declare function parseCodex(filePath: string): SessionEvent[];
 export declare function parseCodexContent(content: string): SessionEvent[];
 /** Parse a Gemini JSON session file into normalized events. */
 export declare function parseGemini(filePath: string): SessionEvent[];
+/**
+ * Parse an Antigravity conversation SQLite DB into normalized tool_use events.
+ * Deduped by the tool-call id so each tool appears once (Antigravity writes a
+ * request step and a completion step that share the id).
+ */
+export declare function parseAntigravity(dbPath: string): SessionEvent[];
 /**
  * Parse an OpenCode session from its SQLite database.
  * filePath format: "/path/to/opencode.db#session_id"

package/dist/lib/session/parse.js

@@ -8,6 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
+import Database from '../sqlite.js';
 /**
  * Largest session file we will load into memory. Above this we throw a clean
  * error instead of OOMing or hitting V8's ERR_STRING_TOO_LONG. Aligns with
@@ -96,6 +97,9 @@ export function parseSession(filePath, agent) {
         case 'gemini':
             events = parseGemini(filePath);
             break;
+        case 'antigravity':
+            events = parseAntigravity(filePath);
+            break;
         case 'opencode':
             events = parseOpenCode(filePath);
             break;
@@ -131,6 +135,12 @@ export function detectAgent(filePath) {
         return 'claude';
     if (filePath.includes('/.codex/') || filePath.includes('\\.codex\\'))
         return 'codex';
+    // Antigravity lives under ~/.gemini/antigravity-cli/conversations/<uuid>.db, so
+    // it must be matched BEFORE the generic /.gemini/ check below or it would be
+    // misdetected as Gemini.
+    if ((filePath.includes('/antigravity-cli/conversations/') || filePath.includes('\\antigravity-cli\\conversations\\'))
+        && filePath.endsWith('.db'))
+        return 'antigravity';
     if (filePath.includes('/.gemini/') || filePath.includes('\\.gemini\\'))
         return 'gemini';
     if (filePath.includes('/.grok/') || filePath.includes('\\.grok\\'))
@@ -178,6 +188,11 @@ export function summarizeToolUse(tool, args) {
         case 'WebSearch':
         case 'WebFetch':
             return `${tool}: ${truncate(args.query || args.url || '', 80)}`;
+        // Codex plan tool: arrives as a function_call with {plan:[{step,status}]}.
+        case 'update_plan': {
+            const steps = Array.isArray(args.plan) ? args.plan.length : 0;
+            return `Plan: ${steps} step${steps === 1 ? '' : 's'}`;
+        }
         // Codex tools
         case 'exec_command':
             return `Bash: ${truncate(String(args.command || args.cmd || '').replace(/\n/g, ' ').trim(), 120)}`;
@@ -418,6 +433,16 @@ export function parseClaudeContent(content) {
 export function parseCodex(filePath) {
     return parseCodexContent(safeReadSessionFile(filePath));
 }
+/**
+ * Extract the target file path from a Codex apply_patch envelope. The patch body
+ * opens with `*** Begin Patch` and carries one or more file ops of the form
+ * `*** Update File: <path>` / `*** Add File: <path>` / `*** Delete File: <path>`.
+ * Returns the first file path found, or undefined for an unparseable body.
+ */
+function applyPatchTargetPath(input) {
+    const m = input.match(/^\*\*\* (?:Update|Add|Delete) File: (.+)$/m);
+    return m ? m[1].trim() : undefined;
+}
 /**
  * Parse Codex JSONL *content* (already read into a string) into normalized
  * events. Split from `parseCodex` so the tail reader can parse just the last
@@ -449,6 +474,23 @@ export function parseCodexContent(content) {
             });
             continue;
         }
+        if (lineType === 'event_msg') {
+            // Web search is reported out-of-band as event_msg (not response_item).
+            // The paired begin (`web_search_call`) has no query; only `web_search_end`
+            // carries the resolved query string, so we emit exactly one tool_use per
+            // search off the end event and ignore the begin to avoid duplicates.
+            if (payload.type === 'web_search_end') {
+                const query = typeof payload.query === 'string' ? payload.query : '';
+                events.push({
+                    type: 'tool_use',
+                    agent: 'codex',
+                    timestamp,
+                    tool: 'WebSearch',
+                    args: { query },
+                });
+            }
+            continue;
+        }
         if (lineType === 'response_item') {
             const ptype = payload.type;
             if (ptype === 'message') {
@@ -523,6 +565,45 @@ export function parseCodexContent(content) {
                 if (callId)
                     callMap.delete(callId);
             }
+            else if (ptype === 'custom_tool_call') {
+                // Codex edits arrive as custom_tool_call (apply_patch), NOT function_call.
+                const rawName = payload.name || 'unknown';
+                const input = typeof payload.input === 'string' ? payload.input : '';
+                const isApplyPatch = rawName === 'apply_patch';
+                const patchPath = isApplyPatch ? applyPatchTargetPath(input) : undefined;
+                // Normalize apply_patch to the shared Edit tool so it flows through
+                // artifact discovery (WRITE_TOOLS) and the Edit summarizer.
+                const tool = isApplyPatch ? 'Edit' : rawName;
+                const args = { input: input.length > 500 ? input.slice(0, 497) + '...' : input };
+                if (patchPath)
+                    args.file_path = patchPath;
+                const callId = payload.call_id || payload.id;
+                if (callId)
+                    callMap.set(callId, { name: tool, args });
+                events.push({
+                    type: 'tool_use',
+                    agent: 'codex',
+                    timestamp,
+                    tool,
+                    args,
+                    path: patchPath,
+                });
+            }
+            else if (ptype === 'custom_tool_call_output') {
+                const callId = payload.call_id || payload.id;
+                const callInfo = callId ? callMap.get(callId) : undefined;
+                const output = String(payload.output || '');
+                events.push({
+                    type: 'tool_result',
+                    agent: 'codex',
+                    timestamp,
+                    tool: callInfo?.name,
+                    success: true,
+                    output: output.length > 500 ? output.slice(0, 497) + '...' : output,
+                });
+                if (callId)
+                    callMap.delete(callId);
+            }
             else if (ptype === 'reasoning') {
                 // Codex reasoning -- try to get the readable summary
                 const summaries = payload.summary || [];
@@ -670,6 +751,206 @@ function extractGeminiContent(content) {
     }
     return '';
 }
+/** Read a base-128 varint from `b` at offset `i`; returns [value, nextOffset]. */
+function readVarint(b, i) {
+    let shift = 0;
+    let val = 0;
+    for (;;) {
+        const byte = b[i++];
+        val += (byte & 0x7f) * 2 ** shift;
+        if ((byte & 0x80) === 0)
+            break;
+        shift += 7;
+    }
+    return [val, i];
+}
+/** Decode a protobuf message into a flat list of fields (one nesting level). */
+function decodeProtoMessage(b) {
+    const out = [];
+    let i = 0;
+    while (i < b.length) {
+        let tag;
+        [tag, i] = readVarint(b, i);
+        const field = tag >>> 3;
+        const wire = tag & 7;
+        if (wire === 0) {
+            let v;
+            [v, i] = readVarint(b, i);
+            out.push({ field, wire, value: v });
+        }
+        else if (wire === 2) {
+            let len;
+            [len, i] = readVarint(b, i);
+            out.push({ field, wire, value: b.subarray(i, i + len) });
+            i += len;
+        }
+        else if (wire === 5) {
+            i += 4; // fixed32 — skipped
+            out.push({ field, wire, value: 0 });
+        }
+        else if (wire === 1) {
+            i += 8; // fixed64 — skipped
+            out.push({ field, wire, value: 0 });
+        }
+        else {
+            break; // unknown wire type — stop to avoid runaway reads
+        }
+    }
+    return out;
+}
+const ANTIGRAVITY_TEXT_DECODER = new TextDecoder('utf-8', { fatal: false });
+/**
+ * Recursively locate the tool-call node: the first sub-message that carries an
+ * f2 string tool-name AND an f3 JSON-args string. Also captures the f1 call id
+ * (used to dedupe the request + completion steps) and the f30/f31 human labels.
+ */
+function findAntigravityToolCall(fields) {
+    let id;
+    let name;
+    let argsJson;
+    let summary;
+    let action;
+    const subs = [];
+    for (const f of fields) {
+        if (f.wire !== 2)
+            continue;
+        const bytes = f.value;
+        const s = ANTIGRAVITY_TEXT_DECODER.decode(bytes);
+        if (f.field === 1 && !id && /^[a-z0-9]{4,16}$/.test(s))
+            id = s;
+        else if (f.field === 2 && !name && /^[a-z][a-z_]{2,30}$/.test(s))
+            name = s;
+        else if (f.field === 3 && !argsJson && s.startsWith('{') && s.includes('"toolAction"'))
+            argsJson = s;
+        else if (f.field === 30 && !summary)
+            summary = s;
+        else if (f.field === 31 && !action)
+            action = s;
+        else {
+            try {
+                subs.push(decodeProtoMessage(bytes));
+            }
+            catch {
+                /* not a nested message */
+            }
+        }
+    }
+    if (name && argsJson) {
+        let args = {};
+        try {
+            args = JSON.parse(argsJson);
+        }
+        catch {
+            args = { _raw: argsJson };
+        }
+        return { id, name, args, summary, action };
+    }
+    for (const sub of subs) {
+        const hit = findAntigravityToolCall(sub);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/**
+ * Map an Antigravity tool name onto the shared normalized vocabulary that the
+ * renderer already handles (so no render.ts changes are needed). Unknown tools
+ * pass through untouched (with their JSON args) so future tools are captured.
+ */
+const ANTIGRAVITY_TOOL_MAP = {
+    run_command: 'Bash',
+    view_file: 'Read',
+    read_file: 'Read',
+    list_dir: 'LS',
+    grep_search: 'Grep',
+    replace_file_content: 'Edit',
+    write_to_file: 'Write',
+    // Web tools surface identically once observed:
+    search_web: 'WebSearch',
+    read_url: 'WebFetch',
+    execute_url: 'WebFetch',
+};
+/**
+ * Parse an Antigravity conversation SQLite DB into normalized tool_use events.
+ * Deduped by the tool-call id so each tool appears once (Antigravity writes a
+ * request step and a completion step that share the id).
+ */
+export function parseAntigravity(dbPath) {
+    // Read the raw BLOB payloads through the node/bun SQLite wrapper (not the
+    // `sqlite3` CLI) so this works on every OS — the CLI is absent on Windows.
+    let rows;
+    let db;
+    try {
+        db = new Database(dbPath);
+        rows = db
+            .prepare('SELECT idx, step_type, step_payload FROM steps ORDER BY idx;')
+            .all();
+    }
+    catch {
+        /* DB not accessible, sqlite module unavailable, or query failed */
+        return [];
+    }
+    finally {
+        try {
+            db?.close();
+        }
+        catch {
+            /* best-effort close */
+        }
+    }
+    // Single timestamp for the whole session: the steps table carries no per-step
+    // time column, so fall back to the DB file's mtime for a stable, sortable value.
+    let timestamp = new Date().toISOString();
+    try {
+        timestamp = fs.statSync(dbPath).mtime.toISOString();
+    }
+    catch {
+        /* file vanished between query and stat — keep now() */
+    }
+    const events = [];
+    const seenCallIds = new Set();
+    for (const row of rows) {
+        const payload = row.step_payload;
+        // Both node:sqlite and bun:sqlite return a BLOB as a Uint8Array (Buffer is
+        // a subclass). NULL / non-blob payloads are skipped.
+        if (!(payload instanceof Uint8Array))
+            continue;
+        const bytes = payload;
+        let fields;
+        try {
+            fields = decodeProtoMessage(bytes);
+        }
+        catch {
+            continue;
+        }
+        const call = findAntigravityToolCall(fields);
+        if (!call)
+            continue;
+        // Dedupe: the request + completion steps of one tool share the f1 call id.
+        if (call.id) {
+            if (seenCallIds.has(call.id))
+                continue;
+            seenCallIds.add(call.id);
+        }
+        const norm = ANTIGRAVITY_TOOL_MAP[call.name] || call.name;
+        const a = call.args || {};
+        events.push({
+            type: 'tool_use',
+            agent: 'antigravity',
+            timestamp,
+            tool: norm,
+            args: a,
+            command: norm === 'Bash' ? a.CommandLine : undefined,
+            // Antigravity uses PascalCase arg keys; probe the known path-bearing ones.
+            path: a.AbsolutePath || a.TargetFile || a.DirectoryPath || a.SearchPath || undefined,
+            // Antigravity's own short human label — free, high quality. It surfaces
+            // either as the f30 string or (more reliably) as `toolSummary` inside the
+            // f3 JSON args.
+            content: call.summary || (typeof a.toolSummary === 'string' ? a.toolSummary : undefined) || undefined,
+        });
+    }
+    return events;
+}
 // ---------------------------------------------------------------------------
 // OpenCode parser
 // ---------------------------------------------------------------------------
@@ -1086,7 +1367,10 @@ export function parseKimi(filePath) {
                 const fn = event.function || {};
                 const toolName = typeof event.name === 'string' ? event.name : (fn.name || 'unknown');
                 let args = {};
-                if (typeof fn.arguments === 'string') {
+                if (event.args && typeof event.args === 'object') {
+                    args = event.args;
+                }
+                else if (typeof fn.arguments === 'string') {
                     try {
                         args = JSON.parse(fn.arguments);
                     }
@@ -1212,7 +1496,7 @@ export function parseDroid(filePath) {
                     tool: toolName,
                     args: toolInput,
                     path: toolInput.file_path || toolInput.path || undefined,
-                    command: toolName === 'Bash' ? toolInput.command : undefined,
+                    command: (toolName === 'Bash' || toolName === 'Execute') ? toolInput.command : undefined,
                 });
             }
             else if (block.type === 'tool_result') {

package/dist/lib/session/pid-registry.d.ts

@@ -0,0 +1,22 @@
+export interface PidSessionEntry {
+    pid: number;
+    agent: string;
+    /** The launch session id. Present for agents launched with a known id (Claude). */
+    sessionId?: string;
+    cwd?: string;
+    /**
+     * `$TMUX_PANE` at launch — stored for diagnostics and possible future
+     * disambiguation. NOT currently consulted on read: the listing path keys
+     * purely on pid (stale entries are pruned when the pid dies), so this is
+     * metadata, not an anti-collision key.
+     */
+    tmuxPane?: string;
+    startedAtMs: number;
+}
+export declare function extractSessionIdArg(args: string[]): string | undefined;
+/** Record a launched agent process. Never throws — the registry is an optimization. */
+export declare function writePidSessionEntry(entry: PidSessionEntry): void;
+/** Look up a live pid's recorded session. Returns undefined if absent/corrupt. */
+export declare function readPidSessionEntry(pid: number): PidSessionEntry | undefined;
+/** Remove entries whose pid is no longer alive. Best-effort housekeeping. */
+export declare function prunePidSessionRegistry(isAlive: (pid: number) => boolean): void;

package/dist/lib/session/pid-registry.js

@@ -0,0 +1,104 @@
+/**
+ * Per-PID session registry — the headless equivalent of the swarmify VS Code
+ * extension's `live-terminals.json`.
+ *
+ * On a machine with no terminal extension (a bare SSH/tmux host), the only way
+ * `ag sessions --active` can attribute a `ps`-discovered agent process to a
+ * session is to guess "newest .jsonl in the cwd" — which collapses N agents
+ * sharing one repo onto a single session (all rows show the same topic/id).
+ *
+ * `ag run` closes that gap by recording, at spawn time, one file per launched
+ * agent process keyed by its OS pid: the exact session id it was launched with
+ * (Claude is started with `--session-id <uuid>`, so the launcher knows it),
+ * plus agent/cwd/tmux pane. The active-sessions headless path reads it back for
+ * an exact pid -> session match instead of a heuristic.
+ *
+ * Best-effort throughout: a failed write or a corrupt file degrades to the old
+ * heuristic, never throws into the launch or the listing path.
+ */
+import fs from 'fs';
+import path from 'path';
+import { getTerminalsDir } from '../state.js';
+/**
+ * Pull an explicit `--session-id <uuid>` (or `--session-id=<uuid>`) out of a
+ * raw agent arg vector. The transparent shim forwards args untouched, but when
+ * a launcher (Claude Code background jobs, IDE harnesses) already names the
+ * session, recording it gives the same exact pid -> session mapping `ag run`
+ * gets from generating the id itself.
+ */
+const SESSION_ID_VALUE_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export function extractSessionIdArg(args) {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--session-id') {
+            const v = args[i + 1];
+            if (v && SESSION_ID_VALUE_RE.test(v))
+                return v;
+        }
+        else if (a.startsWith('--session-id=')) {
+            const v = a.slice('--session-id='.length);
+            if (SESSION_ID_VALUE_RE.test(v))
+                return v;
+        }
+    }
+    return undefined;
+}
+function pidRegistryDir() {
+    return path.join(getTerminalsDir(), 'by-pid');
+}
+function entryPath(pid) {
+    return path.join(pidRegistryDir(), `${pid}.json`);
+}
+/** Record a launched agent process. Never throws — the registry is an optimization. */
+export function writePidSessionEntry(entry) {
+    if (!entry.pid || entry.pid < 1)
+        return;
+    try {
+        fs.mkdirSync(pidRegistryDir(), { recursive: true });
+        fs.writeFileSync(entryPath(entry.pid), JSON.stringify(entry), 'utf8');
+    }
+    catch {
+        /* degrade to the newest-jsonl heuristic */
+    }
+}
+/** Look up a live pid's recorded session. Returns undefined if absent/corrupt. */
+export function readPidSessionEntry(pid) {
+    let raw;
+    try {
+        raw = fs.readFileSync(entryPath(pid), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && typeof parsed.pid === 'number') {
+            return parsed;
+        }
+    }
+    catch {
+        /* unparseable */
+    }
+    return undefined;
+}
+/** Remove entries whose pid is no longer alive. Best-effort housekeeping. */
+export function prunePidSessionRegistry(isAlive) {
+    let files;
+    try {
+        files = fs.readdirSync(pidRegistryDir()).filter(f => f.endsWith('.json'));
+    }
+    catch {
+        return;
+    }
+    for (const f of files) {
+        const pid = Number(f.slice(0, -'.json'.length));
+        if (!Number.isInteger(pid) || isAlive(pid))
+            continue;
+        try {
+            fs.unlinkSync(path.join(pidRegistryDir(), f));
+        }
+        catch {
+            /* raced with another writer/pruner */
+        }
+    }
+}

package/dist/lib/session/provenance.d.ts

@@ -13,11 +13,16 @@ export interface MuxLocation {
     /** screen session name from $STY, e.g. '12345.pts-0.host'. */
     session?: string;
 }
-/** How the feed can type back into a session, derived from rails that exist today. */
+/** How the feed can type back into a session, derived from env rails that exist today. */
 export type ReplyRail = {
     rail: 'tmux';
     target: string;
     socket?: string;
+}
+/** iTerm2 split addressed by its session UUID (the part of $ITERM_SESSION_ID after ':'). */
+ | {
+    rail: 'iterm';
+    session: string;
 } | null;
 export interface SessionProvenance {
     /** Machine the process runs on — os.hostname(). Drives HOSTS grouping. */
@@ -34,7 +39,14 @@ export interface SessionProvenance {
     reply: ReplyRail;
 }
 /** Env vars that carry provenance. Kept small so the macOS `ps` scan stays cheap. */
-export declare const PROVENANCE_ENV_KEYS: readonly ["SSH_CONNECTION", "SSH_TTY", "TMUX", "TMUX_PANE", "TERM_PROGRAM", "STY"];
+export declare const PROVENANCE_ENV_KEYS: readonly ["SSH_CONNECTION", "SSH_TTY", "TMUX", "TMUX_PANE", "TERM_PROGRAM", "STY", "ITERM_SESSION_ID"];
+/**
+ * Extract the iTerm2 session UUID from `$ITERM_SESSION_ID`, whose value is
+ * `w<window>t<tab>p<pane>:<UUID>` — the `:`-suffix is exactly what iTerm2's
+ * `id of session` returns, so it's the address for `tell session id …`. Returns
+ * undefined for an empty/absent value; tolerates a bare value with no `:`.
+ */
+export declare function parseItermSession(value?: string): string | undefined;
 /** Parse the NUL-separated body of /proc/<pid>/environ into a plain object. */
 export declare function parseProcEnviron(buf: string): Record<string, string>;
 /**

package/dist/lib/session/provenance.js

@@ -15,9 +15,22 @@
  * (gone, or owned by another uid) yields `undefined`, never a guess.
  *
  * `reply` is a read-only hint, not a send channel: it reports whether a rail
- * that can type back into this session exists today (tmux pane => addressable;
- * inherited/ignored stdin => null). The feed uses it to decide whether to show
- * a Send box. Actually delivering the keystrokes is Gap 2 (pty/tmux send-keys).
+ * that can type back into this session exists today and, if so, the exact
+ * address to type into. Two env-derived rails, in precedence order:
+ *
+ *   - tmux  — `$TMUX_PANE` (+ `$TMUX` socket): `tmux send-keys -t <pane>`. Works
+ *             inside ANY host app (a tmux pane can live under iTerm/Ghostty/VS
+ *             Code), so it wins whenever present.
+ *   - iterm — `$ITERM_SESSION_ID` (`w<n>t<n>p<n>:<UUID>`): the exact iTerm2
+ *             split, addressable by its session UUID via `tell session id …`
+ *             (focus-safe, no `activate`). Used when there's no tmux above it.
+ *
+ * Both are inherited env vars, so the split the agent lives in is recovered with
+ * zero cooperation from the agent. Inherited/ignored stdin with neither rail =>
+ * null (not env-addressable — resolution may still find an IDE rail off disk,
+ * see src/lib/terminal/resolve.ts). The feed uses `reply` to decide whether to
+ * show a Send box; the resolver turns it into a concrete inject target (Gap 2,
+ * src/lib/terminal/inject.ts).
  */
 import * as os from 'os';
 import { execFile } from 'child_process';
@@ -32,7 +45,20 @@ export const PROVENANCE_ENV_KEYS = [
     'TMUX_PANE',
     'TERM_PROGRAM',
     'STY',
+    'ITERM_SESSION_ID',
 ];
+/**
+ * Extract the iTerm2 session UUID from `$ITERM_SESSION_ID`, whose value is
+ * `w<window>t<tab>p<pane>:<UUID>` — the `:`-suffix is exactly what iTerm2's
+ * `id of session` returns, so it's the address for `tell session id …`. Returns
+ * undefined for an empty/absent value; tolerates a bare value with no `:`.
+ */
+export function parseItermSession(value) {
+    if (!value)
+        return undefined;
+    const uuid = value.includes(':') ? value.slice(value.lastIndexOf(':') + 1) : value;
+    return uuid.trim() || undefined;
+}
 /** Parse the NUL-separated body of /proc/<pid>/environ into a plain object. */
 export function parseProcEnviron(buf) {
     const env = {};
@@ -99,13 +125,18 @@ export function deriveProvenance(env, hostname) {
     else if (env.STY) {
         mux = { kind: 'screen', session: env.STY };
     }
-    // A tmux pane is the one rail that lets an external process type into an
-    // already-running interactive agent (`tmux send-keys -t <pane>`). Everything
-    // else (inherited stdin from `agents run`, ignored stdin from teams) is not
-    // externally addressable without relaunching under a pty/tmux rail.
+    // Env-addressable rails, in precedence order. A tmux pane wins because it can
+    // live inside any host app (`tmux send-keys -t <pane>` reaches it regardless of
+    // whether iTerm/Ghostty/VS Code is above it). Absent tmux, an iTerm2 split is
+    // addressable by its session UUID. Everything else (inherited stdin from
+    // `agents run`, ignored stdin from teams, a plain VS Code integrated terminal)
+    // is not env-addressable — the resolver may still find an IDE rail off disk.
+    const itermSession = parseItermSession(env.ITERM_SESSION_ID);
     const reply = mux?.kind === 'tmux' && mux.pane
         ? { rail: 'tmux', target: mux.pane, socket: mux.socket }
-        : null;
+        : itermSession
+            ? { rail: 'iterm', session: itermSession }
+            : null;
     return {
         host: hostname,
         transport: ssh ? 'ssh' : 'local',

package/dist/lib/session/remote-active.d.ts

@@ -0,0 +1,26 @@
+import type { ActiveSession } from './active.js';
+/**
+ * Recursion guard, passed as an env var (not a CLI flag) so an OLDER remote
+ * `agents` that predates this feature ignores it harmlessly instead of erroring
+ * on an unknown option. A remote new enough to fan out reads it and stays local.
+ */
+export declare const NO_FANOUT_ENV = "AGENTS_SESSIONS_LOCAL";
+/**
+ * Parse a peer's `--active --json` stdout into active sessions, tagging each
+ * with `machine`. Defensive against version skew / partial output: non-JSON or
+ * a non-array yields `[]`, and non-object entries are dropped rather than
+ * throwing. Exported for unit testing without a live tailnet.
+ */
+export declare function parseRemoteActive(stdout: string, machine: string): ActiveSession[];
+export interface RemoteActiveResult {
+    sessions: ActiveSession[];
+    /** How many peer machines we attempted to reach (drives the empty-fleet tip). */
+    deviceCount: number;
+}
+/**
+ * Gather active sessions from other machines. With an explicit `hosts` list
+ * (from `--host`), fan out to exactly those. Otherwise sweep the registered,
+ * online devices from `ag devices`, excluding this machine and any without an
+ * address. Results from all peers run in parallel and are flattened.
+ */
+export declare function gatherRemoteActive(hosts?: string[]): Promise<RemoteActiveResult>;