@botbotgo/better-call 0.1.24 → 0.1.25

package/README.md

@@ -24,6 +24,12 @@ const tools = betterTools([searchTool, calculatorTool]);
 
 No model means validate and block only. Add `repairModel` when you want automatic repair.
 
+Try the built-in demo after installing:
+
+```bash
+npx @botbotgo/better-call demo
+```
+
 ## Why BetterCall?
 
 Small models often know that a tool is needed but still fail at the boundary: wrong tool names, malformed arguments, schema drift, extra fields, or raw tool-call-shaped text. BetterCall sits at that boundary and gives you a typed, auditable way to accept, repair, or reject the call before the real tool runs.
@@ -41,6 +47,9 @@ The `examples/` directory has copyable starting points:
 - `examples/langchain-basic.mjs`: wrap a LangChain-style tool and repair bad args.
 - `examples/ollama-small-model.mjs`: use an Ollama repair callback for a small local model.
 - `examples/gateway-repair.mjs`: repair an invalid tool name at a custom runtime or MCP gateway boundary.
+- `examples/adapters/langchain-tool-wrapper.mjs`: tiny adapter helper for LangChain-style tools.
+- `examples/adapters/mcp-gateway-boundary.mjs`: MCP-style gateway boundary pattern.
+- `examples/adapters/openai-compatible-repair.mjs`: OpenAI-compatible local endpoint repair callback.
 
 ## Installation
 
@@ -247,6 +256,9 @@ Latest completed remote run artifact: `benchmarks/bfcl-real-remote-completed-sum
 - `docs/marketing/positioning.md`: product positioning, audience, differentiators, and calls to action.
 - `docs/marketing/launch-post.md`: launch-post draft and short social version.
 - `docs/marketing/growth-checklist.md`: channel-by-channel launch and adoption checklist.
+- `docs/recipes/`: focused integration recipes.
+- `docs/faq.md`: adoption and boundary FAQ.
+- `docs/case-studies/stable-harness-tool-gateway.md`: production gateway integration pattern.
 
 ## Requirements
 

package/docs/benchmark-lift.svg

@@ -1,26 +1,30 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="920" height="360" viewBox="0 0 920 360" role="img" aria-labelledby="title desc">
+<svg xmlns="http://www.w3.org/2000/svg" width="760" height="330" viewBox="0 0 760 330" role="img" aria-labelledby="title desc">
   <title id="title">BetterCall BFCL small-model lift</title>
-  <desc id="desc">Bar chart showing granite4.1:3b improving from 73.4 percent raw to 83.8 percent with BetterCall on BFCL v4 remote Ollama runs.</desc>
-  <rect width="920" height="360" fill="#0f172a"/>
-  <rect x="34" y="28" width="852" height="304" rx="16" fill="#111827" stroke="#334155"/>
-  <text x="64" y="72" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="28" font-weight="700">Small models fail at the tool boundary</text>
-  <text x="64" y="104" fill="#cbd5e1" font-family="Inter, Arial, sans-serif" font-size="16">BFCL v4 remote Ollama run, granite4.1:3b, 3,625 cases</text>
-  <line x1="86" y1="282" x2="820" y2="282" stroke="#475569"/>
+  <desc id="desc">BetterCall improves granite4.1:3b tool-call accuracy from 73.4 percent raw to 83.8 percent on BFCL v4 remote Ollama runs.</desc>
+
+  <rect width="760" height="330" rx="18" fill="#0f172a"/>
+  <rect x="26" y="26" width="708" height="278" rx="16" fill="#111827" stroke="#334155"/>
+
+  <text x="54" y="70" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="27" font-weight="800">Tool-call reliability lift</text>
+  <text x="54" y="100" fill="#cbd5e1" font-family="Inter, Arial, sans-serif" font-size="14">BFCL v4 remote Ollama · granite4.1:3b · 3,625 cases</text>
+
   <g>
-    <text x="132" y="314" fill="#cbd5e1" font-family="Inter, Arial, sans-serif" font-size="15" text-anchor="middle">Raw</text>
-    <rect x="86" y="127" width="92" height="155" rx="8" fill="#64748b"/>
-    <text x="132" y="116" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="24" font-weight="700" text-anchor="middle">73.4%</text>
+    <text x="54" y="148" fill="#e2e8f0" font-family="Inter, Arial, sans-serif" font-size="17" font-weight="700">Raw model</text>
+    <rect x="54" y="164" width="480" height="30" rx="15" fill="#1e293b"/>
+    <rect x="54" y="164" width="352" height="30" rx="15" fill="#64748b"/>
+    <text x="560" y="188" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="25" font-weight="800">73.4%</text>
   </g>
+
   <g>
-    <text x="328" y="314" fill="#cbd5e1" font-family="Inter, Arial, sans-serif" font-size="15" text-anchor="middle">BetterCall</text>
-    <rect x="282" y="105" width="92" height="177" rx="8" fill="#22c55e"/>
-    <text x="328" y="94" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="24" font-weight="700" text-anchor="middle">83.8%</text>
+    <text x="54" y="226" fill="#e2e8f0" font-family="Inter, Arial, sans-serif" font-size="17" font-weight="700">With BetterCall</text>
+    <rect x="54" y="242" width="480" height="30" rx="15" fill="#1e293b"/>
+    <rect x="54" y="242" width="402" height="30" rx="15" fill="#22c55e"/>
+    <text x="560" y="266" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="25" font-weight="800">83.8%</text>
   </g>
-  <path d="M190 146 C226 118 238 118 268 112" fill="none" stroke="#38bdf8" stroke-width="3"/>
-  <polygon points="270,112 258,106 260,120" fill="#38bdf8"/>
-  <text x="224" y="142" fill="#38bdf8" font-family="Inter, Arial, sans-serif" font-size="18" font-weight="700">+10.4pp</text>
-  <rect x="476" y="126" width="312" height="104" rx="12" fill="#0f172a" stroke="#334155"/>
-  <text x="502" y="163" fill="#f8fafc" font-family="Inter, Arial, sans-serif" font-size="20" font-weight="700">Validate, repair, then execute</text>
-  <text x="502" y="193" fill="#cbd5e1" font-family="Inter, Arial, sans-serif" font-size="15">Unknown tools, malformed args,</text>
-  <text x="502" y="216" fill="#cbd5e1" font-family="Inter, Arial, sans-serif" font-size="15">schema drift, raw tool-call-shaped text.</text>
+
+  <rect x="560" y="204" width="106" height="30" rx="15" fill="#052e16" stroke="#22c55e" stroke-opacity="0.55"/>
+  <text x="613" y="225" fill="#bbf7d0" font-family="Inter, Arial, sans-serif" font-size="15" font-weight="800" text-anchor="middle">+10.4pp</text>
+
+  <line x1="54" y1="288" x2="332" y2="288" stroke="#334155"/>
+  <text x="352" y="293" fill="#94a3b8" font-family="Inter, Arial, sans-serif" font-size="13">Validate, repair, then execute.</text>
 </svg>

package/docs/case-studies/stable-harness-tool-gateway.md

@@ -0,0 +1,42 @@
+# Case Study: BetterCall Inside a Tool Gateway
+
+`stable-harness` uses BetterCall at the tool gateway boundary, not as a replacement for the agent loop.
+
+## Boundary
+
+- The agent or workflow backend decides that a tool should be called.
+- The runtime gateway owns the visible tool inventory and hidden or blocked tools.
+- BetterCall validates, repairs, or rejects the selected tool call before the real tool executes.
+- The original tool implementation still executes only after the repaired call passes the boundary.
+
+## Flow
+
+```mermaid
+sequenceDiagram
+  participant Agent as Agent backend
+  participant Gateway as Tool gateway
+  participant BC as BetterCall
+  participant Tool as Real tool
+
+  Agent->>Gateway: tool id + args
+  Gateway->>BC: visible tools + candidate call
+  BC-->>Gateway: accepted, repaired, or rejected
+  alt accepted or repaired
+    Gateway->>Tool: execute safe args
+    Tool-->>Gateway: result
+  else rejected
+    Gateway-->>Agent: structured validation error
+  end
+```
+
+## Why This Matters
+
+The gateway can keep runtime policy and authorization local while BetterCall handles tool-call contract reliability:
+
+- wrong or unavailable tool names
+- malformed arguments
+- schema drift
+- enum and type errors
+- raw tool-call-shaped text
+
+This keeps BetterCall small: it is the reliability layer inside an agent runtime, not another agent framework.

package/docs/faq.md

@@ -0,0 +1,25 @@
+# BetterCall FAQ
+
+## When should I use BetterCall?
+
+Use BetterCall when your model already emits tool calls, but those calls sometimes fail before execution because of wrong tool names, malformed arguments, schema drift, invalid enum values, extra fields, or raw tool-call-shaped text.
+
+## When should I not use BetterCall?
+
+Do not use BetterCall as a planning system, memory layer, agent loop, authorization system, or replacement for human approval. Keep those responsibilities in your runtime. BetterCall belongs at the tool-call boundary.
+
+## Does BetterCall require a repair model?
+
+No. Without `repair` or `repairModel`, BetterCall validates and blocks invalid calls. Add a repair model or callback only when automatic repair is acceptable for your application.
+
+## Can BetterCall execute hidden or blocked tools?
+
+No. Tool selection repair is constrained by the visible tool inventory you pass in. Hidden tools remain blocked.
+
+## Is BetterCall only for LangChain?
+
+No. `betterTools(...)` works with LangChain-style tools, but the lower-level APIs work in custom runtimes and tool gateways.
+
+## Where should semantic policy live?
+
+Keep semantic policy in your tool boundary with `validate(...)` or your gateway. BetterCall can carry the validation result and block or repair around it, but your runtime should own domain policy.

package/docs/marketing/growth-checklist.md

@@ -12,6 +12,10 @@ The goal is to move developers through three stages:
 - [x] Add discoverable GitHub topics: `tool-calling`, `function-calling`, `langchain`, `ollama`, `mcp`, `small-models`, `tool-call-repair`.
 - [x] Put the benchmark lift near the top of the README.
 - [x] Add copyable examples.
+- [x] Add `npx @botbotgo/better-call demo`.
+- [x] Add focused recipes for common integration problems.
+- [x] Add a stable-harness gateway case study.
+- [x] Add an adapter request issue template.
 - [ ] Add a short GIF or terminal recording showing before and after repair.
 - [ ] Add a `good first issue` label set for example adapters and docs.
 
@@ -19,6 +23,7 @@ The goal is to move developers through three stages:
 
 - [x] Improve package description and keywords.
 - [x] Include examples and README assets in the package allowlist.
+- [x] Add a package binary for the built-in demo.
 - [ ] Publish the next patch version so npm metadata and tarball include the new assets.
 - [ ] Verify the npm package page renders the README image and examples.
 
@@ -44,16 +49,17 @@ The goal is to move developers through three stages:
 - [x] Add LangChain-style example.
 - [x] Add Ollama small-model example.
 - [x] Add custom gateway repair example.
-- [ ] Add MCP server/client gateway example.
-- [ ] Add OpenAI-compatible local model example.
-- [ ] Add LangGraph/stable-harness integration note when stable-harness is the public case study.
+- [x] Add MCP server/client gateway example.
+- [x] Add LangChain adapter helper example.
+- [x] Add OpenAI-compatible local model example.
+- [x] Add LangGraph/stable-harness integration note when stable-harness is the public case study.
 
 ## Conversion
 
-- [ ] Add a one-command reproduction path for the smallest local benchmark.
-- [ ] Add a "When should I use BetterCall?" FAQ.
-- [ ] Add a "When should I not use BetterCall?" FAQ to build trust.
-- [ ] Add a simple issue template for adapter requests.
+- [x] Add a one-command reproduction path for the smallest local demo.
+- [x] Add a "When should I use BetterCall?" FAQ.
+- [x] Add a "When should I not use BetterCall?" FAQ to build trust.
+- [x] Add a simple issue template for adapter requests.
 - [ ] Track install/download/star movement after each post.
 
 ## Launch Sequence

package/docs/recipes/README.md

@@ -0,0 +1,11 @@
+# BetterCall Recipes
+
+Each recipe solves one integration problem with a small copyable pattern.
+
+- `wrong-tool-name.md`: Repair a tool name before gateway dispatch.
+- `zod-schema.md`: Use Zod object schemas or Zod-shaped records.
+- `validate-only.md`: Run without a repair model and block invalid calls.
+- `ollama-repair.md`: Use a local Ollama model as the repair callback.
+- `semantic-validator.md`: Keep domain validation in your tool boundary.
+
+See also `../faq.md` for adoption and boundary guidance.

package/docs/recipes/ollama-repair.md

@@ -0,0 +1,33 @@
+# Recipe: Use Ollama as the Repair Model
+
+Use `reliableToolCalls(...)` when you want full control over the repair callback.
+
+```ts
+import { reliableToolCalls } from "@botbotgo/better-call";
+
+const result = await reliableToolCalls({
+  userInput,
+  tools,
+  calls,
+  repair: async ({ userInput, tools, calls, issues }) => {
+    const prompt = [
+      "Return corrected JSON only as {\"calls\":[{\"tool\":\"name\",\"args\":{}}]}.",
+      `User: ${userInput}`,
+      `Tools: ${JSON.stringify(tools)}`,
+      `Rejected calls: ${JSON.stringify(calls)}`,
+      `Issues: ${JSON.stringify(issues)}`,
+    ].join("\n");
+
+    const response = await fetch("http://127.0.0.1:11434/api/generate", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ model: "granite4.1:3b", prompt, stream: false, format: "json" }),
+    });
+
+    const json = await response.json();
+    return JSON.parse(json.response).calls;
+  },
+});
+```
+
+See `examples/ollama-small-model.mjs` for a runnable version.

package/docs/recipes/semantic-validator.md

@@ -0,0 +1,25 @@
+# Recipe: Add Semantic Validation
+
+Schema validation checks shape. Semantic validation checks whether an argument is allowed in your runtime.
+
+```ts
+import { betterTools } from "@botbotgo/better-call";
+
+const [safeTool] = betterTools([{
+  name: "deploy",
+  schema: deploySchema,
+  validate: ({ call }) => {
+    if (call.args.environment === "prod") {
+      return [{
+        kind: "semantic",
+        path: "$.args.environment",
+        message: "production deploys require a separate approval path",
+      }];
+    }
+    return [];
+  },
+  invoke: deploy,
+}]);
+```
+
+Keep business policy in `validate(...)`; keep model repair constrained to calls that still pass the tool boundary.

package/docs/recipes/validate-only.md

@@ -0,0 +1,17 @@
+# Recipe: Validate and Block Only
+
+You do not need a repair model. Without `repair` or `repairModel`, BetterCall validates the call and blocks invalid execution.
+
+```ts
+import { betterTools } from "@botbotgo/better-call";
+
+const [safeTool] = betterTools([tool]);
+
+try {
+  await safeTool.invoke(modelArgs);
+} catch (error) {
+  console.error(error.issues);
+}
+```
+
+Use this mode when the cost of a wrong repair is higher than the cost of asking the model or user to try again.

package/docs/recipes/wrong-tool-name.md

@@ -0,0 +1,24 @@
+# Recipe: Repair a Wrong Tool Name
+
+Use `repairToolCall(...)` before a custom runtime, gateway, or MCP-style dispatcher executes a tool.
+
+```ts
+import { repairToolCall } from "@botbotgo/better-call";
+
+const repaired = await repairToolCall({
+  userInput: "Research the current market.",
+  visibleTools: [taskTool],
+  hiddenTools: [shellTool],
+  invalidToolName: "research",
+  args: {
+    subagent_type: "research",
+    description: "Research the current market.",
+  },
+});
+
+if (repaired.status === "repaired") {
+  await dispatch(repaired.toolName, repaired.args);
+}
+```
+
+BetterCall only repairs into the visible tool inventory. Hidden tools remain blocked.

package/docs/recipes/zod-schema.md

@@ -0,0 +1,19 @@
+# Recipe: Use Zod Schemas
+
+BetterCall accepts JSON Schema, Zod object schemas, and Zod-shaped records.
+
+```ts
+import { z } from "zod";
+import { betterTools } from "@botbotgo/better-call";
+
+const tools = betterTools([{
+  name: "stock_quote",
+  schema: z.object({
+    ticker: z.string(),
+    market: z.enum(["US", "HK", "CN"]),
+  }),
+  invoke: async (args) => getStockQuote(args),
+}]);
+```
+
+The same schema normalization is used by the lower-level `reliableToolCalls(...)` and `guardToolCalls(...)` APIs.

package/examples/README.md

@@ -7,6 +7,9 @@ Each example is intentionally small enough to copy into an app.
 - `langchain-basic.mjs`: Wrap a LangChain-style tool and repair invalid args before execution.
 - `ollama-small-model.mjs`: Use an Ollama-compatible repair model callback with `reliableToolCalls`.
 - `gateway-repair.mjs`: Repair an invalid tool name at a custom runtime or MCP gateway boundary.
+- `adapters/langchain-tool-wrapper.mjs`: Tiny adapter helper for LangChain-style tools.
+- `adapters/mcp-gateway-boundary.mjs`: Gateway-boundary pattern for MCP-style tool dispatch.
+- `adapters/openai-compatible-repair.mjs`: Repair callback pattern for OpenAI-compatible local endpoints.
 
 ## Run
 
@@ -22,10 +25,13 @@ Then run an example:
 ```bash
 node examples/langchain-basic.mjs
 node examples/gateway-repair.mjs
+node examples/adapters/langchain-tool-wrapper.mjs
+node examples/adapters/mcp-gateway-boundary.mjs
 ```
 
-The Ollama example expects an Ollama-compatible `/api/generate` endpoint:
+The Ollama and OpenAI-compatible examples expect local model endpoints:
 
 ```bash
 OLLAMA_BASE_URL=http://127.0.0.1:11434 OLLAMA_MODEL=granite4.1:3b node examples/ollama-small-model.mjs
+OPENAI_BASE_URL=http://127.0.0.1:8000/v1 OPENAI_MODEL=local-model node examples/adapters/openai-compatible-repair.mjs
 ```

package/examples/adapters/langchain-tool-wrapper.mjs

@@ -0,0 +1,39 @@
+import { betterTools } from "../../dist/index.js";
+
+export function withBetterCallLangChainTools(tools, options = {}) {
+  return betterTools(tools, options);
+}
+
+const searchTool = {
+  name: "search",
+  description: "Search docs.",
+  schema: {
+    type: "object",
+    properties: {
+      query: { type: "string" },
+      limit: { type: "integer", minimum: 1, maximum: 5 },
+    },
+    required: ["query"],
+    additionalProperties: false,
+  },
+  async invoke(args) {
+    return { searched: args };
+  },
+};
+
+const [search] = withBetterCallLangChainTools([searchTool], {
+  userInput: "Search BetterCall docs.",
+  repairPolicy: {
+    allowCoercion: true,
+    allowClamp: true,
+    allowDropUnknownKeys: true,
+  },
+});
+
+const result = await search.invoke({
+  query: "BetterCall tool repair",
+  limit: "50",
+  debug: true,
+});
+
+console.log(JSON.stringify(result, null, 2));

package/examples/adapters/mcp-gateway-boundary.mjs

@@ -0,0 +1,51 @@
+import { repairToolCall } from "../../dist/index.js";
+
+const tools = [{
+  name: "docs.search",
+  description: "Search project documentation.",
+  schema: {
+    type: "object",
+    properties: {
+      query: { type: "string" },
+      max_results: { type: "integer", minimum: 1, maximum: 10 },
+    },
+    required: ["query"],
+    additionalProperties: false,
+  },
+}];
+
+async function dispatchMcpToolCall(request) {
+  const repaired = await repairToolCall({
+    userInput: request.userInput,
+    visibleTools: tools,
+    invalidToolName: request.name,
+    args: request.arguments,
+    repairPolicy: {
+      allowCoercion: true,
+      allowClamp: true,
+      allowDropUnknownKeys: true,
+    },
+  });
+
+  if (repaired.status === "rejected") {
+    return { error: repaired.reason, violations: repaired.violations };
+  }
+
+  return {
+    name: repaired.toolName,
+    arguments: repaired.args,
+    executed: false,
+  };
+}
+
+const response = await dispatchMcpToolCall({
+  userInput: "Search the docs for BetterCall examples.",
+  name: "search_docs",
+  arguments: {
+    query: "BetterCall examples",
+    max_results: "50",
+    debug: true,
+  },
+});
+
+console.log(JSON.stringify(response, null, 2));

package/examples/adapters/openai-compatible-repair.mjs

@@ -0,0 +1,53 @@
+import { reliableToolCalls } from "../../dist/index.js";
+
+const baseUrl = process.env.OPENAI_BASE_URL ?? "http://127.0.0.1:8000/v1";
+const model = process.env.OPENAI_MODEL ?? "local-model";
+const apiKey = process.env.OPENAI_API_KEY ?? "not-needed-for-local";
+
+const tools = [{
+  name: "stock_quote",
+  description: "Get a stock quote.",
+  schema: {
+    type: "object",
+    properties: {
+      ticker: { type: "string" },
+      market: { type: "string", enum: ["US", "HK", "CN"] },
+    },
+    required: ["ticker", "market"],
+    additionalProperties: false,
+  },
+}];
+
+const result = await reliableToolCalls({
+  userInput: "Get Apple stock in the US market.",
+  tools,
+  calls: [{ tool: "stock_price", args: { symbol: "Apple", market: "NASDAQ" } }],
+  repair: async ({ userInput, tools, calls, issues }) => {
+    const response = await fetch(`${baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "authorization": `Bearer ${apiKey}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        model,
+        response_format: { type: "json_object" },
+        messages: [{
+          role: "user",
+          content: [
+            "Return corrected JSON only as {\"calls\":[{\"tool\":\"name\",\"args\":{}}]}.",
+            `User: ${userInput}`,
+            `Tools: ${JSON.stringify(tools)}`,
+            `Rejected calls: ${JSON.stringify(calls)}`,
+            `Issues: ${JSON.stringify(issues)}`,
+          ].join("\n"),
+        }],
+      }),
+    });
+    if (!response.ok) throw new Error(`OpenAI-compatible request failed: ${response.status}`);
+    const json = await response.json();
+    return JSON.parse(json.choices[0].message.content).calls;
+  },
+});
+
+console.log(JSON.stringify({ model, result }, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/better-call",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "Small-model tool-call reliability layer for LangChain and custom agent runtimes.",
   "type": "module",
   "license": "Apache-2.0",
@@ -33,6 +33,9 @@
       "import": "./dist/index.js"
     }
   },
+  "bin": {
+    "better-call": "./scripts/demo.mjs"
+  },
   "files": [
     "dist",
     "benchmarks",
@@ -40,7 +43,10 @@
     "examples",
     "docs/banner.svg",
     "docs/benchmark-lift.svg",
+    "docs/faq.md",
+    "docs/case-studies",
     "docs/marketing",
+    "docs/recipes",
     "README.md",
     "NOTICE",
     "LICENSE"

package/scripts/demo.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { betterTools, repairToolCall, reliableToolCalls } from "../dist/index.js";
+
+const json = process.argv.includes("--json");
+
+const stockQuote = {
+  name: "stock_quote",
+  description: "Get a stock quote.",
+  schema: {
+    type: "object",
+    properties: {
+      ticker: { type: "string" },
+      market: { type: "string", enum: ["US", "HK", "CN"] },
+    },
+    required: ["ticker", "market"],
+    additionalProperties: false,
+  },
+  async invoke(args) {
+    return { quote: args };
+  },
+};
+
+const badArgs = { symbol: "Apple", market: "NASDAQ" };
+
+const [wrappedStockQuote] = betterTools([stockQuote], {
+  userInput: "Get Apple stock in the US market.",
+  repair() {
+    return [{ tool: "stock_quote", args: { ticker: "AAPL", market: "US" } }];
+  },
+});
+
+const wrappedOutput = await wrappedStockQuote.invoke(badArgs);
+
+const reliableResult = await reliableToolCalls({
+  userInput: "Get Apple stock in the US market.",
+  tools: [stockQuote],
+  calls: [{ tool: "stock_price", args: badArgs }],
+  repair() {
+    return [{ tool: "stock_quote", args: { ticker: "AAPL", market: "US" } }];
+  },
+});
+
+const gatewayResult = await repairToolCall({
+  userInput: "Research the current market.",
+  visibleTools: [{
+    name: "task",
+    description: "Delegate a task to a visible specialist.",
+    schema: {
+      type: "object",
+      properties: {
+        subagent_type: { type: "string", enum: ["research", "ops"] },
+        description: { type: "string" },
+      },
+      required: ["subagent_type", "description"],
+      additionalProperties: false,
+    },
+  }],
+  invalidToolName: "research",
+  args: {
+    subagent_type: "research",
+    description: "Research the current market.",
+  },
+});
+
+const report = {
+  wrappedTool: {
+    before: badArgs,
+    after: wrappedOutput,
+  },
+  reliableToolCalls: {
+    before: { tool: "stock_price", args: badArgs },
+    repaired: reliableResult.calls[0],
+    diagnostics: reliableResult.diagnostics,
+  },
+  gatewayRepair: gatewayResult,
+};
+
+if (json) {
+  console.log(JSON.stringify(report, null, 2));
+} else {
+  console.log("BetterCall demo");
+  console.log("");
+  console.log("1. Wrapped tool args");
+  console.log(`   before: ${JSON.stringify(report.wrappedTool.before)}`);
+  console.log(`   after:  ${JSON.stringify(report.wrappedTool.after)}`);
+  console.log("");
+  console.log("2. Tool-call repair");
+  console.log(`   before: ${JSON.stringify(report.reliableToolCalls.before)}`);
+  console.log(`   after:  ${JSON.stringify(report.reliableToolCalls.repaired)}`);
+  console.log("");
+  console.log("3. Gateway tool-name repair");
+  console.log(`   status: ${report.gatewayRepair.status}`);
+  console.log(`   tool:   ${report.gatewayRepair.originalToolName} -> ${report.gatewayRepair.toolName}`);
+  console.log(`   reason: ${report.gatewayRepair.reason}`);
+  console.log("");
+  console.log("Run with --json for the full structured result.");
+}