@pinecall/skills 0.1.0

package/skills/pinecall-examples/references/examples/outbound-dispatch.md

@@ -0,0 +1,109 @@
+---
+title: "Outbound Dispatch"
+description: "CSV-driven outbound campaign with rate limiting, dedup, and result writeback."
+---
+
+# Outbound Dispatch
+
+> **Source:** [`examples/outbound-dispatch/`](https://github.com/pinecall/sdk/tree/main/examples/outbound-dispatch)
+
+This example builds a complete outbound campaign system that:
+
+1. Reads leads from a CSV file
+2. Dispatches personalized appointment reminder calls
+3. Uses per-call `promptVars` to inject contact details into the AI prompt
+4. Lets the AI confirm/cancel via a tool that writes results back to CSV
+5. Handles no-answer, busy, and rejection automatically
+
+## Architecture
+
+![Outbound dispatch architecture](/assets/diagrams/outbound-dispatch-arch.png)
+
+## Prerequisites
+
+- A Pinecall API key with outbound calling enabled
+- A phone number (Twilio) registered in your Pinecall organization
+- Node.js ≥ 18
+
+## Setup
+
+```bash
+cd examples/outbound-dispatch
+cp .env.example .env
+# Edit .env with your API key and phone
+npm install
+```
+
+## CSV format
+
+The CSV must have a header row. The dispatcher skips rows that already have a `status` value:
+
+```csv
+name,phone,service,date,time
+Maria,+14155551234,Eye Exam,June 12,10:00 AM
+Carlos,+14155559876,Physiotherapy,June 15,5:30 PM
+```
+
+After calls complete, the CSV is updated:
+
+```csv
+name,phone,service,date,time,status
+Maria,+14155551234,Eye Exam,June 12,10:00 AM,confirmed
+Carlos,+14155559876,Physiotherapy,June 15,5:30 PM,no_answer
+```
+
+## Key concepts
+
+### Content-based dedup
+
+Records are identified by `phone + service + date`, not by row index. Two identical CSV entries produce the same ID and are dispatched only once:
+
+```javascript
+mapRow: (row) => ({
+  id: `${row.phone}-${row.service}-${row.date}`,
+  // ...
+})
+```
+
+### Phone-level dedup
+
+The hub tracks active phones. If Bernardo has two appointments (Eye Exam + Physio), only one call runs at a time. The second dispatches automatically after the first ends.
+
+### Prompt variables
+
+Each call sends per-call context via `promptVars` on the record returned by `mapRow`:
+
+```javascript
+promptVars: {
+  appointment_details: `Name: ${row.name}\nService: ${row.service}\nDate: ${row.date}\nTime: ${row.time}`,
+},
+```
+
+These replace `{{appointment_details}}` in the agent prompt.
+
+### Lifecycle callbacks
+
+Handle calls that end without the AI calling a tool (rejected, no answer):
+
+```javascript
+csv.onCompleted = (record, callId, reason) => {
+  // Don't overwrite if the tool already wrote a status
+  writeResultToCsv(record.phone, record.service, reason);
+};
+
+csv.onFailed = (record, error) => {
+  writeResultToCsv(record.phone, record.service, "no_answer");
+};
+```
+
+### Dial rejection
+
+`agent.dial()` rejects immediately when Twilio reports `busy`, `no-answer`, `failed`, or `canceled` — no 30-second timeout. The hub catches this in `onFailed`.
+
+## Run
+
+```bash
+node server.js
+```
+
+Add rows to `data/leads.csv` while the script is running — the dispatcher detects new rows on every poll cycle (default 5s) and places calls automatically.

package/skills/pinecall-examples/references/examples/turn-detection.md

@@ -0,0 +1,150 @@
+---
+title: "Example: Turn Detection"
+description: "Debug turn events in real-time — per-turn containers showing the full state machine lifecycle."
+---
+
+# Example: Turn Detection
+
+A dev-friendly debug tool that shows **every turn event in real-time**, grouped into visual containers that mirror the server-side turn state machine. Each turn container shows state transitions as they happen.
+
+## State machine
+
+The server maintains a 5-state machine for every call:
+
+![Turn detection state machine](/assets/diagrams/turn-state-machine.png)
+
+## What you'll see
+
+Each turn is rendered as a bordered container:
+
+```
+    ┌ Turn #1  ·  IDLE → LISTENING                     08:53:08.000
+    │  🎙  speech.started
+    │  💬  "Hola, ¿qué tal?"
+    │  📝  "Hola. ¿Qué tal?"
+    │
+    │  LISTENING → BOT_PENDING  prob=96%
+    │
+    │  BOT_PENDING → BOT_SPEAKING
+    │  🤖  bot.speaking  "..."
+    │  🗣  "¡Hola! Estoy bien, gracias. ¿Y tú?"
+    │  📨  message.confirmed
+    │  🔇  bot.finished  3846ms
+    │
+    └ 4.2s
+```
+
+### Interruptions (barge-in)
+
+When the user cuts off the bot, a highlighted interruption section appears:
+
+```
+    ┌ Turn #3  ·  IDLE → LISTENING                     08:54:01.000
+    │  🎙  speech.started
+    │  📝  "Cuéntame un cuento largo"
+    │
+    │  LISTENING → BOT_PENDING  prob=95%
+    │
+    │  BOT_PENDING → BOT_SPEAKING
+    │  🤖  bot.speaking  "..."
+    │  🗣  "Érase una vez, en un reino muy lejano..."
+    │
+    ├─── ⚡ INTERRUPTION ─────────────────────────────
+    │  BOT_SPEAKING → LISTENING  barge-in after 2100ms
+    │  🗣  said: "Érase una vez, en un reino muy lejano..."
+    │  ↻  continuation — user keeps talking
+    │
+    │  💬  "No, algo más corto"
+    │  📝  "No, algo más corto"
+    │
+    │  LISTENING → BOT_PENDING  prob=97%
+    │
+    │  BOT_PENDING → BOT_SPEAKING
+    │  🤖  bot.speaking  "..."
+    │  🗣  "¡Claro! Había una vez un gato que..."
+    │  🔇  bot.finished  3200ms
+    │
+    └ 12.4s
+```
+
+## The code
+
+The key pattern: a `turn` tracker object that maps SDK events to server states:
+
+```typescript
+const turn = {
+  id: 0, state: "IDLE", startTime: null, open: false,
+
+  log(icon, detail) {
+    console.log(`    │  ${icon}  ${detail}`);
+  },
+  transition(to, extra = "") {
+    const arrow = `${this.state} → ${to}`;
+    this.state = to;
+    console.log(`    │\n    │  ${arrow}  ${extra}\n    │`);
+  },
+  start(turnId) {
+    this.id = turnId;
+    this.state = "LISTENING";
+    this.startTime = Date.now();
+    this.open = true;
+    console.log(`\n    ┌ Turn #${this.id}  ·  IDLE → LISTENING`);
+  },
+  end() {
+    const dur = ((Date.now() - this.startTime) / 1000).toFixed(1);
+    this.state = "IDLE";
+    this.open = false;
+    console.log(`    └ ${dur}s`);
+  },
+};
+
+// Map events to state transitions
+agent.on("speech.started", (e) => { turn.start(e.turnId); });
+agent.on("user.message", (e) => { turn.log("📝", `"${e.text}"`); });
+agent.on("turn.end", () => { turn.transition("BOT_PENDING"); });
+agent.on("bot.speaking", () => { turn.transition("BOT_SPEAKING"); });
+agent.on("bot.word", (e, call) => { /* live preview via call.currentBotText */ });
+agent.on("bot.finished", () => { turn.end(); });
+agent.on("bot.interrupted", (e, call) => {
+  // Render interruption divider, show what was said
+  turn.interruption(e.playedMs, e.reason, call.currentBotText);
+});
+```
+
+The full runnable version is in [`examples/turn-detection/server.js`](https://github.com/pinecall/sdk/tree/master/examples/turn-detection) — with ANSI colors, timestamps, and the state machine diagram in the startup banner.
+
+## Run it
+
+```bash
+cd examples/turn-detection
+cp .env.example .env    # edit with your API key and phone number
+node server.js
+```
+
+## Configuration
+
+Set in `.env`:
+
+| Variable | Default | Description |
+|---|---|---|
+| `PINECALL_API_KEY` | required | Your API key |
+| `PHONE` | required | Phone number to register |
+| `MODEL` | `nova` | `nova` → SmartTurn + Silero, `flux` → native turns |
+| `STT_LANG` | `es` | Language code (`en`, `es`, `ar`, `fr`, `de`, `pt`) |
+
+## State transitions to observe
+
+| SDK Event | State Before | State After | Notes |
+|---|---|---|---|
+| `speech.started` | IDLE | LISTENING | New turn opens |
+| `turn.pause` | LISTENING | LISTENING | SmartTurn analyzing (nova only) |
+| `turn.end` | LISTENING | BOT_PENDING | User finished, LLM fires |
+| `bot.speaking` | BOT_PENDING | BOT_SPEAKING | TTS audio starts |
+| `bot.finished` | BOT_SPEAKING | IDLE | Turn closes |
+| `bot.interrupted` | BOT_SPEAKING | LISTENING | Barge-in, user keeps talking |
+
+## What's next
+
+- [Turn Detection guide](/concepts/turn-detection) — full explanation of the state machine
+- [STT Providers](/reference/stt-providers) — language coverage and tuning parameters
+- [Events reference](/reference/events) — all events including `bot.word` and `currentBotText`

package/skills/pinecall-guides/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: pinecall-guides
+description: >-
+  Task guides for building Pinecall agent features. Use when the user is building, configuring, or debugging with @pinecall/sdk. Keywords: inbound, outbound, whatsapp, tools, function calling, events, live listening, conversation history, human takeover, webrtc, multi-tenant, dev mode, testing, agent.dial, call.say, tool().
+license: MIT
+---
+
+# Guides
+
+Task guides for building Pinecall agent features.
+
+This skill bundles the official Pinecall documentation for **Guides**. The
+table below indexes every page; open the `references/…` file for the full text
+(loaded on demand). Source of truth: <https://docs.pinecall.io>.
+
+| Page | What it covers | Open |
+|------|----------------|------|
+| **Inbound Voice** | Build a voice agent that answers phone calls. | [`references/guides/inbound-voice.md`](references/guides/inbound-voice.md) · [docs](https://docs.pinecall.io/guides/inbound-voice) |
+| **Outbound Calls** | Make programmatic outbound phone calls with a greeting and metadata. | [`references/guides/outbound-calls.md`](references/guides/outbound-calls.md) · [docs](https://docs.pinecall.io/guides/outbound-calls) |
+| **Events Guide** | Complete guide to every event in the Pinecall SDK — lifecycle, speech, turn, bot, tools, session, WhatsApp, and more. | [`references/guides/events.md`](references/guides/events.md) · [docs](https://docs.pinecall.io/guides/events) |
+| **Live Listening** | Listen to active calls in real-time from a browser or custom client. | [`references/guides/live-listening.md`](references/guides/live-listening.md) · [docs](https://docs.pinecall.io/guides/live-listening) |
+| **WhatsApp** | Build a WhatsApp messaging agent using Meta's Cloud API. | [`references/guides/whatsapp.md`](references/guides/whatsapp.md) · [docs](https://docs.pinecall.io/guides/whatsapp) |
+| **Conversation History** | Save and restore conversations across calls so your agent remembers returning contacts. | [`references/guides/conversation-history.md`](references/guides/conversation-history.md) · [docs](https://docs.pinecall.io/guides/conversation-history) |
+| **Human Takeover** | Pause the AI agent so a human can intervene in real-time conversations. | [`references/guides/human-takeover.md`](references/guides/human-takeover.md) · [docs](https://docs.pinecall.io/guides/human-takeover) |
+| **WebRTC in the Browser** | Embed a Pinecall voice agent in your web app using the React widget. | [`references/guides/webrtc-browser.md`](references/guides/webrtc-browser.md) · [docs](https://docs.pinecall.io/guides/webrtc-browser) |
+| **Tools and Functions** | Let your agent take actions: look up data, transfer calls, book appointments. | [`references/guides/tools-and-functions.md`](references/guides/tools-and-functions.md) · [docs](https://docs.pinecall.io/guides/tools-and-functions) |
+| **Knowledge bases (RAG)** | Tutorial — ground a voice or chat agent on your own documents with retrieval-augmented generation. | [`references/guides/knowledge-bases.md`](references/guides/knowledge-bases.md) · [docs](https://docs.pinecall.io/guides/knowledge-bases) |
+| **Multi-Tenant Dashboards** | Host many tenants on one Pinecall instance with scoped event streams. | [`references/guides/multi-tenant.md`](references/guides/multi-tenant.md) · [docs](https://docs.pinecall.io/guides/multi-tenant) |
+| **SSE Event Streaming** | Stream agent events to your frontend in real time with Server-Sent Events. | [`references/guides/sse-streaming.md`](references/guides/sse-streaming.md) · [docs](https://docs.pinecall.io/guides/sse-streaming) |
+| **WebSocket Event Streaming** | Stream agent events over WebSocket for bidirectional, real-time communication with your frontend. | [`references/guides/ws-streaming.md`](references/guides/ws-streaming.md) · [docs](https://docs.pinecall.io/guides/ws-streaming) |
+| **Dev Mode** | Run dev and production agents on the same phone number, with zero extra Twilio cost. | [`references/guides/dev-mode.md`](references/guides/dev-mode.md) · [docs](https://docs.pinecall.io/guides/dev-mode) |
+| **Call Ringing & Reject** | Screen incoming calls before answering — accept, reject, or route based on caller info. | [`references/guides/call-ringing.md`](references/guides/call-ringing.md) · [docs](https://docs.pinecall.io/guides/call-ringing) |
+| **Testing Agents** | Automated QA for voice agents using YAML specs and LLM judges. | [`references/guides/testing-agents.md`](references/guides/testing-agents.md) · [docs](https://docs.pinecall.io/guides/testing-agents) |
+
+## Canonical agent
+
+```typescript
+import { Pinecall } from "@pinecall/sdk";
+
+const pc = new Pinecall(); // reads PINECALL_API_KEY, auto-connects
+
+const agent = pc.agent("mara", {
+  prompt: "You are Mara, a friendly voice assistant. Be concise.",
+  llm: "openai/gpt-5-chat-latest",
+  voice: "elevenlabs/sarah",
+  stt: "deepgram/flux",
+  language: "en",
+  greeting: "Hello! How can I help?",
+});
+```
+
+## House rules — always apply
+
+- **Example defaults** (use these exact strings unless the user asks otherwise):
+  `stt: "deepgram/flux"`, `llm: "openai/gpt-5-chat-latest"`, `voice: "elevenlabs/sarah"`.
+  **NEVER use `deepgram/nova-2`** — it is not supported. Use `deepgram/nova-3`
+  only for languages Flux doesn't support (e.g. Arabic).
+- **Turn detection & VAD are auto-derived from the STT provider — never set
+  `turnDetection` or `vad` manually.** Flux → native turns + native VAD;
+  every other STT → `smart_turn` + `silero`.
+- **Greeting**: inbound → `greeting` field in `pc.agent()`; outbound → `greeting`
+  field in `agent.dial()`. It is sugar for `call.say()` in `call.started`.
+- **Auth**: `new Pinecall()` reads `PINECALL_API_KEY` from env and auto-connects.
+- Full documentation: <https://docs.pinecall.io>
+
+---
+*Generated from `sdk/docs/` by `@pinecall/skills` — do not edit by hand; edit the
+docs and re-run `node build.mjs`.*

package/skills/pinecall-guides/references/guides/call-ringing.md

@@ -0,0 +1,149 @@
+---
+title: "Call Ringing & Reject"
+description: "Screen incoming calls before answering — accept, reject, or route based on caller info."
+---
+
+# Call Ringing & Reject
+
+By default, Pinecall auto-accepts every incoming call. The **ringing** feature gives you a window to inspect the call _before_ it's answered, so you can:
+
+- **Reject** spam or blacklisted callers
+- **Route** calls to different agents based on caller ID
+- **Log** incoming calls for analytics
+- **Conditionally accept** based on time of day, capacity, etc.
+
+## How it works
+
+![Call ringing flow — accept or reject](/assets/diagrams/call-ringing-flow.png)
+
+Without ringing enabled, the flow goes directly from ring → `call.started` (auto-accept).
+
+## Enable ringing
+
+Pass `ringing: true` in the phone number config:
+
+```typescript
+const agent = pc.agent("receptionist", {
+  phoneNumber: { number: "+13186330963", ringing: true },
+});
+```
+
+> **Warning:** Only phone channels support ringing. WebRTC and chat channels don't have a ringing phase.
+
+## Handle `call.ringing`
+
+When a call comes in, the SDK emits `call.ringing` with a `RingingCall` object. This object has caller info but no audio — the call isn't connected yet.
+
+```typescript
+agent.on("call.ringing", (call) => {
+  console.log(`Incoming: ${call.from} → ${call.to}`);
+  console.log(`Call SID: ${call.callId}`);
+
+  // Accept the call — proceeds to call.started
+  call.accept();
+});
+```
+
+### RingingCall API
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `call.callId` | `string` | Twilio Call SID |
+| `call.from` | `string` | Caller phone number (E.164) |
+| `call.to` | `string` | Called phone number (E.164) |
+| `call.accept()` | `void` | Accept the call — triggers `call.started` |
+| `call.reject(reason?)` | `void` | Reject the call. Reason: `"busy"` or `"rejected"` |
+
+## Reject calls
+
+Reject with an optional reason that maps to a Twilio rejection:
+
+```typescript
+agent.on("call.ringing", (call) => {
+  if (BLACKLIST.has(call.from)) {
+    call.reject("busy");    // caller hears busy signal
+    return;
+  }
+  call.accept();
+});
+```
+
+| Reason | Caller experience |
+|--------|-------------------|
+| `"busy"` | Hears busy tone |
+| `"rejected"` | Call is dropped immediately |
+| _(none)_ | Defaults to `"busy"` |
+
+## Default behavior
+
+If you don't call `accept()` or `reject()` within the timeout (configurable on the server, default ~5s), the call is **auto-accepted**. This prevents calls from hanging indefinitely if your handler crashes.
+
+> **Note:** If you don't register a `call.ringing` handler at all, calls are auto-accepted immediately — same as before this feature existed. Ringing is fully opt-in.
+
+## Full example
+
+```typescript
+import { Pinecall } from "@pinecall/sdk";
+
+const pc = new Pinecall({ apiKey: process.env.PINECALL_API_KEY });
+
+const BLACKLIST = new Set(["+15551234567", "+15559876543"]);
+
+const agent = pc.agent("receptionist", {
+  voice: "elevenlabs/sarah",
+  language: "en",
+  stt: "deepgram/flux",
+  llm: "openai/gpt-5-chat-latest",
+  prompt: "You are a receptionist. Be brief and helpful.",
+  // Enable ringing on the phone channel
+  phoneNumber: { number: "+13186330963", ringing: true },
+});
+
+// Screen calls before answering
+agent.on("call.ringing", (call) => {
+  console.log(`🔔 Incoming: ${call.from}`);
+
+  if (BLACKLIST.has(call.from)) {
+    console.log(`❌ Rejected: ${call.from} (blacklisted)`);
+    call.reject("busy");
+    return;
+  }
+
+  console.log(`✅ Accepted: ${call.from}`);
+  call.accept();
+});
+
+// Normal call lifecycle
+agent.on("call.started", (call) => {
+  call.say("Thanks for calling! How can I help?");
+});
+
+agent.on("call.ended", (call, reason) => {
+  console.log(`📴 ${call.id} ended: ${reason} (${call.duration}s)`);
+});
+```
+
+Run the example from the SDK repo:
+
+```bash
+cd sdk/examples/ringing
+PHONE=+13186330963 node server.js
+```
+
+## Wire protocol
+
+The ringing handshake uses two new events and commands:
+
+| Direction | Message | Payload |
+|-----------|---------|---------|
+| Server → SDK | `call.ringing` | `{ call_id, from, to }` |
+| SDK → Server | `call.accept` | `{ call_id }` |
+| SDK → Server | `call.reject` | `{ call_id, reason }` |
+
+For full wire protocol details, see `sdk-server/PROTOCOL.md`.
+
+## What's next
+
+- [Inbound Voice](/guides/inbound-voice) — the standard (non-ringing) flow
+- [Dev Mode](/guides/dev-mode) — route dev calls to your local agent
+- [Events Reference](/reference/events) — all SDK events