@f-o-h/cli 0.1.34 → 0.1.35

package/README.md

@@ -4,7 +4,7 @@ AI-operator provisioning CLI for Front Of House.
 
 Public mirror: https://github.com/iiko38/front-of-house-cli
 
-Current published baseline: `@f-o-h/cli@0.1.34`
+Current candidate baseline: `@f-o-h/cli@0.1.35`
 
 This mirror is a generated release artifact. The private product monorepo is not
 published here, and no open-source license is granted unless stated separately.
@@ -61,7 +61,7 @@ foh auth login --web --json
 foh auth login --email "$FOH_EMAIL" --password "$FOH_PASSWORD" --json
 foh org list --json
 foh org use --org <org-id> --json
-foh setup --org <org-id> --agent-template <template-id> --agent-name "Demo Agent" --json
+FOH_CLI_SPEND_POLICY=no_spend foh setup --org <org-id> --agent-template <template-id> --agent-name "Demo Agent" --phone-mode observe --json
 foh prove --agent <agent-id> --json --out foh-proof.json
 foh test run --suite ./suite.yml --agent <agent-id> --json --out foh-test-report.json
 foh agent replay --file ./transcript-export.json --json
@@ -80,13 +80,25 @@ prints the fallback URL. `auth login --web` starts browser device
 authorization, opens `/cli-auth`, waits for console approval, and stores the
 returned short-lived token. Credential auth remains available as fallback.
 
-`foh prove` produces a compact signed proof report across auth, org context,
-agent validation, contact phone readiness, voice provider health, widget
-channel/embed readiness, widget smoke, and simulation certification. It is
-read-only by default; pass `--mutation-mode ensure` or `--repair` only when you
-explicitly want proof to ensure missing widget state. Use `--strict` in
-automation when holds should fail the command, and `--mission voice` or
-`--require-phone` when a voice/contact number is mandatory for the demo.
+`foh prove` produces a compact signed proof report across auth, org context,
+agent validation, contact phone readiness, voice provider health, widget
+channel/embed readiness, widget smoke, and simulation certification. It is
+read-only by default; pass `--mutation-mode ensure` or `--repair` only when you
+explicitly want proof to ensure missing widget state. Use `--strict` in
+automation when holds should fail the command, and `--mission voice` or
+`--require-phone` when a voice/contact number is mandatory for the demo.
+
+For mass AI-agent evals and repeated demo rehearsals, keep setup on the free
+scaffold lane:
+
+```bash
+FOH_CLI_SPEND_POLICY=no_spend foh setup --org <org-id> --agent-template <template-id> --agent-name "Demo Agent" --phone-mode observe --json
+```
+
+`--phone-mode observe` checks whether a contact phone already exists without
+buying one. `--phone-mode skip` bypasses the phone step. `--phone-mode purchase`
+is the explicit paid contact path and is fail-closed when
+`FOH_CLI_SPEND_POLICY=no_spend` is set.
 
 The CLI defaults to the production API at `https://api.frontofhouse.okii.uk`.
 

package/dist/foh.js

@@ -11055,6 +11055,47 @@ function registerCompliance(program3) {
 
 // src/commands/provision.ts
 var import_crypto = require("crypto");
+
+// src/lib/spend-policy.ts
+var FOH_CLI_SPEND_POLICY_ENV = "FOH_CLI_SPEND_POLICY";
+var NO_SPEND_POLICY = "no_spend";
+var PAID_RESOURCE_BLOCKED_REASON_CODE = "paid_resource_blocked_by_spend_policy";
+function resolveCliSpendPolicy(env = process.env) {
+  const value = String(env[FOH_CLI_SPEND_POLICY_ENV] || "").trim().toLowerCase();
+  return value === NO_SPEND_POLICY ? NO_SPEND_POLICY : "default";
+}
+function isNoSpendPolicy(env = process.env) {
+  return resolveCliSpendPolicy(env) === NO_SPEND_POLICY;
+}
+function buildPaidResourceBlockedEnvelope(input) {
+  return cliEnvelope({
+    status: "blocked",
+    reasonCode: PAID_RESOURCE_BLOCKED_REASON_CODE,
+    summary: "Paid or scarce resource mutation blocked by the active no-spend CLI policy.",
+    ids: { org_id: input.orgId ?? null },
+    checks: [
+      {
+        name: "spend_policy",
+        status: "blocked",
+        reason_code: PAID_RESOURCE_BLOCKED_REASON_CODE,
+        spend_policy: NO_SPEND_POLICY,
+        spend_class: "paid_foh",
+        resource: input.resource
+      }
+    ],
+    nextCommands: input.nextCommands,
+    extra: {
+      spend_policy: NO_SPEND_POLICY,
+      spend_class: "paid_foh",
+      safe_to_retry: false,
+      resource: input.resource,
+      command: input.command,
+      operator_note: "No-spend eval mode allows setup and proof work, but blocks FOH-owned phone-number purchasing. Use an existing/BYON phone path or rerun outside no-spend eval mode with explicit operator approval."
+    }
+  });
+}
+
+// src/commands/provision.ts
 function requiredOrg2(opts, step) {
   return resolveRequiredOrgId(opts.org, {
     apiUrl: opts.apiUrl,
@@ -11089,6 +11130,22 @@ function registerProvision(program3) {
       format({ status: "skipped", reason: "already_provisioned", phone_number: onboarding.phone_number }, { json: opts.json ?? false });
       return;
     }
+    if (isNoSpendPolicy()) {
+      format(
+        buildPaidResourceBlockedEnvelope({
+          resource: "foh_twilio_phone_number",
+          command: "foh provision buy",
+          orgId: resolvedOrg,
+          nextCommands: [
+            `foh provision status --org ${resolvedOrg} --json`,
+            `foh prove --mission voice --require-phone --org ${resolvedOrg} --json`
+          ]
+        }),
+        { json: opts.json ?? false }
+      );
+      markCommandFailed(1);
+      return;
+    }
     const data = await apiFetch("/v1/console/org/twilio/provision", {
       method: "POST",
       body: JSON.stringify({ country: opts.country, area_code: opts.areaCode }),
@@ -32698,7 +32755,7 @@ var StdioServerTransport = class {
 };
 
 // src/lib/cli-version.ts
-var CLI_VERSION = "0.1.34";
+var CLI_VERSION = "0.1.35";
 
 // src/commands/mcp-serve.ts
 var DEFAULT_TIMEOUT_MS = 12e4;
@@ -34331,6 +34388,16 @@ function timedStepResult(result, startedAtIso, startedAtMs) {
 function optionNameToFlag(key) {
   return "--" + key.replace(/([A-Z])/g, "-$1").toLowerCase();
 }
+function normalizeSetupPhoneMode(raw) {
+  const value = String(raw || "purchase").trim().toLowerCase();
+  if (value === "observe" || value === "skip" || value === "purchase") return value;
+  throw new FohError({
+    step: "setup.phone_mode",
+    error: `Invalid --phone-mode "${String(raw)}"`,
+    remediation: "Use one of: observe, skip, purchase.",
+    reasonCode: "setup_invalid_phone_mode"
+  });
+}
 function buildMissingOptionsPlan(missing, opts) {
   const missingFlags = missing.map(optionNameToFlag);
   const signInUrl = buildConsoleSignInUrl(resolveConsoleBaseUrl(opts.consoleUrl));
@@ -34381,7 +34448,7 @@ function emitMissingOptionsPlan(missing, opts) {
   }
 }
 function registerSetup(program3) {
-  program3.command("setup").description("Fully provision a new agency customer in one command").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--agent-template <id>", "Agent template ID (e.g. viewing-request)").option("--agent-name <name>", "Name for the new agent").option("--phone-country <cc>", "Phone number country code", "GB").option("--phone-area-code <code>", "Phone area code preference").option("--widget-domains <domains>", "Comma-separated widget domain allowlist").option("--voice-provider <p>", "TTS provider: openai, azure, twilio").option("--voice-id <id>", "Voice ID").option("--skip-compliance", "Skip compliance submission and wait").option("--skip-voice", "Skip voice configuration").option("--skip-tests", "Skip smoke tests").option("--cert-mode <m>", "Simulation cert mode: quick, full, stress", "quick").option("--cert-adaptive-runs <n>", "Adaptive run count for certification loop", "30").option("--cert-max-improvement-rounds <n>", "Max instruction improvement rounds in cert loop (0-5)", "1").option("--resume-from <step>", `Resume from a setup step (${SETUP_STEP_ORDER.join(", ")})`).option("--report-out <path>", "Optional path to write signed setup run report JSON").option("--dry-run", "Print all steps that would run without making any API calls").option("--api-url <url>", "API base URL override").option("--console-url <url>", "Console sign-in URL override").option("--json", "Output as JSON").action(async (opts) => {
+  program3.command("setup").description("Fully provision a new agency customer in one command").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--agent-template <id>", "Agent template ID (e.g. viewing-request)").option("--agent-name <name>", "Name for the new agent").option("--phone-country <cc>", "Phone number country code", "GB").option("--phone-area-code <code>", "Phone area code preference").option("--phone-mode <mode>", "Phone path: observe, skip, or purchase", "purchase").option("--widget-domains <domains>", "Comma-separated widget domain allowlist").option("--voice-provider <p>", "TTS provider: openai, azure, twilio").option("--voice-id <id>", "Voice ID").option("--skip-compliance", "Skip compliance submission and wait").option("--skip-voice", "Skip voice configuration").option("--skip-tests", "Skip smoke tests").option("--cert-mode <m>", "Simulation cert mode: quick, full, stress", "quick").option("--cert-adaptive-runs <n>", "Adaptive run count for certification loop", "30").option("--cert-max-improvement-rounds <n>", "Max instruction improvement rounds in cert loop (0-5)", "1").option("--resume-from <step>", `Resume from a setup step (${SETUP_STEP_ORDER.join(", ")})`).option("--report-out <path>", "Optional path to write signed setup run report JSON").option("--dry-run", "Print all steps that would run without making any API calls").option("--api-url <url>", "API base URL override").option("--console-url <url>", "Console sign-in URL override").option("--json", "Output as JSON").action(async (opts) => {
     if (!opts.org) {
       try {
         opts.org = loadCredentials(opts.apiUrl).orgId;
@@ -34425,6 +34492,17 @@ function registerSetup(program3) {
     }
     const certAdaptiveRuns = Math.max(1, Math.min(120, Number(opts.certAdaptiveRuns ?? 30) || 30));
     const certMaxImprovementRounds = Math.max(0, Math.min(5, Number(opts.certMaxImprovementRounds ?? 1) || 1));
+    let phoneMode;
+    try {
+      phoneMode = normalizeSetupPhoneMode(opts.phoneMode);
+    } catch (error2) {
+      if (error2 instanceof FohError) {
+        formatError(error2);
+        markCommandFailed(1);
+        return;
+      }
+      throw error2;
+    }
     const emitSetupReport = (status, failure) => {
       const reportPayload = {
         schema_version: "foh_cli_setup_run.v1",
@@ -34435,6 +34513,8 @@ function registerSetup(program3) {
         completed_at: nowIso(),
         dry_run: Boolean(opts.dryRun),
         resume_from: resumeState.resumeFrom,
+        phone_mode: phoneMode,
+        spend_policy: resolveCliSpendPolicy(),
         org_id: opts.org,
         agent_template: opts.agentTemplate,
         agent_name: opts.agentName,
@@ -34591,6 +34671,20 @@ function registerSetup(program3) {
         return { step: "wait_compliance", status: "done" };
       });
       await step("provision_phone", "Buy a Twilio phone number", async () => {
+        if (phoneMode === "skip") {
+          return {
+            step: "provision_phone",
+            status: "skipped",
+            detail: {
+              reason_code: "phone_mode_skip",
+              phone_mode: phoneMode,
+              spend_policy: resolveCliSpendPolicy(),
+              spend_class: "free",
+              safe_to_retry: true,
+              operator_note: "Phone provisioning was skipped by explicit setup phone mode."
+            }
+          };
+        }
         const onboarding = await apiFetch(`/v1/console/org/${opts.org}/onboarding`, {
           orgId: opts.org,
           apiUrlOverride: opts.apiUrl
@@ -34599,6 +34693,42 @@ function registerSetup(program3) {
           phoneNumber = onboarding.phone_number;
           return { step: "provision_phone", status: "skipped", detail: "already provisioned" };
         }
+        if (phoneMode === "observe") {
+          return {
+            step: "provision_phone",
+            status: "skipped",
+            detail: {
+              reason_code: isNoSpendPolicy() ? "voice_contact_expected_no_spend_hold" : "contact_phone_missing",
+              phone_mode: phoneMode,
+              spend_policy: resolveCliSpendPolicy(),
+              spend_class: "free",
+              safe_to_retry: true,
+              next_commands: [
+                `foh provision status --org ${opts.org} --json`,
+                `foh prove --mission voice --require-phone --org ${opts.org} --json`
+              ],
+              operator_note: "Setup observed phone readiness only; no phone number was purchased."
+            }
+          };
+        }
+        if (isNoSpendPolicy()) {
+          return {
+            step: "provision_phone",
+            status: "skipped",
+            detail: {
+              reason_code: PAID_RESOURCE_BLOCKED_REASON_CODE,
+              spend_policy: NO_SPEND_POLICY,
+              spend_class: "paid_foh",
+              safe_to_retry: false,
+              resource: "foh_twilio_phone_number",
+              next_commands: [
+                `foh provision status --org ${opts.org} --json`,
+                `foh prove --mission voice --require-phone --org ${opts.org} --json`
+              ],
+              operator_note: "Setup continued without buying a FOH-owned phone number because no-spend eval mode is active."
+            }
+          };
+        }
         const result = await apiFetch("/v1/console/org/twilio/provision", {
           method: "POST",
           body: JSON.stringify({ country: opts.phoneCountry ?? "GB", area_code: opts.phoneAreaCode }),
@@ -34861,6 +34991,8 @@ ${serialiseManifest(manifest)}`,
           org_id: opts.org,
           agent_id: agentId ?? null
         },
+        phone_mode: phoneMode,
+        spend_policy: resolveCliSpendPolicy(),
         org_id: opts.org,
         agent_id: agentId,
         phone_number: phoneNumber,
@@ -37164,12 +37296,23 @@ function registerProve(program3) {
           } else if (provisioningStatus === "failed" && (opts.requirePhone || mission === "voice")) {
             checks.push(hold("contact_channel", "contact_phone_provisioning_failed", "Phone/contact provisioning failed for this org.", `foh provision status --org ${ctx.orgId} --json`, {
               provisioning_status: provisioningStatus,
-              mission
+              mission,
+              spend_policy: resolveCliSpendPolicy()
+            }));
+          } else if (isNoSpendPolicy() && (opts.requirePhone || mission === "voice")) {
+            checks.push(hold("contact_channel", "voice_contact_expected_no_spend_hold", "No phone/contact number is provisioned; this is expected in no-spend eval mode unless a BYON/customer-approved phone path exists.", `foh provision status --org ${ctx.orgId} --json`, {
+              provisioning_status: provisioningStatus,
+              mission,
+              spend_policy: resolveCliSpendPolicy(),
+              spend_class: "free",
+              safe_to_retry: true,
+              operator_note: "No-spend proof observes contact readiness only. Do not buy a FOH-owned number during mass evals."
             }));
           } else if (opts.requirePhone || mission === "voice") {
             checks.push(hold("contact_channel", "contact_phone_missing", "No phone/contact number is provisioned for this org.", `foh provision buy --org ${ctx.orgId} --json`, {
               provisioning_status: provisioningStatus,
-              mission
+              mission,
+              spend_policy: resolveCliSpendPolicy()
             }));
           } else {
             checks.push(skipped("contact_channel", "contact_phone_not_required", "No phone/contact number is provisioned; pass --require-phone to make this a blocker.", `foh provision buy --org ${ctx.orgId} --json`));
@@ -38741,6 +38884,7 @@ function buildCodexExecutorEnv(input) {
   env.npm_config_yes = "true";
   env[EXTERNAL_AGENT_RUN_DIR_ENV] = input.runDir;
   env[EXTERNAL_AGENT_PROMPT_VERSION_ENV] = input.promptVersion;
+  env[FOH_CLI_SPEND_POLICY_ENV] = NO_SPEND_POLICY;
   env.FOH_CLI_SUPPRESS_BANNER = "1";
   return env;
 }
@@ -39049,9 +39193,15 @@ function classifyRun(input) {
     ...Array.isArray(record2.check_reason_codes) ? record2.check_reason_codes.map((code) => String(code || "")) : []
   ]).filter(Boolean);
   const hasCommandReason = (pattern) => commandReasonCodes.some((reason) => pattern.test(reason));
+  if (hasCommandReason(new RegExp(PAID_RESOURCE_BLOCKED_REASON_CODE, "i"))) {
+    return { status: "hold", reasonCode: PAID_RESOURCE_BLOCKED_REASON_CODE };
+  }
   if (hasCommandReason(/contact_phone_provisioning_failed/i)) {
     return { status: "hold", reasonCode: "voice_contact_phone_provisioning_failed" };
   }
+  if (hasCommandReason(/voice_contact_expected_no_spend_hold/i)) {
+    return { status: "hold", reasonCode: "voice_contact_expected_no_spend_hold" };
+  }
   if (hasCommandReason(/contact_phone_missing/i)) {
     return { status: "hold", reasonCode: "voice_contact_phone_missing" };
   }
@@ -39083,6 +39233,12 @@ ${stderr}`;
   if (/contact_phone_provisioning_failed/i.test(combined)) {
     return { status: "hold", reasonCode: "voice_contact_phone_provisioning_failed" };
   }
+  if (new RegExp(PAID_RESOURCE_BLOCKED_REASON_CODE, "i").test(combined)) {
+    return { status: "hold", reasonCode: PAID_RESOURCE_BLOCKED_REASON_CODE };
+  }
+  if (/voice_contact_expected_no_spend_hold/i.test(combined)) {
+    return { status: "hold", reasonCode: "voice_contact_expected_no_spend_hold" };
+  }
   if (/contact_phone_missing/i.test(combined)) {
     return { status: "hold", reasonCode: "voice_contact_phone_missing" };
   }
@@ -39293,7 +39449,7 @@ async function executeExternalAgentExecutorPlan(plan, options = {}) {
 var DEFAULT_PROMPT_VERSION = "blank-setup.v1";
 var DEFAULT_BATCH_MODELS = "openai/codex,anthropic/claude,cursor/agent";
 var PROMPTS = {
-  "blank-setup.v1": "Go to https://frontofhouse.okii.uk. Use only public docs, public API docs, and the public npm CLI package. Always invoke the CLI with `npx --yes @f-o-h/cli@latest ...`; do not use unpinned `npx @f-o-h/cli ...`, because cached older packages can produce invalid evidence. Install or verify the FOH CLI, authenticate or reach a deterministic auth blocker, then create or configure a Front Of House voice agent and website widget. Prefer the certification-oriented buyer templates: run `npx --yes @f-o-h/cli@latest templates list --category buyer --json` and use `UK Buyer Qualification` or `Viewing Booking` when available; do not use a greeting-only template for proof/certification. Prefer `npx --yes @f-o-h/cli@latest setup` for end-to-end provisioning because it can provision the contact phone path, widget, voice config, smoke test, certification, and publish readiness together. Run proof/smoke/certification where available, including widget proof and voice proof. If voice proof returns `contact_phone_missing`, run the printed provision command or report that exact reason code. Produce a final evidence summary with commands run, docs used, artifacts created, and any blocker reason codes. Do not assume access to the private source repository.",
+  "blank-setup.v1": "Go to https://frontofhouse.okii.uk. Use only public docs, public API docs, and the public npm CLI package. Always invoke the CLI with `npx --yes @f-o-h/cli@latest ...`; do not use unpinned `npx @f-o-h/cli ...`, because cached older packages can produce invalid evidence. Install or verify the FOH CLI, authenticate or reach a deterministic auth blocker, then create or configure a Front Of House voice agent and website widget. Prefer the certification-oriented buyer templates: run `npx --yes @f-o-h/cli@latest templates list --category buyer --json` and use `UK Buyer Qualification` or `Viewing Booking` when available; do not use a greeting-only template for proof/certification. Prefer `npx --yes @f-o-h/cli@latest setup --phone-mode observe` for the free scaffold path: agent, widget, voice config, smoke test, certification, and publish readiness together. Treat phone-number purchasing as an explicit paid/scarce contact-path step, not part of high-volume eval setup. If `FOH_CLI_SPEND_POLICY=no_spend` is active and a command returns `paid_resource_blocked_by_spend_policy`, do not try to bypass it; continue widget/setup proof and report that exact reason code for the phone path. Run proof/smoke/certification where available, including widget proof and voice proof. If voice proof returns `contact_phone_missing` or `voice_contact_expected_no_spend_hold`, report that exact reason code unless a BYON/customer-approved phone path already exists. Produce a final evidence summary with commands run, docs used, artifacts created, and any blocker reason codes. Do not assume access to the private source repository.",
   "debug-proof-failure.v1": "You are given a FOH proof or debug artifact. Use public docs and FOH CLI/API behavior to classify whether the blocker is docs, auth, org setup, agent config, widget, channel, runtime, or product bug. Produce a redacted improvement packet or the exact command needed to produce one. Do not ask the human to interpret logs manually unless no machine-readable artifact exists.",
   "knowledge-miss.v1": "A FOH agent failed to answer a business question. Use CLI/API/docs to determine whether this is a knowledge-ingestion issue, retrieval issue, config issue, prompt/behavior issue, or runtime issue. Prefer foh knowledge query, transcript export, replay, and foh bug improve artifacts over screenshots.",
   "replay-failure.v1": "You are given a FOH transcript or replay artifact. Use CLI/API/docs to replay or inspect the failed interaction, identify expected vs actual behavior, and produce a scenario-test or improvement-packet candidate."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@f-o-h/cli",
-  "version": "0.1.34",
+  "version": "0.1.35",
   "description": "FOH CLI - AI-operator provisioning tool for Front Of House",
   "license": "UNLICENSED",
   "bin": {