@pinecall/skills 0.1.0

package/skills/pinecall-guides/references/guides/live-listening.md

@@ -0,0 +1,199 @@
+---
+title: "Live Listening"
+description: "Listen to active calls in real-time from a browser or custom client."
+---
+
+# Live Listening
+
+Monitor active calls in real-time. Pinecall mixes both sides of the conversation (user + bot) into a single audio stream accessible via WebSocket.
+
+## Enable media
+
+Add `media` to your agent config to enable live listening, recording, or both:
+
+```typescript
+const agent = pc.agent("support", {
+  prompt: "You are a support agent.",
+  voice: "elevenlabs/sarah",
+  llm: "openai/gpt-5-chat-latest",
+  stt: "deepgram/flux",
+  media: {
+    live: true,       // enables real-time WebSocket stream
+    recording: true,  // keeps full call recording in memory
+  },
+});
+```
+
+When a call starts, you can build a live listening URL from the call ID:
+
+```typescript
+agent.on("call.started", (call) => {
+  const url = `https://voice.pinecall.io/live/${call.id}/player?token=${API_KEY}`;
+  console.log(`Listen live: ${url}`);
+});
+```
+
+## Built-in player
+
+Pinecall provides a hosted player page. Open the URL in any browser:
+
+```
+https://voice.pinecall.io/live/{callId}/player?token=pk_xxx
+```
+
+The page connects via WebSocket and plays the mixed audio through an AudioWorklet with minimal latency. No dependencies or setup needed.
+
+## Authentication
+
+All live listening endpoints require a valid Pinecall API key passed as a `token` query parameter. The key must belong to the same organization as the active session.
+
+| Endpoint | Auth |
+|---|---|
+| `GET /live/{id}/player?token=pk_xxx` | API key in query param |
+| `WS /live/{id}/ws?token=pk_xxx` | API key in query param |
+
+Without a valid token the server returns `401`.
+
+## Build a custom player
+
+If you need a custom UI or integration, connect directly to the WebSocket endpoint.
+
+### WebSocket protocol
+
+**Connect:**
+
+```
+wss://voice.pinecall.io/live/{callId}/ws?token=pk_xxx
+```
+
+**First message** — JSON metadata:
+
+```json
+{
+  "type": "metadata",
+  "sampleRate": 8000,
+  "channels": 1,
+  "bitDepth": 16,
+  "sessionId": "CA..."
+}
+```
+
+**Subsequent messages** — binary frames containing raw PCM audio:
+- Format: 16-bit signed little-endian (Int16LE), mono
+- Sample rate: `8000` for Twilio calls, `16000` for WebRTC calls
+- Chunk size: ~800 bytes per frame (50ms at 8kHz)
+
+**End of call** — the server sends an empty binary frame (`0 bytes`) and closes the connection.
+
+**Keepalive** — during silence the server sends a 2-byte zero frame every 5 seconds.
+
+### Browser example (AudioWorklet)
+
+This is a minimal browser implementation. It connects to the WebSocket, converts PCM Int16 to Float32, and plays through an AudioWorklet:
+
+```javascript
+// 1. Create the AudioWorklet processor
+const PROCESSOR = `
+class Player extends AudioWorkletProcessor {
+  constructor() {
+    super();
+    this._q = [];
+    this.port.onmessage = (e) => this._q.push(e.data.samples);
+  }
+  process(inputs, outputs) {
+    const out = outputs[0][0];
+    let i = 0;
+    while (i < out.length && this._q.length) {
+      const chunk = this._q[0];
+      const take = Math.min(chunk.length, out.length - i);
+      out.set(chunk.subarray(0, take), i);
+      i += take;
+      if (take === chunk.length) this._q.shift();
+      else this._q[0] = chunk.subarray(take);
+    }
+    for (; i < out.length; i++) out[i] = 0;
+    return true;
+  }
+}
+registerProcessor('player', Player);
+`;
+
+// 2. Set up AudioContext + Worklet
+async function listen(callId, token) {
+  const ctx = new AudioContext({ sampleRate: 8000 });
+  const blob = new Blob([PROCESSOR], { type: 'application/javascript' });
+  await ctx.audioWorklet.addModule(URL.createObjectURL(blob));
+  const node = new AudioWorkletNode(ctx, 'player');
+  node.connect(ctx.destination);
+
+  // 3. Connect WebSocket
+  const ws = new WebSocket(
+    `wss://voice.pinecall.io/live/${callId}/ws?token=${token}`
+  );
+  ws.binaryType = 'arraybuffer';
+
+  ws.onmessage = (e) => {
+    if (typeof e.data === 'string') return; // metadata frame
+
+    const pcm = new Int16Array(e.data);
+    if (pcm.length < 2) return; // keepalive
+
+    // Convert Int16 → Float32
+    const f32 = new Float32Array(pcm.length);
+    for (let i = 0; i < pcm.length; i++) f32[i] = pcm[i] / 32768;
+
+    node.port.postMessage({ samples: f32 });
+  };
+
+  ws.onclose = () => ctx.close();
+
+  return { stop: () => { ws.close(); ctx.close(); } };
+}
+```
+
+### Node.js example
+
+Stream live audio to a file or pipe it to another process:
+
+```typescript
+import WebSocket from "ws";
+import { createWriteStream } from "fs";
+
+const ws = new WebSocket(
+  `wss://voice.pinecall.io/live/${callId}/ws?token=${apiKey}`
+);
+const out = createWriteStream("call.pcm");
+
+ws.on("message", (data, isBinary) => {
+  if (!isBinary) return; // skip metadata
+  if (data.length < 4) return; // skip keepalive
+  out.write(data);
+});
+
+ws.on("close", () => {
+  out.end();
+  // Convert to WAV: ffmpeg -f s16le -ar 8000 -ac 1 -i call.pcm call.wav
+});
+```
+
+## Media config reference
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `live` | `boolean` | `false` | Enable real-time WebSocket streaming |
+| `recording` | `boolean` | `false` | Keep full mixed audio in memory |
+| `maxDurationSeconds` | `number` | `1800` | Max recording length (30 min) |
+
+## How it works
+
+The server maintains two audio buffers — one for user (mic) audio and one for bot (TTS) audio. A background task runs every 50ms, mixing both buffers into a single PCM stream. When bot audio arrives later in the call (e.g., after a greeting delay), the mixer automatically inserts silence to keep the timelines aligned.
+
+On barge-in (user interrupts bot), the bot's remaining audio is discarded and the mixer pads with silence to maintain alignment.
+
+Live listeners subscribe to the mixed output and receive chunks as they're produced. Recording captures the full mixed buffer for export after the call ends.
+
+## What's next
+
+- [Inbound Voice](/guides/inbound-voice) — build a phone agent
+- [Tools and Functions](/guides/tools-and-functions) — let the agent take actions
+- [Events Reference](/reference/events) — all SDK events

package/skills/pinecall-guides/references/guides/multi-tenant.md

@@ -0,0 +1,158 @@
+---
+title: "Multi-Tenant Dashboards"
+description: "Host many tenants on one Pinecall instance with scoped event streams."
+---
+
+# Multi-Tenant Dashboards
+
+A common pattern: you're building a SaaS where each customer has their own agents, and each customer's dashboard should only show their own calls. Pinecall's SSE filtering handles this server-side — no data leakage between tenants.
+
+## The pattern
+
+Each tenant owns one or more agents. When a tenant loads their dashboard, the SSE endpoint streams only events from their agents.
+
+![Multi-tenant SSE scoping](/assets/diagrams/multi-tenant-sse.png)
+
+## Building it
+
+### 1. Store the agent-tenant mapping
+
+In your existing app database, track which agents belong to which tenant:
+
+```typescript
+// e.g. in your tenants table
+{
+  id: "tenant_acme",
+  name: "Acme Corp",
+  agents: ["acme-support", "acme-sales"],
+}
+```
+
+### 2. Spin up the agents
+
+```typescript
+import { Pinecall } from "@pinecall/sdk";
+
+const pc = new Pinecall({ apiKey: process.env.PINECALL_API_KEY! });
+
+const tenants = await db.tenants.findAll();
+
+for (const tenant of tenants) {
+  for (const agentId of tenant.agents) {
+    const config = await db.agentConfigs.findOne(agentId);
+    pc.agent(agentId, {
+      prompt: config.prompt,
+      llm: config.llm,
+      voice: config.voice,
+      language: config.language,
+      phoneNumber: config.phoneNumber,
+    });
+  }
+}
+```
+
+### 3. Stream events scoped to the user's tenant
+
+`pc.stream()` accepts an `agents` filter. Pass only the agents this user is allowed to see:
+
+```typescript
+app.get("/api/events", authMiddleware, (req, res) => {
+  const userId = req.auth.userId;
+  const tenantId = req.auth.tenantId;
+
+  // Look up which agents this tenant owns
+  const tenant = req.cache.tenants.get(tenantId);
+  const allowedAgents = tenant?.agents ?? [];
+
+  if (allowedAgents.length === 0) {
+    res.status(403).end();
+    return;
+  }
+
+  // Subscribe only to those agents — events from other tenants never reach the stream
+  pc.stream(res, { agents: allowedAgents });
+});
+```
+
+The filter is **server-side**. Events from agents the user doesn't own never touch the wire. There's no data leakage possible from the client.
+
+### 4. Consume the stream in the browser
+
+```javascript
+const source = new EventSource("/api/events");
+
+source.addEventListener("call.started", (e) => {
+  const { agent, from, transport } = JSON.parse(e.data);
+  showCallNotification(`[${agent}] Incoming from ${from}`);
+});
+
+source.addEventListener("user.message", (e) => {
+  const { agent, callId, text } = JSON.parse(e.data);
+  appendToTranscript(callId, "user", text);
+});
+
+source.addEventListener("bot.speaking", (e) => {
+  const { agent, callId, text } = JSON.parse(e.data);
+  appendToTranscript(callId, "bot", text);
+});
+```
+
+## Per-tenant token endpoints
+
+The same pattern applies to WebRTC and chat tokens. Each tenant can only mint tokens for their own agents:
+
+```typescript
+app.get("/api/token", authMiddleware, async (req, res) => {
+  const { agentId, channel } = req.query;
+  const tenant = req.cache.tenants.get(req.auth.tenantId);
+
+  if (!tenant.agents.includes(agentId)) {
+    return res.status(403).json({ error: "Forbidden" });
+  }
+
+  const agent = pc.getAgent(agentId);
+  const token = await agent.createToken(channel);
+  res.json(token);
+});
+```
+
+## Per-tenant tool isolation
+
+Tools also need to be tenant-aware. Since tools are registered per agent, build them with a factory that closes over the tenant — each agent gets its own tenant-scoped tool:
+
+```typescript
+import { tool } from "@pinecall/sdk";
+import { z } from "zod";
+
+function lookupOrderTool(tenantId) {
+  const tenantDb = db.scope(tenantId);
+  return tool({
+    name: "lookupOrder",
+    description: "Look up an order by ID",
+    schema: z.object({ orderId: z.string() }),
+    execute: async ({ orderId }) => {
+      return await tenantDb.orders.findOne(orderId);
+    },
+  });
+}
+
+// When spinning up each agent, pass its tenant-scoped tools:
+pc.agent(agentId, {
+  prompt: config.prompt,
+  tools: [lookupOrderTool(tenant.id)],
+});
+```
+
+## Scaling considerations
+
+A single `Pinecall` instance handles dozens to hundreds of agents on one WebSocket. For larger fleets:
+
+- **Split by region** — run one `Pinecall` instance per geographic region, route tenants to the nearest
+- **Split by tier** — separate processes for free/paid tiers to isolate resource limits
+- **Split by capability** — one process for voice-only tenants, another for WhatsApp-heavy tenants
+
+## What's next
+
+- [Deployment topologies](/concepts/deployment-topologies) — embedded is required for SSE
+- [Security](/security) — token model details
+- [Events reference](/reference/events) — all events available over SSE

package/skills/pinecall-guides/references/guides/outbound-calls.md

@@ -0,0 +1,279 @@
+---
+title: "Outbound Calls"
+description: "Make programmatic outbound phone calls with a greeting and metadata."
+---
+
+# Outbound Calls
+
+Pinecall agents can place outbound calls. Use it for appointment reminders, follow-ups, surveys, or any flow where the agent is the one initiating contact.
+
+## The minimum example
+
+```typescript
+const call = await agent.dial({
+  to: "+14155551234",
+  from: "+13186330963",
+  greeting: "Hi! This is a follow-up call from Acme.",
+});
+
+call.on("call.ended", (_, reason) => {
+  console.log(`Done: ${reason}`);
+});
+```
+
+`agent.dial()` returns a `Promise<Call>` — same `Call` object you get from `call.started`.
+
+## How the greeting works
+
+Unlike inbound calls (where you use `call.say()` in `call.started`), outbound calls take a `greeting` string. The server speaks it via TTS the instant the callee picks up — no roundtrip through your code, no race condition between picking up and greeting.
+
+```typescript
+await agent.dial({
+  to: "+14155551234",
+  from: "+13186330963",
+  greeting: "Hi, this is Mara from Acme calling to confirm your appointment tomorrow at 3 PM.",
+});
+```
+
+After the greeting, the conversation continues normally — `turn.end`, `llm.toolCall`, etc. all fire as on inbound calls.
+
+## Required fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `to` | `string` | ✅ | Destination number in E.164 format |
+| `from` | `string` | — | Caller ID — auto-resolved if agent has one phone channel. Required when multiple. |
+| `greeting` | `string` | — | Text the server speaks when the callee picks up |
+| `metadata` | `object` | — | Custom data attached to the call (visible on the `Call` object) |
+| `config` | `object` | — | Per-call config override (voice, STT, language) |
+| `detectTurnEnd` | `boolean` | — | Relay the OTHER party's end-of-turn (`turn.end`) to *your* code. Default `false`. See below. |
+
+> **Tip:** If your agent has exactly one phone channel, you can omit `from` — the SDK auto-resolves it. Only pass `from` explicitly when the agent has multiple phone numbers.
+
+## `detectTurnEnd` — knowing when the other party stops talking
+
+By default an outbound call works like an inbound one: the **server** runs turn
+detection on the callee, decides when they've finished a sentence, and the agent's
+own pipeline (LLM → TTS) replies automatically. Your code doesn't need to be told
+"they stopped talking" — the server already acted on it.
+
+`detectTurnEnd` controls whether that end-of-turn signal is **also relayed to your
+SDK code** as a `turn.end` event:
+
+| Value | What the server does | Use it when |
+|---|---|---|
+| `false` *(default)* | Detects the callee's turns internally and lets the agent's own LLM reply. No `turn.end` is emitted to your code. | A normal call — the agent (or a human on the line) handles the conversation. You don't need to know turn boundaries in code. |
+| `true` | Additionally runs turn detection on the **callee** and emits `turn.end` (plus `eager.turn` / `turn.pause`) to the initiating side. | Your code is the one driving the conversation and must know *exactly* when the other side finished — e.g. an automated/test/judge agent that speaks with `call.say()` instead of a server LLM. |
+
+In short: `false` = the agent talks for itself, you stay hands-off. `true` = your
+code is puppeting the call and needs the turn signal to decide when to speak.
+
+```typescript
+// Driving the call by hand: react to the callee finishing a turn.
+const call = await agent.dial({ to: "+14155551234", detectTurnEnd: true });
+
+call.on("user.message", (e) => {/* what the callee said */});
+call.on("turn.end", () => {
+  call.say("Got it — let me confirm that for you.");
+});
+```
+
+Under the hood this just adds `detect_turn_end: true` to the dial request; nothing
+else about the call changes. For agent-to-agent (`agent.bridge`) the default is the
+opposite — `true` — because the initiator is *always* code-driven there (see below).
+
+## Agent-to-agent voice (`agent.bridge`)
+
+To have one Pinecall agent hold a **voice** conversation with **another** Pinecall
+agent — no phone, no WebRTC — use `agent.bridge(target)`. The server cross-wires
+the two agents' audio (each side's TTS becomes the other's incoming audio), so
+both run their real STT/turn-detection/TTS pipelines. The calling agent is driven
+manually: speak with `call.say()`, read the target via `user.message` / `turn.end`.
+
+```typescript
+// The judge has voice + STT but no server-side LLM — your code is its brain.
+const judge = pc.agent("judge", { voice: "elevenlabs/sarah", stt: "deepgram/flux" });
+await pc.ready;
+
+const call = await judge.bridge("pines", { detectTurnEnd: true });
+
+call.on("user.message", (e) => {/* what the judge HEARD the target say */});
+call.on("turn.end", () => {/* target finished → take your turn */ call.say("…"); });
+```
+
+`detectTurnEnd` (default `true` for `bridge`, `false` for `dial`) makes the server
+emit the other party's end-of-turn (`turn.end`, `source: "bot"`) to the initiator,
+so an automated caller knows when to speak. This is what powers voice-mode
+`pinecall test`.
+
+## Attaching metadata
+
+Use `metadata` to carry context from your scheduling system into the call. It's available as `call.metadata` throughout the call.
+
+```typescript
+const call = await agent.dial({
+  to: "+14155551234",
+  from: "+13186330963",
+  greeting: "Hi! This is Mara with a quick reminder about your appointment.",
+  metadata: {
+    appointmentId: "appt_001",
+    patientName: "Maria",
+    doctorName: "Dr. García",
+    appointmentTime: "2026-06-01T15:00:00Z",
+  },
+});
+
+agent.on("call.started", async (call) => {
+  if (call.direction === "outbound" && call.metadata?.patientName) {
+    await call.setPromptVars({
+      patient: call.metadata.patientName,
+      doctor: call.metadata.doctorName,
+      time: call.metadata.appointmentTime,
+    });
+  }
+});
+```
+
+## Per-call config overrides
+
+Override voice, STT, or language for a specific outbound call. The agent's defaults stay untouched.
+
+```typescript
+const call = await agent.dial({
+  to: "+34611234567",
+  from: "+13186330963",
+  greeting: "¡Hola! Te llamo para confirmar tu cita.",
+  config: {
+    voice: "elevenlabs/valentina",
+    language: "es",
+  },
+});
+```
+
+## Running a campaign
+
+To call a list of people, just loop:
+
+```typescript
+const recipients = await db.appointments.dueForReminder();
+
+for (const r of recipients) {
+  try {
+    const call = await agent.dial({
+      to: r.phone,
+      from: "+13186330963",
+      greeting: `Hi ${r.name}, this is a quick reminder about your appointment tomorrow at ${r.time}.`,
+      metadata: { appointmentId: r.id },
+    });
+
+    call.on("call.ended", async (_, reason) => {
+      await db.appointments.markReminderSent(r.id, reason);
+    });
+
+    // throttle to avoid hammering the network
+    await new Promise((res) => setTimeout(res, 1000));
+  } catch (err) {
+    console.error(`Failed to dial ${r.phone}:`, err);
+    await db.appointments.markReminderFailed(r.id, err.message);
+  }
+}
+```
+
+For production campaigns, add: concurrency limits, retry logic, time-of-day enforcement, do-not-call list filtering, and call result logging.
+
+## Handling no-answer / busy / rejected
+
+When the callee doesn't pick up or rejects, `dial()` rejects immediately with the Twilio reason — no 30-second timeout:
+
+```typescript
+try {
+  const call = await agent.dial({ to: "+14155551234" });
+  // Call connected — run your logic
+} catch (err) {
+  // err.message is one of: "no-answer", "busy", "failed", "canceled", "Dial timeout"
+  console.log(`Call failed: ${err.message}`);
+}
+```
+
+If the call connects and then ends, `call.ended` fires with the reason:
+
+```typescript
+agent.on("call.ended", (call, reason) => {
+  // reason: "hangup", "disconnected", "idle_timeout", "max_duration", etc.
+  console.log(`Call ended: ${reason} (${call.duration}s)`);
+});
+```
+
+## Running a campaign with `@pinecall/dispatch`
+
+For production outbound campaigns, use the `@pinecall/dispatch` library. It handles rate limiting, concurrency control, deduplication by phone, and call result tracking.
+
+```bash
+npm install @pinecall/dispatch
+```
+
+```typescript
+import { DispatchHub, CsvStrategy } from "@pinecall/dispatch";
+
+const csv = new CsvStrategy({
+  file: "./leads.csv",
+  mapRow: (row) => {
+    if (!row.phone || row.status) return null; // Skip processed rows
+    return {
+      id: `${row.phone}-${row.service}-${row.date}`,
+      phone: row.phone,
+      greeting: `Hi ${row.name}, this is a reminder about your appointment on ${row.date}.`,
+      metadata: { name: row.name, service: row.service },
+    };
+  },
+});
+
+const hub = new DispatchHub({
+  agent,
+  strategies: [csv],
+  from: "+13186330963",
+  maxCallsPerMinute: 5,
+  maxConcurrent: 2,
+  retryAttempts: 1,
+  pollIntervalMs: 5000,
+});
+
+hub.start();
+```
+
+### What `DispatchHub` does
+
+| Feature | Description |
+|---|---|
+| **Hot-reload** | Re-reads the CSV on every poll — add rows while it's running |
+| **Dedup by phone** | Won't call the same phone twice simultaneously |
+| **Dedup by ID** | Won't re-dispatch a record that's already been handled |
+| **Rate limiting** | Configurable calls per minute (sliding window) |
+| **Concurrency** | Max simultaneous active calls |
+| **Lifecycle callbacks** | `onDispatched`, `onCompleted`, `onFailed`, `onSkipped` |
+
+### Strategy callbacks
+
+Override callbacks on the strategy to react to call lifecycle events:
+
+```typescript
+csv.onCompleted = (record, callId, reason) => {
+  writeResultToCsv(record.phone, reason); // "hangup", "no-answer", etc.
+};
+
+csv.onFailed = (record, error) => {
+  writeResultToCsv(record.phone, "no_answer");
+};
+
+csv.onSkipped = (record, reason) => {
+  console.log(`Skipped ${record.phone}: ${reason}`); // "duplicate"
+};
+```
+
+> **See the full working example:** [`examples/outbound-dispatch/`](https://github.com/pinecall/sdk/tree/main/examples/outbound-dispatch) — CSV-driven appointment reminders with a `confirm_appointment` tool that writes results back to the CSV.
+
+## What's next
+
+- [Inbound voice](/guides/inbound-voice) — for receiving calls
+- [Tools and Functions](/guides/tools-and-functions) — let the outbound agent act on responses (book a slot, cancel, transfer)
+- [Session limits](/reference/session-limits) — cap outbound call duration