@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/lib/workflows.js

@@ -11,6 +11,13 @@ import * as yaml from 'yaml';
 import { capableAgents } from './capabilities.js';
 import { getProjectAgentsDir, getSystemWorkflowsDir, getUserWorkflowsDir, getTrashWorkflowsDir, getEnabledExtraRepos, } from './state.js';
 import { listInstalledVersions, getVersionHomePath } from './versions.js';
+/**
+ * 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 const DEFAULT_FOR_EACH_CAP = 256;
 /** Parse WORKFLOW.md frontmatter from a workflow directory. Returns null if invalid. */
 export function parseWorkflowFrontmatter(workflowDir) {
     const workflowMdPath = path.join(workflowDir, 'WORKFLOW.md');
@@ -42,6 +49,7 @@ export function parseWorkflowFrontmatter(workflowDir) {
             allowedAgents: asStringArray(parsed.allowedAgents),
             secrets: asStringArray(parsed.secrets),
             loop: parseLoopBlock(parsed.loop),
+            forEach: parseForEachBlock(parsed.for_each),
         };
     }
     catch {
@@ -83,6 +91,152 @@ export function parseLoopBlock(v) {
         out.interval = raw.interval;
     return Object.keys(out).length > 0 ? out : undefined;
 }
+/** A finite positive integer, or undefined. Shared guard for count-like fields. */
+function asPosInt(v) {
+    return typeof v === 'number' && Number.isFinite(v) && Number.isInteger(v) && v > 0
+        ? v
+        : undefined;
+}
+/** A non-empty trimmed string, or undefined. */
+function asNonEmptyString(v) {
+    return typeof v === 'string' && v.trim().length > 0 ? v : 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 function parseVerifyBlock(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return undefined;
+    const raw = v;
+    const agent = asNonEmptyString(raw.agent);
+    if (!agent)
+        return undefined;
+    const keepIf = raw.keep_if;
+    const out = {
+        agent,
+        votes: asPosInt(raw.votes) ?? 1,
+        keep_if: keepIf === 'all' || keepIf === 'any' || keepIf === 'majority'
+            ? keepIf
+            : 'majority',
+    };
+    const prompt = asNonEmptyString(raw.prompt);
+    if (prompt)
+        out.prompt = prompt;
+    return out;
+}
+/**
+ * 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 function parseForEachBlock(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return undefined;
+    const raw = v;
+    const agent = asNonEmptyString(raw.agent);
+    const prompt = asNonEmptyString(raw.prompt);
+    if (!agent || !prompt)
+        return undefined;
+    const out = { agent, prompt };
+    const produce = asNonEmptyString(raw.produce);
+    if (produce)
+        out.produce = produce;
+    // `for_each: ${step}` references a prior step's list. Accept either the
+    // snake-case `for_each` key or an explicit `items_ref`.
+    const itemsRef = asNonEmptyString(raw.for_each) ?? asNonEmptyString(raw.items_ref);
+    if (itemsRef)
+        out.itemsRef = itemsRef;
+    const name = asNonEmptyString(raw.name);
+    if (name)
+        out.name = name;
+    const concurrency = asPosInt(raw.concurrency);
+    if (concurrency)
+        out.concurrency = concurrency;
+    const maxItems = asPosInt(raw.max_items);
+    if (maxItems)
+        out.max_items = maxItems;
+    const verify = parseVerifyBlock(raw.verify);
+    if (verify)
+        out.verify = verify;
+    return out;
+}
+/**
+ * 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 function renderForEachTemplate(template, item, index) {
+    return template
+        .replace(/\{\{\s*item\s*\}\}/g, item)
+        .replace(/\{\{\s*index\s*\}\}/g, String(index))
+        .replace(/\{\{\s*n\s*\}\}/g, String(index + 1));
+}
+/**
+ * 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 function expandForEach(spec, items, opts = {}) {
+    const cap = spec.max_items ?? DEFAULT_FOR_EACH_CAP;
+    const producedCount = items.length;
+    const used = items.slice(0, cap);
+    const base = spec.name ?? 'item';
+    const teammates = [];
+    used.forEach((item, itemIndex) => {
+        const stageName = `${base}-${itemIndex + 1}`;
+        teammates.push({
+            role: 'stage',
+            name: stageName,
+            agentType: spec.agent,
+            prompt: renderForEachTemplate(spec.prompt, item, itemIndex),
+            after: opts.producerName ? [opts.producerName] : [],
+            item,
+            itemIndex,
+        });
+        if (spec.verify) {
+            const verifyPrompt = spec.verify.prompt ?? spec.prompt;
+            for (let vote = 1; vote <= spec.verify.votes; vote++) {
+                teammates.push({
+                    role: 'verify',
+                    name: `${stageName}-verify-${vote}`,
+                    agentType: spec.verify.agent,
+                    prompt: renderForEachTemplate(verifyPrompt, item, itemIndex),
+                    after: [stageName],
+                    item,
+                    itemIndex,
+                    vote,
+                    votes: spec.verify.votes,
+                    keep_if: spec.verify.keep_if,
+                });
+            }
+        }
+    });
+    return {
+        teammates,
+        producedCount,
+        usedCount: used.length,
+        truncated: producedCount - used.length,
+        cap,
+    };
+}
 /**
  * Decide which subagent .md stems a workflow may use, given the discovered
  * subagent files and the parsed `allowedAgents` frontmatter. This is the
@@ -110,6 +264,45 @@ export function resolveAllowedSubagents(available, allowedAgents) {
         missing: allowedAgents.filter(a => !present.has(a)),
     };
 }
+/**
+ * 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 function pruneStaleWorkflowSubagents(sharedAgentsDir, workflowSubagentFiles, allowedStems) {
+    if (!fs.existsSync(sharedAgentsDir))
+        return [];
+    const allow = new Set(allowedStems);
+    const pruned = [];
+    for (const file of workflowSubagentFiles) {
+        if (!file.endsWith('.md'))
+            continue;
+        const stem = file.replace(/\.md$/, '');
+        if (allow.has(stem))
+            continue; // permitted → the copy step will (re)write it
+        const target = path.join(sharedAgentsDir, file);
+        if (fs.existsSync(target)) {
+            fs.rmSync(target, { force: true });
+            pruned.push(file);
+        }
+    }
+    return pruned;
+}
 /** Count subagent .md files in a workflow's subagents/ directory. */
 export function countWorkflowSubagents(workflowDir) {
     const subagentsDir = path.join(workflowDir, 'subagents');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.20.34",
+  "version": "1.20.36",
   "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",
@@ -46,6 +46,7 @@
   "scripts": {
     "build": "tsc && rm -rf 'dist/lib/secrets/AgentsKeychain.app' 'dist/lib/secrets/Agents CLI.app' 'dist/lib/menubar/MenubarHelper.app' && ([ \"$(uname)\" = \"Darwin\" ] && cp -R 'bin/Agents CLI.app' 'dist/lib/secrets/Agents CLI.app' || true) && ([ \"$(uname)\" = \"Darwin\" ] && [ -d 'bin/MenubarHelper.app' ] && mkdir -p 'dist/lib/menubar' && cp -R 'bin/MenubarHelper.app' 'dist/lib/menubar/MenubarHelper.app' || true)",
     "build:bin": "scripts/build-bin.sh",
+    "prepare": "npm run build",
     "prepack": "scripts/verify-keychain-helper.sh && scripts/verify-menubar-helper.sh",
     "postinstall": "node scripts/postinstall.js",
     "dev": "tsx src/index.ts",
@@ -72,7 +73,7 @@
     "multi-agent"
   ],
   "author": "Phoenix Labs",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "engines": {
     "node": ">=22.5.0",
     "npm": ">=9"
@@ -102,8 +103,8 @@
   "devDependencies": {
     "@types/diff": "8.0.0",
     "@types/marked-terminal": "6.1.1",
-    "@types/node": "25.9.3",
-    "tsx": "4.22.4",
+    "@types/node": "26.1.0",
+    "tsx": "4.23.0",
     "typescript": "6.0.3",
     "vitest": "4.1.9"
   }