@pinecall/skills 0.1.0

package/skills/pinecall-examples/references/examples/chat-bot.md

@@ -0,0 +1,184 @@
+---
+title: "Example: Chat Bot"
+description: "Text chat agent using @pinecall/web/chat — same agent, text instead of voice."
+---
+
+# Example: Chat Bot
+
+A text-based chat agent using `@pinecall/web/chat`. Same Pinecall agent, same prompt, same tools — but text over WebSocket instead of audio over WebRTC.
+
+## What it does
+
+A booking assistant for a spa. Users chat via a React widget, the agent responds with streamed text, and calls a tool to check availability.
+
+## Backend — `server.js`
+
+```typescript
+import { Pinecall, tool } from "@pinecall/sdk";
+import { z } from "zod";
+import express from "express";
+
+const pc = new Pinecall();
+
+const getAvailability = tool({
+  name: "getAvailability",
+  description: "Check available time slots for a service and date.",
+  schema: z.object({
+    service: z.string(),
+    date: z.string().describe("YYYY-MM-DD"),
+  }),
+  execute: async ({ service, date }) => ({
+    slots: ["10:00", "11:30", "14:00", "16:00"],
+  }),
+});
+
+const agent = pc.agent("florencia", {
+  prompt: `You are Florencia, the booking assistant for Blossom Beauty Spa.
+Help customers book appointments. Be warm and concise.
+Available services: Haircut ($30), Color ($80), Facial ($60), Massage ($90).`,
+  llm: "openai/gpt-5-chat-latest",
+  language: "es",
+  allowedOrigins: ["http://localhost:*"],
+  tools: [getAvailability],
+});
+
+const app = express();
+app.use(express.static("public"));
+app.get("/events", (req, res) => agent.stream(res));
+app.listen(3000, () => console.log("http://localhost:3000"));
+```
+
+## Frontend — React chat widget
+
+```tsx
+import { usePinecallChat } from "@pinecall/web/chat/react";
+
+function Chat() {
+  const { messages, send, connected, typing } = usePinecallChat({
+    agent: "florencia",
+  });
+
+  if (!connected) return <p>Connecting...</p>;
+
+  return (
+    <div className="chat">
+      <div className="messages">
+        {messages.map((m) => (
+          <div key={m.id} className={`msg ${m.role}`}>
+            <strong>{m.role === "user" ? "You" : "Florencia"}:</strong>{" "}
+            {m.text}
+            {m.isStreaming && "▊"}
+          </div>
+        ))}
+        {typing && <div className="msg bot typing">Florencia is typing…</div>}
+      </div>
+
+      <input
+        placeholder="Type a message..."
+        onKeyDown={(e) => {
+          if (e.key === "Enter" && e.currentTarget.value.trim()) {
+            send(e.currentTarget.value);
+            e.currentTarget.value = "";
+          }
+        }}
+      />
+    </div>
+  );
+}
+```
+
+The `usePinecallChat` hook handles token fetching (via `allowedOrigins`), WebSocket lifecycle, streamed messages (token-by-token), typing indicator, and auto-reconnect.
+
+## Rendering tool results in the UI
+
+Tools execute on the backend — the agent calls `getAvailability`, gets slots, and **responds with text** describing them. But you can also show rich UI alongside the chat.
+
+Use `setContext` to sync frontend state into the agent's prompt, so it knows what the user is seeing:
+
+```tsx
+import { usePinecallChat } from "@pinecall/web/chat/react";
+import { useState, useEffect } from "react";
+
+function BookingChat() {
+  const { messages, send, connected, typing, setContext } = usePinecallChat({
+    agent: "florencia",
+  });
+  const [selectedSlot, setSelectedSlot] = useState<string | null>(null);
+
+  // Sync selection to the agent's prompt
+  useEffect(() => {
+    if (selectedSlot) {
+      setContext("user_selection", `User selected time slot: ${selectedSlot}`);
+    }
+    return () => setContext("user_selection", null);
+  }, [selectedSlot, setContext]);
+
+  if (!connected) return <p>Connecting...</p>;
+
+  return (
+    <div className="chat">
+      <div className="messages">
+        {messages.map((m) => (
+          <div key={m.id} className={`msg ${m.role}`}>
+            <strong>{m.role === "user" ? "You" : "Florencia"}:</strong>{" "}
+            {m.text}
+            {m.isStreaming && "▊"}
+          </div>
+        ))}
+        {typing && <div className="msg bot typing">Florencia is typing…</div>}
+      </div>
+
+      {/* Quick-select buttons — inject user choice as text */}
+      <div className="quick-actions">
+        {["Haircut", "Facial", "Massage"].map((service) => (
+          <button
+            key={service}
+            onClick={() => send(`I'd like to book a ${service}`)}
+          >
+            {service}
+          </button>
+        ))}
+      </div>
+
+      <input
+        placeholder="Type a message..."
+        onKeyDown={(e) => {
+          if (e.key === "Enter" && e.currentTarget.value.trim()) {
+            send(e.currentTarget.value);
+            e.currentTarget.value = "";
+          }
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### Chat API reference
+
+| API | What it does |
+|-----|-------------|
+| `messages` | Array of `{ id, role, text, isStreaming }` — full conversation |
+| `send(text)` | Send a user message |
+| `typing` | True while the bot is streaming |
+| `setContext(key, value)` | Inject context into the LLM prompt (e.g. form state) |
+| `connected` | True when WebSocket is connected |
+
+### How `setContext` works in chat
+
+Same as voice — the server appends your context as a `## UI Context` section in the system prompt. The agent can reference it naturally:
+
+```
+"The user selected the 10:00 AM slot, now ask for their name."
+```
+
+## Same agent, voice + chat
+
+The same agent handles **both** text (chat) and voice (WebRTC) automatically. Same prompt, same tools, same conversation context — no extra configuration needed.
+
+## What's next
+
+- [`@pinecall/web/chat` reference](/web/chat/overview) — full ChatSession API
+- [Browser Widget example](/examples/browser-widget) — the voice equivalent with interactive tool UI
+- [SSE Event Streaming](/guides/sse-streaming) — build a live dashboard
+

package/skills/pinecall-examples/references/examples/headless-agent.md

@@ -0,0 +1,121 @@
+---
+title: "Example: Headless Agent"
+description: "Complete runnable example — a phone support agent with zero web server."
+---
+
+# Example: Headless Agent
+
+A complete, production-ready voice agent in a single file. No web server, no frontend, no infrastructure beyond a Node.js process. This pattern is ideal for intercoms, IoT devices, single-purpose phone bots, and WhatsApp-only deployments.
+
+Run it with `pinecall run agent/index.js`.
+
+## What it does
+
+`agent/index.js` is a phone support agent for an e-commerce store. It answers calls, looks up orders by phone number, and handles returns.
+
+## The complete file
+
+```typescript
+// agent/index.js
+import { Pinecall, tool } from "@pinecall/sdk";
+import { z } from "zod";
+import { promises as fs } from "node:fs";
+
+const pc = new Pinecall();
+
+const lookupOrder = tool({
+  name: "lookupOrder",
+  description: "Look up the customer's most recent order.",
+  schema: z.object({
+    phone: z.string().describe("Customer phone number"),
+  }),
+  execute: async ({ phone }) => {
+    // your logic — query your database, etc.
+    return { orderId: "ORD-1234", status: "shipped", eta: "tomorrow" };
+  },
+});
+
+export const agent = pc.agent("support", {
+  voice: "elevenlabs/sarah",
+  language: "en",
+  llm: "openai/gpt-5-chat-latest",
+  stt: "deepgram/flux",
+  prompt: `You are a support agent for an online store.
+Help customers check order status and process returns.
+Be friendly, brief, and professional.`,
+  phoneNumber: "+13186330963",
+  greeting: "Hi! Thanks for calling. How can I help you today?",
+  tools: [lookupOrder],
+});
+
+// Log every call to disk
+agent.on("call.ended", async (call, reason) => {
+  await fs.appendFile("./calls.jsonl", JSON.stringify({
+    id: call.id, from: call.from, duration: call.duration,
+    reason, endedAt: new Date().toISOString(),
+  }) + "\n");
+});
+```
+
+## Run it
+
+```bash
+pinecall run agent/index.js
+```
+
+You'll see the boot banner with agent name, model, and phone number. When calls come in, the runner displays a live transcript with tool calls.
+
+That's it. No web server, no token endpoint, no frontend. The agent answers calls to `+13186330963` and logs every call to `calls.jsonl`. When the LLM calls `lookupOrder`, the SDK validates the args with Zod and runs the execute function automatically.
+
+## Adding more tools
+
+Just define more `tool()` objects and include them in the array:
+
+```typescript
+const processReturn = tool({
+  name: "processReturn",
+  description: "Start a return process for an order.",
+  schema: z.object({
+    orderId: z.string().describe("The order ID to return"),
+    reason: z.string().describe("Reason for the return"),
+  }),
+  execute: async ({ orderId, reason }) => {
+    // your logic — create a return ticket, etc.
+    return { returnId: "RET-001", status: "initiated" };
+  },
+});
+
+const agent = pc.agent("support", {
+  // ...same config
+  tools: [lookupOrder, processReturn],
+});
+```
+
+## Adding WhatsApp
+
+Same headless pattern — add a channel:
+
+```typescript
+agent.addWhatsapp({
+  phoneNumberId: process.env.WA_PHONE_NUMBER_ID,
+  accessToken: process.env.WA_TOKEN,
+  appSecret: process.env.WA_APP_SECRET,
+});
+```
+
+Now the agent answers both phone calls **and** WhatsApp messages. Same prompt, same tools, no extra code.
+
+## Deploy options
+
+- **PM2 / systemd** — long-running daemon on a server
+- **Docker container** — one image, multiple instances
+- **Fly.io / Railway / Render** — managed processes
+
+The agent only needs outbound network access to `voice.pinecall.io`. No inbound ports, no public IPs.
+
+## What's next
+
+- [Multi-channel bot example](/examples/multi-channel-bot)
+- [Chat bot example](/examples/chat-bot)
+- [Browser widget example](/examples/browser-widget)
+- [Deployment topologies](/concepts/deployment-topologies)

package/skills/pinecall-examples/references/examples/index.md

@@ -0,0 +1,183 @@
+---
+title: "Examples"
+description: "Runnable examples showing Pinecall SDK features in action."
+---
+
+# Examples
+
+Each example is a self-contained project in `examples/` following the `agent/index.js` convention. Clone, configure, and run.
+
+## Quick Start
+
+```bash
+cd examples/<example>
+cp .env.example .env         # edit with your values
+npm install
+pinecall run agent/index.js   # or agent/index.ts
+```
+
+---
+
+## Runnable Examples
+
+### Simple Agent
+
+**`examples/simple/`** — The minimal Pinecall setup. A voice agent with `JsonFileHistory` for automatic call persistence.
+
+**What it shows:**
+- `agent/index.js` convention — auto-connect, export agent
+- `greeting` in config — no `call.started` handler needed
+- `JsonFileHistory` for automatic call persistence
+- Auto-restored history for returning callers
+
+```typescript
+// agent/index.js
+const pc = new Pinecall();
+
+export const agent = pc.agent("simple-agent", {
+  voice: "elevenlabs/sarah",
+  stt: "deepgram/flux",
+  llm: "openai/gpt-5-chat-latest",
+  phoneNumber: process.env.PHONE,
+  greeting: "Hello! How can I help you today?",
+  history: new JsonFileHistory("./data/calls.json"),
+});
+```
+
+📖 Related: [Inbound Voice](/guides/inbound-voice) · [Conversation History](/guides/conversation-history)
+
+---
+
+### Reservations Agent
+
+**`examples/reservations/`** — A restaurant reservation agent with tools. Demonstrates the `tool()` + Zod pattern with `agent/index.ts` and `agent/tools.ts`.
+
+**What it shows:**
+- `tool()` with Zod schemas for type-safe tool definitions
+- Tools in a separate `agent/tools.ts` module
+- Agent exports pattern — `export const agent = pc.agent(...)`
+- `pinecall run agent/index.ts` for live development
+
+```typescript
+// agent/tools.ts
+export const checkAvailability = tool({
+  name: "checkAvailability",
+  description: "Check table availability for a date and party size.",
+  schema: z.object({
+    date: z.string(),
+    time: z.string(),
+    partySize: z.number(),
+  }),
+  execute: async ({ date, time, partySize }) => ({ available: true, table: "garden terrace" }),
+});
+```
+
+📖 Related: [Tool definitions](/api/agent#creation) · [CLI reference](/reference/cli#pinecall-run-file)
+
+---
+
+### Turn Detection
+
+**`examples/turn-detection/`** — Debug turn detection events in real-time. Switch between Flux (native turns) and Nova-3 (SmartTurn + Silero) by changing `MODEL` in `.env`.
+
+**What it shows:**
+- `speech.started`, `user.speaking`, `user.message` event flow
+- `turn.pause` (SmartTurn analyzing) vs `turn.end` (confirmed)
+- `bot.speaking` / `bot.finished` / `bot.interrupted` (barge-in)
+- Colored console output with timestamps
+
+**Config via `.env`:**
+```env
+PHONE=+13049709763
+MODEL=nova          # "flux" or "nova"
+STT_LANG=es         # "en", "es", "ar", etc.
+```
+
+**Key difference to observe:**
+| | Flux | Nova-3 |
+|---|---|---|
+| `turn.pause` | ❌ Never | ✅ SmartTurn emits while analyzing |
+| Turn speed | ~200ms (native) | ~400-600ms (Silero → SmartTurn) |
+
+📖 Related: [Turn Detection Guide](/concepts/turn-detection) · [STT Providers](/reference/stt-providers)
+
+---
+
+### Call Ringing
+
+**`examples/ringing/`** — Accept or reject incoming calls programmatically. When `ringing: true`, calls emit `call.ringing` instead of auto-answering.
+
+**What it shows:**
+- `call.ringing` event with caller info
+- `call.accept()` and `call.reject(reason)` flow
+- Blacklist filtering (reject specific numbers)
+- Timeout auto-accept (if SDK doesn't respond in time)
+
+```typescript
+agent.on("call.ringing", (call) => {
+  if (BLACKLIST.includes(call.from)) {
+    call.reject("busy");
+  } else {
+    call.accept();
+  }
+});
+```
+
+📖 Related: [Call Ringing Guide](/guides/call-ringing)
+
+---
+
+### Conversation History
+
+**`examples/history/`** — Conversation persistence across calls. When the same contact calls again, the agent restores the previous conversation context.
+
+**What it shows:**
+- `JsonFileHistory` — save/load to a JSON file
+- `history.findByContact()` — find prior conversations
+- `call.setHistory()` — inject previous messages
+- Custom `HistoryStore` interface for your own backend
+
+📖 Related: [Conversation History Guide](/guides/conversation-history)
+
+---
+
+### WhatsApp Dashboard
+
+**`examples/whatsapp-dashboard/`** — A WhatsApp agent with a human takeover dashboard. Express backend + React frontend with SSE live updates.
+
+**What it shows:**
+- `agent.addWhatsapp()` channel registration
+- `whatsapp.sessionStarted` / `whatsapp.message` / `whatsapp.response` events
+- `agent.pause()` / `agent.resume()` for human takeover
+- `agent.sendMessage()` — human operator sends messages
+- `agent.stream(res)` — SSE event stream for React dashboard
+- Conversation history via `JsonFileHistory`
+
+```typescript
+const agent = pc.agent("support", {
+  llm: "openai/gpt-5-chat-latest",
+  prompt: "You are a helpful customer support agent on WhatsApp.",
+  history: new JsonFileHistory("./data/conversations.json"),
+});
+
+agent.addWhatsapp({
+  phoneNumberId: process.env.WA_PHONE_NUMBER_ID,
+  accessToken: process.env.WA_ACCESS_TOKEN,
+});
+```
+
+📖 Related: [WhatsApp Guide](/guides/whatsapp) · [Human Takeover](/guides/human-takeover) · [SSE Streaming](/guides/sse-streaming)
+
+---
+
+## Conceptual Examples (docs only)
+
+These examples live in the docs as full code walkthroughs — no separate `examples/` folder.
+
+| Example | What it covers |
+|---|---|
+| [Browser Widget](/examples/browser-widget) | WebRTC `@pinecall/web` integration |
+| [Chat Bot](/examples/chat-bot) | Text-only LLM chat (no audio) |
+| [Headless Agent](/examples/headless-agent) | Server-side agent without UI |
+| [Multi-Channel Bot](/examples/multi-channel-bot) | Voice + WhatsApp + chat on one agent |
+| [Turn Detection](/examples/turn-detection) | Flux vs SmartTurn event comparison |

package/skills/pinecall-examples/references/examples/multi-channel-bot.md

@@ -0,0 +1,173 @@
+---
+title: "Example: Multi-Channel Bot"
+description: "One agent serving phone, WhatsApp, and browser WebRTC simultaneously."
+---
+
+# Example: Multi-Channel Bot
+
+A support bot serving phone calls, WhatsApp messages, and a browser widget — from the **same agent**, with the **same prompt and tools**. The agent code doesn't care which transport the conversation arrived on.
+
+## What it does
+
+`support.js` is the support bot for Acme Corp:
+
+- Customers call `+13186330963` (Twilio) → phone conversation
+- Customers message Acme's WhatsApp Business number → WhatsApp conversation
+- Customers in the app click "Talk to support" → WebRTC browser conversation
+
+All three converge on the same agent. Same prompt. Same tools. Same database. Same logging.
+
+## The complete file
+
+```typescript
+// support.js
+import { Pinecall } from "@pinecall/sdk";
+import express from "express";
+
+// ---- Mock database (replace with yours) ----
+const orders = {
+  "ORD-001": { status: "shipped", tracking: "1Z999AA10123456784" },
+  "ORD-002": { status: "processing" },
+  "ORD-003": { status: "delivered", deliveredAt: "2026-05-20" },
+};
+
+// ---- Pinecall client ----
+const pc = new Pinecall();
+
+// ---- Tools ----
+import { tool } from "@pinecall/sdk";
+import { z } from "zod";
+
+const lookupOrder = tool({
+  name: "lookupOrder",
+  description: "Look up an order by its ID (format: ORD-XXX)",
+  schema: z.object({ orderId: z.string() }),
+  execute: async ({ orderId }) => orders[orderId] ?? { error: "not_found" },
+});
+
+const transferToHuman = tool({
+  name: "transferToHuman",
+  description: "Transfer voice call to a human agent. Only works on phone/WebRTC.",
+  schema: z.object({}),
+  execute: async (_, call) => {
+    if (call.transport === "phone" || call.transport === "webrtc") {
+      call.say("Sure, let me get a human on the line.");
+      call.forward("+15558675309");
+      return { transferred: true };
+    }
+    return { transferred: false, note: "A human will respond within an hour." };
+  },
+});
+
+const endConversation = tool({
+  name: "endConversation",
+  description: "End the conversation when the customer says goodbye.",
+  schema: z.object({}),
+  execute: async (_, call) => {
+    if (call.transport === "phone" || call.transport === "webrtc") {
+      call.say("Thanks for calling. Have a great day!");
+      call.once("bot.finished", () => call.hangup());
+    }
+    return { ended: true };
+  },
+});
+
+// ---- The agent ----
+const support = pc.agent("acme-support", {
+  voice: "elevenlabs/sarah",
+  language: "en",
+  llm: "openai/gpt-5-chat-latest",
+  stt: "deepgram/flux",
+  phoneNumber: "+13186330963",
+  prompt: `You are Nova, a support agent at Acme Corp.
+
+You can:
+- Look up order status with lookupOrder
+- Transfer to a human with transferToHuman (use sparingly)
+- End the call/conversation when the customer is done
+
+Be concise. On voice, keep responses to 1-2 sentences.
+On WhatsApp, you can be slightly longer but still brief.`,
+  tools: [lookupOrder, transferToHuman, endConversation],
+  greeting: "Hi, this is Nova at Acme. How can I help?",
+});
+
+// ---- Register WhatsApp ----
+support.addWhatsapp({
+  phoneNumberId: process.env.WA_PHONE_NUMBER_ID,
+  accessToken: process.env.WA_TOKEN,
+  appSecret: process.env.WA_APP_SECRET,
+});
+
+
+
+// ---- Logging (universal) ----
+support.on("call.ended", async (call, reason) => {
+  console.log(
+    `[${call.transport}] ${call.id} ended (${reason}) — ${call.duration}s, ${call.transcript.length} msgs`,
+  );
+  // Save to your DB...
+});
+
+// ---- WhatsApp-specific observability ----
+support.on("whatsapp.message", (event) => {
+  console.log(`💬 ${event.name}: ${event.text}`);
+});
+
+// ---- Express server for token endpoint (WebRTC) ----
+const app = express();
+
+app.get("/api/token", async (req, res) => {
+  // In production: add your auth check here
+  const token = await support.createToken("webrtc");
+  res.json(token);
+});
+
+// ---- Live event stream for dashboard ----
+app.get("/api/events", (req, res) => {
+  support.stream(res);
+});
+
+app.listen(3000, () => {
+  console.log("Support bot live on phone, WhatsApp, and WebRTC");
+  console.log("Token endpoint: http://localhost:3000/api/token");
+  console.log("Event stream:   http://localhost:3000/api/events");
+});
+```
+
+## Why this works
+
+The agent code never branches on transport. The LLM gets the same prompt and tools regardless of whether the user is calling, messaging, or in the browser. The only places the code checks `call.transport` are:
+
+1. **Greeting** — voice channels need a greeting, WhatsApp doesn't (they message first)
+2. **Tool effects** — `transferToHuman` and `endConversation` only make sense on voice
+
+Everything else — tool definitions, the LLM, the response generation — is unified.
+
+## Adding a fourth channel
+
+Need to add SIP for a call center integration? One line:
+
+```typescript
+support.addPhoneNumber("sip:bot@trunk.acmetel.com");
+```
+
+WebRTC and Chat work automatically via tokens — the agent handles all transports.
+
+## Deploy
+
+```bash
+PINECALL_API_KEY=pk_... \
+WA_PHONE_NUMBER_ID=123... \
+WA_TOKEN=EAA... \
+WA_APP_SECRET=abc... \
+node support.js
+```
+
+Configure the WhatsApp webhook (in Meta's dashboard) to point to `https://voice.pinecall.io/whatsapp/webhook`. Done.
+
+## What's next
+
+- [Browser widget example](/examples/browser-widget)
+- [Multi-tenant guide](/guides/multi-tenant) — host many bots like this
+- [WhatsApp guide](/guides/whatsapp) — full WhatsApp setup