@phnx-labs/agents-cli 1.22.45 → 1.22.47

package/dist/lib/watchdog/watchdog.js

@@ -1,53 +1,9 @@
-// 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',
-];
+// Watchdog: pure logic for detecting stalled agent terminals and rendering the
+// prompt that the watchdog AGENT reads to decide idle-vs-unfinished and craft a
+// nudge. There is deliberately no heuristic decider here (no regex over the tail
+// guessing "done" vs "stuck") — that judgment is the agent's job. This module
+// only classifies idleness by timestamp and renders/parses the agent's I/O, so
+// it reads no files and touches no host APIs and can be unit-tested in isolation.
 export function classifyTerminal(input) {
     if (input.optedOut)
         return { kind: 'opted_out' };
@@ -64,14 +20,16 @@ export function classifyTerminal(input) {
     }
     return { kind: 'stalled', stalledForMs: age };
 }
-export const WATCHDOG_SYSTEM_PROMPT = `You are the watchdog for AI coding agents running in terminals. Your one job is to get
-IDLE agents moving to completion: each agent has a goal and is expected to DRIVE TO
-COMPLETION end-to-end, but the terminals below have gone idle. Read each one's goal and
-WHY it stopped, then decide NUDGE (send a message that unsticks it and drives it to
-finish) or SKIP (it genuinely needs the human).
+export const WATCHDOG_SYSTEM_PROMPT = `You are the watchdog for AI coding agents running in terminals. You are given the idle
+sessions on this machine — each with its originating TASK, how long it has been idle, and
+the tail of its transcript. Your one job is to tell, for each one, whether it is
+IDLE-BUT-UNFINISHED (it was given a task, went quiet, and has NOT finished or handed it
+off) or IDLE-AND-DONE (it finished, or it genuinely needs the human). Idle-but-unfinished
+is the dangerous state — the work is most likely to be silently abandoned — so those get a
+NUDGE that drives them to finish. Everything else is a SKIP.
 
-Read the transcript before judging — an agent that already reached a decision needs "do
-it," not "decide."
+Read each transcript before judging — an agent that already reached a decision needs "do
+it," not "decide." Judge from the task + tail, not from keywords.
 
 NUDGE when the agent went idle and could keep going on its own:
 - It asked permission for an obvious or already-authorized next step
@@ -92,18 +50,19 @@ The nudge text MUST carry context, not shove:
 - Tell it to use best judgment and finish end-to-end WITHOUT asking again.
 - Imperative, 1-2 sentences, no emojis, under 240 characters.
 
-SKIP when the agent genuinely needs the human (these belong in the user's feed, not a
-nudge):
-- Credentials, auth, login, 2FA, or biometric.
-- An irreversible or outward-facing action that needs sign-off (force-push, delete
-  prod data, publish/release, spend money, send an external message) — UNLESS the House
-  Rules below authorize it.
-- A real product or intent decision with genuine ambiguity (not a trivial default).
-- The task is actually complete.
-- You cannot tell what the agent is doing.
+SKIP in two distinct cases — mark which with "needsHuman":
+- needsHuman=true — the agent is genuinely blocked on a human (these belong in the user's
+  feed): credentials, auth, login, 2FA, or biometric; an irreversible or outward-facing
+  action needing sign-off (force-push, delete prod data, publish/release, spend money,
+  send an external message) UNLESS the House Rules below authorize it; a real product or
+  intent decision with genuine ambiguity (not a trivial default); or you cannot tell what
+  the agent is doing.
+- needsHuman=false — the task is actually complete (idle-and-done). Leave it alone; do NOT
+  poke a finished session.
 
-Respond with ONLY a JSON array (no prose, no code fence):
-[{"terminalId":"<id>","action":"nudge"|"skip","text":"<message or empty>","reason":"<brief>"}]`;
+Respond with ONLY a JSON array (no prose, no code fence). Include "needsHuman" on every
+skip:
+[{"terminalId":"<id>","action":"nudge"|"skip","text":"<message or empty>","reason":"<brief>","needsHuman":true|false}]`;
 // 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.
@@ -115,10 +74,14 @@ export function composePromptWithPlaybook(basePrompt, playbook) {
 }
 export function renderWatchdogPrompt(candidates, playbook = '') {
     const systemPrompt = composePromptWithPlaybook(WATCHDOG_SYSTEM_PROMPT, playbook);
-    const parts = [systemPrompt, '', 'STALLED TERMINALS:', ''];
+    const parts = [systemPrompt, '', 'IDLE SESSIONS:', ''];
     for (const c of candidates) {
         const seconds = Math.round(c.stalledForMs / 1000);
         parts.push(`--- terminal ${c.terminalId} (${c.agentType}, idle ${seconds}s) ---`);
+        if (c.task)
+            parts.push(`task: ${c.task}`);
+        if (c.cwd)
+            parts.push(`cwd: ${c.cwd}`);
         parts.push('last JSONL lines:');
         for (const line of c.tailLines) {
             parts.push(line);
@@ -153,41 +116,11 @@ export function parseWatchdogResponse(stdout) {
         const reason = typeof obj.reason === 'string' ? obj.reason : '';
         if (!terminalId || !action)
             continue;
-        decisions.push({ terminalId, action, text, reason });
+        // needsHuman only meaningful on a skip; a nudge is never "needs human".
+        const needsHuman = action === 'skip' && obj.needsHuman === true ? true
+            : action === 'skip' && obj.needsHuman === false ? false
+                : undefined;
+        decisions.push({ terminalId, action, text, reason, needsHuman });
     }
     return decisions;
 }
-export function isLikelyTrulyBlocked(candidate) {
-    // With no tail to reason over, only a very long stall counts as blocked.
-    if (candidate.tailLines.length === 0)
-        return candidate.stalledForMs >= FORCE_REVIEW_STALL_MS;
-    const lowerTail = candidate.tailLines.join('\n').toLowerCase();
-    // Waiting-on-user and completion hints are checked BEFORE the 15m force-review
-    // short-circuit — a long-idle OPEN QUESTION must defer (not be blindly
-    // force-nudged) and a finished task is done. The old order tested stall age
-    // first, so a 15m-60m idle session whose tail said "waiting on user" / "done"
-    // was force-nudged anyway. Precedence fixed here (watchdog-brain-v2).
-    if (WAITING_HINTS.some((hint) => lowerTail.includes(hint)))
-        return false;
-    if (COMPLETION_HINTS.some((hint) => lowerTail.includes(hint)))
-        return false;
-    if (candidate.stalledForMs >= FORCE_REVIEW_STALL_MS)
-        return true;
-    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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.22.45",
+  "version": "1.22.47",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams (now with first-class Grok Build CLI support)",
   "type": "module",
   "main": "dist/index.js",
@@ -79,7 +79,7 @@
     "multi-agent"
   ],
   "author": "Phoenix Labs",
-  "license": "Apache-2.0",
+  "license": "FSL-1.1-Apache-2.0",
   "engines": {
     "node": ">=22.5.0",
     "npm": ">=9"

package/dist/commands/usage.d.ts

@@ -1,27 +0,0 @@
-/**
- * Usage command -- show rate-limit / quota status for each installed agent.
- *
- * Lists every installed agent with the best available usage snapshot:
- *   - claude: live OAuth API call (cached for 5 minutes)
- *   - codex:  parsed from latest session log's rate_limits event
- *   - kimi:   live Kimi Code /usages API call (cached for 5 minutes)
- *   - droid:  live Factory billing/limits API call (cached for 5 minutes)
- *   - grok:   parsed from the latest local usage event
- *   - cursor: live Cursor usage API call (cached for 5 minutes)
- *   - others: marked as "not exposed by CLI"
- */
-import type { Command } from 'commander';
-import type { AgentId } from '../lib/types.js';
-import { getUsageInfoForIdentity } from '../lib/accounting/usage.js';
-/** One agent's usage snapshot — the unit the text and --json renderers share. */
-export interface AgentUsageRecord {
-    agent: AgentId;
-    /** Plain agent name (no ANSI) — safe to emit in --json; the text table colorizes it. */
-    label: string;
-    status: 'unsupported' | 'no-version' | 'not-signed-in' | 'ok';
-    email?: string;
-    usage?: Awaited<ReturnType<typeof getUsageInfoForIdentity>>;
-}
-export declare function registerUsageCommand(program: Command): void;
-/** Render one usage record as the human table section. */
-export declare function formatAgentUsage(rec: AgentUsageRecord): string;

package/dist/commands/usage.js

@@ -1,96 +0,0 @@
-import { addHostOption } from '../lib/hosts/option.js';
-import chalk from 'chalk';
-import { ALL_AGENT_IDS, AGENTS, getAccountInfo, agentLabel, resolveAgentName, formatAgentError, } from '../lib/agents.js';
-import { listInstalledVersions, getGlobalDefault, getVersionHomePath } from '../lib/installations/versions.js';
-import { agentReportsUsage, formatUsageSection, getUsageInfoForIdentity } from '../lib/accounting/usage.js';
-export function registerUsageCommand(program) {
-    addHostOption(program.command('usage [agent]'))
-        .description('Show rate-limit / quota usage per agent')
-        .option('--json', 'Emit machine-readable JSON (per-agent usage snapshot) instead of the table')
-        .option('-r, --refresh', 'Collect fresh usage through the shared device coordinator before rendering')
-        .addHelpText('after', `
-Examples:
-  agents usage              Show usage for all installed agents
-  agents usage claude       Show usage for Claude only
-  agents usage codex        Show usage for Codex only
-  agents usage claude --refresh  Explicitly refresh Claude once, device-wide
-  agents usage --json       Machine-readable snapshot for scripts
-`)
-        .action(async (agentFilter, options) => {
-        let filter;
-        if (agentFilter) {
-            const resolved = resolveAgentName(agentFilter);
-            if (!resolved) {
-                console.error(chalk.red(formatAgentError(agentFilter)));
-                process.exit(1);
-            }
-            filter = resolved;
-        }
-        const targets = filter
-            ? [filter]
-            : ALL_AGENT_IDS.filter((id) => listInstalledVersions(id).length > 0);
-        if (targets.length === 0) {
-            if (options.json) {
-                console.log('[]');
-                return;
-            }
-            console.log(chalk.gray('No agents installed. Run `agents add <agent>` first.'));
-            return;
-        }
-        const records = await Promise.all(targets.map((agentId) => collectAgentUsage(agentId, options.refresh === true)));
-        if (options.json) {
-            console.log(JSON.stringify(records, null, 2));
-            return;
-        }
-        console.log(records.map(formatAgentUsage).filter(Boolean).join('\n\n'));
-    });
-}
-/** Gather one agent's usage snapshot as structured data (shared by both renderers). */
-async function collectAgentUsage(agentId, forceRefresh = false) {
-    // Plain name — color is applied only at text-render time (formatAgentUsage), so
-    // `--json` never emits ANSI escapes in `label` (e.g. under FORCE_COLOR=1).
-    const label = AGENTS[agentId].name;
-    if (!agentReportsUsage(agentId)) {
-        return { agent: agentId, label, status: 'unsupported' };
-    }
-    const versions = listInstalledVersions(agentId);
-    const version = getGlobalDefault(agentId) || versions[0];
-    if (!version) {
-        return { agent: agentId, label, status: 'no-version' };
-    }
-    const home = getVersionHomePath(agentId, version);
-    const info = await getAccountInfo(agentId, home);
-    if (!info.usageKey && !info.accountKey) {
-        return { agent: agentId, label, status: 'not-signed-in' };
-    }
-    const usage = await getUsageInfoForIdentity({ agentId, home, info, cliVersion: null }, forceRefresh ? { forceRefresh: true } : undefined);
-    return { agent: agentId, label, status: 'ok', email: info.email ?? undefined, usage };
-}
-/** Render one usage record as the human table section. */
-export function formatAgentUsage(rec) {
-    const cfg = AGENTS[rec.agent];
-    // Colorize the heading here (not in the record) so the plain `label` stays
-    // clean for --json while the text table keeps its per-agent color.
-    const heading = agentLabel(rec.agent);
-    switch (rec.status) {
-        case 'unsupported':
-            return [heading, `  ${chalk.dim(`${cfg.name} CLI does not publish usage data.`)}`].join('\n');
-        case 'no-version':
-            return [heading, `  ${chalk.dim('No version installed.')}`].join('\n');
-        case 'not-signed-in':
-            return [heading, `  ${chalk.dim('Not signed in.')}`].join('\n');
-        case 'ok': {
-            const lines = [heading];
-            if (rec.email)
-                lines.push(`  ${chalk.dim(rec.email)}`);
-            const section = formatUsageSection(rec.usage);
-            if (section.length === 0) {
-                lines.push(`  ${chalk.dim('No usage data available right now.')}`);
-            }
-            else {
-                lines.push(...section);
-            }
-            return lines.join('\n');
-        }
-    }
-}