@f-o-h/cli 0.1.51 → 0.1.53

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
 
@@ -133,13 +143,26 @@ foh eval external-agent run \
   --prompt-version blank-setup.v1
 ```
 
-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.
+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 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
+
+| Mission | Command |
+|---|---|
+| Start | `foh start` |
+| Setup | `foh setup --phone-mode observe --json` |
+| Prove | `foh prove --agent <agent_id> --mission widget --json` |
+| Debug | `foh debug --out test-results/foh-cli-diag.latest.json --json` |
+| Improve | `foh bug improve --from-file <artifact.json> --json` |
+| Publish | `foh agent publish --agent <agent_id> --json` |
 
 For a planted knowledge-miss benchmark:
 

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.51";
+var CLI_VERSION = "0.1.53";
 
 // src/commands/mcp-serve.ts
 var DEFAULT_TIMEOUT_MS = 12e4;
@@ -36486,7 +36515,7 @@ function toErrorRecord(error2) {
   return { message: String(error2) };
 }
 function registerDiag(program3) {
-  program3.command("diag").description("Collect support diagnostics bundle for current CLI/API context").requiredOption("--out <path>", "Write diagnostics bundle JSON to this file path").option("--org <id>", "Org ID to probe (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as machine-readable JSON").action(async (opts) => {
+  program3.command("diag").alias("debug").description("Collect support diagnostics bundle for current CLI/API context").requiredOption("--out <path>", "Write diagnostics bundle JSON to this file path").option("--org <id>", "Org ID to probe (default: stored org from foh org use)").option("--api-url <url>", "API base URL override").option("--json", "Output as machine-readable JSON").action(async (opts) => {
     try {
       const checks = [];
       const generatedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -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: {
@@ -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."
   };
 }
@@ -40506,6 +40545,28 @@ function installSoftExitTrap() {
   });
 }
 
+// src/lib/mission-help.ts
+var CLI_MISSION_EXAMPLES = [
+  { mission: "Start", command: "foh start", description: "guided setup and next action selector" },
+  { mission: "Setup", command: "foh setup --phone-mode observe --json", description: "create or update agent, widget, voice config, and proof scaffold" },
+  { mission: "Prove", command: "foh prove --agent <agent_id> --mission widget --json", description: "produce a machine-readable proof report" },
+  { mission: "Debug", command: "foh debug --out test-results/foh-cli-diag.latest.json --json", description: "collect auth/org/API diagnostics" },
+  { mission: "Improve", command: "foh bug improve --from-file <artifact.json> --json", description: "convert a failure artifact into a redacted improvement packet" },
+  { mission: "Publish", command: "foh agent publish --agent <agent_id> --json", description: "publish after proof gates pass" }
+];
+function missionHelpText() {
+  return [
+    "",
+    "Common missions:",
+    ...CLI_MISSION_EXAMPLES.map((item) => `  ${item.command.padEnd(66)} ${item.description}`),
+    "",
+    "For AI agents: prefer --json and follow next_commands exactly when a command blocks."
+  ].join("\n");
+}
+function addMissionHelp(program3) {
+  program3.addHelpText("afterAll", missionHelpText());
+}
+
 // src/index.ts
 installSoftExitTrap();
 installExternalAgentCliCompletionRecorder(recordExternalAgentCliInvocation({ argv: process.argv, cliVersion: CLI_VERSION }));
@@ -40563,6 +40624,7 @@ function writeKnownError(message, remediation) {
 `);
 }
 program2.name("foh").description("Front Of House CLI - AI-operator provisioning tool").version(CLI_VERSION).option("--json", "Output as machine-readable JSON").option("--api-url <url>", "Internal API base URL override (operators only)").option("--no-color", "Disable colour output");
+addMissionHelp(program2);
 registerAuth(program2);
 registerOrg(program2);
 registerTenant(program2);

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.51",
+  "version": "0.1.53",
   "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