@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/lib/watchdog/watchdog-agent.js

@@ -1,22 +1,4 @@
-/**
- * The watchdog AGENT — the whole decider, in ONE call per tick.
- *
- * The watchdog does not use a heuristic script to guess idle-vs-unfinished. It
- * hands every idle session's task + tail to an agent (via `agents run <target>
- * --mode plan`, read-only) and asks it, for each, whether it is idle-but-unfinished
- * (→ nudge) or idle-and-done / needs-human (→ skip). The whole idle set goes in ONE
- * invocation, so the cost is one bounded plan-mode call per tick regardless of how
- * many sessions are idle — not one agent per session, and only when something is
- * actually idle (the caller does not invoke this with an empty list).
- *
- * A resolved `watchdog` workflow (repo > user > system, via resolveWorkflowRef)
- * runs by name so its WORKFLOW.md body + `model:` frontmatter apply; otherwise the
- * bare agent runs the built-in WATCHDOG_SYSTEM_PROMPT. Best-effort: any failure
- * (agent unavailable, timeout, no verdict) yields an empty map, and the caller
- * treats an unlisted terminal as a SAFE skip — never a blind nudge.
- */
 import { renderWatchdogPrompt, parseWatchdogResponse } from './watchdog.js';
-/** The real runner: one `agents run <target> --mode plan <prompt>` subprocess. */
 async function defaultAgentRunner(runTarget, prompt) {
     const [{ execFile }, { promisify }] = await Promise.all([import('child_process'), import('util')]);
     const execFileAsync = promisify(execFile);
@@ -27,13 +9,6 @@ async function defaultAgentRunner(runTarget, prompt) {
     });
     return stdout;
 }
-/**
- * The default agent decider. `agent` is the harness the built-in prompt runs as
- * (default 'claude'); `workflowCwd` is where a `watchdog` workflow override is
- * resolved from (the daemon's cwd — the batch spans many projects, so there is no
- * single per-session cwd to key on); `run` is the injectable subprocess seam
- * (tests pass a synthetic one). The whole idle set goes to the runner in ONE call.
- */
 export function makeWatchdogAgentDecider(agent, opts = {}) {
     return async (candidates) => {
         const result = new Map();
@@ -51,8 +26,6 @@ export function makeWatchdogAgentDecider(agent, opts = {}) {
                 result.set(d.terminalId, d);
         }
         catch {
-            // Agent unavailable / timed out — return what we have (possibly empty); the
-            // caller safe-skips any terminal with no verdict. Never a blind nudge.
         }
         return result;
     };

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

@@ -3,9 +3,7 @@ export interface WatchdogCandidate {
     agentType: 'claude' | 'codex';
     tailLines: string[];
     stalledForMs: number;
-    /** The originating task / first prompt / topic — so the agent can judge "was given a task but hasn't finished it". */
     task?: string;
-    /** Working directory of the session, for context. */
     cwd?: string;
 }
 export interface Decision {
@@ -13,11 +11,6 @@ export interface Decision {
     action: 'nudge' | 'skip';
     text: string;
     reason: string;
-    /**
-     * Set by the agent on a SKIP to distinguish "genuinely needs the human"
-     * (true → surface it) from "the task is actually done" (false/absent → leave
-     * it alone, do not poke). `done` is a distinct terminal state from `idle`.
-     */
     needsHuman?: boolean;
 }
 export type StallStatus = {

package/dist/lib/watchdog/watchdog.js

@@ -1,9 +1,3 @@
-// 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' };
@@ -63,9 +57,6 @@ SKIP in two distinct cases — mark which with "needsHuman":
 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.
 export function composePromptWithPlaybook(basePrompt, playbook) {
     const trimmed = playbook.trim();
     if (!trimmed)
@@ -116,7 +107,6 @@ export function parseWatchdogResponse(stdout) {
         const reason = typeof obj.reason === 'string' ? obj.reason : '';
         if (!terminalId || !action)
             continue;
-        // 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;

package/dist/lib/watchdog/watchdogTail.js

@@ -1,7 +1,3 @@
-// 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;
@@ -82,9 +78,6 @@ function pickContentText(content) {
     }
     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',

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

@@ -1,11 +1 @@
-/**
- * Render a compact "What's new" summary from a CHANGELOG.md body: one bullet
- * per feature/fix heading for each version in the range the user actually
- * moved through, `(fromVersion, toVersion]`. Headings are recognized in both
- * changelog formats — the current `- **Title.** prose…` single-line bullets
- * and the older standalone `**Heading**` lines. The verbose prose/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

@@ -1,30 +1,13 @@
 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 for each version in the range the user actually
- * moved through, `(fromVersion, toVersion]`. Headings are recognized in both
- * changelog formats — the current `- **Title.** prose…` single-line bullets
- * and the older standalone `**Heading**` lines. The verbose prose/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;
-    // Whether the CURRENT version section uses the old standalone-heading format.
-    // Old sections nest `-` sub-bullets under each `**Heading**` line, and some
-    // sub-bullets are themselves bold-led (`- **Claim.** detail…`) — once a
-    // standalone heading is seen, `- **` lines in that section are sub-bullets,
-    // not entries, and must not render.
     let sectionUsesStandaloneHeadings = 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;
@@ -35,10 +18,6 @@ export function renderWhatsNew(changelog, fromVersion, toVersion) {
             }
             continue;
         }
-        // Only the entry headings — one bullet per feature/fix. Two formats exist
-        // across the changelog's history: the current single-line bullets
-        // (`- **Title.** verbose prose…`, heading kept, prose dropped) and the
-        // older standalone `**Heading**` lines with `-` sub-bullets beneath.
         if (!inRelevantSection)
             continue;
         if (line.startsWith('**') && line.endsWith('**')) {

package/dist/lib/workflows-registry.d.ts

@@ -1,72 +1,27 @@
 import type { AgentId } from './types.js';
-/** A central workflow bundle: its synced name and the source dir holding WORKFLOW.md. */
 interface WorkflowSource {
     name: string;
     path: string;
 }
-/**
- * The complete on-disk contract for one harness's workflows. Every operation
- * is expressed here so the engine below never branches on the agent id.
- */
 interface WorkflowTarget {
-    /** Noun used in ownership errors, e.g. "Kimi skill", "Grok workflow". */
     readonly label: string;
-    /**
-     * Absolute container dir for `versionHome`. A harness whose native store is
-     * HOME-global (antigravity) ignores `versionHome` and resolves from `$HOME`.
-     */
     dir(versionHome: string): string;
-    /** Names of the workflows in `dir` that agents-cli manages (lister + detector). */
     names(dir: string): string[];
-    /** Materialize `wf` into `dir`. Throws on an invalid source or fs error. */
     write(dir: string, wf: WorkflowSource): void;
-    /** Paths workflow `name` occupies in `dir`; empty when it is not installed. */
     occupied(dir: string, name: string): string[];
-    /**
-     * Ownership of what sits at `name` in `dir`: `null` when nothing is there,
-     * `true` when agents-cli wrote it (or the format has no ownership marker),
-     * `false` when a user-authored file of the same name is in the way.
-     */
     managed(dir: string, name: string): boolean | null;
-    /**
-     * True when the installed copy byte-matches what `write` would render from
-     * `wf.path` NOW — the drift predicate `agents doctor` uses. Re-renders the
-     * current source through the same transform the writer uses (never a stored
-     * hash), so a body edit to the source surfaces as drift under an unchanged name.
-     */
     matches(dir: string, wf: WorkflowSource): boolean;
 }
-/**
- * Single source of truth for how each workflows-capable harness stores
- * workflows. The keys MUST match `capableAgents('workflows')` (the `workflows`
- * flag in `agent-spec/agents.ts`): the capability flag is the version gate,
- * this table is the shape.
- */
 export declare const WORKFLOW_TARGETS: Partial<Record<AgentId, WorkflowTarget>>;
-/** The registered target for `agent`; throws for a harness that has none. */
 export declare function workflowTarget(agent: AgentId): WorkflowTarget;
-/** Workflow names agents-cli has synced into `versionHome` for `agent`. */
 export declare function listWorkflowsForAgent(agent: AgentId, versionHome: string): string[];
-/**
- * Materialize the central bundle at `workflowPath` as `name` in `agent`'s
- * `versionHome`, in that harness's native layout. Refuses to clobber a
- * user-authored file of the same name (the ownership marker is the tell) and
- * is idempotent over an agents-cli-managed one.
- */
 export declare function syncWorkflowToVersion(workflowPath: string, name: string, agent: AgentId, versionHome: string): {
     success: boolean;
     error?: string;
 };
-/** Remove workflow `name` from `agent@version`; refuses a user-authored file. */
 export declare function removeWorkflowFromVersion(agent: AgentId, version: string, name: string): {
     success: boolean;
     error?: string;
 };
-/**
- * True when workflow `name` materialized in `agent`'s `versionHome` byte-matches
- * what the writer would produce NOW from `sourcePath` — the content-drift
- * predicate `agents doctor` uses. Returns false when the home copy is absent
- * (surfaced as `missing` at the name level, not here).
- */
 export declare function workflowContentMatches(agent: AgentId, versionHome: string, name: string, sourcePath: string): boolean;
 export {};

package/dist/lib/workflows-registry.js

@@ -1,19 +1,3 @@
-/**
- * Workflow target registry — the ONE place that says how each
- * workflows-capable harness stores a synced workflow on disk.
- *
- * `WORKFLOW_TARGETS` is the declarative shape (container dir, file layout,
- * transform, ownership marker); the engine below (`listWorkflowsForAgent`,
- * `syncWorkflowToVersion`, `removeWorkflowFromVersion`,
- * `workflowContentMatches`) and the staleness detector are generic over it, so
- * adding a harness is one entry here plus its `workflows` capability flag in
- * `agent-spec/agents.ts` — never another `if (agent === '...')` arm in the
- * writer, the lister, the remover, the doctor drift check, and the detector.
- * A completeness test pins `Object.keys(WORKFLOW_TARGETS)` to
- * `capableAgents('workflows')` so the flag and the shape cannot drift.
- *
- * Same pattern as `SUBAGENT_TARGETS` in `subagents-registry.ts`.
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getVersionHomePath } from './installations/versions.js';
@@ -37,11 +21,6 @@ function renderedMatches(homePath, expected) {
     }
     return normalizeResourceContent(actual) === normalizeResourceContent(expected);
 }
-// ── layouts ──────────────────────────────────────────────────────────────────
-/**
- * One rendered `<name><ext>` file per workflow, owned via a marker the
- * transform embeds (antigravity, openclaw, grok).
- */
 function renderedFile(opts) {
     const file = (dir, name) => path.join(dir, `${name}${opts.ext}`);
     return {
@@ -72,10 +51,6 @@ function renderedFile(opts) {
         },
     };
 }
-/**
- * Kimi flow skill: a `<name>/SKILL.md` directory whose frontmatter carries
- * `type: flow` and the `agents_workflow` marker.
- */
 const kimiFlowSkill = {
     label: 'Kimi skill',
     dir: (versionHome) => path.join(versionHome, '.kimi-code', 'skills'),
@@ -104,11 +79,6 @@ const kimiFlowSkill = {
         return renderedMatches(path.join(dir, wf.name, 'SKILL.md'), transformWorkflowForKimi(wf.path, wf.name));
     },
 };
-/**
- * Goose recipe: `<name>.yaml` plus a `<name>.subrecipes/` dir holding one YAML
- * per selected workflow subagent. Goose has no ownership marker, so presence
- * is ownership.
- */
 const gooseRecipe = {
     label: 'Goose recipe',
     dir: (versionHome) => path.join(versionHome, '.config', 'goose', 'recipes'),
@@ -146,11 +116,6 @@ const gooseRecipe = {
         return renderedMatches(path.join(dir, `${wf.name}.yaml`), expected);
     },
 };
-/**
- * The canonical bundle copied verbatim: `<name>/WORKFLOW.md` (plus its
- * subagents/ tree) under `{versionHome}/workflows/`. No marker — the dir is
- * agents-cli's by construction.
- */
 const workflowBundle = {
     label: 'Workflow',
     dir: (versionHome) => path.join(versionHome, 'workflows'),
@@ -178,19 +143,10 @@ const workflowBundle = {
         return dirsContentMatch(wf.path, path.join(dir, wf.name));
     },
 };
-// ── the registry ─────────────────────────────────────────────────────────────
-/**
- * Single source of truth for how each workflows-capable harness stores
- * workflows. The keys MUST match `capableAgents('workflows')` (the `workflows`
- * flag in `agent-spec/agents.ts`): the capability flag is the version gate,
- * this table is the shape.
- */
 export const WORKFLOW_TARGETS = {
     claude: workflowBundle,
     kimi: kimiFlowSkill,
     goose: gooseRecipe,
-    // Antigravity discovers workflows in the shared HOME-global dir `agy` scans
-    // at startup, never in a version home — see `antigravityWorkflowsDir`.
     antigravity: renderedFile({
         label: 'Antigravity workflow',
         dir: () => antigravityWorkflowsDir(),
@@ -213,7 +169,6 @@ export const WORKFLOW_TARGETS = {
         marker: grokWorkflowMarker,
     }),
 };
-/** The registered target for `agent`; throws for a harness that has none. */
 export function workflowTarget(agent) {
     const target = WORKFLOW_TARGETS[agent];
     if (!target) {
@@ -221,18 +176,10 @@ export function workflowTarget(agent) {
     }
     return target;
 }
-// ── the generic engine ───────────────────────────────────────────────────────
-/** Workflow names agents-cli has synced into `versionHome` for `agent`. */
 export function listWorkflowsForAgent(agent, versionHome) {
     const target = workflowTarget(agent);
     return target.names(target.dir(versionHome));
 }
-/**
- * Materialize the central bundle at `workflowPath` as `name` in `agent`'s
- * `versionHome`, in that harness's native layout. Refuses to clobber a
- * user-authored file of the same name (the ownership marker is the tell) and
- * is idempotent over an agents-cli-managed one.
- */
 export function syncWorkflowToVersion(workflowPath, name, agent, versionHome) {
     const target = workflowTarget(agent);
     const dir = target.dir(versionHome);
@@ -247,7 +194,6 @@ export function syncWorkflowToVersion(workflowPath, name, agent, versionHome) {
         return { success: false, error: err.message };
     }
 }
-/** Remove workflow `name` from `agent@version`; refuses a user-authored file. */
 export function removeWorkflowFromVersion(agent, version, name) {
     const target = workflowTarget(agent);
     const dir = target.dir(getVersionHomePath(agent, version));
@@ -268,12 +214,6 @@ export function removeWorkflowFromVersion(agent, version, name) {
         return { success: false, error: err.message };
     }
 }
-/**
- * True when workflow `name` materialized in `agent`'s `versionHome` byte-matches
- * what the writer would produce NOW from `sourcePath` — the content-drift
- * predicate `agents doctor` uses. Returns false when the home copy is absent
- * (surfaced as `missing` at the name level, not here).
- */
 export function workflowContentMatches(agent, versionHome, name, sourcePath) {
     const target = workflowTarget(agent);
     return target.matches(target.dir(versionHome), { name, path: sourcePath });