@vibeframe/cli 0.83.0 → 0.85.0

package/dist/index.js

@@ -35865,8 +35865,9 @@ var init_video = __esm({
 // src/commands/_shared/cost-tier.ts
 function applyTier(cmd, tier) {
   cmd[COST_TIER_KEY] = tier;
+  const colored = TIER_COLOR[tier](`Cost: ${tier} (${TIER_DESCRIPTION[tier]})`);
   cmd.addHelpText("after", `
-Cost: ${tier} (${TIER_DESCRIPTION[tier]})
+${colored}
 `);
   return cmd;
 }
@@ -35879,16 +35880,23 @@ function applyTiers(parent, tiers) {
     if (tier) applyTier(cmd, tier);
   }
 }
-var TIER_DESCRIPTION, COST_TIER_KEY;
+var TIER_DESCRIPTION, TIER_COLOR, COST_TIER_KEY;
 var init_cost_tier = __esm({
   "src/commands/_shared/cost-tier.ts"() {
     "use strict";
+    init_source();
     TIER_DESCRIPTION = {
       "free": "FFmpeg only, no API call",
       "low": "$0.01\u2013$0.10 per call",
       "high": "$1\u2013$5 per call",
       "very-high": "$5\u2013$50+ per call"
     };
+    TIER_COLOR = {
+      "free": source_default.green,
+      "low": source_default.cyan,
+      "high": source_default.yellow,
+      "very-high": source_default.red
+    };
     COST_TIER_KEY = Symbol.for("@vibeframe/cli.costTier");
   }
 });
@@ -51025,7 +51033,7 @@ function listWalkthroughs() {
 function isWalkthroughTopic(value) {
   return typeof value === "string" && WALKTHROUGH_TOPICS.includes(value);
 }
-var SCENE_WALKTHROUGH, PIPELINE_WALKTHROUGH, META, CONTENT, WALKTHROUGH_TOPICS;
+var SCENE_WALKTHROUGH, PIPELINE_WALKTHROUGH, ARCHITECTURE_WALKTHROUGH, META, CONTENT, WALKTHROUGH_TOPICS;
 var init_walkthroughs = __esm({
   "src/commands/_shared/walkthroughs/walkthroughs.ts"() {
     "use strict";
@@ -51265,6 +51273,59 @@ When the user has a working shell sequence, extract steps:
 
 The \`compose\` action is the catch-all assembly step (audio mux, video
 overlay, etc.) \u2014 useful at the tail of a pipeline.
+`;
+    ARCHITECTURE_WALKTHROUGH = `# vibe agent / build / run \u2014 when to pick which
+
+The CLI has three orchestrating commands that coordinate other primitives:
+\`vibe agent\`, \`vibe build\`, \`vibe run\`. New users routinely ask which one
+they want for a given task. The full audit lives in
+[\`docs/cli-architecture.md\`](../../../docs/cli-architecture.md); this
+walkthrough is the operator-facing summary.
+
+## TL;DR
+
+| | \`vibe agent\` | \`vibe build\` | \`vibe run\` |
+|---|---|---|---|
+| **Driving input** | natural-language prompt | \`STORYBOARD.md\` | YAML pipeline file |
+| **Interactivity** | REPL or one-shot | one-shot | one-shot |
+| **Reproducibility** | none | high (idempotent) | highest (checkpointed) |
+| **Budget caps** | per-session max-turns | none | \`--budget-usd\`, \`--budget-tokens\`, \`--max-errors\` |
+| **Resume after crash** | no | re-invoke | \`--resume\` |
+| **Best for** | exploration | finished script | repeatable workflows |
+
+## Decision tree
+
+- "I want to play, I'll know it when I see it" \u2192 \`vibe agent\`
+- "I have a finished script + visual identity" \u2192 \`vibe build\`
+- "I want this to run again next month" \u2192 \`vibe run\`
+
+If two seem to fit, pick the rightmost one \u2014 more reproducible, less surprise.
+
+## Cost-tier awareness (v0.83+)
+
+Every primitive subcommand carries a cost tier (\`free\` / \`low\` / \`high\` /
+\`very-high\`). \`vibe schema --list\` exposes the tier as JSON, and each
+\`vibe <group> <sub> --help\` page shows it as a colored footer. Use
+\`vibe doctor --test-keys\` before kicking off any high-cost orchestrator \u2014
+a single bad key wastes time and money.
+
+## Cross-command primitives
+
+All three commands ultimately call the same primitives:
+\`generate\` / \`edit\` / \`audio\` / \`inspect\` / \`detect\` / \`remix\`. The
+agent calls them through a tool manifest; \`build\` calls a curated subset
+(TTS + image + compose + render); \`run\` exposes 55+ actions one per primitive.
+
+## Known overlap
+
+- \`vibe build\` is conceptually a 4-step pipeline; \`vibe run\` could express
+  the same flow but build's STORYBOARD.md input + opinionated defaults are
+  the value-add.
+- \`vibe agent\`'s tool registry currently exposes primitives, not
+  orchestrators. Adding \`vibe.build\` / \`vibe.run\` as agent tools is on the
+  table for a future major.
+- \`vibe run --resume\` has no analog in build/agent; build's idempotent
+  re-invoke covers the common case.
 `;
     META = {
       scene: {
@@ -51303,13 +51364,32 @@ overlay, etc.) \u2014 useful at the tail of a pipeline.
           "vibe schema --list",
           "vibe doctor"
         ]
+      },
+      architecture: {
+        title: "vibe agent / build / run \u2014 when to pick which",
+        summary: "Compare the three orchestrating commands on the dimensions that actually decide the choice",
+        steps: [
+          "Pick agent for exploration (NL prompt, REPL, no checkpoints).",
+          "Pick build for STORYBOARD.md \u2192 MP4 with opinionated defaults.",
+          "Pick run for repeatable, budget-capped, checkpointed YAML pipelines.",
+          "Run `vibe doctor --test-keys` before any high-cost orchestrator to validate keys upfront.",
+          "Use `vibe schema --list` (cost field, v0.84) to plan the budget per step before kicking off `vibe run --budget-usd`."
+        ],
+        relatedCommands: [
+          "vibe agent",
+          "vibe build",
+          "vibe run",
+          "vibe doctor",
+          "vibe schema --list"
+        ]
       }
     };
     CONTENT = {
       scene: SCENE_WALKTHROUGH,
-      pipeline: PIPELINE_WALKTHROUGH
+      pipeline: PIPELINE_WALKTHROUGH,
+      architecture: ARCHITECTURE_WALKTHROUGH
     };
-    WALKTHROUGH_TOPICS = ["scene", "pipeline"];
+    WALKTHROUGH_TOPICS = ["scene", "pipeline", "architecture"];
   }
 });
 
@@ -51423,22 +51503,30 @@ var init_key_live_test = __esm({
           signal
         )
       },
-      // The three below still have no cheap authenticated GET as of v0.83:
-      // fal lacks a documented validation endpoint, Kling auth is per-
-      // request HMAC-signed, ImgBB's only authenticated route is image
-      // upload. Surface them as `skipped` so the user knows we didn't
-      // blank-check.
+      // The three below still have no cheap authenticated GET as of
+      // 2026-04-30 (re-checked while shipping v0.85). Surface them as
+      // `skipped` so the user knows we didn't blank-check; revisit when a
+      // provider publishes an account/me endpoint.
       fal: {
+        // Probed: /api/account, /v1/account, /v1/me, /queue/health, /v1/users/me,
+        // /api/users/me, /v1/billing — all 404 with the standard `Authorization:
+        // Key <key>` header. The platform docs reference an "Accounts API" but
+        // its endpoint paths are unpublished as of this check.
         name: "fal.ai",
-        test: async () => ({ ok: false, skipped: true, message: "no auth-only endpoint published" })
+        test: async () => ({ ok: false, skipped: true, message: "no auth-only endpoint (checked 2026-04-30)" })
       },
       kling: {
+        // Per-request HMAC signing means we'd need to sign every probe with the
+        // key's secret half plus a timestamp — possible, but the cheapest
+        // signed endpoint is also a generation request. Not worth the code.
         name: "Kling",
-        test: async () => ({ ok: false, skipped: true, message: "per-request HMAC; can't test cheaply" })
+        test: async () => ({ ok: false, skipped: true, message: "HMAC-signed per request (checked 2026-04-30)" })
       },
       imgbb: {
+        // Only documented route is POST /1/upload. Probing it would consume an
+        // upload quota even if we send a 1×1 PNG, so SKIP is the right call.
         name: "ImgBB",
-        test: async () => ({ ok: false, skipped: true, message: "only auth route is image upload" })
+        test: async () => ({ ok: false, skipped: true, message: "only route is upload (checked 2026-04-30)" })
       }
     };
   }
@@ -62677,6 +62765,10 @@ function toAgentDefinition(t) {
   return {
     name: t.name,
     description: t.description,
+    // Propagate the manifest's cost tier so the agent's executor can
+    // mandate a confirm prompt for high-spend tools without needing a
+    // parallel SSOT.
+    cost: t.cost,
     parameters: {
       type: "object",
       properties,
@@ -62745,7 +62837,7 @@ init_source();
 // package.json
 var package_default = {
   name: "@vibeframe/cli",
-  version: "0.83.0",
+  version: "0.85.0",
   description: "VibeFrame CLI - natural language video editing from the terminal",
   private: false,
   license: "MIT",
@@ -65086,15 +65178,18 @@ function listCommands(program3) {
     if (subCmds.length === 0) {
       const desc = group.description() || "";
       if (desc.toLowerCase().includes("deprecated")) continue;
-      commands.push({ path: name, description: desc });
+      const cost = getCostTier(group);
+      commands.push({ path: name, description: desc, ...cost ? { cost } : {} });
       continue;
     }
     for (const sub of subCmds) {
       const desc = sub.description() || "";
       if (desc.toLowerCase().includes("deprecated")) continue;
+      const cost = getCostTier(sub);
       commands.push({
         path: `${name}.${sub.name()}`,
-        description: desc
+        description: desc,
+        ...cost ? { cost } : {}
       });
     }
   }
@@ -72365,10 +72460,26 @@ function maskSensitiveArgs(args) {
   }
   return masked;
 }
+function estimateToolCost(cost) {
+  if (!cost) return 0;
+  switch (cost) {
+    case "free":
+      return 0;
+    case "low":
+      return 0.05;
+    case "medium":
+      return 0.5;
+    case "high":
+      return 3;
+    case "very-high":
+      return 25;
+  }
+}
 var AgentExecutor = class {
   adapter = null;
   registry;
   memory;
+  cumulativeUsd = 0;
   context;
   config;
   initialized = false;
@@ -72456,12 +72567,39 @@ var AgentExecutor = class {
   }
   /**
    * Execute a single tool
+   *
+   * Confirm-prompt logic:
+   *   - `noConfirm: true`               → never prompt (automation / CI)
+   *   - `confirmAlways: true`           → prompt for every tool call
+   *   - default                         → prompt only when the tool's
+   *                                       cost is high/very-high (the
+   *                                       `costGate`)
+   *
+   * The two non-trivial cases require `confirmCallback` to be set; if
+   * it isn't, no prompt fires and the tool runs.
    */
   async executeTool(toolCall) {
-    if (this.config.confirmCallback) {
+    const def = this.registry.getDefinition(toolCall.name);
+    const cost = def?.cost;
+    const isExpensive = cost === "high" || cost === "very-high";
+    if (this.config.budgetUsd !== void 0) {
+      const estimate = estimateToolCost(cost);
+      if (this.cumulativeUsd + estimate > this.config.budgetUsd) {
+        const remaining = (this.config.budgetUsd - this.cumulativeUsd).toFixed(2);
+        return {
+          toolCallId: toolCall.id,
+          success: false,
+          output: "",
+          error: `Budget exceeded: ${toolCall.name} estimated at $${estimate.toFixed(2)} but only $${remaining} remains of $${this.config.budgetUsd.toFixed(2)} cap.`
+        };
+      }
+    }
+    const shouldConfirm = !this.config.noConfirm && this.config.confirmCallback && (this.config.confirmAlways || isExpensive);
+    if (shouldConfirm && this.config.confirmCallback) {
       const confirmed = await this.config.confirmCallback(
         toolCall.name,
-        toolCall.arguments
+        toolCall.arguments,
+        cost
       );
       if (!confirmed) {
         return {
@@ -72477,8 +72615,18 @@ var AgentExecutor = class {
       this.context
     );
     result.toolCallId = toolCall.id;
+    if (result.success) {
+      this.cumulativeUsd += estimateToolCost(cost);
+    }
     return result;
   }
+  /**
+   * Cumulative tier-estimated USD spent in this session. Updates after
+   * every successful tool call. Useful for status output / `tools` REPL.
+   */
+  getCumulativeUsd() {
+    return this.cumulativeUsd;
+  }
   /**
    * Update context (e.g., when project changes)
    */
@@ -72518,7 +72666,7 @@ init_config();
 init_tty();
 init_api_key();
 init_output();
-async function promptConfirm2(toolName, args) {
+async function promptConfirm2(toolName, args, cost) {
   const { createInterface: createInterface4 } = await import("node:readline");
   const rl = createInterface4({
     input: process.stdin,
@@ -72528,7 +72676,15 @@ async function promptConfirm2(toolName, args) {
   return new Promise((resolve64) => {
     const argsStr = JSON.stringify(args, null, 2);
     console.log();
-    console.log(source_default.yellow(`Execute ${source_default.bold(toolName)}?`));
+    const tierColor = {
+      "free": source_default.green,
+      "low": source_default.cyan,
+      "medium": source_default.yellow,
+      "high": source_default.yellow,
+      "very-high": source_default.red
+    };
+    const costBadge = cost ? ` ${tierColor[cost](`[${cost.toUpperCase()}]`)}` : "";
+    console.log(source_default.yellow(`Execute ${source_default.bold(toolName)}?${costBadge}`));
     console.log(source_default.dim(argsStr));
     rl.question(source_default.cyan("(y/n): "), (answer) => {
       rl.close();
@@ -72538,7 +72694,12 @@ async function promptConfirm2(toolName, args) {
 }
 async function startAgent(options = {}) {
   const isNonInteractive = !!options.input;
-  const confirmMode = options.confirm || false;
+  const confirmAlways = options.confirm || false;
+  const noConfirm = options.noConfirm || false;
+  const budgetUsd = options.budgetUsd ? parseFloat(options.budgetUsd) : void 0;
+  if (budgetUsd !== void 0 && (Number.isNaN(budgetUsd) || budgetUsd < 0)) {
+    exitWithError(generalError(`Invalid --budget-usd: ${options.budgetUsd}`, "Must be a non-negative number (e.g., --budget-usd 5)"));
+  }
   if (!isNonInteractive && !hasTTY()) {
     exitWithError(generalError("Agent mode requires a terminal.", "Run 'vibe agent' directly from your terminal, or use --input <query> for non-interactive mode."));
   }
@@ -72575,7 +72736,13 @@ async function startAgent(options = {}) {
       maxTurns,
       verbose,
       projectPath: options.project,
-      confirmCallback: confirmMode ? promptConfirm2 : void 0
+      // Always supply the callback so the cost gate (high/very-high
+      // tools) can prompt even without `--confirm`. The executor
+      // decides whether to invoke based on `confirmAlways` / `noConfirm`.
+      confirmCallback: noConfirm ? void 0 : promptConfirm2,
+      confirmAlways,
+      noConfirm,
+      budgetUsd
     });
     await agent.initialize();
     spinner2.succeed(source_default.green("Agent initialized"));
@@ -72612,9 +72779,11 @@ async function startAgent(options = {}) {
   console.log();
   console.log(source_default.dim(`  v${version} \xB7 ${provider}${options.model ? ` \xB7 ${options.model}` : ""} \xB7 ${cwd}`));
   console.log();
+  const confirmStatus = noConfirm ? source_default.dim("no-confirm") : confirmAlways ? source_default.yellow("confirm mode") : source_default.dim("cost gate (high/very-high)");
   const statusParts = [
     source_default.green(`${toolCount} tools`),
-    confirmMode ? source_default.yellow("confirm mode") : null,
+    confirmStatus,
+    budgetUsd !== void 0 ? source_default.magenta(`budget: $${budgetUsd.toFixed(2)}`) : null,
     options.project ? source_default.blue(`project: ${options.project}`) : null
   ].filter(Boolean);
   console.log(source_default.dim("  ") + statusParts.join(source_default.dim(" \xB7 ")));
@@ -72728,7 +72897,7 @@ async function startAgent(options = {}) {
     rl.prompt();
   });
 }
-var agentCommand = new Command("agent").description("Start the AI agent with natural language interface").option("-p, --provider <provider>", "LLM provider (openai, claude, gemini, ollama, xai, openrouter)", "openai").option("-m, --model <model>", "Model to use (provider-specific)").option("--project <path>", "Timeline file or directory to load").option("-v, --verbose", "Show verbose output including tool calls").option("--max-turns <n>", "Maximum turns per request", "10").option("-i, --input <query>", "Run a single query and exit (non-interactive)").option("-c, --confirm", "Confirm before each tool execution").action(async (options) => {
+var agentCommand = new Command("agent").description("Start the AI agent with natural language interface").option("-p, --provider <provider>", "LLM provider (openai, claude, gemini, ollama, xai, openrouter)", "openai").option("-m, --model <model>", "Model to use (provider-specific)").option("--project <path>", "Timeline file or directory to load").option("-v, --verbose", "Show verbose output including tool calls").option("--max-turns <n>", "Maximum turns per request", "10").option("-i, --input <query>", "Run a single query and exit (non-interactive)").option("-c, --confirm", "Confirm before EVERY tool execution (overrides cost gate)").option("--no-confirm", "Disable all confirm prompts including the high/very-high cost gate (CI / automation)").option("--budget-usd <usd>", "Reject tool calls past this cumulative USD ceiling (tier-estimated, conservative)").action(async (options) => {
   await startAgent(options);
 });
 function getEnvVar(provider) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/cli",
-  "version": "0.83.0",
+  "version": "0.85.0",
   "description": "VibeFrame CLI - natural language video editing from the terminal",
   "private": false,
   "license": "MIT",
@@ -183,8 +183,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/ai-providers": "0.83.0",
-    "@vibeframe/core": "0.83.0"
+    "@vibeframe/ai-providers": "0.85.0",
+    "@vibeframe/core": "0.85.0"
   },
   "engines": {
     "node": ">=20"