@seldonframe/mcp 1.27.10 → 1.28.0

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@seldonframe/mcp",
-  "version": "1.27.10",
+  "version": "1.28.0",
+  "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.28.0: BUILD_WEBSITE_CHATBOT SKILL BUNDLE + BYOK ENV AUTO-DETECT — Phase B of the Karpathy/antifragility refactor (sugar over primitives). PROBLEM: even after v1.27.x's tool-discovery doc upgrade, the canonical 'build me a chatbot for [business]' flow still required ~5 sequential MCP calls (configure_llm_provider → create_agent → publish_agent test → operator sandbox-tests → publish_agent live), each round-tripping through Vercel. ~30s wall time. BYOK setup added a key-paste step every time even though most Claude Code users already have ANTHROPIC_API_KEY set in their shell. WHAT SHIPS: (1) BYOK ENV AUTO-DETECT. configure_llm_provider gains a 'pass nothing / pass api_key=\"env\"' mode. The MCP server reads process.env.ANTHROPIC_API_KEY (or OPENAI_API_KEY for provider='openai') from its OWN local environment — which is the user's shell where Claude Code launched. Most Claude Code users already have this set (it's how Claude Code itself works). Returns { ok: false, error: 'no_env_key' } with a clear hint if the env var isn't set. The handler annotates ok=true responses with source='env_inherited' vs source='explicit' so the LLM can tell the user 'I auto-detected your Anthropic key from your shell environment' instead of 'I saved the key you provided.' WHITE-LABEL ESCAPE HATCH: pass api_key explicitly when an agency manages multiple operators with separate Anthropic billing (env auto-detect would use the agency's key for every operator — wrong for billing isolation). (2) NEW SKILL-BUNDLE TOOL build_website_chatbot. ONE call wraps the canonical 4-step sequence: configure_llm_provider (auto-detects env if no anthropic_api_key passed) → create_agent (archetype='website-chatbot', channel='web_chat', with faq + pricing_facts + greeting from args) → publish_agent (status='test', sandbox-callable, eval gate doesn't run yet) → returns { agent, embed_url, turn_url, dashboard_url, sandbox_url, steps[], next_steps[] }. Each internal step's success/failure surfaces in the steps array so the LLM can report cleanly. Partial-success handling: if create_agent succeeds but publish fails, returns the created agent + a clear next_step to publish manually. Reduces typical 'create chatbot for HVAC' from 5 round-trips + ~30s to 1 round-trip + ~5s. (3) WELCOME.JS CAPABILITY MAP UPDATED. The 'add a chatbot to my website' row now points at build_website_chatbot instead of create_agent. Canonical short flow walkthrough rewritten to show the 1-call version. FIRST_CALL_BANNER similarly updated. Primitives stay fully callable for custom flows (different archetype, custom capability allowlist, multi-step blueprint construction); the bundle is just sugar over them. PHILOSOPHY (Karpathy / antifragile / thin-harness-fat-skill): the bundle is sugar, not a replacement. Primitives stay clean — operators on Claude Code with sufficient model capability can still call them directly for nuanced flows. As Claude gets better at orchestrating the 4-call sequence itself, the bundle becomes less necessary but still works. Smaller models or one-shot prompts lean on the bundle; larger models orchestrate primitives. Same architecture serves both. NO new HTTP endpoints (build_website_chatbot uses existing /api/v1/agents ops via the MCP-tool layer). NO migrations, NO new env vars on the server side. ENCRYPTION_KEY still required (already shipped). DEFERRED to v1.28.1: embed widget polish (markdown rendering, mobile-first responsive, brand inheritance, a11y, action chips). DEFERRED to v1.28.2: skill-pack architecture (move inline behavioral guidance from prompt.ts to agents/<archetype>/skills/*.md files the composer reads on demand). DEFERRED to v1.28.3: post-booking 24h reminder via Vercel Workflows (first SF use of Workflows for a new durable flow). EXPECTED IMPACT: 'create a chatbot for Cypress Pine HVAC with these FAQ + pricing facts' resolves in ~5s with one tool call, instead of ~30s with 5 sequential calls. Operator sees one consolidated next-steps list (sandbox-test, run evals, publish-live, drop embed snippet) instead of having to compose them mentally across 5 separate responses.",
   "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.27.10: HALLUCINATED-STATE-CHANGE VALIDATOR (CRM-side; MCP package version bumped for SemVer hygiene). PROBLEM: even after v1.27.8 (added reschedule_appointment + cancel_appointment tools + system-prompt rule 'NEVER claim an action you didn't take'), real-world dogfood STILL caught the agent hallucinating. Conversation: 'Done! You're rescheduled for tomorrow, May 8 at 1pm. See you then, Maxime!' But database wasn't updated; contact's bookings page still showed May 21. Two failure paths converge here: (a) the existing Cypress Pine agent's blueprint was created in v1.26.x with the ORIGINAL 5 capabilities — v1.27.8 added the new tools to DEFAULTS for new agents but deliberately didn't auto-mutate existing operator blueprints. So the LLM never had reschedule_appointment in its tool list — system prompt told it 'you MUST call reschedule_appointment' (which doesn't exist for it), contradictory state, LLM picked 'claim success' over 'tell user we can't.' (b) Even when the capability IS there, system prompts aren't 100% reliable — Claude can still hallucinate completion claims. Both paths produce the same critical-failure: customer is told the booking moved when it didn't. ARCHITECTURAL FIX (defense in depth at the runtime layer, since system-prompt rules alone are insufficient): a new critical validator that catches the hallucination regardless of WHY it happened. WHAT SHIPS: (1) NEW VALIDATOR no_hallucinated_state_change. ValidatorContext gains turnToolCalls + turnToolResults (this turn's tool activity). The validator scans the response for completion phrases mapped to required tool calls: 'rescheduled / moved your appointment / appointment moved / new time is set / see you (then|tomorrow|<weekday>)' → requires reschedule_appointment with ok=true; 'cancelled your appointment / cancellation confirmed' → requires cancel_appointment; 'you're booked / appointment confirmed / I've booked' → requires book_appointment; 'team will follow up / I've passed this on / someone will reach out' → requires escalate_to_human. If the response claims completion AND the matching tool was NOT called with ok=true this turn, fail critical. The runtime then replaces the response with the safe fallback ('let me check'). Customer NEVER hears a fabricated state change. (2) ALL_VALIDATORS array gains the new validator. Existing 5 validators unchanged. (3) RUNTIME passes allToolCalls + allToolResults from the turn loop into runValidators. NO migrations, NO new env vars, NO MCP tool changes. Backend redeploy required. EXPECTED IMPACT on the conversation that triggered this fix: even if the agent's blueprint still doesn't have reschedule_appointment in capabilities (the v1.27.8 manual-backfill step the user hasn't done yet), the runtime will catch the hallucinated 'rescheduled!' response and replace with the safe fallback — customer hears 'let me check on that' instead of being lied to. Once the user backfills their agent's capabilities (call update_agent_blueprint from Claude Code with the full 7-tool list, or tick the 2 new boxes in /agents/<id>/settings + Save), the agent will ACTUALLY call reschedule_appointment and the booking will move. Belt + suspenders: even if the LLM lies despite having the tool, the validator catches it. As Claude gets better at not hallucinating actions, this validator fires less and less; architecture stable.",
   "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.27.9: REMOVE DAILY TOKEN BUDGET (CRM-side; MCP package version bumped for SemVer hygiene). PROBLEM: real-world dogfood reschedule conversation halted with 'RUNTIME ERROR · DAILY_BUDGET_EXHAUSTED — Token budget 92% used (45,855 / 50,000 tokens today)'. The artificial cap broke a perfectly valid conversation. The cap was a v1.26.0 design artifact from when SF was going to resell LLM at markup — it protected SF from runaway cost exposure. Under BYOK (since v1.26.1), the OPERATOR pays Anthropic directly. SF has zero cost exposure. The cap is now: (a) irrelevant for SF (no cost to protect), (b) confusing for operators (they have an Anthropic billing dashboard for this), and (c) actively harmful (artificial halts on busy days with plenty of Anthropic credits available). FIX: remove the budget mechanism entirely. WHAT SHIPS: (1) RUNTIME: dropped the isDailyBudgetExhausted() check at step 2 of executeTurn. Dropped the 'daily_budget_exhausted' fallback reason code. Dropped the 'agents.tokensUsedToday + dailyTokenBudget' aggregate increment. Per-turn tokensIn/tokensOut still persist on agent_turns rows for cost analytics + observability — that data stays useful even when SF doesn't bill on it. The isDailyBudgetExhausted helper function deleted. (2) AGENT OVERVIEW: dropped the 'Daily token usage' card with progress bar. Token-budget concept is gone from the UI; the at-a-glance health stat row (24h conversations, validator pass rate, eval pass rate, avg latency) stays. (3) SANDBOX PRE-FLIGHT: dropped the budget pre-flight checks (block-level when 100% used + warning-level at 80%). Anthropic-key pre-flight check stays (still relevant; no key = no chat). (4) AGENT LIST: dropped the 'Tokens today: X / 50,000 (X%)' line on each agent row. Cleaner display. (5) DB SCHEMA UNCHANGED. agents.tokensUsedToday + dailyTokenBudget + tokensUsedResetAt columns stay (no migration; future-proof for if we ever want to surface 'cost spent today' analytics). They're just no longer read or written by the runtime. NO migrations, NO new env vars. Backend redeploy required. EXPECTED IMPACT on the conversation that triggered this fix: the agent will no longer halt mid-turn with DAILY_BUDGET_EXHAUSTED. Conversations run as long as the operator's Anthropic key has credits. Operators see their actual spend on their Anthropic dashboard, not an artificial SF-imposed limit. Simpler architecture, fewer concepts.",
   "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.27.8: RESCHEDULE/CANCEL TOOLS + ANTI-HALLUCINATION RULE (CRM-side; MCP package version bumped for SemVer hygiene). PROBLEM: real-world dogfood reschedule conversation went perfectly UX-wise — agent asked the right questions, resolved 'next Monday at 2pm', confirmed, said 'Perfect! Your appointment has been rescheduled to Monday, May 12 at 2:00 PM. You'll receive a confirmation email at dresslikeag@gmail.com.' But the database wasn't actually updated. Customer's contact-detail page in the operator's CRM still showed the OLD May 21 booking. The agent had hallucinated success. WHY: the website-chatbot archetype's default capabilities were [look_up_availability, book_appointment, find_my_existing_appointment, escalate_to_human, provide_faq_answer]. There was NO reschedule_appointment OR cancel_appointment tool. The agent, when asked to reschedule, found the booking via find_my_existing_appointment, then had no actual mutation path — but rather than escalate, it confidently fabricated the completion. ARCHITECTURAL FIX (two layers): the missing tools AND the missing constraint. WHAT SHIPS: (1) reschedule_appointment TOOL. New agent tool that ACTUALLY mutates bookings.startsAt + endsAt + updatedAt, atomic UPDATE WHERE id=booking_id AND orgId=ctx.orgId AND email=customer_email. The customer_email arg is a security check — a hallucinated bookingId from a different workspace can't slip through because the email won't match. Preserves duration (computes newEndsAt = newStartsAt + (oldEndsAt - oldStartsAt)). Returns { ok, bookingId, newStartsAt } on success, { ok: false, reason } on email mismatch / missing booking / invalid date. (2) cancel_appointment TOOL. New agent tool. UPDATE bookings SET status='cancelled' WHERE same triple-match (id, orgId, email). Same security model. (3) UPDATED DEFAULT CAPABILITIES. DEFAULT_CAPABILITIES_BY_ARCHETYPE in store.ts adds reschedule_appointment + cancel_appointment to website-chatbot, voice-receptionist, and sms-followup-bot. New agents created from v1.27.8 onwards include them automatically. (4) SETTINGS UI EXPOSES NEW CAPS. ALL_CAPABILITIES in /agents/[id]/settings/page.tsx adds the two new toggles. Existing agents (created pre-v1.27.8) need their operator to check the new boxes + Save to enable the tools — auto-mutation of existing blueprints is intentionally avoided. (5) ANTI-HALLUCINATION SYSTEM PROMPT RULE. The 'Be smart by default' section in composeSystemPrompt gains a new rule #6: 'NEVER claim an action you didn't actually take.' Explicit list: 'I rescheduled it' / 'Done, you're booked' / 'I cancelled it' / 'I let the team know' all REQUIRE the corresponding tool call (reschedule_appointment / book_appointment / cancel_appointment / escalate_to_human) with ok=true returned BEFORE the agent confirms to the visitor. Operator never authors this — platform owns it. As Claude gets better at avoiding action hallucinations, this rule becomes a hint instead of a crutch; architecture stable. NO migrations, NO new env vars. Backend redeploy required. EXISTING-AGENT MIGRATION: operators of pre-v1.27.8 agents need ONE manual step — open /agents/<id>/settings, tick the two new capability boxes (reschedule_appointment + cancel_appointment), Save. Or call update_agent_blueprint from Claude Code with the full new capabilities array. EXPECTED IMPACT on the conversation that triggered this fix: agent calls reschedule_appointment(booking_id=..., new_starts_at_iso='2026-05-12T14:00:00Z', customer_email='dresslikeag@gmail.com'), gets ok=true, THEN tells the visitor 'Done — you're now booked for Monday, May 12 at 2:00 PM.' The booking row actually moves. Operator's CRM contact-detail page reflects the new time.",

package/src/tools.js

@@ -4056,6 +4056,7 @@ export const TOOLS = [
       "The OPERATOR pays the LLM provider directly (Anthropic / OpenAI / etc.); SF charges separately for agent platform usage. " +
       "Stored encrypted at rest using the deployment's ENCRYPTION_KEY. " +
       "Operators get keys from console.anthropic.com (recommended for v1.26.x — best tool-use support) or platform.openai.com. " +
+      "v1.28+ AUTO-DETECT: pass api_key='env' (or omit api_key entirely) and the MCP server will read process.env.ANTHROPIC_API_KEY / OPENAI_API_KEY from its own environment. Most Claude Code users already have this set (it's how Claude Code works), so this lets a solo SF client onboard with zero key-paste step. Returns { ok: false, error: 'no_env_key' } if the env var isn't set; in that case the user must paste the key explicitly. " +
       "Skip if the workspace already has a key — agents fail-graceful with 'I'm not set up yet' if no key configured, so a 'not configured' chatbot response means CALL THIS TOOL.",
     inputSchema: obj(
       {
@@ -4067,21 +4068,50 @@ export const TOOLS = [
             "LLM provider. v1.26 ships full Anthropic support (tool use, streaming-ready). OpenAI support for chat is partial — recommend Anthropic for production agents.",
         },
         api_key: str(
-          "API key. Anthropic keys start with 'sk-ant-...'. Stored encrypted; never echoed back in responses.",
+          "API key. Anthropic keys start with 'sk-ant-...'. Stored encrypted; never echoed back. v1.28+ AUTO-DETECT: pass 'env' (literal string) or omit entirely to read process.env.{ANTHROPIC,OPENAI}_API_KEY from the MCP server's local environment.",
         ),
       },
-      ["workspace_id", "provider", "api_key"],
+      ["workspace_id", "provider"],
     ),
     handler: async (args) => {
       const ws = args.workspace_id;
+      let apiKey = args.api_key;
+
+      // v1.28 — auto-detect from MCP server's local environment.
+      // Triggered by: omitted api_key, empty string, or literal 'env'.
+      const wantsEnv = !apiKey || apiKey === "env" || apiKey === "$ENV";
+      if (wantsEnv) {
+        const envName =
+          args.provider === "openai" ? "OPENAI_API_KEY" : "ANTHROPIC_API_KEY";
+        apiKey = process.env[envName];
+        if (!apiKey) {
+          return {
+            ok: false,
+            error: "no_env_key",
+            hint:
+              `${envName} not set in the MCP server's environment. ` +
+              `Either: (a) set ${envName} in your shell before launching Claude Code (most Claude Code users already have this), ` +
+              `or (b) pass api_key='sk-ant-...' explicitly. ` +
+              `For platform-deployment scenarios where keys differ per workspace (e.g. agency managing multiple HVAC clients with separate Anthropic billing), always pass api_key explicitly — env auto-detect is for solo-operator convenience.`,
+            envName,
+          };
+        }
+      }
+
       const result = await api("POST", "/agents", {
         body: {
           op: "set_llm_key",
           provider: args.provider,
-          api_key: args.api_key,
+          api_key: apiKey,
         },
         workspace_id: ws,
       });
+      // v1.28 — annotate the response so the LLM knows whether env was used
+      // (so it can tell the user 'I auto-detected your key from your shell env'
+      // vs 'I saved the key you provided').
+      if (result && typeof result === "object" && result.ok) {
+        return { ...result, source: wantsEnv ? "env_inherited" : "explicit" };
+      }
       return result;
     },
   },
@@ -4256,6 +4286,199 @@ export const TOOLS = [
     },
   },
 
+  // ───────────────────────────────────────────────────────────────────────
+  // v1.28.0 — SKILL BUNDLE. Wraps the canonical 4-call chatbot-build
+  // sequence (configure_llm_provider → create_agent → publish_agent test
+  // → return embed snippet) into ONE call. Reduces ~30s + 4 round-trips
+  // to ~5s + 1 round-trip. Primitives stay fully callable for power users
+  // who need a custom flow; this is sugar.
+  // ───────────────────────────────────────────────────────────────────────
+
+  {
+    name: "build_website_chatbot",
+    description:
+      "USE WHEN USER SAYS: 'build me a chatbot for [business]', 'add a chatbot to my website', 'create a website chatbot', 'put a chat widget on my homepage', 'set up an AI assistant for my landing page'. " +
+      "ONE-CALL skill bundle that does the canonical chatbot setup end-to-end: " +
+      "(1) auto-configures the workspace's Anthropic LLM key from process.env.ANTHROPIC_API_KEY if no key is configured yet (most Claude Code users already have this set), or accepts an explicit anthropic_api_key arg; " +
+      "(2) creates a website-chatbot agent with the FAQ + pricing facts + greeting you provide; " +
+      "(3) publishes to status='test' so the operator can sandbox-test before going live (the eval gate runs only on 'live'); " +
+      "(4) returns the embed snippet, dashboard URL, and clear next-steps. " +
+      "USE THIS as the default for natural-language 'create a chatbot' requests. Fall back to the primitive tools (configure_llm_provider + create_agent + publish_agent) only when you need a custom flow (e.g. agency managing multiple operators with separate Anthropic billing — pass anthropic_api_key explicitly per workspace).",
+    inputSchema: obj(
+      {
+        workspace_id: str("Workspace id (bearer workspace)."),
+        name: str(
+          "Agent display name (e.g. 'Cypress & Pine HVAC Assistant'). Surfaces in chat header.",
+        ),
+        faq: {
+          type: "array",
+          description:
+            "Operator-curated FAQ pairs. Each item is { q, a }. Pass at least 3-5 covering the top customer questions: hours, service area, common issues, what to expect.",
+          items: obj(
+            {
+              q: str("Question as a visitor would phrase it."),
+              a: str("Operator's exact answer (1-3 sentences)."),
+            },
+            ["q", "a"],
+          ),
+        },
+        pricing_facts: {
+          type: "array",
+          description:
+            "ONLY prices the agent may quote. Critical for safety — without this, agent refuses ALL price questions (safer default). With this, agent can quote ONLY listed amounts; anything else gets validator-blocked. Each item: { label, amount, currency }.",
+          items: obj(
+            {
+              label: str("Service name (e.g. 'Service call', 'AC tune-up')."),
+              amount: { type: "number" },
+              currency: str("3-letter code, e.g. USD."),
+            },
+            ["label", "amount", "currency"],
+          ),
+        },
+        greeting: str(
+          "First message shown when chat opens (~120 chars). E.g. 'Hi! Asking about HVAC service in Phoenix? I can book you in or answer common questions.' Default if omitted: 'Hi! How can I help you today?'",
+        ),
+        anthropic_api_key: str(
+          "Optional explicit Anthropic API key (sk-ant-...). If omitted, reads from process.env.ANTHROPIC_API_KEY in the MCP server's environment. Pass explicitly for white-label scenarios (different operator = different Anthropic billing). Skipped entirely if the workspace already has a key configured.",
+        ),
+      },
+      ["workspace_id", "name"],
+    ),
+    handler: async (args) => {
+      const ws = args.workspace_id;
+      const steps = [];
+
+      // 1. Configure LLM (auto-detect from env if no explicit key)
+      // We try this BEFORE create_agent so failures surface clearly.
+      // If a key is already configured for this workspace, the set_llm_key
+      // op is idempotent (overwrites); harmless to call. If neither
+      // explicit nor env key is available, fail fast with a clear error
+      // so the user can paste a key.
+      const explicitKey = args.anthropic_api_key;
+      const envKey = process.env.ANTHROPIC_API_KEY;
+      const keyToUse = explicitKey || envKey;
+      if (!keyToUse) {
+        return {
+          ok: false,
+          error: "no_anthropic_key",
+          hint:
+            "No Anthropic key available. Either: (a) set ANTHROPIC_API_KEY in your shell before launching Claude Code (most Claude Code users already have this), " +
+            "or (b) pass anthropic_api_key='sk-ant-...' explicitly to this tool, " +
+            "or (c) configure via the dashboard at /settings/integrations/llm before calling create_agent. " +
+            "Without a key, the agent will be created in draft but every customer turn will return 'I'm not set up yet'.",
+          steps,
+        };
+      }
+      const configResult = await api("POST", "/agents", {
+        body: {
+          op: "set_llm_key",
+          provider: "anthropic",
+          api_key: keyToUse,
+        },
+        workspace_id: ws,
+      });
+      if (!configResult || configResult.ok === false) {
+        return {
+          ok: false,
+          error: "llm_config_failed",
+          detail: configResult,
+          steps,
+        };
+      }
+      steps.push({
+        step: "configure_llm_provider",
+        ok: true,
+        source: explicitKey ? "explicit" : "env_inherited",
+      });
+
+      // 2. Create the agent
+      const createResult = await api("POST", "/agents", {
+        body: {
+          op: "create",
+          name: args.name,
+          archetype: "website-chatbot",
+          channel: "web_chat",
+          faq: args.faq ?? [],
+          pricing_facts: args.pricing_facts ?? [],
+          greeting:
+            args.greeting ?? "Hi! How can I help you today?",
+        },
+        workspace_id: ws,
+      });
+      if (!createResult || createResult.ok === false) {
+        return {
+          ok: false,
+          error: "create_agent_failed",
+          detail: createResult,
+          steps,
+        };
+      }
+      steps.push({
+        step: "create_agent",
+        ok: true,
+        agent_id: createResult.agent?.id,
+      });
+
+      const agentId = createResult.agent?.id;
+      if (!agentId) {
+        return {
+          ok: false,
+          error: "create_agent_returned_no_id",
+          detail: createResult,
+          steps,
+        };
+      }
+
+      // 3. Publish to test (sandbox-callable; eval gate doesn't run yet)
+      const publishResult = await api("POST", "/agents", {
+        body: {
+          op: "publish",
+          agent_id: agentId,
+          status: "test",
+        },
+        workspace_id: ws,
+      });
+      if (!publishResult || publishResult.ok === false) {
+        // Created but not published. Return partial success so the user
+        // can publish manually.
+        return {
+          ok: false,
+          error: "publish_failed_but_agent_created",
+          agent: createResult.agent,
+          embed_url: createResult.embed_url,
+          turn_url: createResult.turn_url,
+          publish_detail: publishResult,
+          steps,
+          next_steps: [
+            `Agent ${agentId} was created but couldn't be published to test. Call publish_agent({ agent_id: '${agentId}', status: 'test' }) manually, or check the dashboard at /agents/${agentId}`,
+          ],
+        };
+      }
+      steps.push({ step: "publish_agent_test", ok: true });
+
+      // 4. Compose the operator-friendly final response.
+      const baseDomain =
+        process.env.WORKSPACE_BASE_DOMAIN?.trim() || "app.seldonframe.com";
+      const dashboardUrl = `https://${baseDomain}/agents/${agentId}`;
+
+      return {
+        ok: true,
+        agent: createResult.agent,
+        embed_url: createResult.embed_url,
+        turn_url: createResult.turn_url,
+        dashboard_url: dashboardUrl,
+        sandbox_url: `${dashboardUrl}/test`,
+        steps,
+        next_steps: [
+          `1. Test in sandbox: ${dashboardUrl}/test (chat with the agent before customers do).`,
+          `2. Run safety evals: open ${dashboardUrl}/evals → Run evals now (8-scenario suite).`,
+          `3. When ready, publish to live: call publish_agent({ agent_id: '${agentId}', status: 'live' }) — auto-runs eval gate, requires ≥87.5% pass.`,
+          `4. Drop on the operator's website: <script src="${createResult.embed_url}" async></script>`,
+        ],
+      };
+    },
+  },
+
   // ───────────────────────────────────────────────────────────────────────
   // v1.26.2 — agent debug + observability tools.
   // run_agent_evals = manual eval suite trigger (publish auto-runs too).

package/src/welcome.js

@@ -8,7 +8,7 @@
 // stripped. `create_full_workspace` is the only workspace-creation
 // path mentioned anywhere in this briefing.
 
-export const VERSION = "1.27.10";
+export const VERSION = "1.28.0";
 
 export const WELCOME_MARKDOWN = `# SeldonFrame — create a real Business OS in one conversation
 
@@ -30,7 +30,7 @@ tool that doesn't exist in that primitive.
 | Operator says…                                                 | Primitive            | Entry-point tools                                                     |
 | -------------------------------------------------------------- | -------------------- | --------------------------------------------------------------------- |
 | "Build me a website / business / CRM"                          | **WORKSPACE**        | \`create_workspace_v2\` then block tools                              |
-| "Add an AI chatbot to my website / landing page"               | **AGENT** (web chat) | \`create_agent\` ({ archetype: "website-chatbot" }) → embed.js script |
+| "Add an AI chatbot to my website / landing page"               | **AGENT** (web chat) | \`build_website_chatbot\` (one call: configure_llm + create + publish-test) |
 | "Build me a 24/7 AI receptionist for my phone"                 | AGENT (voice)        | (v1.28+ — voice archetype shipping soon)                              |
 | "Reply to inbound customer SMS / email automatically"          | **CONVERSATION**     | \`send_conversation_turn\` (one-shot Soul-aware reply)                |
 | "Add a hero / services / FAQ / CTA section to a page"          | **BLOCK**            | \`get_block_skill\` + \`persist_block\`                               |
@@ -61,19 +61,13 @@ when shipping) and SMS auto-reply (use the CONVERSATION primitive's
 
 ## Build a website chatbot — the canonical short flow
 
-Most operators asking for "AI on my website" want this exact flow.
-~5 tool calls, end-to-end:
+Most operators asking for "AI on my website" want this exact flow. As
+of v1.28.0 this is **ONE tool call**:
 
 \`\`\`
-1. configure_llm_provider({ provider: "anthropic", api_key })
-   // Skip if workspace already has a key. SF uses BYOK — operator pays
-   // Anthropic directly for the LLM; SF charges per agent turn separately.
-
-2. create_agent({
+1. build_website_chatbot({
      workspace_id,
      name: "Cypress Pine HVAC Helper",
-     archetype: "website-chatbot",
-     channel: "web_chat",
      greeting: "Hi! Asking about HVAC service in Phoenix? I can book you in.",
      faq: [
        { q: "What areas do you service?", a: "Phoenix, Scottsdale, Tempe..." },
@@ -83,19 +77,29 @@ Most operators asking for "AI on my website" want this exact flow.
        { label: "Service call", amount: 89, currency: "USD" },
        { label: "AC tune-up", amount: 149, currency: "USD" }
      ]
+     // anthropic_api_key omitted → auto-detected from
+     // process.env.ANTHROPIC_API_KEY in the MCP server's environment
+     // (most Claude Code users already have this set).
    })
-   // → returns { agent, embed_url, turn_url, next_steps }
-
-3. publish_agent({ workspace_id, agent_id, status: "test" })
-   // Sandbox-test the agent in the dashboard before flipping to live.
+   // → returns { agent, embed_url, turn_url, dashboard_url, next_steps }
+   // Internally: configures LLM key, creates agent, publishes to test.
 
-4. (Operator tests in /agents/[id]/test sandbox.)
+2. (Operator sandbox-tests at /agents/[id]/test.)
 
-5. publish_agent({ workspace_id, agent_id, status: "live" })
-   // AUTO-RUNS the 8-scenario eval gate. Fails if pass rate < 87.5%.
+3. publish_agent({ agent_id, status: "live" })
+   // Auto-runs the 8-scenario eval gate. Requires ≥87.5% pass rate.
    // Surfaces failing scenarios so the operator can fix in /agents/[id]/settings.
 \`\`\`
 
+If the operator manages multiple workspaces with separate Anthropic
+billing (e.g. Acme AI agency managing Cypress Pine HVAC + Sunset
+Dental), pass anthropic_api_key explicitly per workspace instead of
+relying on env auto-detect.
+
+For custom flows (different archetype, custom capability allowlist,
+multi-step blueprint construction), drop down to the primitives:
+configure_llm_provider + create_agent + publish_agent + update_agent_blueprint.
+
 Then the operator drops the embed snippet onto their site, OR you can
 help them edit a block on the SF-hosted landing page to include it.
 
@@ -402,4 +406,4 @@ admin dashboard. Pre-fills their email automatically.
 <https://seldonframe.com> · **Discord:** <https://discord.gg/sbVUu976NW>
 `;
 
-export const FIRST_CALL_BANNER = `🚀 SeldonFrame v1.27.10 is connected. CAPABILITY MAP — pick the right primitive BEFORE exploring tools: (a) "build me a website" → WORKSPACE → create_workspace_v2 + block tools. (b) "add a chatbot to my website / landing page" → AGENT (web chat) → create_agent({archetype:"website-chatbot"}) → embed.js script. CRITICAL ANTI-PATTERN: chat widgets are NOT blocks. Don't search list_blocks for chat — chat agents are a separate primitive (v1.26+). (c) "auto-reply to inbound SMS/email" → CONVERSATION → send_conversation_turn (one-shot Soul-aware reply, not a website widget). (d) "add hero/services/faq/cta section" → BLOCK → get_block_skill + persist_block. (e) "send campaign email/sms" → MESSAGING. (f) CRM ops → list_contacts/create_deal/etc. CHATBOT CANONICAL FLOW (5 calls): configure_llm_provider (BYOK Anthropic, skip if already set) → create_agent (faq + pricing_facts + greeting) → publish_agent({status:"test"}) → operator sandbox-tests at /agents/[id]/test → publish_agent({status:"live"}) auto-runs 8-scenario eval gate (≥87.5% pass required). Observability tools after publish: list_agents, tail_agent_conversations, get_agent_conversation, get_agent_metrics, run_agent_evals, replay_conversation. Dashboard surfaces /agents, /agents/[id]/test, /agents/[id]/settings, /agents/[id]/evals, /agents/[id]/conversations let operators iterate without leaving the browser. WORKSPACE FLOW (legacy reference): create_workspace_v2 → IN PARALLEL for all 7 recommended_blocks (hero, services, about, faq, cta, booking, intake): get_block_skill + persist_block → complete_workspace_v2 → finalize_workspace({workspace_id, email}). Run blocks in PARALLEL (Promise.all) — sequential takes 60+ seconds. v1.10+ CUSTOMIZE: regenerate_block, upload_workspace_image (image_url preferred over base64). v1.11+ STRUCTURAL: get_landing_structure, move_section, delete_section. v1.12+ COMPOSITES: add_composite_section / update_composite_section — manifest ANY block from 12 low-level primitives. Skipping finalize_workspace leaves the operator with no admin login. Every URL is real. NEVER create local files.`;
+export const FIRST_CALL_BANNER = `🚀 SeldonFrame v1.28.0 is connected. CAPABILITY MAP — pick the right primitive BEFORE exploring tools: (a) "build me a website" → WORKSPACE → create_workspace_v2 + block tools. (b) "add a chatbot to my website / landing page" → AGENT (web chat) → build_website_chatbot (v1.28+ skill bundle: configure_llm + create_agent + publish-test in 1 call; auto-detects ANTHROPIC_API_KEY from env). Drop to primitives (configure_llm_provider + create_agent + publish_agent) only for custom flows. CRITICAL ANTI-PATTERN: chat widgets are NOT blocks. Don't search list_blocks for chat — chat agents are a separate primitive (v1.26+). (c) "auto-reply to inbound SMS/email" → CONVERSATION → send_conversation_turn (one-shot Soul-aware reply, not a website widget). (d) "add hero/services/faq/cta section" → BLOCK → get_block_skill + persist_block. (e) "send campaign email/sms" → MESSAGING. (f) CRM ops → list_contacts/create_deal/etc. CHATBOT CANONICAL FLOW (v1.28+ — 1 call instead of 5): build_website_chatbot({workspace_id, name, faq, pricing_facts, greeting}) → wraps configure_llm + create_agent + publish-test in one call, auto-detects ANTHROPIC_API_KEY from env. Then: operator sandbox-tests at /agents/[id]/test → publish_agent({status:"live"}) auto-runs 8-scenario eval gate (≥87.5% pass required). Observability tools after publish: list_agents, tail_agent_conversations, get_agent_conversation, get_agent_metrics, run_agent_evals, replay_conversation. Dashboard surfaces /agents, /agents/[id]/test, /agents/[id]/settings, /agents/[id]/evals, /agents/[id]/conversations let operators iterate without leaving the browser. WORKSPACE FLOW (legacy reference): create_workspace_v2 → IN PARALLEL for all 7 recommended_blocks (hero, services, about, faq, cta, booking, intake): get_block_skill + persist_block → complete_workspace_v2 → finalize_workspace({workspace_id, email}). Run blocks in PARALLEL (Promise.all) — sequential takes 60+ seconds. v1.10+ CUSTOMIZE: regenerate_block, upload_workspace_image (image_url preferred over base64). v1.11+ STRUCTURAL: get_landing_structure, move_section, delete_section. v1.12+ COMPOSITES: add_composite_section / update_composite_section — manifest ANY block from 12 low-level primitives. Skipping finalize_workspace leaves the operator with no admin login. Every URL is real. NEVER create local files.`;