@phnx-labs/agents-cli 1.20.52 → 1.20.53

package/dist/lib/cloud/types.js

@@ -5,6 +5,87 @@
  * Factory) implement, plus the shared task and event types that flow through
  * the dispatch pipeline.
  */
+/**
+ * Normalize a provider's raw wire status into the canonical `CloudTaskStatus`.
+ *
+ * Each cloud backend speaks its own status vocabulary and had its own copy of
+ * this mapping, which had drifted. This dispatches per provider while keeping
+ * provider-specific defaults explicit:
+ *   - `rush`        — switch over the Factory Floor's known strings; includes
+ *                     `allocating` and stopped/resumable `idle` states, has no
+ *                     `queued`, default `running`.
+ *   - `codex`       — substring match on the lowercased CLI status; default
+ *                     `running`.
+ *   - `antigravity` — substring match on the (possibly `undefined`) Interactions
+ *                     API status; default `completed` (its synchronous response
+ *                     is terminal), and `undefined`-safe.
+ *
+ * Factory's `mapResultStatus` is structurally different (it maps a droid *exit*
+ * result, not a lifecycle string) and deliberately stays in `factory.ts`.
+ */
+export function normalizeProviderStatus(provider, wireStatus) {
+    switch (provider) {
+        case 'rush':
+            return normalizeRushStatus(wireStatus ?? '');
+        case 'codex':
+            return normalizeCodexStatus(wireStatus ?? '');
+        case 'antigravity':
+            return normalizeAntigravityStatus(wireStatus);
+    }
+}
+/** Rush Factory Floor status → canonical enum. Default `running`; no `queued`. */
+function normalizeRushStatus(s) {
+    switch (s) {
+        case 'allocating': return 'allocating';
+        case 'running': return 'running';
+        case 'idle':
+        case 'paused':
+        case 'needs_review': return 'idle';
+        case 'input_required': return 'input_required';
+        case 'completed': return 'completed';
+        case 'failed': return 'failed';
+        case 'cancelled': return 'cancelled';
+        default: return 'running';
+    }
+}
+/** Codex Cloud CLI status → canonical enum. Substring match; default `running`. */
+function normalizeCodexStatus(s) {
+    const lower = s.toLowerCase();
+    if (lower.includes('queued') || lower.includes('pending'))
+        return 'queued';
+    if (lower.includes('running') || lower.includes('in_progress'))
+        return 'running';
+    if (lower.includes('idle') || lower.includes('paused') || lower.includes('needs_review'))
+        return 'idle';
+    if (lower.includes('completed') || lower.includes('succeeded') || lower.includes('success'))
+        return 'completed';
+    if (lower.includes('failed') || lower.includes('error'))
+        return 'failed';
+    if (lower.includes('cancelled') || lower.includes('canceled'))
+        return 'cancelled';
+    return 'running';
+}
+/**
+ * Antigravity Interactions API status → canonical enum. Substring match,
+ * `undefined`-safe; default `completed` because the synchronous response is
+ * already terminal.
+ */
+function normalizeAntigravityStatus(s) {
+    const lower = (s ?? '').toLowerCase();
+    if (lower.includes('queue') || lower.includes('pending'))
+        return 'queued';
+    if (lower.includes('run') || lower.includes('progress'))
+        return 'running';
+    if (lower.includes('idle') || lower.includes('paused') || lower.includes('needs_review'))
+        return 'idle';
+    if (lower.includes('complete') || lower.includes('success'))
+        return 'completed';
+    if (lower.includes('fail') || lower.includes('error'))
+        return 'failed';
+    if (lower.includes('cancel'))
+        return 'cancelled';
+    return 'completed';
+}
 /** Maximum images allowed per dispatch (matches Cursor Background Agents). */
 export const MAX_IMAGES_PER_DISPATCH = 5;
 /**

package/dist/lib/crabbox/cli.d.ts

@@ -62,7 +62,7 @@ export interface WarmupOptions extends CrabboxOptions {
  * created even if warmup's stdout format changes — the new lease id is the one
  * that wasn't present before.
  */
-export declare function crabboxWarmup(opts?: WarmupOptions): CrabboxBox;
+export declare function crabboxWarmup(opts?: WarmupOptions): Promise<CrabboxBox>;
 /**
  * Poll until the box reports ready, or throw after timeoutMs.
  * `sleep` is injectable so tests don't wall-clock wait.

package/dist/lib/crabbox/cli.js

@@ -87,7 +87,7 @@ export function crabboxFind(slug, opts = {}) {
  * created even if warmup's stdout format changes — the new lease id is the one
  * that wasn't present before.
  */
-export function crabboxWarmup(opts = {}) {
+export async function crabboxWarmup(opts = {}) {
     findCrabbox();
     const env = crabboxEnv(opts);
     const before = new Set(crabboxList(opts).map((b) => b.lease));
@@ -100,7 +100,17 @@ export function crabboxWarmup(opts = {}) {
         args.push('--provider', opts.provider);
     if (opts.code)
         args.push('--code');
-    const r = spawnSync('crabbox', args, { encoding: 'utf-8', env, stdio: ['ignore', 'pipe', 'pipe'] });
+    // Async spawn (not spawnSync): provisioning takes 30-90s and a blocking call
+    // would freeze any caller's progress spinner. Output is captured, not streamed.
+    const r = await new Promise((resolve) => {
+        const proc = spawn('crabbox', args, { env, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        proc.stdout.on('data', (c) => (stdout += c.toString('utf-8')));
+        proc.stderr.on('data', (c) => (stderr += c.toString('utf-8')));
+        proc.on('error', () => resolve({ status: null, stdout, stderr }));
+        proc.on('close', (code) => resolve({ status: code, stdout, stderr }));
+    });
     if (r.status !== 0) {
         const detail = (r.stderr || r.stdout || '').trim();
         throw new Error(`crabbox warmup failed: ${detail || 'unknown error'}. ` +

package/dist/lib/crabbox/lease.d.ts

@@ -9,6 +9,17 @@
 import type { AgentId } from '../types.js';
 import { type CrabboxBox } from './cli.js';
 import { type DetectedRuntime } from './runtimes.js';
+/** Phase signal for a lease run, so the command layer can drive a progress UI. */
+export type LeasePhase = {
+    kind: 'warmup';
+    backend?: string;
+} | {
+    kind: 'ready';
+    box: CrabboxBox;
+    elapsedMs: number;
+} | {
+    kind: 'teardown';
+};
 export interface LeaseRunOptions {
     agent: string;
     prompt: string;
@@ -24,6 +35,8 @@ export interface LeaseRunOptions {
     /** Secrets bundle providing crabbox's provider token. */
     secretsBundle?: string;
     onData?: (s: string) => void;
+    /** Progress phases (warmup → ready → teardown) for a command-layer spinner. */
+    onPhase?: (phase: LeasePhase) => void;
     /** Keep the box after the run instead of stopping it. */
     keep?: boolean;
     /**

package/dist/lib/crabbox/lease.js

@@ -8,6 +8,7 @@
  */
 import { crabboxWarmup, crabboxWaitReady, crabboxRunScript, crabboxStop } from './cli.js';
 import { buildCredentialScript, CLAUDE_TOKEN_REMOTE } from './runtimes.js';
+import { LEASE_AGENT_MARKER } from './progress.js';
 /** POSIX single-quote for safe embedding in the generated bootstrap script. */
 function q(s) {
     return "'" + s.replace(/'/g, "'\\''") + "'";
@@ -68,6 +69,9 @@ export function buildBootstrapScript(opts) {
         ENSURE_AGENTS_CLI,
         installRuntimes,
         credScript,
+        // Marker on its own line: the command layer shows everything before this as
+        // setup progress and everything after (the agent's output) verbatim.
+        `echo ${q(LEASE_AGENT_MARKER)}`,
         `${runParts.join(' ')}`,
         'rc=$?',
         shred,
@@ -77,13 +81,16 @@ export function buildBootstrapScript(opts) {
         .join('\n');
 }
 export async function leaseAndRun(opts) {
-    const box = crabboxWarmup({
+    const startedAt = Date.now();
+    opts.onPhase?.({ kind: 'warmup', backend: opts.backend });
+    const box = await crabboxWarmup({
         class: opts.boxClass,
         profile: opts.profile,
         provider: opts.backend,
         secretsBundle: opts.secretsBundle,
     });
     await crabboxWaitReady(box.slug, { secretsBundle: opts.secretsBundle });
+    opts.onPhase?.({ kind: 'ready', box, elapsedMs: Date.now() - startedAt });
     const script = buildBootstrapScript(opts);
     let exitCode = null;
     let toreDown = false;
@@ -96,8 +103,10 @@ export async function leaseAndRun(opts) {
     finally {
         // Always attempt teardown (bounds credential lifetime to the run) unless the
         // caller explicitly asked to keep the box.
-        if (!opts.keep)
+        if (!opts.keep) {
+            opts.onPhase?.({ kind: 'teardown' });
             toreDown = crabboxStop(box.slug, { secretsBundle: opts.secretsBundle });
+        }
     }
     return { box, exitCode, toreDown };
 }

package/dist/lib/crabbox/progress.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Progress routing for `agents run --lease`.
+ *
+ * The box-side bootstrap emits `LEASE_AGENT_MARKER` on its own line right before
+ * `agents run`. Everything the crabbox run streams BEFORE that marker is setup
+ * noise (sync bytes, node/agents install, `agents setup`) — shown as spinner
+ * text and captured for a failure dump. Everything AFTER is the agent's own
+ * output — printed through verbatim. The marker line itself is swallowed.
+ */
+/** Sentinel echoed on the box right before `agents run`. Distinctive + collision-proof. */
+export declare const LEASE_AGENT_MARKER = "___AGENTS_LEASE_AGENT_OUTPUT_b1f4c2___";
+export interface Spinner {
+    /** Begin animating a phase (renders `frame text` on one line, TTY only). */
+    start(text: string): void;
+    /** Change the text shown; rendered on the next throttled tick (no write itself). */
+    update(text: string): void;
+    /** Finalize the current line with a symbol (e.g. ✔) and a newline. */
+    stopAndPersist(symbol: string, text: string): void;
+    /** Clear the current animated line without persisting anything. */
+    stop(): void;
+    /** True while a phase is active. */
+    readonly active: boolean;
+}
+/**
+ * A deliberately minimal, self-throttled spinner. Unlike `ora`, it does NOT hook
+ * the stream's `write` to re-render on external output — it writes exactly one
+ * short line per fixed tick and nowhere else, so it is structurally incapable of
+ * a re-render feedback loop (the failure mode that made `ora` blow up when a
+ * lease streamed output past a live spinner). On a non-TTY it prints each phase
+ * label once and stays silent on `update`, so piped/CI output never floods.
+ *
+ * Only ever run ONE phase at a time, and never stream other output to the same
+ * stream while a phase is active — stop it first.
+ */
+export declare function createSpinner(opts?: {
+    stream?: {
+        write(s: string): unknown;
+        isTTY?: boolean;
+    };
+    enabled?: boolean;
+    intervalMs?: number;
+}): Spinner;
+export interface LeaseOutputRouter {
+    /** Feed a raw chunk of the crabbox run's combined stdout/stderr. */
+    push(chunk: string): void;
+    /** Flush any buffered partial line (call once the stream closes). */
+    end(): void;
+    /** True once the agent-output marker has been seen. */
+    sawAgent(): boolean;
+    /** The setup lines seen so far (for a failure dump). */
+    setupLines(): string[];
+}
+/**
+ * Split the crabbox run stream at `LEASE_AGENT_MARKER`. `onSetupLine` fires for
+ * each complete non-empty line before the marker; `onAgentChunk` fires with raw
+ * text after it (streamed promptly, not line-buffered, so agent output is live).
+ */
+export declare function createLeaseOutputRouter(cb: {
+    onSetupLine: (line: string) => void;
+    onAgentChunk: (chunk: string) => void;
+    marker?: string;
+}): LeaseOutputRouter;

package/dist/lib/crabbox/progress.js

@@ -0,0 +1,129 @@
+/**
+ * Progress routing for `agents run --lease`.
+ *
+ * The box-side bootstrap emits `LEASE_AGENT_MARKER` on its own line right before
+ * `agents run`. Everything the crabbox run streams BEFORE that marker is setup
+ * noise (sync bytes, node/agents install, `agents setup`) — shown as spinner
+ * text and captured for a failure dump. Everything AFTER is the agent's own
+ * output — printed through verbatim. The marker line itself is swallowed.
+ */
+/** Sentinel echoed on the box right before `agents run`. Distinctive + collision-proof. */
+export const LEASE_AGENT_MARKER = '___AGENTS_LEASE_AGENT_OUTPUT_b1f4c2___';
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+/**
+ * A deliberately minimal, self-throttled spinner. Unlike `ora`, it does NOT hook
+ * the stream's `write` to re-render on external output — it writes exactly one
+ * short line per fixed tick and nowhere else, so it is structurally incapable of
+ * a re-render feedback loop (the failure mode that made `ora` blow up when a
+ * lease streamed output past a live spinner). On a non-TTY it prints each phase
+ * label once and stays silent on `update`, so piped/CI output never floods.
+ *
+ * Only ever run ONE phase at a time, and never stream other output to the same
+ * stream while a phase is active — stop it first.
+ */
+export function createSpinner(opts = {}) {
+    const stream = opts.stream ?? process.stderr;
+    const enabled = opts.enabled ?? !!stream.isTTY;
+    const intervalMs = opts.intervalMs ?? 120;
+    const CLEAR = '\r\u001b[2K';
+    let text = '';
+    let frame = 0;
+    let timer;
+    let running = false;
+    const write = (s) => stream.write(s);
+    return {
+        start(t) {
+            text = t;
+            running = true;
+            if (!enabled) {
+                write(`${t}\n`);
+                return;
+            }
+            if (timer)
+                return;
+            frame = 0;
+            write(`${CLEAR}${SPINNER_FRAMES[0]} ${text}`);
+            timer = setInterval(() => {
+                frame = (frame + 1) % SPINNER_FRAMES.length;
+                write(`${CLEAR}${SPINNER_FRAMES[frame]} ${text}`);
+            }, intervalMs);
+        },
+        update(t) {
+            text = t; // next tick renders it; on a non-TTY we stay silent (no flood)
+        },
+        stopAndPersist(symbol, t) {
+            if (timer) {
+                clearInterval(timer);
+                timer = undefined;
+            }
+            running = false;
+            write(enabled ? `${CLEAR}${symbol} ${t}\n` : `${symbol} ${t}\n`);
+        },
+        stop() {
+            if (timer) {
+                clearInterval(timer);
+                timer = undefined;
+                if (enabled)
+                    write(CLEAR);
+            }
+            running = false;
+        },
+        get active() {
+            return running;
+        },
+    };
+}
+/**
+ * Split the crabbox run stream at `LEASE_AGENT_MARKER`. `onSetupLine` fires for
+ * each complete non-empty line before the marker; `onAgentChunk` fires with raw
+ * text after it (streamed promptly, not line-buffered, so agent output is live).
+ */
+export function createLeaseOutputRouter(cb) {
+    const marker = cb.marker ?? LEASE_AGENT_MARKER;
+    let seen = false;
+    let buf = '';
+    const setup = [];
+    const emitLine = (line) => {
+        const t = line.replace(/\r$/, '');
+        if (t.trim()) {
+            setup.push(t);
+            cb.onSetupLine(t);
+        }
+    };
+    return {
+        push(chunk) {
+            if (seen) {
+                cb.onAgentChunk(chunk);
+                return;
+            }
+            buf += chunk;
+            let idx;
+            while ((idx = buf.indexOf('\n')) !== -1) {
+                const line = buf.slice(0, idx);
+                buf = buf.slice(idx + 1);
+                if (line.includes(marker)) {
+                    seen = true;
+                    // Anything already buffered past the marker is agent output.
+                    if (buf) {
+                        cb.onAgentChunk(buf);
+                        buf = '';
+                    }
+                    return;
+                }
+                emitLine(line);
+            }
+            // A trailing partial line stays in `buf` — it may be the marker forming.
+        },
+        end() {
+            if (!seen && buf)
+                emitLine(buf);
+            buf = '';
+        },
+        sawAgent() {
+            return seen;
+        },
+        setupLines() {
+            return setup;
+        },
+    };
+}

package/dist/lib/events.js

@@ -22,9 +22,12 @@ import { getUserAgentsDir } from './state.js';
 // ─── Constants ────────────────────────────────────────────────────────────────
 // Resolved lazily: events.ts is imported transitively by most CLI surfaces, and
 // import itself must stay side-effect free. Tests may override the exact path.
+// AGENTS_EVENTS_PATH redirects the sink — a test seam like AGENTS_SECRETS_AGENT_DIR:
+// unlike _resetForTest it survives a bare reset AND propagates to CLI subprocesses
+// a test spawns, so fixture events can never land in the user's real log (#910).
 let _eventsPath;
 function eventsPath() {
-    return (_eventsPath ??= path.join(getUserAgentsDir(), 'events.jsonl'));
+    return (_eventsPath ??= process.env.AGENTS_EVENTS_PATH || path.join(getUserAgentsDir(), 'events.jsonl'));
 }
 function eventsDir() {
     return path.dirname(eventsPath());

package/dist/lib/exec.js

@@ -398,7 +398,10 @@ export const AGENT_COMMANDS = {
         modelFlag: '--model',
     },
     kiro: {
-        base: ['kiro-cli'],
+        // Standalone hooks live under ~/.kiro/hooks/*.json and only fire on the
+        // v3 engine (opt-in via --v3; see https://kiro.dev/docs/cli/v3/hooks/).
+        // Without this flag agents-cli would write v3 hook files that never run.
+        base: ['kiro-cli', '--v3'],
         promptFlag: 'positional',
         modeFlags: {
             // kiro-cli has no permission flags — edit is the default behavior.
@@ -471,6 +474,21 @@ export const AGENT_COMMANDS = {
         jsonFlags: ['-o', 'stream-json'],
         modelFlag: '-m',
     },
+    hermes: {
+        base: ['hermes', 'chat'],
+        promptFlag: 'positional',
+        modeFlags: {
+            edit: [],
+        },
+        modelFlag: '--model',
+    },
+    forge: {
+        base: ['forge'],
+        promptFlag: 'positional',
+        modeFlags: {
+            edit: [],
+        },
+    },
 };
 /**
  * Whether `agent` has a native resume form (Tier 1). Derived solely from the

package/dist/lib/feed-outcome.d.ts

@@ -0,0 +1,101 @@
+import type { OpenBlock } from './feed.js';
+export type OutcomeKind = 'ticket' | 'pr' | 'worktree' | 'unassigned';
+/** Stable attribution of a block (or agent) to one deliverable. */
+export interface OutcomeRef {
+    /** Map/JSON key, e.g. `ticket:RUSH-1125`, `pr:#534`, `worktree:headless-secrets`, `unassigned`. */
+    key: string;
+    kind: OutcomeKind;
+    /** Human header label, e.g. `RUSH-1125`, `PR#534`, `headless-secrets`, `Unassigned`. */
+    label: string;
+}
+/**
+ * Signals used to derive an outcome. All optional — callers pass whatever they
+ * already know (block fields, session meta, free-text questions).
+ */
+export interface OutcomeSignals {
+    ticket?: string | null;
+    pr?: string | null;
+    worktreeSlug?: string | null;
+    /** Branch name — scanned for `rush-1125`-style ticket slugs. */
+    branch?: string | null;
+    /** Epic / team label when no ticket/PR/worktree is known. */
+    epic?: string | null;
+    /** Free text (question headers + bodies) scanned for ticket/PR refs. */
+    text?: string | null;
+}
+/**
+ * Normalize a PR ref.
+ * - Full GitHub URL → `owner/repo#N` (repo identity included)
+ * - Bare `#123` / `PR#123` → `#123` (no repo known)
+ */
+export declare function normalizePrRef(raw: string | null | undefined): string | undefined;
+/** `https://github.com/owner/repo/pull/N` → `owner/repo`. */
+export declare function repoFromPrUrl(url: string | null | undefined): string | undefined;
+/** Canonical ticket id (uppercase team key). */
+export declare function normalizeTicketRef(raw: string | null | undefined): string | undefined;
+/**
+ * Derive the single outcome a block/agent belongs to.
+ * Exactly one outcome per call — never ambiguous, never empty.
+ */
+export declare function deriveOutcome(signals: OutcomeSignals): OutcomeRef;
+/** Join question headers + bodies into one scan target for ticket/PR detection. */
+export declare function blockScanText(block: Pick<OpenBlock, 'questions'>): string;
+/** Outcome for a stored open block (uses stamped fields + question text). */
+export declare function outcomeForBlock(block: OpenBlock): OutcomeRef;
+/** Per-outcome rollup used by the default `agents feed` view. */
+export interface OutcomeGroup {
+    outcome: OutcomeRef;
+    blocks: OpenBlock[];
+    counts: {
+        /** Distinct mailbox ids under this outcome. */
+        agents: number;
+        /** Still open: unanswered and not hard-parked. */
+        open: number;
+        answered: number;
+        parked: number;
+    };
+}
+/**
+ * Collapse blocks under their outcome. Order: needs-you outcomes first
+ * (open count desc), then by label. Unassigned always last among ties of 0 open.
+ */
+export declare function groupBlocksByOutcome(blocks: OpenBlock[]): OutcomeGroup[];
+/**
+ * Stamp each block with its derived outcome for JSON consumers.
+ * Does not mutate the input records.
+ */
+export declare function stampBlockOutcomes(blocks: OpenBlock[]): Array<OpenBlock & {
+    outcome: OutcomeRef;
+}>;
+/**
+ * True when every still-open block under the outcome asks the same question
+ * (same cluster of header+text). Fan-out answers are only safe when this holds
+ * — otherwise the operator must pick a specific agent.
+ */
+export declare function isUnambiguousOutcomeAnswer(group: OutcomeGroup): boolean;
+/** Still-open blocks under an outcome (candidates for a fan-out reply). */
+export declare function openBlocksForOutcome(group: OutcomeGroup): OpenBlock[];
+/**
+ * Lightweight session signals used to fill missing ticket/PR/worktree on a
+ * block at list time (the publish hook may not have had them yet).
+ */
+export interface SessionOutcomeHint {
+    sessionId?: string | null;
+    agentId?: string | null;
+    mailboxId?: string | null;
+    ticketId?: string | null;
+    prNumber?: number | null;
+    prUrl?: string | null;
+    worktreeSlug?: string | null;
+    branch?: string | null;
+}
+/**
+ * Overlay session meta onto a block when the block itself is missing ticket/PR/
+ * worktree. Never overwrites a field the block already carries.
+ */
+export declare function enrichBlockFromSession(block: OpenBlock, hint: SessionOutcomeHint): OpenBlock;
+/**
+ * Build a mailboxId → session-hint index and enrich every block. Pure.
+ * Matching order: mailboxId, then sessionId, then agentId.
+ */
+export declare function enrichBlocksFromSessions(blocks: OpenBlock[], sessions: SessionOutcomeHint[]): OpenBlock[];