@phnx-labs/agents-cli 1.20.51 → 1.20.53

package/dist/lib/answer-router.js

@@ -0,0 +1,149 @@
+import { injectTargetFromReplyRail } from './session/inject.js';
+/**
+ * Match free-text answer against question options.
+ * Exact (case-insensitive) > startsWith > includes. Returns 0-based index or -1.
+ */
+export function matchOptionIndex(answer, options) {
+    if (!options?.length)
+        return -1;
+    const needle = answer.trim().toLowerCase();
+    if (!needle)
+        return -1;
+    const labels = options.map((o) => (o.label ?? '').trim());
+    const exact = labels.findIndex((l) => l.toLowerCase() === needle);
+    if (exact >= 0)
+        return exact;
+    const starts = labels.findIndex((l) => l.toLowerCase().startsWith(needle));
+    if (starts >= 0)
+        return starts;
+    const includes = labels.findIndex((l) => l.toLowerCase().includes(needle));
+    return includes;
+}
+/**
+ * Build the keystroke payload that closes an AskUserQuestion TUI.
+ * Numbered options are selected by digit (1-based) + Enter. Free text with an
+ * "Other" option selects Other then types; without Other, types the answer.
+ */
+export function keystrokesForAnswer(answer, options) {
+    const idx = matchOptionIndex(answer, options);
+    if (idx >= 0) {
+        // AskUserQuestion / plan select-lists are 1-indexed digits.
+        return { payload: `${idx + 1}`, matched: 'option' };
+    }
+    if (options?.length) {
+        const otherIdx = options.findIndex((o) => /^other$/i.test((o.label ?? '').trim()));
+        if (otherIdx >= 0) {
+            // Select Other, then type the free text on the next field.
+            return { payload: `${otherIdx + 1}\n${answer}`, matched: 'other' };
+        }
+    }
+    return { payload: answer, matched: 'free-text' };
+}
+/** True when the session is waiting on user input (parked on a question/plan). */
+export function isParkedOnInput(session) {
+    if (!session)
+        return false;
+    if (session.status === 'input_required')
+        return true;
+    if (session.activity === 'waiting_input')
+        return true;
+    if (session.awaitingReason === 'question' || session.awaitingReason === 'plan_review' || session.awaitingReason === 'permission') {
+        return true;
+    }
+    return false;
+}
+/** True when an open feed block still needs an answer. */
+export function isOpenQuestionBlock(block) {
+    if (!block)
+        return false;
+    if (block.answer || block.parkedAt || block.continuedAt || block.defaultedAt)
+        return false;
+    return (block.questions?.length ?? 0) > 0;
+}
+function injectTargetForSession(session) {
+    if (session.provenance?.reply) {
+        const fromRail = injectTargetFromReplyRail(session.provenance.reply);
+        if (fromRail)
+            return fromRail;
+    }
+    // Only the agents-pty sidecar is addressable by session id. Generic headless
+    // runs have no PTY server entry — those go through resume, not inject.
+    if (session.sessionId && session.host === 'pty') {
+        return { backend: 'pty', id: session.sessionId };
+    }
+    return null;
+}
+/**
+ * Pick the delivery mechanism for one answer.
+ *
+ * Precedence:
+ *   1. Parked on open question + injectable rail (tmux/iterm/pty) → keystroke
+ *   2. Parked on open question + headless (no rail) → resume with answer
+ *   3. Parked on open question + no rail + interactive → refuse (don't mailbox-drop)
+ *   4. Otherwise → mailbox (running agent between tool calls)
+ */
+export function resolveAnswerRoute(input) {
+    const { answer, block, session } = input;
+    const openQ = isOpenQuestionBlock(block);
+    const parked = isParkedOnInput(session);
+    // Options from the first question on the block (or the session's structured question).
+    const options = block?.questions?.[0]?.options ??
+        session?.question?.options?.map((o) => ({ label: o.label }));
+    if (openQ && parked && session) {
+        const inject = injectTargetForSession(session);
+        const { payload, matched } = keystrokesForAnswer(answer, options);
+        if (inject) {
+            const kind = inject.backend === 'tmux' ? 'tmux'
+                : inject.backend === 'iterm' ? 'iterm'
+                    : inject.backend === 'pty' ? 'pty'
+                        : 'pty';
+            return {
+                kind,
+                reason: `Parked on open question — drive ${inject.backend} selection (${matched}).`,
+                payload,
+                inject,
+            };
+        }
+        // Headless / no rail: re-enter via resume.
+        if (session.context === 'headless' || session.context === 'teams' || !session.tty) {
+            const sid = session.sessionId ?? input.mailboxId;
+            if (!sid) {
+                return {
+                    kind: 'refuse',
+                    reason: 'Parked headless agent has no session id to resume.',
+                };
+            }
+            return {
+                kind: 'resume',
+                reason: 'Parked headless agent — resume with the answer as the next user turn.',
+                payload: answer,
+                resume: { sessionId: sid, agent: session.kind },
+            };
+        }
+        return {
+            kind: 'refuse',
+            reason: 'Agent is parked on a question but has no addressable terminal (no tmux/iterm/pty rail). ' +
+                'Open its terminal and answer there, or run `agents sessions focus <id>` first.',
+        };
+    }
+    // Open block but agent is still looping between tool calls — mailbox is correct.
+    // No block — free-form mid-flight steer — mailbox.
+    return {
+        kind: 'mailbox',
+        reason: openQ
+            ? 'Open block on a running agent — deliver via mailbox at next tool call.'
+            : 'No open question — deliver via mailbox at next tool call.',
+        payload: answer,
+    };
+}
+/** Build argv for a headless resume that continues with the answer text. */
+export function resumeArgv(route) {
+    if (route.kind !== 'resume' || !route.resume) {
+        throw new Error('resumeArgv requires a resume route');
+    }
+    const { agent, sessionId } = route.resume;
+    const text = route.payload ?? '';
+    // `agents run <agent> --resume <id> -- <answer>` — the trailing prompt is the
+    // next user turn after native resume (claude/codex) or /continue replay.
+    return ['run', agent, '--resume', sessionId, '--', text];
+}

package/dist/lib/ask-classifier.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Ask classifier + stall suppression (RUSH-1477).
+ *
+ * ~39% of AskUserQuestion calls are workflow-stalls ("should I…?", "what's next?",
+ * "merge now?"). The feed's first job is to make those disappear so real Decisions
+ * and Approvals stay visible.
+ *
+ * Pipeline:
+ *   1. Classify every block into Decision / Approval / Clarification / Stall / Fyi
+ *   2. Suppress stalls (and pure FYIs) with an auto-answer so they never render
+ *   3. Surface Decision + Approval (+ Clarification when it needs a real fact)
+ *
+ * Rules-based on stable high-volume shapes. Pure classify/match; suppression has
+ * side effects via the feed store when applied.
+ */
+import type { OpenBlock } from './feed.js';
+/** Taxonomy for a published ask. Exactly one class per block. */
+export type AskClass = 'decision' | 'approval' | 'clarification' | 'stall' | 'fyi';
+export interface Classification {
+    class: AskClass;
+    /** Why this class was chosen (rule name). */
+    rule: string;
+    /** True when the feed should hide this block and auto-answer it. */
+    suppress: boolean;
+    /** Auto-answer text when suppress is true. */
+    autoAnswer?: string;
+}
+/** Scan text used for classification. */
+export declare function askScanText(block: Pick<OpenBlock, 'questions'>): string;
+/**
+ * Classify one ask from free text (+ optional explicit blockClass from the agent).
+ * Explicit blockClass from the agent is honored as a floor: 'decision' never becomes
+ * a suppressible stall (false-suppress rate ~0 for real Decisions).
+ */
+export declare function classifyAsk(text: string, opts?: {
+    header?: string;
+    blockClass?: OpenBlock['blockClass'];
+}): Classification;
+/** Classify a full open block (all questions concatenated). */
+export declare function classifyBlock(block: OpenBlock): Classification;
+export interface SuppressResult {
+    blockId: string;
+    class: AskClass;
+    rule: string;
+    autoAnswer: string;
+    /** True when the block was removed from the visible feed. */
+    suppressed: boolean;
+}
+/**
+ * Auto-answer + remove a suppressible block so it never renders as a card.
+ * Logs the stall as answered by policy:stall-suppression.
+ */
+export declare function suppressStallBlock(block: OpenBlock, root?: string): SuppressResult;
+export interface FeedFilterResult {
+    /** Blocks that should render as cards. */
+    surfaced: OpenBlock[];
+    /** Suppression audit rows (stalls auto-resolved). */
+    suppressed: SuppressResult[];
+    /** Per-class counts over the input set (before suppression). */
+    counts: Record<AskClass, number>;
+}
+/**
+ * Classify every block; optionally apply stall suppression (mutate store).
+ * When `apply` is false, only classifies (dry run for --json audit).
+ */
+export declare function filterBlocksForFeed(blocks: OpenBlock[], opts?: {
+    apply?: boolean;
+    root?: string;
+}): FeedFilterResult;
+/** Human digest: "31 stalls auto-resolved by policy". */
+export declare function suppressionDigest(result: FeedFilterResult): string;

package/dist/lib/ask-classifier.js

@@ -0,0 +1,197 @@
+import { recordAnswer, recordMessageReceipt, removeBlock } from './feed.js';
+import { enqueue, mailboxDir } from './mailbox.js';
+/** Scan text used for classification. */
+export function askScanText(block) {
+    return block.questions
+        .map((q) => [q.header, q.text].filter(Boolean).join(' '))
+        .join('\n')
+        .toLowerCase();
+}
+const RULES = [
+    // FYI / done — no action needed
+    {
+        name: 'fyi-done',
+        class: 'fyi',
+        suppress: true,
+        autoAnswer: 'acknowledged',
+        test: (t) => /\b(fyi|for your information|just letting you know|heads.?up|no action needed|already done|completed successfully)\b/.test(t) ||
+            /^(done|shipped|merged|complete)[.!]?$/.test(t.trim()),
+    },
+    // Stall: "should I / want me to / shall I continue"
+    {
+        name: 'stall-should-i',
+        class: 'stall',
+        suppress: true,
+        autoAnswer: 'Yes, continue.',
+        test: (t) => /\b(should i|shall i|want me to|would you like me to|do you want me to|can i go ahead|ok to proceed|okay to continue)\b/.test(t),
+    },
+    // Stall: "what's next / continue?"
+    {
+        name: 'stall-whats-next',
+        class: 'stall',
+        suppress: true,
+        autoAnswer: 'Continue with the next step.',
+        test: (t) => /\b(what('?s| is)? next|what now|continue\??|keep going\??|ready for the next|next step\??)\b/.test(t) ||
+            /^continue\??$/.test(t.trim()),
+    },
+    // Stall: verify-then-proceed / looks good?
+    {
+        name: 'stall-verify-proceed',
+        class: 'stall',
+        suppress: true,
+        autoAnswer: 'Looks good — proceed.',
+        test: (t) => /\b(looks good\??|does this look (ok|right|good)|sound good\??|ready to (go|ship|land)\??|any objections\??)\b/.test(t),
+    },
+    // Approval: merge/release/ship/commit yes-no (surfaces; policy can default later)
+    {
+        name: 'approval-merge-release',
+        class: 'approval',
+        suppress: false,
+        test: (t) => /\b(merge (now|this|the pr|it)\??|release\??|ship (it|now)\??|publish\??|cut (a )?release|tag (and )?release|commit (this|these changes)\??)\b/.test(t) ||
+            /\b(approve|deny|allow|reject)\b.*\b(merge|release|deploy|pr)\b/.test(t),
+    },
+    // Clarification: which X / which repo / pick one fact
+    {
+        name: 'clarification-which',
+        class: 'clarification',
+        suppress: false,
+        test: (t) => /\b(which (repo|branch|host|file|path|environment|env|project|package|version|account|device|machine)|what is the (path|url|id|name) of)\b/.test(t) ||
+            /\b(missing (the )?(path|url|id|name|repo)|need (the )?(path|url|id|repo) for)\b/.test(t),
+    },
+    // Decision: scope / approach / tradeoff (never auto-suppress)
+    {
+        name: 'decision-scope-approach',
+        class: 'decision',
+        suppress: false,
+        test: (t) => /\b(scope|approach|architecture|design|trade-?off|which approach|how should we|prefer A or B|option a or b)\b/.test(t) ||
+            /\b(break(ing)? change|public api|migrate everyone|rewrite)\b/.test(t),
+    },
+];
+/**
+ * Classify one ask from free text (+ optional explicit blockClass from the agent).
+ * Explicit blockClass from the agent is honored as a floor: 'decision' never becomes
+ * a suppressible stall (false-suppress rate ~0 for real Decisions).
+ */
+export function classifyAsk(text, opts) {
+    const scan = [opts?.header, text].filter(Boolean).join(' ').toLowerCase();
+    for (const rule of RULES) {
+        if (!rule.test(scan))
+            continue;
+        // Safety: agent-tagged decisions never suppress.
+        if (opts?.blockClass === 'decision' && rule.suppress) {
+            return { class: 'decision', rule: 'agent-blockClass-decision', suppress: false };
+        }
+        return {
+            class: rule.class,
+            rule: rule.name,
+            suppress: rule.suppress,
+            autoAnswer: rule.autoAnswer,
+        };
+    }
+    // Explicit agent tag with no text rule.
+    if (opts?.blockClass === 'decision') {
+        return { class: 'decision', rule: 'agent-blockClass-decision', suppress: false };
+    }
+    if (opts?.blockClass === 'approval') {
+        return { class: 'approval', rule: 'agent-blockClass-approval', suppress: false };
+    }
+    // Default: surface as decision so we never silent-drop unknowns.
+    return { class: 'decision', rule: 'default-decision', suppress: false };
+}
+/** Classify a full open block (all questions concatenated). */
+export function classifyBlock(block) {
+    const text = block.questions.map((q) => q.text).join(' ');
+    const header = block.questions.map((q) => q.header).filter(Boolean).join(' ');
+    return classifyAsk(text, { header, blockClass: block.blockClass });
+}
+/**
+ * Auto-answer + remove a suppressible block so it never renders as a card.
+ * Logs the stall as answered by policy:stall-suppression.
+ */
+export function suppressStallBlock(block, root) {
+    const c = classifyBlock(block);
+    if (!c.suppress || !c.autoAnswer) {
+        return { blockId: block.blockId, class: c.class, rule: c.rule, autoAnswer: '', suppressed: false };
+    }
+    const claim = recordAnswer(block.blockId, {
+        answeredFrom: 'policy',
+        answeredBy: 'stall-suppression',
+        operatorId: 'policy',
+        verified: true,
+    }, root);
+    if (!claim.ok) {
+        return { blockId: block.blockId, class: c.class, rule: c.rule, autoAnswer: c.autoAnswer, suppressed: false };
+    }
+    try {
+        // Mailbox lives under the global mailbox root (not the feed dir).
+        const msgId = enqueue(mailboxDir(block.mailboxId), {
+            to: block.mailboxId,
+            text: c.autoAnswer,
+            from: 'stall-suppression',
+            blockId: block.blockId,
+        });
+        recordMessageReceipt(block.blockId, { msgId, status: 'queued', at: new Date().toISOString(), from: 'stall-suppression' }, root);
+    }
+    catch {
+        // Mailbox write can fail if the box id is invalid; still drop the card.
+    }
+    removeBlock(block.blockId, root);
+    return {
+        blockId: block.blockId,
+        class: c.class,
+        rule: c.rule,
+        autoAnswer: c.autoAnswer,
+        suppressed: true,
+    };
+}
+/**
+ * Classify every block; optionally apply stall suppression (mutate store).
+ * When `apply` is false, only classifies (dry run for --json audit).
+ */
+export function filterBlocksForFeed(blocks, opts) {
+    const counts = {
+        decision: 0,
+        approval: 0,
+        clarification: 0,
+        stall: 0,
+        fyi: 0,
+    };
+    const surfaced = [];
+    const suppressed = [];
+    const apply = opts?.apply === true;
+    for (const block of blocks) {
+        const c = classifyBlock(block);
+        counts[c.class] += 1;
+        if (c.suppress) {
+            if (apply) {
+                const r = suppressStallBlock(block, opts?.root);
+                suppressed.push(r);
+                if (!r.suppressed)
+                    surfaced.push(block);
+            }
+            else {
+                suppressed.push({
+                    blockId: block.blockId,
+                    class: c.class,
+                    rule: c.rule,
+                    autoAnswer: c.autoAnswer ?? '',
+                    suppressed: false,
+                });
+            }
+        }
+        else {
+            surfaced.push(block);
+        }
+    }
+    return { surfaced, suppressed, counts };
+}
+/** Human digest: "31 stalls auto-resolved by policy". */
+export function suppressionDigest(result) {
+    const n = result.suppressed.filter((s) => s.suppressed || s.class === 'stall' || s.class === 'fyi').length;
+    if (n === 0)
+        return '';
+    const applied = result.suppressed.filter((s) => s.suppressed).length;
+    if (applied > 0)
+        return `${applied} stall${applied === 1 ? '' : 's'} auto-resolved by policy`;
+    return `${n} stall${n === 1 ? '' : 's'} eligible for suppression`;
+}

package/dist/lib/browser/login-detection.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Best-effort login-state detection for browser profiles.
+ *
+ * Reads a profile's Chromium cookie store (presence only — never decrypts the
+ * Keychain-encrypted values) to tell which login-gated services have a live
+ * session in that profile. Powers the `agents browser start` guardrail (warn
+ * when an agent opens a logged-out profile for a login-gated URL) and the
+ * `agents browser profiles logins` view.
+ *
+ * Everything here is advisory: any failure (missing DB, locked file, unknown
+ * schema) degrades to "no known session" and NEVER throws to callers — browser
+ * start must not slow down or break because cookie inspection hiccuped.
+ */
+/** A login-gated service signature: host substrings + the auth-cookie names
+ *  whose presence indicates a live session, plus optional login metadata. */
+interface ServiceSignature {
+    hosts: string[];
+    cookies: string[];
+    /**
+     * Where an interactive login for this service starts, and the bundle key
+     * PREFIX its credentials live under. By convention a profile's `--secrets`
+     * bundle holds `<PREFIX>_USERNAME` / `<PREFIX>_PASSWORD` (see
+     * `credKeysForService`). The prefix is explicit — never string-munged from the
+     * service id — so e.g. `x` → `X`, `google` → `GOOGLE`.
+     */
+    login?: {
+        loginUrl: string;
+        keyPrefix: string;
+    };
+}
+/**
+ * Known login-gated services. Presence of ANY listed cookie on a matching host
+ * (unexpired, or a session cookie) = logged in. Deliberately conservative: a
+ * service absent from this map simply never triggers a warning — we do not
+ * guess. Each cookie name here is the definitive authenticated-session token for
+ * that service (e.g. LinkedIn's `li_at` is only set for a signed-in member;
+ * visitor cookies like `bcookie`/`JSESSIONID` are NOT auth). Services whose
+ * session is not reliably expressed as a recognizable cookie (e.g. Attio, whose
+ * only same-site cookies are third-party analytics) are deliberately omitted so
+ * we never emit a false "logged out" warning. Extend as needed.
+ */
+export declare const AUTH_SIGNATURES: Record<string, ServiceSignature>;
+/**
+ * The bundle keys a profile's `--secrets` bundle should hold to log into
+ * `service`: `<PREFIX>_USERNAME` / `<PREFIX>_PASSWORD`. Null for services with no
+ * login metadata. Feed a resolved value to the page with
+ * `agents browser type <ref> --secret <bundle>/<KEY>` (never printed).
+ */
+export declare function credKeysForService(service: string): {
+    user: string;
+    pass: string;
+} | null;
+/** The interactive login URL for a service, or null. */
+export declare function loginUrlForService(service: string): string | null;
+export interface CookieRow {
+    host_key: string;
+    name: string;
+}
+/**
+ * Pure core: given a profile's (already expiry-filtered) cookie rows, return the
+ * services with a live session. Exported for direct unit testing without disk.
+ */
+export declare function detectServices(rows: CookieRow[]): string[];
+/** Map a URL to a known login-gated service key, or null. */
+export declare function serviceForUrl(url: string): string | null;
+/** A saved-login row from Chromium `Login Data` (username plaintext; password
+ *  encrypted and never read). */
+export interface LoginRow {
+    origin_url: string;
+    username_value: string;
+    signon_realm: string;
+}
+/**
+ * Map a profile's saved logins to service → account username (identity, not
+ * session). Best-effort; `{}` if `Login Data` is unreadable. The first non-empty
+ * username per service wins.
+ */
+export declare function accountsForProfile(profileName: string): Promise<Record<string, string>>;
+/**
+ * For each service with a LIVE session in the profile (cookie-gated), the
+ * account it is signed in as (from saved logins). Intersecting with live
+ * sessions means a stale saved-login for a service you've since logged out of
+ * never shows.
+ */
+export declare function loginsWithAccountsForProfile(profileName: string): Promise<Array<{
+    service: string;
+    username?: string;
+}>>;
+/** Services with a live session in the given profile (best-effort; [] if none
+ *  detected or the cookie store is unreadable). */
+export declare function loginsForProfile(profileName: string): Promise<string[]>;
+/** Profile names that have a live session for the given service. */
+export declare function profilesLoggedInto(service: string): Promise<string[]>;
+export {};