@f-o-h/cli 0.1.52 → 0.1.54

package/README.md

@@ -106,11 +106,21 @@ 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.
 
-If managed-number provisioning is blocked by account/provider capacity or empty
-reserve inventory, proof reports `provider_capacity_blocked`; fix capacity or
-switch to BYON rather than retrying blindly.
-
-The CLI defaults to the production API at `https://api.frontofhouse.okii.uk`.
+If managed-number provisioning is blocked by account/provider capacity or empty
+reserve inventory, proof reports `provider_capacity_blocked`; fix capacity or
+switch to BYON rather than retrying blindly.
+
+Attach a customer-owned voice number without FOH purchasing inventory:
+
+```bash
+foh provision byon attach --phone-number <e164> --confirm-owned --org <org-id> --json
+```
+
+The attach command requires explicit ownership confirmation, writes the org's
+voice channel, returns Twilio webhook URLs, and preserves the cost boundary:
+the customer owns the number/provider account.
+
+The CLI defaults to the production API at `https://api.frontofhouse.okii.uk`.
 
 ## External-Agent Eval Capture
 
@@ -137,9 +147,11 @@ The command writes a versioned prompt, launches an instrumented shell, captures
 FOH CLI commands into `commands.ndjson`, and finalizes `run.json` as an
 `external_agent_run.v1` artifact when the shell exits.
 
-Run artifacts include `eval_state` so repeated benchmark runs make reuse
-explicit: org, agent, and widget reuse are expected; fresh paid phone-number
-creation is not expected.
+Run artifacts include `eval_state` so repeated benchmark runs make lifecycle
+intent explicit: reuse the existing eval org, agent, and widget by default;
+create ephemeral orgs only for explicit lifecycle tests; do not create paid
+phone resources unless a BYON/customer-owned or operator-approved paid lane is
+selected.
 
 ## Common Missions
 

package/dist/foh.js

@@ -11164,6 +11164,35 @@ function registerProvision(program3) {
     });
     format(data, { json: opts.json ?? false });
   }));
+  const byon = provision.command("byon").description("Attach a customer-owned voice number without FOH number purchase");
+  byon.command("attach").description("Attach a customer-owned Twilio/voice number to the current org").requiredOption("--phone-number <e164>", "Customer-owned E.164 phone number, for example +447700900000").option("--twilio-sid <sid>", "Optional Twilio phone number SID reference").option("--twilio-account-sid <sid>", "Optional customer Twilio account SID reference; only a suffix is stored in metadata").option("--label <label>", "Optional human label for this BYON contact path").option("--confirm-owned", "Confirm the customer controls this number and authorizes attachment").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
+    const resolvedOrg = requiredOrg2(opts, "provision.byon.attach");
+    if (!opts.confirmOwned) {
+      format({
+        ok: false,
+        status: "blocked",
+        reason_code: "ownership_confirmation_required",
+        safe_to_retry: false,
+        remediation: "Retry only after the customer confirms ownership: foh provision byon attach --phone-number <e164> --confirm-owned --org <org> --json"
+      }, { json: opts.json ?? false });
+      markCommandFailed(1);
+      return;
+    }
+    const data = await apiFetch("/v1/console/org/twilio/byon/attach", {
+      method: "POST",
+      body: JSON.stringify({
+        phone_number: opts.phoneNumber,
+        twilio_sid: opts.twilioSid,
+        twilio_account_sid: opts.twilioAccountSid,
+        label: opts.label,
+        ownership_confirmed: true
+      }),
+      headers: { "Idempotency-Key": `foh-cli-byon-attach:${(0, import_crypto.randomUUID)()}` },
+      orgId: resolvedOrg,
+      apiUrlOverride: opts.apiUrl
+    });
+    format(data, { json: opts.json ?? false });
+  }));
   provision.command("status").description("Show provisioning status for an org").option("--org <id>", "Org ID (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as JSON").action(async (opts) => withCommandErrorHandling(async () => {
     const resolvedOrg = requiredOrg2(opts, "provision.status");
     const data = await apiFetch(`/v1/console/org/${resolvedOrg}/onboarding`, {
@@ -32801,7 +32830,7 @@ var StdioServerTransport = class {
 };
 
 // src/lib/cli-version.ts
-var CLI_VERSION = "0.1.52";
+var CLI_VERSION = "0.1.54";
 
 // src/commands/mcp-serve.ts
 var DEFAULT_TIMEOUT_MS = 12e4;
@@ -39794,14 +39823,19 @@ function buildExecutedRunArtifact(input) {
     commands_run: commands.map((command) => command.command),
     docs_pages_used: agentMetadata.docs_pages_used,
     eval_state: {
+      lifecycle_strategy: "reuse_existing_eval_state",
       org_reuse_expected: true,
       agent_reuse_expected: true,
       widget_reuse_expected: true,
       fresh_org_expected: false,
+      ephemeral_org_expected: false,
       fresh_agent_expected: false,
       phone_purchase_expected: false,
       paid_resource_creation_expected: false,
       spend_policy_expected: NO_SPEND_POLICY,
+      cleanup_expected: false,
+      cleanup_strategy: "no_cleanup_for_reused_eval_state",
+      paid_resource_strategy: "blocked_unless_explicit_byon_or_operator_approved",
       rationale: "Mass external-agent evals benchmark public docs/CLI/API clarity; reuse avoids paid phone and Twilio inventory churn."
     },
     artifacts: {
@@ -40003,7 +40037,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 --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. When running more than one `foh prove` mission for the same agent, pass `--proof-cache-dir .foh/proof-cache` so simulation certification can be shared instead of recomputed. 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. If `FOH_EXTERNAL_AGENT_RUN_DIR` is set, write `${FOH_EXTERNAL_AGENT_RUN_DIR}/external-agent-metadata.json` with `schema_version`, `docs_pages_used`, key decisions, and blocker reason codes before finishing. 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. If the customer/operator explicitly owns a number and asks for real PSTN proof, use `npx --yes @f-o-h/cli@latest provision byon attach --phone-number <e164> --confirm-owned --json`; do not invent ownership or buy a FOH-owned number. Run proof/smoke/certification where available, including widget proof and voice proof. When running more than one `foh prove` mission for the same agent, pass `--proof-cache-dir .foh/proof-cache` so simulation certification can be shared instead of recomputed. 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. If `FOH_EXTERNAL_AGENT_RUN_DIR` is set, write `${FOH_EXTERNAL_AGENT_RUN_DIR}/external-agent-metadata.json` with `schema_version`, `docs_pages_used`, key decisions, and blocker reason codes before finishing. 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."
@@ -40108,14 +40142,19 @@ function writeSession(runDir, session) {
 }
 function buildDefaultEvalState() {
   return {
+    lifecycle_strategy: "reuse_existing_eval_state",
     org_reuse_expected: true,
     agent_reuse_expected: true,
     widget_reuse_expected: true,
     fresh_org_expected: false,
+    ephemeral_org_expected: false,
     fresh_agent_expected: false,
     phone_purchase_expected: false,
     paid_resource_creation_expected: false,
     spend_policy_expected: "no_spend",
+    cleanup_expected: false,
+    cleanup_strategy: "no_cleanup_for_reused_eval_state",
+    paid_resource_strategy: "blocked_unless_explicit_byon_or_operator_approved",
     rationale: "Mass external-agent evals benchmark public docs/CLI/API clarity; reuse avoids paid phone and Twilio inventory churn."
   };
 }

package/examples/external-agent-run.example.json

@@ -39,14 +39,19 @@
     "https://frontofhouse.okii.uk/guides/error-handling-and-debugging"
   ],
   "eval_state": {
+    "lifecycle_strategy": "reuse_existing_eval_state",
     "org_reuse_expected": true,
     "agent_reuse_expected": true,
     "widget_reuse_expected": true,
     "fresh_org_expected": false,
+    "ephemeral_org_expected": false,
     "fresh_agent_expected": false,
     "phone_purchase_expected": false,
     "paid_resource_creation_expected": false,
     "spend_policy_expected": "no_spend",
+    "cleanup_expected": false,
+    "cleanup_strategy": "no_cleanup_for_reused_eval_state",
+    "paid_resource_strategy": "blocked_unless_explicit_byon_or_operator_approved",
     "rationale": "Mass external-agent evals benchmark public docs/CLI/API clarity; reuse avoids paid phone and Twilio inventory churn."
   },
   "artifacts": {

package/package.json

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

package/schemas/external-agent-run.schema.json

@@ -70,14 +70,19 @@
     "eval_state": {
       "type": "object",
       "properties": {
+        "lifecycle_strategy": { "type": "string" },
         "org_reuse_expected": { "type": "boolean" },
         "agent_reuse_expected": { "type": "boolean" },
         "widget_reuse_expected": { "type": "boolean" },
         "fresh_org_expected": { "type": "boolean" },
+        "ephemeral_org_expected": { "type": "boolean" },
         "fresh_agent_expected": { "type": "boolean" },
         "phone_purchase_expected": { "type": "boolean" },
         "paid_resource_creation_expected": { "type": "boolean" },
         "spend_policy_expected": { "type": "string" },
+        "cleanup_expected": { "type": "boolean" },
+        "cleanup_strategy": { "type": "string" },
+        "paid_resource_strategy": { "type": "string" },
         "rationale": { "type": "string" }
       },
       "additionalProperties": true