@phnx-labs/agents-cli 1.20.17 → 1.20.18

package/dist/lib/teams/agents.js

@@ -135,6 +135,25 @@ function hasTransitiveDep(byName, startName, targetName, seen = new Set()) {
     }
     return false;
 }
+/**
+ * Single-quote a string for safe interpolation into a POSIX `sh -c` command.
+ * Wraps in single quotes and escapes embedded single quotes via the standard
+ * `'\''` close-escape-reopen idiom, so arbitrary prompts/paths can't break out
+ * of quoting or inject shell syntax.
+ */
+function shSingleQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Wrap a teammate argv in a POSIX shell command that runs it and then records
+ * the real exit code to `exitCodePath`. `echo $?` captures the status of the
+ * preceding command, so the sentinel reflects the underlying CLI's exit code,
+ * not the shell's. Single source of truth shared by launchProcess() and its
+ * test. See reapProcess() for how the sentinel is consumed.
+ */
+export function buildSentinelCommand(cmd, exitCodePath) {
+    return `${cmd.map(shSingleQuote).join(' ')}; echo $? > ${shSingleQuote(exitCodePath)}`;
+}
 /**
  * Capture a stable identifier for a process at the moment it was started.
  * Used to defeat PID reuse: a kill(pid, ...) is only safe when the process
@@ -456,6 +475,15 @@ export class AgentProcess {
     async getMetaPath() {
         return path.join(await this.getAgentDir(), 'meta.json');
     }
+    /**
+     * Path to the exit-code sentinel. The launcher wraps the teammate command in
+     * a shell that writes the underlying CLI's `$?` here once it exits. Detached
+     * teammates can't be wait()ed on by the parent, so this file is the only
+     * durable record of the real exit status — see reapProcess().
+     */
+    async getExitCodePath() {
+        return path.join(await this.getAgentDir(), 'exit_code');
+    }
     toDict() {
         return {
             agent_id: this.agentId,
@@ -748,14 +776,37 @@ export class AgentProcess {
         }
         await this.saveMeta();
     }
+    /**
+     * Recover the teammate's exit status after its process is gone.
+     *
+     * The teammate is spawned detached + unref()'d (see launchProcess), so the
+     * parent never gets the child's exit code from the OS. Instead the launcher
+     * wraps the command in a shell that records `$?` to the exit-code sentinel.
+     * This reads that file:
+     *   - still alive            -> null (no verdict yet)
+     *   - sentinel present       -> the real exit code (0 = success)
+     *   - sentinel absent        -> 1 (the shell was killed before it could write
+     *                                  it, e.g. SIGKILL on timeout/stop — a real
+     *                                  failure)
+     *
+     * Returning a real code (not a hardcoded 1) is what lets agents whose stream
+     * never emits a parsed terminal event — kimi, antigravity, droid — be marked
+     * completed on success instead of falsely failed.
+     */
     async reapProcess() {
         if (!this.pid)
             return null;
-        try {
-            process.kill(this.pid, 0);
+        // isProcessAlive() applies the start-time guard, so a recycled PID now
+        // owned by an unrelated process doesn't read as still-alive.
+        if (this.isProcessAlive())
             return null;
+        try {
+            const raw = (await fs.readFile(await this.getExitCodePath(), 'utf-8')).trim();
+            const code = Number.parseInt(raw, 10);
+            return Number.isNaN(code) ? 1 : code;
         }
         catch {
+            // No sentinel: the shell died before recording $? (killed mid-run).
             return 1;
         }
     }
@@ -998,7 +1049,19 @@ export class AgentManager {
             const stdoutPath = await agent.getStdoutPath();
             const stdoutFile = await fs.open(stdoutPath, 'w');
             const stdoutFd = stdoutFile.fd;
-            const childProcess = spawn(cmd[0], cmd.slice(1), {
+            // Wrap the teammate command in a shell that records the underlying CLI's
+            // exit code to a sentinel file. Detached + unref()'d children can't be
+            // wait()ed on by this parent, so the sentinel is the only durable record
+            // of the real exit status — reapProcess() reads it to decide
+            // completed-vs-failed for agents whose stream emits no parsed terminal
+            // event (kimi, antigravity, droid). Remove any stale sentinel from a
+            // prior run of the same agent id first so a restart can't read it.
+            const exitCodePath = await agent.getExitCodePath();
+            await fs.rm(exitCodePath, { force: true }).catch(() => { });
+            const wrappedCmd = buildSentinelCommand(cmd, exitCodePath);
+            // detached:true makes the shell the process-group leader, so stop()'s
+            // `kill(-pid)` still reaches the underlying CLI through the group.
+            const childProcess = spawn('/bin/sh', ['-c', wrappedCmd], {
                 stdio: ['ignore', stdoutFd, stdoutFd],
                 cwd: agent.cwd || undefined,
                 detached: true,

package/dist/lib/teams/api.js

@@ -139,6 +139,26 @@ export async function handleSpawn(manager, taskName, agentType, prompt, cwd, mod
     const resolvedMode = resolveMode(mode, defaultMode);
     const resolvedEffort = effort ?? 'medium';
     debug(`[spawn] Spawning ${agentType} agent for task "${taskName}" [${resolvedMode}] effort=${resolvedEffort}${profileName ? ` profile=${profileName}` : ''}...`);
+    // Budget pre-flight gate (issue #346). Teammates inherit the project's caps:
+    // before launching one, project its estimated cost onto current spend and
+    // refuse when on_exceed:block would be breached. Cross-vendor by construction
+    // — a Claude teammate and a Codex teammate draw down the same per_project /
+    // per_day pool. Dormant (no-op) when no caps are configured.
+    {
+        const gateCwd = cwd || workspaceDir || worktreePath || process.cwd();
+        const { runPreflightGate } = await import('../budget/preflight.js');
+        const gate = runPreflightGate({
+            agent: agentType,
+            model: model ?? `${agentType}-default`,
+            mode: resolvedMode,
+            prompt,
+            project: gateCwd,
+            cwd: gateCwd,
+        });
+        if (!gate.dormant && !gate.decision.allow) {
+            throw new Error(`[budget] BLOCKED teammate "${taskName}" (${agentType}): ${gate.decision.reason}`);
+        }
+    }
     const agent = await manager.spawn(taskName, agentType, prompt, cwd, resolvedMode, resolvedEffort, parentSessionId, workspaceDir, version, name, after, model, envOverrides, taskType, cloudProvider, cloudSessionId, cloudRepo, cloudBranch, worktreeName, worktreePath, profileName);
     debug(`[spawn] Spawned ${agentType} agent ${agent.agentId} for task "${taskName}"`);
     return {

package/dist/lib/teams/parsers.js

@@ -917,9 +917,16 @@ function normalizeGrok(raw) {
 //   - {"role":"assistant","content":"..."}                          → final message
 //   - {"role":"assistant","tool_calls":[{"function":{"name":"Bash","arguments":"<json>"}}]} → tool use
 //   - {"role":"tool","tool_call_id":"...","content":"..."}            → tool result
-//   - {"role":"meta","type":"session.resume_hint","session_id":"..."} → init / session id
-// Tool arguments are JSON-stringified inside `function.arguments` and must be
-// parsed before extracting paths/commands. Verified against live `kimi` runs.
+//   - {"role":"meta","type":"session.resume_hint","session_id":"..."} → terminal/result
+// Kimi emits NO dedicated result/turn-complete event and NO init event. The
+// `session.resume_hint` meta is its terminal marker: emitted exactly once, as
+// the LAST line, on clean completion (it carries the `kimi -r <id>` resume
+// command). We map it to a success `result` so the team runner resolves status
+// from the stream; the run's exit code remains the safety net for crashes that
+// never reach the hint. Tool arguments are JSON-stringified inside
+// `function.arguments` and must be parsed before extracting paths/commands.
+// Verified against live `kimi` runs (no-tool and tool-using) — see
+// __tests__/testdata/kimi-stream-*.jsonl.
 function normalizeKimi(raw) {
     const timestamp = new Date().toISOString();
     if (!raw || typeof raw !== 'object') {
@@ -1044,9 +1051,14 @@ function normalizeKimi(raw) {
     if (role === 'meta') {
         const metaType = typeof raw.type === 'string' ? raw.type : '';
         if (metaType === 'session.resume_hint') {
+            // Kimi's terminal marker (see header). Emit a success `result` so the
+            // team runner's terminal-event detection resolves the teammate to
+            // COMPLETED from the stream. session_id is preserved for cross-
+            // referencing — readNewEvents() captures it off any event.
             return [{
-                    type: 'init',
+                    type: 'result',
                     agent: 'kimi',
+                    status: 'success',
                     session_id: typeof raw.session_id === 'string' ? raw.session_id : null,
                     timestamp: timestamp,
                 }];

package/dist/lib/types.d.ts

@@ -22,6 +22,43 @@ export interface RunDefaults {
 export type RunConfig = Partial<Record<AgentId, AgentRunConfig>> & {
     defaults?: Record<string, RunDefaults>;
 };
+/**
+ * What to do when a configured budget cap would be exceeded (issue #346).
+ * `block` refuses to launch (or kills a running child) and exits non-zero so
+ * CI/headless/teams/cloud all inherit the decision. `warn` prints the overrun
+ * but proceeds — useful for soft rollout / observability-only.
+ */
+export type BudgetOnExceed = 'block' | 'warn';
+/**
+ * `budget:` block in agents.yaml — cross-vendor spend guardrails (issue #346).
+ *
+ * Resolution is project > user (same precedence as `run:`); see
+ * `resolveBudgetConfig` in lib/budget/config.ts. Every cap is in USD. A cap is
+ * "unset" when undefined — only set caps are enforced. `per_agent` caps apply
+ * to one agent's spend; the top-level caps (`per_run`, `per_day`,
+ * `per_project`) aggregate ACROSS every vendor the CLI dispatches, which is the
+ * cross-vendor property no single-vendor control has.
+ */
+export interface BudgetConfig {
+    /** Display currency. Only "USD" is priced today; carried for forward-compat. */
+    currency?: string;
+    /** Hard cap on the estimated/actual cost of a single run. */
+    per_run?: number;
+    /** Hard cap on total spend attributed to the current day (local date). */
+    per_day?: number;
+    /** Per-agent daily caps, keyed by agent id (e.g. { claude: 30, codex: 20 }). */
+    per_agent?: Partial<Record<AgentId, number>>;
+    /** Hard cap on cumulative spend attributed to the current project. */
+    per_project?: number;
+    /** block (refuse/kill) or warn (proceed). Defaults to block. */
+    on_exceed?: BudgetOnExceed;
+    /**
+     * Interactive confirm threshold (USD). When a run's pre-flight estimate is at
+     * or above this, prompt before launching (unless --yes). Does NOT gate a hard
+     * block — a cap breach always blocks regardless of this value.
+     */
+    require_confirm_over?: number;
+}
 /** Preview features that users can opt into via `agents beta`. */
 export type BetaFeatureName = 'drive' | 'factory';
 /** Subset of chalk color names used for agent-specific terminal output. */
@@ -210,6 +247,8 @@ export interface InstalledHook {
 export interface Manifest {
     agents?: Partial<Record<AgentId, string>>;
     run?: RunConfig;
+    /** Spend guardrails (issue #346). Project-local block overrides user. */
+    budget?: BudgetConfig;
     beta?: {
         enabled?: BetaFeatureName[];
     };
@@ -516,6 +555,15 @@ export interface ExtraRepoConfig {
 export interface Meta {
     agents?: Partial<Record<AgentId, string>>;
     run?: RunConfig;
+    /** macOS secrets-agent config. `auto` makes the first real keychain read of a
+     * `session`-tier bundle populate the broker so concurrent runs read silently. */
+    secrets?: {
+        agent?: {
+            auto?: boolean;
+        };
+    };
+    /** Spend guardrails (issue #346). User-global caps; project agents.yaml overrides. */
+    budget?: BudgetConfig;
     beta?: {
         enabled?: BetaFeatureName[];
     };

package/dist/lib/workflows.d.ts

@@ -6,6 +6,21 @@
  * are composed at runtime by `agents run <workflow>`.
  */
 import type { AgentId } from './types.js';
+/**
+ * The `loop:` block as it appears in WORKFLOW.md frontmatter (YAML, snake_case).
+ * Parsed defensively and translated to the camelCase LoopConfig the driver
+ * consumes (src/lib/loop.ts). See docs/07-entrypoints-and-loops.md.
+ */
+export interface LoopConfigRaw {
+    /** Stop condition. Only `signal` is supported today. */
+    until?: 'signal';
+    /** Hard cap on iterations. */
+    max_iterations?: number;
+    /** Token hard-cap, enforced outside the agent. */
+    budget?: number;
+    /** Delay between iterations ("0" back-to-back, "30m" paces). */
+    interval?: string;
+}
 /** Parsed WORKFLOW.md frontmatter. */
 export interface WorkflowFrontmatter {
     name: string;
@@ -22,6 +37,12 @@ export interface WorkflowFrontmatter {
      * Pass `--no-auto-secrets` to skip this injection.
      */
     secrets?: string[];
+    /**
+     * Optional loop block: wraps the workflow in a bounded until-condition loop
+     * (issue #332). When present, `agents run <workflow>` honors it without a
+     * `--loop` flag. Validated/coerced in parseWorkflowFrontmatter.
+     */
+    loop?: LoopConfigRaw;
 }
 /** A workflow found during repo discovery. */
 export interface DiscoveredWorkflow {
@@ -39,6 +60,41 @@ export interface InstalledWorkflow {
 }
 /** Parse WORKFLOW.md frontmatter from a workflow directory. Returns null if invalid. */
 export declare function parseWorkflowFrontmatter(workflowDir: string): WorkflowFrontmatter | null;
+/**
+ * Defensively coerce a frontmatter `loop:` value into a LoopConfigRaw.
+ *
+ * Mirrors the asStringArray discipline above: a malformed field is dropped to
+ * undefined rather than passed through, so the loop driver never sees a bad
+ * shape. Returns undefined when `loop:` is absent or not an object, or when no
+ * recognized field survives coercion (an all-garbage block is treated as
+ * "no loop", not "empty loop").
+ *
+ * Field rules:
+ *   - until:          only the literal `signal` is accepted; anything else dropped.
+ *   - max_iterations: a finite positive integer; non-numbers/<=0 dropped.
+ *   - budget:         a finite positive number (tokens); non-numbers/<=0 dropped.
+ *   - interval:       a string (e.g. "0", "30m"); non-strings dropped.
+ */
+export declare function parseLoopBlock(v: unknown): LoopConfigRaw | undefined;
+/**
+ * Decide which subagent .md stems a workflow may use, given the discovered
+ * subagent files and the parsed `allowedAgents` frontmatter. This is the
+ * fail-closed security boundary for issue #324:
+ *
+ *   - `allowedAgents === undefined` (field absent)  -> NO restriction; allow all.
+ *   - `allowedAgents === []`        (present, empty) -> allow ZERO; copy none.
+ *   - `allowedAgents = [a, b]`                       -> allow only those stems.
+ *
+ * An explicit empty array must NEVER widen to "allow all" — that would copy
+ * every subagent definition into the run, granting MORE access than declared.
+ *
+ * `available` are the .md filenames found in subagents/ (e.g. `security.md`).
+ * Returns the stems to copy and any allowedAgents entries with no matching file.
+ */
+export declare function resolveAllowedSubagents(available: string[], allowedAgents: string[] | undefined): {
+    allowedStems: string[];
+    missing: string[];
+};
 /** Count subagent .md files in a workflow's subagents/ directory. */
 export declare function countWorkflowSubagents(workflowDir: string): number;
 /**

package/dist/lib/workflows.js

@@ -28,21 +28,88 @@ export function parseWorkflowFrontmatter(workflowDir) {
         const parsed = yaml.parse(frontmatter);
         if (!parsed || typeof parsed !== 'object')
             return null;
+        // Capability-scoping fields are wired into the run (see src/commands/exec.ts);
+        // coerce to string arrays defensively so a malformed `tools: foo` (scalar) or
+        // `tools: [Read, 3]` (mixed) never reaches buildExecCommand as a bad shape.
+        const asStringArray = (v) => Array.isArray(v) && v.every((x) => typeof x === 'string') ? v : undefined;
         return {
             name: parsed.name || '',
             description: parsed.description || '',
             model: parsed.model,
-            tools: parsed.tools,
-            skills: parsed.skills,
-            mcpServers: parsed.mcpServers,
-            allowedAgents: parsed.allowedAgents,
-            secrets: parsed.secrets,
+            tools: asStringArray(parsed.tools),
+            skills: asStringArray(parsed.skills),
+            mcpServers: asStringArray(parsed.mcpServers),
+            allowedAgents: asStringArray(parsed.allowedAgents),
+            secrets: asStringArray(parsed.secrets),
+            loop: parseLoopBlock(parsed.loop),
         };
     }
     catch {
         return null;
     }
 }
+/**
+ * Defensively coerce a frontmatter `loop:` value into a LoopConfigRaw.
+ *
+ * Mirrors the asStringArray discipline above: a malformed field is dropped to
+ * undefined rather than passed through, so the loop driver never sees a bad
+ * shape. Returns undefined when `loop:` is absent or not an object, or when no
+ * recognized field survives coercion (an all-garbage block is treated as
+ * "no loop", not "empty loop").
+ *
+ * Field rules:
+ *   - until:          only the literal `signal` is accepted; anything else dropped.
+ *   - max_iterations: a finite positive integer; non-numbers/<=0 dropped.
+ *   - budget:         a finite positive number (tokens); non-numbers/<=0 dropped.
+ *   - interval:       a string (e.g. "0", "30m"); non-strings dropped.
+ */
+export function parseLoopBlock(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return undefined;
+    const raw = v;
+    const out = {};
+    if (raw.until === 'signal')
+        out.until = 'signal';
+    if (typeof raw.max_iterations === 'number'
+        && Number.isFinite(raw.max_iterations)
+        && Number.isInteger(raw.max_iterations)
+        && raw.max_iterations > 0) {
+        out.max_iterations = raw.max_iterations;
+    }
+    if (typeof raw.budget === 'number' && Number.isFinite(raw.budget) && raw.budget > 0) {
+        out.budget = raw.budget;
+    }
+    if (typeof raw.interval === 'string')
+        out.interval = raw.interval;
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Decide which subagent .md stems a workflow may use, given the discovered
+ * subagent files and the parsed `allowedAgents` frontmatter. This is the
+ * fail-closed security boundary for issue #324:
+ *
+ *   - `allowedAgents === undefined` (field absent)  -> NO restriction; allow all.
+ *   - `allowedAgents === []`        (present, empty) -> allow ZERO; copy none.
+ *   - `allowedAgents = [a, b]`                       -> allow only those stems.
+ *
+ * An explicit empty array must NEVER widen to "allow all" — that would copy
+ * every subagent definition into the run, granting MORE access than declared.
+ *
+ * `available` are the .md filenames found in subagents/ (e.g. `security.md`).
+ * Returns the stems to copy and any allowedAgents entries with no matching file.
+ */
+export function resolveAllowedSubagents(available, allowedAgents) {
+    const stems = available.filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, ''));
+    if (allowedAgents === undefined) {
+        return { allowedStems: stems, missing: [] };
+    }
+    const allow = new Set(allowedAgents);
+    const present = new Set(stems);
+    return {
+        allowedStems: stems.filter(s => allow.has(s)),
+        missing: allowedAgents.filter(a => !present.has(a)),
+    };
+}
 /** 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.17",
+  "version": "1.20.18",
   "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",
@@ -23,6 +23,7 @@
   "files": [
     "dist/**/*.js",
     "dist/**/*.d.ts",
+    "dist/**/*.json",
     "dist/lib/secrets/Agents CLI.app/**",
     "scripts/postinstall.js",
     "scripts/install-helper.js",