@phnx-labs/agents-cli 1.20.51 → 1.20.53

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[];

package/dist/lib/feed-outcome.js

@@ -0,0 +1,244 @@
+/**
+ * Outcome keys for the agent feed.
+ *
+ * 1,100 agents is not 1,100 things the operator cares about — dozens of agents
+ * map onto each real deliverable (a Linear ticket, a PR, a worktree/epic). The
+ * feed groups by **outcome** so one human reasons about initiatives, not
+ * processes. Every block is attributed to exactly one outcome; orphans land in
+ * the shared "Unassigned" bucket.
+ *
+ * Precedence (first match wins):
+ *   1. ticket   — RUSH-1125 / explicit `ticket` field / ticket-shaped branch
+ *   2. pr       — #534 / PR#534 / github.com/.../pull/534
+ *   3. worktree — `.agents/worktrees/<slug>` slug (or epic label)
+ *   4. unassigned
+ *
+ * Pure functions, no I/O — unit-testable and shared by `agents feed` rendering
+ * and any UI that collapses blocks under deliverables.
+ */
+import { detectTicket, extractPrUrl } from './session/state.js';
+const UNASSIGNED = {
+    key: 'unassigned',
+    kind: 'unassigned',
+    label: 'Unassigned',
+};
+/**
+ * Normalize a PR ref.
+ * - Full GitHub URL → `owner/repo#N` (repo identity included)
+ * - Bare `#123` / `PR#123` → `#123` (no repo known)
+ */
+export function normalizePrRef(raw) {
+    if (!raw)
+        return undefined;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return undefined;
+    const fromUrl = extractPrUrl(trimmed);
+    if (fromUrl?.number != null) {
+        const repo = repoFromPrUrl(fromUrl.url);
+        return repo ? `${repo}#${fromUrl.number}` : `#${fromUrl.number}`;
+    }
+    const m = /(?:^|\bpr\s*#?\s*|pull\/|#)(\d{1,7})\b/i.exec(trimmed);
+    if (m)
+        return `#${m[1]}`;
+    return undefined;
+}
+/** `https://github.com/owner/repo/pull/N` → `owner/repo`. */
+export function repoFromPrUrl(url) {
+    if (!url)
+        return undefined;
+    const m = /github\.com\/([^/\s]+)\/([^/\s]+)\/pull\/\d+/i.exec(url);
+    if (!m)
+        return undefined;
+    return `${m[1]}/${m[2]}`;
+}
+/** Canonical ticket id (uppercase team key). */
+export function normalizeTicketRef(raw) {
+    if (!raw)
+        return undefined;
+    const m = raw.trim().match(/\b([A-Za-z]{2,6}-\d{1,6})\b/);
+    if (!m)
+        return undefined;
+    const id = m[1].toUpperCase();
+    // Reuse the session state's denylist via detectTicket on the id alone.
+    return detectTicket(id)?.id ?? id;
+}
+function ticketFromSignals(s) {
+    const direct = normalizeTicketRef(s.ticket ?? undefined);
+    if (direct)
+        return direct;
+    const fromText = detectTicket(s.text ?? undefined, s.branch ?? undefined)?.id;
+    return fromText;
+}
+function prFromSignals(s) {
+    const direct = normalizePrRef(s.pr ?? undefined);
+    if (direct)
+        return direct;
+    if (s.text) {
+        // Prefer full URL so keys include owner/repo (RUSH-1630).
+        const fromUrl = extractPrUrl(s.text);
+        if (fromUrl?.number != null) {
+            return normalizePrRef(fromUrl.url) ?? `#${fromUrl.number}`;
+        }
+        const m = /(?:\bpr\s*#?\s*|#)(\d{1,7})\b/i.exec(s.text);
+        if (m)
+            return `#${m[1]}`;
+    }
+    return undefined;
+}
+/**
+ * Derive the single outcome a block/agent belongs to.
+ * Exactly one outcome per call — never ambiguous, never empty.
+ */
+export function deriveOutcome(signals) {
+    const ticket = ticketFromSignals(signals);
+    if (ticket) {
+        return { key: `ticket:${ticket}`, kind: 'ticket', label: ticket };
+    }
+    const pr = prFromSignals(signals);
+    if (pr) {
+        // pr is either `owner/repo#N` or `#N`
+        const hash = pr.includes('#') ? pr.slice(pr.indexOf('#')) : pr;
+        const n = hash.replace(/^#/, '');
+        const label = pr.includes('/') ? `PR ${pr}` : `PR#${n}`;
+        return { key: `pr:${pr}`, kind: 'pr', label };
+    }
+    const wt = (signals.worktreeSlug ?? '').trim();
+    if (wt) {
+        return { key: `worktree:${wt}`, kind: 'worktree', label: wt };
+    }
+    const epic = (signals.epic ?? '').trim();
+    if (epic) {
+        // Epic folds into the worktree kind: both are soft deliverable labels
+        // without a tracker id. Key prefix keeps them disjoint from worktree slugs.
+        return { key: `epic:${epic}`, kind: 'worktree', label: epic };
+    }
+    return UNASSIGNED;
+}
+/** Join question headers + bodies into one scan target for ticket/PR detection. */
+export function blockScanText(block) {
+    return block.questions
+        .map((q) => [q.header, q.text].filter(Boolean).join(' '))
+        .filter(Boolean)
+        .join('\n');
+}
+/** Outcome for a stored open block (uses stamped fields + question text). */
+export function outcomeForBlock(block) {
+    return deriveOutcome({
+        ticket: block.ticket,
+        pr: block.pr,
+        worktreeSlug: block.worktreeSlug,
+        epic: block.epic,
+        text: blockScanText(block),
+    });
+}
+function isOpen(block) {
+    return !block.answer && !block.parkedAt && !block.continuedAt && !block.defaultedAt;
+}
+/**
+ * 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 function groupBlocksByOutcome(blocks) {
+    const byKey = new Map();
+    for (const block of blocks) {
+        const outcome = outcomeForBlock(block);
+        const bucket = byKey.get(outcome.key);
+        if (bucket)
+            bucket.blocks.push(block);
+        else
+            byKey.set(outcome.key, { outcome, blocks: [block] });
+    }
+    const groups = [];
+    for (const { outcome, blocks: members } of byKey.values()) {
+        const mailboxes = new Set(members.map((b) => b.mailboxId));
+        let open = 0;
+        let answered = 0;
+        let parked = 0;
+        for (const b of members) {
+            if (b.parkedAt)
+                parked += 1;
+            else if (b.answer || b.defaultedAt || b.continuedAt)
+                answered += 1;
+            else
+                open += 1;
+        }
+        groups.push({
+            outcome,
+            blocks: members,
+            counts: { agents: mailboxes.size, open, answered, parked },
+        });
+    }
+    groups.sort((a, b) => {
+        // Unassigned always last.
+        if (a.outcome.kind === 'unassigned' && b.outcome.kind !== 'unassigned')
+            return 1;
+        if (b.outcome.kind === 'unassigned' && a.outcome.kind !== 'unassigned')
+            return -1;
+        if (b.counts.open !== a.counts.open)
+            return b.counts.open - a.counts.open;
+        return a.outcome.label.localeCompare(b.outcome.label);
+    });
+    return groups;
+}
+/**
+ * Stamp each block with its derived outcome for JSON consumers.
+ * Does not mutate the input records.
+ */
+export function stampBlockOutcomes(blocks) {
+    return blocks.map((b) => ({ ...b, outcome: outcomeForBlock(b) }));
+}
+/**
+ * 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 function isUnambiguousOutcomeAnswer(group) {
+    const open = group.blocks.filter(isOpen);
+    if (open.length <= 1)
+        return open.length === 1;
+    const keys = new Set(open.map((b) => b.questions.map((q) => `${q.header ?? ''}\0${q.text}`).join('\n')));
+    return keys.size === 1;
+}
+/** Still-open blocks under an outcome (candidates for a fan-out reply). */
+export function openBlocksForOutcome(group) {
+    return group.blocks.filter(isOpen);
+}
+/**
+ * Overlay session meta onto a block when the block itself is missing ticket/PR/
+ * worktree. Never overwrites a field the block already carries.
+ */
+export function enrichBlockFromSession(block, hint) {
+    const next = { ...block };
+    if (!next.ticket && hint.ticketId)
+        next.ticket = hint.ticketId;
+    if (!next.pr) {
+        if (hint.prUrl)
+            next.pr = hint.prUrl;
+        else if (hint.prNumber != null)
+            next.pr = `#${hint.prNumber}`;
+    }
+    if (!next.worktreeSlug && hint.worktreeSlug)
+        next.worktreeSlug = hint.worktreeSlug;
+    return next;
+}
+/**
+ * Build a mailboxId → session-hint index and enrich every block. Pure.
+ * Matching order: mailboxId, then sessionId, then agentId.
+ */
+export function enrichBlocksFromSessions(blocks, sessions) {
+    const byMailbox = new Map();
+    const bySession = new Map();
+    for (const s of sessions) {
+        if (s.mailboxId)
+            byMailbox.set(s.mailboxId, s);
+        if (s.sessionId)
+            bySession.set(s.sessionId, s);
+        if (s.agentId)
+            bySession.set(s.agentId, s);
+    }
+    return blocks.map((b) => {
+        const hint = byMailbox.get(b.mailboxId) ?? bySession.get(b.sessionId);
+        return hint ? enrichBlockFromSession(b, hint) : b;
+    });
+}

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

@@ -0,0 +1,30 @@
+import { type OpenBlock, type AnswerRecord } from './feed.js';
+export type BlockClass = 'approval' | 'decision';
+export interface ClassPolicy {
+    timeoutMinutes: number;
+    /** For approval class only: the answer to apply when the timeout fires. */
+    safeDefault?: string;
+}
+export interface FeedPolicy {
+    approval: ClassPolicy;
+    decision: ClassPolicy;
+    /** High-cost-of-delay blocks below this threshold do not page the phone. */
+    phoneNotifyThreshold: 'low' | 'medium' | 'high';
+}
+export declare const DEFAULT_POLICY: FeedPolicy;
+export declare function getPolicyPath(root?: string): string;
+export declare function loadPolicy(root?: string): FeedPolicy;
+export declare function blockClass(block: OpenBlock): BlockClass;
+export declare function isPhoneUrgent(block: OpenBlock, policy: FeedPolicy): boolean;
+export declare function minutesElapsed(block: OpenBlock, now: Date): number;
+export declare function isTimedOut(block: OpenBlock, policy: FeedPolicy, now: Date): boolean;
+export interface PolicyResult {
+    blockId: string;
+    action: 'none' | 'defaulted' | 'parked';
+    answer?: AnswerRecord;
+}
+/**
+ * Apply policy to a single open block. Returns the action taken (none/defaulted/parked).
+ * Caller is responsible for persistence/logging side effects not owned by feed.ts.
+ */
+export declare function applyPolicyToBlock(block: OpenBlock, policy: FeedPolicy, now: Date, root?: string): PolicyResult;

package/dist/lib/feed-policy.js

@@ -0,0 +1,133 @@
+/**
+ * Feed timeout policy — unattended default-on-no-answer behavior.
+ *
+ * Two block classes:
+ *   - Approval: has a safe default (e.g. 'deny'). After the configured timeout with
+ *     no operator answer, the policy auto-records that default and queues it to the
+ *     agent. Logged so the operator can audit later.
+ *   - Decision: no safe default (a real choice). After the timeout the block is
+ *     hard-parked: a parked marker is recorded and, if we can locate the session
+ *     process, it is stopped so the agent cannot proceed on a stale default.
+ *
+ * Policy is loaded from ~/.agents/feed-policy.yaml. Missing file uses the built-in
+ * conservative defaults.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { getUserAgentsDir } from './state.js';
+import { recordAnswer, recordDefaulted, recordMessageReceipt, recordParked, } from './feed.js';
+import { enqueue, mailboxDir } from './mailbox.js';
+const POLICY_FILE = 'feed-policy.yaml';
+const COST_RANK = { low: 0, medium: 1, high: 2 };
+export const DEFAULT_POLICY = {
+    approval: { timeoutMinutes: 30, safeDefault: 'deny' },
+    decision: { timeoutMinutes: 60 },
+    phoneNotifyThreshold: 'medium',
+};
+export function getPolicyPath(root) {
+    return path.join(root ?? getUserAgentsDir(), POLICY_FILE);
+}
+function normalizeClassPolicy(raw) {
+    const p = (raw ?? {});
+    const timeout = typeof p.timeoutMinutes === 'number' ? p.timeoutMinutes : DEFAULT_POLICY.approval.timeoutMinutes;
+    return {
+        timeoutMinutes: Math.max(1, Math.round(timeout)),
+        safeDefault: typeof p.safeDefault === 'string' ? p.safeDefault : undefined,
+    };
+}
+export function loadPolicy(root) {
+    const file = getPolicyPath(root);
+    try {
+        const raw = fs.readFileSync(file, 'utf-8');
+        const parsed = yaml.parse(raw);
+        if (parsed && typeof parsed === 'object') {
+            const p = parsed;
+            const threshold = p.phoneNotifyThreshold;
+            return {
+                approval: normalizeClassPolicy(p.approval ?? { timeoutMinutes: DEFAULT_POLICY.approval.timeoutMinutes, safeDefault: DEFAULT_POLICY.approval.safeDefault }),
+                decision: normalizeClassPolicy(p.decision ?? { timeoutMinutes: DEFAULT_POLICY.decision.timeoutMinutes }),
+                phoneNotifyThreshold: threshold === 'low' || threshold === 'medium' || threshold === 'high' ? threshold : DEFAULT_POLICY.phoneNotifyThreshold,
+            };
+        }
+    }
+    catch {
+        // missing or malformed -> defaults
+    }
+    return DEFAULT_POLICY;
+}
+export function blockClass(block) {
+    return block.blockClass === 'decision' ? 'decision' : 'approval';
+}
+export function isPhoneUrgent(block, policy) {
+    if (block.answer)
+        return false; // already answered
+    const cost = block.costOfDelay ?? 'low';
+    return COST_RANK[cost] >= COST_RANK[policy.phoneNotifyThreshold];
+}
+export function minutesElapsed(block, now) {
+    const ts = Date.parse(block.ts);
+    if (Number.isNaN(ts))
+        return 0;
+    return (now.getTime() - ts) / 60_000;
+}
+export function isTimedOut(block, policy, now) {
+    const cls = blockClass(block);
+    const minutes = minutesElapsed(block, now);
+    return minutes >= policy[cls].timeoutMinutes;
+}
+/**
+ * Apply policy to a single open block. Returns the action taken (none/defaulted/parked).
+ * Caller is responsible for persistence/logging side effects not owned by feed.ts.
+ */
+export function applyPolicyToBlock(block, policy, now, root) {
+    if (block.answer || block.parkedAt || block.defaultedAt) {
+        return { blockId: block.blockId, action: 'none' };
+    }
+    if (!isTimedOut(block, policy, now)) {
+        return { blockId: block.blockId, action: 'none' };
+    }
+    const cls = blockClass(block);
+    if (cls === 'approval') {
+        const safeDefault = block.safeDefault ?? policy.approval.safeDefault;
+        if (!safeDefault) {
+            return { blockId: block.blockId, action: 'none' };
+        }
+        const claim = recordAnswer(block.blockId, { answeredFrom: 'policy', answeredBy: 'default-on-no-answer', operatorId: 'policy', verified: true }, root);
+        if (!claim.ok) {
+            return { blockId: block.blockId, action: 'none' };
+        }
+        const msgId = enqueue(mailboxDir(block.mailboxId, root ?? undefined), {
+            to: block.mailboxId,
+            text: safeDefault,
+            from: 'policy',
+            blockId: block.blockId,
+        });
+        recordMessageReceipt(block.blockId, { msgId, status: 'queued', at: now.toISOString(), from: 'policy' }, root);
+        recordDefaulted(block.blockId, root);
+        return {
+            blockId: block.blockId,
+            action: 'defaulted',
+            answer: {
+                answeredAt: now.toISOString(),
+                answeredFrom: 'policy',
+                answeredBy: 'default-on-no-answer',
+                operatorId: 'policy',
+                verified: true,
+            },
+        };
+    }
+    // Decision class: hard-park.
+    recordParked(block.blockId, root);
+    return {
+        blockId: block.blockId,
+        action: 'parked',
+        answer: {
+            answeredAt: now.toISOString(),
+            answeredFrom: 'policy',
+            answeredBy: 'hard-park',
+            operatorId: 'policy',
+            verified: true,
+        },
+    };
+}