@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/watchdog/watchdog.js

@@ -0,0 +1,166 @@
+// Watchdog: pure logic for detecting stalled agent terminals and rendering
+// prompts to a headless decider instance that decides whether to nudge them.
+// Ported from Swarmify (extension/src/core/watchdog.ts) — behavior verbatim.
+// Terminal/session delivery lives elsewhere; this module reads no files and
+// touches no host APIs so it can be unit-tested in isolation.
+const FORCE_REVIEW_STALL_MS = 15 * 60 * 1000;
+const BLOCKED_HINTS = [
+    'blocked',
+    'stuck',
+    "can't",
+    'cannot',
+    'unable',
+    'failed',
+    'error',
+    'exception',
+    'traceback',
+    'timed out',
+    'timeout',
+    'rate limit',
+    'permission denied',
+];
+const WAITING_HINTS = [
+    'waiting on user',
+    'awaiting user',
+    'askuserquestion',
+];
+const COMPLETION_HINTS = [
+    'done',
+    'completed',
+    'all set',
+    'finished',
+];
+const TOOL_CALL_HINTS = [
+    '"type":"tool_use"',
+    '"type":"tool_call"',
+    '"type":"function_call"',
+];
+const ASSISTANT_LINE_HINTS = [
+    '"type":"assistant"',
+    '"role":"assistant"',
+    '"payload":{"type":"message"',
+];
+const PROMISE_HINTS = [
+    "i'll",
+    'i will',
+    'let me',
+    'going to',
+    "next i'll",
+    'next i will',
+];
+export function classifyTerminal(input) {
+    if (input.optedOut)
+        return { kind: 'opted_out' };
+    const age = input.nowMs - input.lastActivityMs;
+    if (age < input.stallMs)
+        return { kind: 'active' };
+    if (age > input.dormantMs)
+        return { kind: 'dormant' };
+    if (input.lastNudgeMs !== null) {
+        const sinceNudge = input.nowMs - input.lastNudgeMs;
+        if (sinceNudge < input.cooldownMs) {
+            return { kind: 'rate_limited', cooldownRemainingMs: input.cooldownMs - sinceNudge };
+        }
+    }
+    return { kind: 'stalled', stalledForMs: age };
+}
+export const WATCHDOG_SYSTEM_PROMPT = `You are a watchdog monitoring AI coding agents that run in terminals.
+For each stalled terminal below, decide: NUDGE (send a short message to unstick it) or SKIP.
+
+Nudge when:
+- The last assistant turn announced an action ("I'll write X", "let me run Y")
+  but no matching tool call followed.
+- The agent appears stuck mid-task with no recent progress and the task is incomplete.
+
+Skip when:
+- The agent asked the user a direct question (waiting on human input).
+- The task looks complete.
+- You cannot tell what the agent is doing.
+
+Nudge text must be:
+- One sentence, imperative ("Show me the file.", "Run the tests.").
+- No emojis. No apologies. Under 120 characters.
+
+Respond with ONLY a JSON array (no prose, no code fence):
+[{"terminalId":"<id>","action":"nudge"|"skip","text":"<message or empty>","reason":"<brief>"}]`;
+// User-editable playbook appended below the built-in prompt. The user maintains
+// the source at ~/.agents/playbooks/watchdog.md (read by the delivery layer);
+// this function is pure so it can be tested without filesystem access.
+export function composePromptWithPlaybook(basePrompt, playbook) {
+    const trimmed = playbook.trim();
+    if (!trimmed)
+        return basePrompt;
+    return `${basePrompt}\n\n## House Rules (user playbook)\n\n${trimmed}`;
+}
+export function renderWatchdogPrompt(candidates, playbook = '') {
+    const systemPrompt = composePromptWithPlaybook(WATCHDOG_SYSTEM_PROMPT, playbook);
+    const parts = [systemPrompt, '', 'STALLED TERMINALS:', ''];
+    for (const c of candidates) {
+        const seconds = Math.round(c.stalledForMs / 1000);
+        parts.push(`--- terminal ${c.terminalId} (${c.agentType}, idle ${seconds}s) ---`);
+        parts.push('last JSONL lines:');
+        for (const line of c.tailLines) {
+            parts.push(line);
+        }
+        parts.push('');
+    }
+    return parts.join('\n');
+}
+export function parseWatchdogResponse(stdout) {
+    if (!stdout || !stdout.trim())
+        return [];
+    const arrayMatch = stdout.match(/\[[\s\S]*\]/);
+    if (!arrayMatch)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(arrayMatch[0]);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const decisions = [];
+    for (const d of parsed) {
+        if (!d || typeof d !== 'object')
+            continue;
+        const obj = d;
+        const terminalId = typeof obj.terminalId === 'string' ? obj.terminalId : '';
+        const action = obj.action === 'nudge' || obj.action === 'skip' ? obj.action : null;
+        const text = typeof obj.text === 'string' ? obj.text : '';
+        const reason = typeof obj.reason === 'string' ? obj.reason : '';
+        if (!terminalId || !action)
+            continue;
+        decisions.push({ terminalId, action, text, reason });
+    }
+    return decisions;
+}
+export function isLikelyTrulyBlocked(candidate) {
+    if (candidate.stalledForMs >= FORCE_REVIEW_STALL_MS)
+        return true;
+    if (candidate.tailLines.length === 0)
+        return false;
+    const lowerTail = candidate.tailLines.join('\n').toLowerCase();
+    if (WAITING_HINTS.some((hint) => lowerTail.includes(hint)))
+        return false;
+    if (COMPLETION_HINTS.some((hint) => lowerTail.includes(hint)))
+        return false;
+    if (BLOCKED_HINTS.some((hint) => lowerTail.includes(hint)))
+        return true;
+    let sawToolAfter = false;
+    for (let i = candidate.tailLines.length - 1; i >= 0; i--) {
+        const line = candidate.tailLines[i].toLowerCase();
+        if (TOOL_CALL_HINTS.some((hint) => line.includes(hint))) {
+            sawToolAfter = true;
+            continue;
+        }
+        if (!sawToolAfter) {
+            const isAssistantLine = ASSISTANT_LINE_HINTS.some((hint) => line.includes(hint));
+            const hasPromise = PROMISE_HINTS.some((hint) => line.includes(hint));
+            if (isAssistantLine && hasPromise)
+                return true;
+        }
+    }
+    return false;
+}

package/dist/lib/watchdog/watchdogTail.d.ts

@@ -0,0 +1,5 @@
+export interface TailSummary {
+    lastUserMessage?: string;
+    lastAssistantMessage?: string;
+}
+export declare function summarizeWatchdogTail(tailLines: string[], agentType: string | undefined): TailSummary;

package/dist/lib/watchdog/watchdogTail.js

@@ -0,0 +1,154 @@
+// Watchdog tail summarization: pull the most recent user / assistant message
+// out of the session JSONL window the watchdog read this tick. Pure functions —
+// the watchdog runtime hands us tailLines + agentType and we read no files.
+// Ported from Swarmify (extension/src/core/watchdogTail.ts) — behavior verbatim.
+const MAX_MESSAGE_CHARS = 600;
+export function summarizeWatchdogTail(tailLines, agentType) {
+    let lastUser;
+    let lastAssistant;
+    for (let i = tailLines.length - 1; i >= 0; i--) {
+        if (lastUser && lastAssistant)
+            break;
+        let raw;
+        try {
+            raw = JSON.parse(tailLines[i]);
+        }
+        catch {
+            continue;
+        }
+        if (!raw || typeof raw !== 'object')
+            continue;
+        if (agentType === 'claude') {
+            const claim = readClaude(raw);
+            if (claim?.role === 'user' && !lastUser)
+                lastUser = claim.text;
+            else if (claim?.role === 'assistant' && !lastAssistant)
+                lastAssistant = claim.text;
+        }
+        else if (agentType === 'codex') {
+            const claim = readCodex(raw);
+            if (claim?.role === 'user' && !lastUser)
+                lastUser = claim.text;
+            else if (claim?.role === 'assistant' && !lastAssistant)
+                lastAssistant = claim.text;
+        }
+        else if (agentType === 'gemini') {
+            const claim = readGemini(raw);
+            if (claim?.role === 'user' && !lastUser)
+                lastUser = claim.text;
+            else if (claim?.role === 'assistant' && !lastAssistant)
+                lastAssistant = claim.text;
+        }
+    }
+    return {
+        lastUserMessage: clip(lastUser),
+        lastAssistantMessage: clip(lastAssistant),
+    };
+}
+function readClaude(raw) {
+    const t = raw.type;
+    if (t !== 'user' && t !== 'assistant')
+        return null;
+    const msg = raw.message;
+    if (!msg)
+        return null;
+    const text = pickContentText(msg.content);
+    if (!text)
+        return null;
+    return { role: t, text };
+}
+function readCodex(raw) {
+    if (raw.type !== 'response_item')
+        return null;
+    const payload = raw.payload;
+    if (!payload || payload.type !== 'message')
+        return null;
+    const role = payload.role;
+    if (role !== 'user' && role !== 'assistant')
+        return null;
+    const text = pickContentText(payload.content);
+    if (!text)
+        return null;
+    return { role, text };
+}
+// Gemini stores chats as a single pretty-printed JSON document — readTailLines
+// returns partial fragments that JSON.parse rejects. So in practice this
+// branch only fires for the JSONL-style events that some Gemini wrappers emit
+// during a live session. Acceptable: the result is an empty summary, which
+// the UI handles gracefully.
+function readGemini(raw) {
+    const t = raw.type;
+    if (t === 'user_message') {
+        const text = typeof raw.text === 'string' ? raw.text : null;
+        return text ? { role: 'user', text } : null;
+    }
+    if (t === 'agent_message' || t === 'model_message') {
+        const text = typeof raw.text === 'string' ? raw.text : null;
+        return text ? { role: 'assistant', text } : null;
+    }
+    if (t === 'message') {
+        const role = raw.role === 'user' ? 'user' : raw.role === 'assistant' ? 'assistant' : null;
+        if (!role)
+            return null;
+        const text = typeof raw.text === 'string' ? raw.text : pickContentText(raw.content);
+        return text ? { role, text } : null;
+    }
+    return null;
+}
+function pickContentText(content) {
+    if (typeof content === 'string')
+        return isSyntheticTagged(content) ? null : content;
+    if (!Array.isArray(content))
+        return null;
+    const parts = [];
+    for (const part of content) {
+        if (!part || typeof part !== 'object')
+            continue;
+        const p = part;
+        if ((p.type === 'text' || p.type === 'input_text' || p.type === 'output_text') && typeof p.text === 'string') {
+            if (isSyntheticTagged(p.text))
+                continue;
+            parts.push(p.text);
+        }
+    }
+    return parts.length ? parts.join('\n') : null;
+}
+// Mirrors the synthetic-tag filter in the session readers so a "User: …"
+// surfaced in the watchdog UI never shows a <local-command-stdout>,
+// <system-reminder>, or similar harness chunk that Claude wraps tool output in.
+const SYNTHETIC_TAG_PREFIXES = [
+    '<local-command-caveat',
+    '<local-command-stdout',
+    '<local-command-stderr',
+    '<command-name',
+    '<command-message',
+    '<command-args',
+    '<bash-input',
+    '<bash-stdout',
+    '<bash-stderr',
+    '<system-reminder',
+    '<user-prompt-submit-hook',
+    '<task-notification',
+    '<persisted-output',
+];
+function isSyntheticTagged(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return true;
+    const lower = trimmed.toLowerCase();
+    for (const prefix of SYNTHETIC_TAG_PREFIXES) {
+        if (lower.startsWith(prefix))
+            return true;
+    }
+    return false;
+}
+function clip(text) {
+    if (!text)
+        return undefined;
+    const cleaned = text.replace(/\s+/g, ' ').trim();
+    if (!cleaned)
+        return undefined;
+    return cleaned.length > MAX_MESSAGE_CHARS
+        ? cleaned.slice(0, MAX_MESSAGE_CHARS - 1) + '…'
+        : cleaned;
+}

package/dist/lib/whats-new.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Render a compact "What's new" summary from a CHANGELOG.md body: one bullet
+ * per feature/fix heading (the `**...**` lines) for each version in the range
+ * the user actually moved through, `(fromVersion, toVersion]`. The verbose
+ * sub-bullets are intentionally dropped — the full notes live in the changelog.
+ *
+ * Returns colored lines ready to print, empty when nothing is in range.
+ */
+export declare function renderWhatsNew(changelog: string, fromVersion: string, toVersion: string): string[];

package/dist/lib/whats-new.js

@@ -0,0 +1,35 @@
+import chalk from 'chalk';
+import { compareVersions } from './agent-spec/primitives.js';
+/**
+ * Render a compact "What's new" summary from a CHANGELOG.md body: one bullet
+ * per feature/fix heading (the `**...**` lines) for each version in the range
+ * the user actually moved through, `(fromVersion, toVersion]`. The verbose
+ * sub-bullets are intentionally dropped — the full notes live in the changelog.
+ *
+ * Returns colored lines ready to print, empty when nothing is in range.
+ */
+export function renderWhatsNew(changelog, fromVersion, toVersion) {
+    const out = [];
+    let inRelevantSection = false;
+    for (const line of changelog.split('\n')) {
+        const versionMatch = line.match(/^## (\d+\.\d+\.\d+)/);
+        if (versionMatch) {
+            const currentVersion = versionMatch[1];
+            // Bounding the top end matters when upgrading to a specific older
+            // version, and guards against a changelog that lists unreleased entries.
+            inRelevantSection =
+                compareVersions(currentVersion, fromVersion) > 0 &&
+                    compareVersions(currentVersion, toVersion) <= 0;
+            if (inRelevantSection) {
+                out.push('');
+                out.push(chalk.bold(`v${currentVersion}`));
+            }
+            continue;
+        }
+        // Only the bold headings — one bullet per feature/fix.
+        if (inRelevantSection && line.startsWith('**') && line.endsWith('**')) {
+            out.push(`  ${chalk.cyan('•')} ${line.replace(/\*\*/g, '')}`);
+        }
+    }
+    return out;
+}

package/dist/lib/workflows.d.ts

@@ -21,6 +21,70 @@ export interface LoopConfigRaw {
     /** Delay between iterations ("0" back-to-back, "30m" paces). */
     interval?: string;
 }
+/**
+ * The `verify:` sub-block of a `for_each:` construct (issue #343).
+ *
+ * Each produced item's stage teammate can be gated by a panel of independent
+ * skeptics: `votes` of them run (as teammates that depend on the stage), and
+ * `keep_if` records how their verdicts converge (`majority` / `all` / `any`).
+ * The vote-counting itself is a downstream concern — the declarative layer's
+ * job is to expand the panel; see `expandForEach`.
+ */
+export interface ForEachVerifySpec {
+    /** Subagent / agent id that plays skeptic for each item. */
+    agent: string;
+    /** Prompt template for each skeptic (`{{item}}`, `{{index}}` substituted). */
+    prompt?: string;
+    /** How many independent skeptics run per item (>= 1). */
+    votes: number;
+    /** Convergence rule for keeping a finding. */
+    keep_if: 'majority' | 'all' | 'any';
+}
+/**
+ * The `for_each:` block as it appears in WORKFLOW.md frontmatter (issue #343).
+ *
+ * Declarative dynamic fan-out: a producer emits a list at runtime, one stage
+ * teammate runs per produced item (runtime-computed N), optionally followed by
+ * a `verify` panel. This is a thin declarative layer over the existing teams
+ * substrate — each expanded teammate is staged into the supervisor's
+ * mid-flight-add path (`AgentManager.spawn`), NOT a new engine. See
+ * `expandForEach` and `src/lib/teams/forEach.ts`.
+ *
+ * Parsed defensively (mirrors `parseLoopBlock`): a malformed block drops to
+ * undefined rather than passing a bad shape downstream.
+ */
+export interface ForEachSpec {
+    /**
+     * The producer: a shell command or subagent whose stdout is a JSON array (or
+     * newline-delimited list) of items. Alternatively `itemsRef` names a prior
+     * step's output. At least one of the two is expected for a runnable spec.
+     */
+    produce?: string;
+    /** `${step}`-style reference to a prior step's produced list. */
+    itemsRef?: string;
+    /** Subagent / agent id for the per-item stage. */
+    agent: string;
+    /** Base name for the expanded teammates (default `item`). */
+    name?: string;
+    /** Per-item prompt template (`{{item}}`, `{{index}}` substituted). */
+    prompt: string;
+    /** In-flight cap — maps to the supervisor's wave size (>= 1). */
+    concurrency?: number;
+    /**
+     * Hard runaway guard: the producer can emit at most this many items before
+     * the fan-out is truncated. Defaults to `DEFAULT_FOR_EACH_CAP`.
+     */
+    max_items?: number;
+    /** Optional convergence gate run after each item's stage. */
+    verify?: ForEachVerifySpec;
+}
+/**
+ * Hard upper bound on items a single `for_each` expands, absent an explicit
+ * `max_items`. A guard against a runaway producer spawning unbounded teammates
+ * (acceptance criterion in issue #343). Anthropic's Dynamic Workflows cap at
+ * 1000; we default lower and let authors raise it deliberately.
+ */
+export declare const DEFAULT_FOR_EACH_CAP = 256;
 /** Parsed WORKFLOW.md frontmatter. */
 export interface WorkflowFrontmatter {
     name: string;
@@ -43,6 +107,12 @@ export interface WorkflowFrontmatter {
      * `--loop` flag. Validated/coerced in parseWorkflowFrontmatter.
      */
     loop?: LoopConfigRaw;
+    /**
+     * Optional declarative dynamic fan-out (issue #343): a producer emits a list
+     * and one stage teammate runs per item, with an optional verify panel.
+     * Validated/coerced in parseWorkflowFrontmatter via `parseForEachBlock`.
+     */
+    forEach?: ForEachSpec;
 }
 /** A workflow found during repo discovery. */
 export interface DiscoveredWorkflow {
@@ -76,6 +146,81 @@ export declare function parseWorkflowFrontmatter(workflowDir: string): WorkflowF
  *   - interval:       a string (e.g. "0", "30m"); non-strings dropped.
  */
 export declare function parseLoopBlock(v: unknown): LoopConfigRaw | undefined;
+/**
+ * Defensively coerce a frontmatter `verify:` sub-block into a ForEachVerifySpec.
+ *
+ * Requires an `agent`; drops the whole block otherwise (a verify panel with no
+ * skeptic is meaningless). `votes` defaults to 1 (a single confirmation) and
+ * `keep_if` to `majority`; both are validated against their allowed shapes.
+ */
+export declare function parseVerifyBlock(v: unknown): ForEachVerifySpec | undefined;
+/**
+ * Defensively coerce a frontmatter `for_each:` block into a ForEachSpec (issue
+ * #343). Mirrors `parseLoopBlock`'s discipline: a block missing the two
+ * load-bearing fields (`agent` + `prompt`) drops to undefined rather than
+ * passing a half-formed spec to the expander. Optional numeric/verify fields
+ * are individually validated and dropped when malformed.
+ */
+export declare function parseForEachBlock(v: unknown): ForEachSpec | undefined;
+/** One teammate produced by expanding a `for_each` spec against a produced list. */
+export interface ForEachTeammate {
+    /** `stage` runs the per-item work; `verify` is a skeptic in the panel. */
+    role: 'stage' | 'verify';
+    /** Unique teammate name within the team (used for `--after` linkage). */
+    name: string;
+    /** Subagent / agent id this teammate runs as. */
+    agentType: string;
+    /** Fully-resolved prompt (template variables already substituted). */
+    prompt: string;
+    /** Names of sibling teammates this one waits on (`--after` semantics). */
+    after: string[];
+    /** The produced item this teammate handles. */
+    item: string;
+    /** Zero-based index of the item in the (capped) produced list. */
+    itemIndex: number;
+    /** For `verify` teammates: 1-based vote index and the panel's gate config. */
+    vote?: number;
+    votes?: number;
+    keep_if?: 'majority' | 'all' | 'any';
+}
+/** Result of expanding a `for_each` spec: the teammates plus cap accounting. */
+export interface ForEachExpansion {
+    teammates: ForEachTeammate[];
+    /** How many items the producer emitted (pre-cap). */
+    producedCount: number;
+    /** How many items were actually expanded (post-cap). */
+    usedCount: number;
+    /** producedCount - usedCount; > 0 means the runaway guard truncated. */
+    truncated: number;
+    /** The effective per-`for_each` item cap that was applied. */
+    cap: number;
+}
+/**
+ * Substitute `{{item}}` / `{{index}}` (and 1-based `{{n}}`) in a prompt
+ * template. Unknown `{{...}}` tokens are left intact so a template can carry
+ * placeholders the caller resolves elsewhere.
+ */
+export declare function renderForEachTemplate(template: string, item: string, index: number): string;
+/**
+ * Expand a `for_each` spec against a producer's output into concrete teammate
+ * descriptors (issue #343) — the heart of the declarative fan-out.
+ *
+ * Pure and deterministic: no I/O, no spawning. `src/lib/teams/forEach.ts`
+ * feeds the result to `AgentManager.spawn`, staging each descriptor into the
+ * supervisor's existing mid-flight-add path — so this reuses the dynamic-DAG
+ * substrate rather than introducing a new engine.
+ *
+ * For N produced items (capped at `spec.max_items` / `DEFAULT_FOR_EACH_CAP`):
+ *   - one `stage` teammate per item, depending on `producerName` if given;
+ *   - when `verify` is set, `votes` `verify` teammates per item, each
+ *     depending on that item's stage teammate.
+ *
+ * Names are unique (`<base>-<n>` and `<base>-<n>-verify-<v>`) so `--after`
+ * linkage and the teams cycle check carry over unchanged.
+ */
+export declare function expandForEach(spec: ForEachSpec, items: string[], opts?: {
+    producerName?: string;
+}): ForEachExpansion;
 /**
  * Decide which subagent .md stems a workflow may use, given the discovered
  * subagent files and the parsed `allowedAgents` frontmatter. This is the
@@ -95,6 +240,27 @@ export declare function resolveAllowedSubagents(available: string[], allowedAgen
     allowedStems: string[];
     missing: string[];
 };
+/**
+ * Prune stale workflow-managed subagent files from the shared per-agent agents
+ * dir before a scoped run writes the permitted set (issue #401, follow-up to
+ * #324). A prior *unrestricted* run of a workflow copies every subagent
+ * definition into the shared `~/.claude/agents/` dir; a later run that declares
+ * `allowedAgents:` copies only the permitted ones but never removes the
+ * leftovers — so an unlisted subagent stays on disk and remains dispatchable,
+ * silently defeating the fail-closed scope.
+ *
+ * Fail-closed fix (mirrors how `cleanupWorkflowMcpConfig` only tears down what
+ * the workflow itself created): remove any file that (a) belongs to THIS
+ * workflow's subagents/ — matched by filename, i.e. the workflow-managed
+ * universe — and (b) is NOT in the permitted set. A user's own hand-placed
+ * subagent shares no name with a workflow subagent file, so it is never
+ * touched. Permitted files are left in place; the caller (re)copies them.
+ *
+ * `workflowSubagentFiles` are the .md filenames in the workflow's subagents/
+ * dir (e.g. `security.md`); `allowedStems` are the permitted stems from
+ * `resolveAllowedSubagents`. Returns the filenames actually removed.
+ */
+export declare function pruneStaleWorkflowSubagents(sharedAgentsDir: string, workflowSubagentFiles: string[], allowedStems: string[]): string[];
 /** Count subagent .md files in a workflow's subagents/ directory. */
 export declare function countWorkflowSubagents(workflowDir: string): number;
 /**