@pinecall/skills 0.1.0

package/skills/pinecall-sdk-api/references/api/pinecall.md

@@ -0,0 +1,186 @@
+---
+title: "Pinecall"
+description: "The WebSocket client. Manages auth, reconnection, and agent multiplexing."
+---
+
+# Pinecall
+
+The WebSocket client. One per process. Manages the connection to `voice.pinecall.io`, handles auth and reconnection, and multiplexes events across multiple agents.
+
+**Auto-connects on construction.** When you create a `Pinecall` instance with an API key, it connects immediately — no need to call `connect()`.
+
+## Constructor
+
+```typescript
+new Pinecall(options)
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | `PINECALL_API_KEY` env var | Your Pinecall API key. Auto-read from env if not provided. |
+| `apiUrl` | `string` | `wss://voice.pinecall.io` | Server URL |
+| `autoReconnect` | `boolean` | `true` | Auto-reconnect on disconnect |
+| `promptsDir` | `string` | `"prompts"` | Prompts directory for `setPromptFile` |
+
+### Example
+
+```typescript
+// Reads PINECALL_API_KEY from env automatically
+const pc = new Pinecall();
+
+// Or pass explicitly
+const pc = new Pinecall({ apiKey: "pk_..." });
+```
+
+Agents can be created immediately — they queue and register when the connection is ready:
+
+```typescript
+const pc = new Pinecall();
+const agent = pc.agent("support", { /* ... */ }); // works before connected
+```
+
+## Methods
+
+### `ready`
+
+`Promise<void>` that resolves when the connection is established. Use it when you need to wait for the connection before proceeding (e.g. before dialing an outbound call).
+
+```typescript
+await pc.ready;
+const call = await agent.dial({ to: "+14155551234" });
+```
+
+### `connect()`
+
+Manually open the WebSocket connection. **Rarely needed** — the constructor auto-connects when an API key is present. Idempotent (safe to call multiple times).
+
+```typescript
+await pc.connect();
+```
+
+### `disconnect()`
+
+Gracefully close the connection.
+
+```typescript
+await pc.disconnect();
+```
+
+### `agent(id, config?)`
+
+Create or retrieve an agent. If an agent with this ID already exists, returns it (idempotent).
+
+```typescript
+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. Be concise.",
+  greeting: "Hi! How can I help you today?",
+  phoneNumber: "+13186330963",
+});
+```
+
+**`AgentConfig` fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `voice` | `string \| VoiceConfig` | TTS voice shortcut (e.g. `elevenlabs/sarah`) |
+| `language` | `string` | BCP-47 language code |
+| `stt` | `string \| STTConfig` | STT shortcut (e.g. `deepgram/flux`) |
+| `llm` | `string \| LLMConfig` | LLM shortcut (e.g. `openai/gpt-5-chat-latest`) or full config |
+| `prompt` | `string` | System prompt for the LLM |
+| `greeting` | `string \| { text, addToHistory? } \| (call) => string` | Greeting spoken on inbound calls. Added to LLM history by default. |
+| `tools` | `Tool[]` | Declarative tool definitions created with `tool()` |
+| `phoneNumber` | `string \| PhoneNumberConfig` | Phone number or SIP URI to register (Twilio) |
+| `phoneNumbers` | `Array<string \| PhoneNumberConfig>` | Multiple phone numbers with per-number config (e.g. one per language) |
+| `whatsapp` | `WhatsAppChannelConfig[]` | WhatsApp channels (Meta Cloud API credentials) |
+| `sessionLimits` | `object` | Session timeout config (see [Session Limits](/reference/session-limits)) |
+| `allowedOrigins` | `string[]` | Allowed origins for public browser token access (see [Security](/security)) |
+
+Dynamic greetings with a function:
+
+```typescript
+greeting: async (call) => {
+  const customer = await db.findByPhone(call.from);
+  return `Hi ${customer.name}! How can I help?`;
+},
+```
+
+Greeting without LLM history (e.g. a standalone announcement):
+
+```typescript
+greeting: { text: "Welcome! Please hold.", addToHistory: false },
+```
+
+See [`Agent`](/api/agent) for full API reference.
+
+### `getAgent(id)`
+
+Look up an agent by ID. Returns `Agent | undefined`.
+
+```typescript
+const mara = pc.getAgent("mara");
+```
+
+### `removeAgent(id)`
+
+Unregister an agent. Returns `boolean` indicating whether the agent existed.
+
+```typescript
+const removed = pc.removeAgent("mara");
+```
+
+### `createToken(channel, agentId)`
+
+Generate a short-lived, single-use token for browser WebRTC or chat connections. Used to mint tokens for browsers.
+
+```typescript
+const token = await pc.createToken("webrtc", "mara");
+// { token, server, expiresIn }
+```
+
+See [Security](/security) for the full token model.
+
+### `stream(res?, options?)`
+
+Open an SSE stream of agent events. Works with any framework — returns a Web API `Response` or writes to a Node.js `ServerResponse`.
+
+```typescript
+// Web API (Remix, Next.js, Hono, Bun)
+app.get("/events", () => pc.stream());
+
+// Express / Node.js
+app.get("/events", (req, res) => pc.stream(res));
+
+// Filtered to specific agents
+app.get("/events", () => pc.stream({ agents: ["mara", "support"] }));
+app.get("/events", (req, res) => pc.stream(res, { agents: ["mara"] }));
+```
+
+See [Multi-tenant guide](/guides/multi-tenant) for the filtering pattern.
+
+## Events
+
+Subscribe via `pc.on(event, handler)`.
+
+| Event | Signature | When |
+|---|---|---|
+| `connected` | `()` | WebSocket auth succeeded |
+| `disconnected` | `(reason)` | Connection closed |
+| `reconnecting` | `(attempt, delay)` | Auto-reconnect attempt N |
+| `error` | `(err)` | Protocol or transport error |
+
+```typescript
+pc.on("connected", () => console.log("Live"));
+pc.on("disconnected", (reason) => console.log("Down:", reason));
+pc.on("reconnecting", (n) => console.log(`Retry ${n}`));
+pc.on("error", (err) => console.error(err));
+```
+
+## What's next
+
+- [`Agent`](/api/agent) — channels, events, hot-reload, dial
+- [`Call`](/api/call) — per-session control
+- [Security](/security) — token model and best practices

package/skills/pinecall-sdk-api/references/api/reply-stream.md

@@ -0,0 +1,148 @@
+---
+title: "ReplyStream"
+description: "Token-by-token streaming for client-side LLM responses."
+---
+
+# ReplyStream
+
+A streaming interface for sending LLM tokens to the server. TTS starts as soon as a sentence boundary is detected — you don't wait for the full response.
+
+Use it when running a client-side LLM (bring your own provider). For server-side LLMs, you don't need it — the server streams TTS automatically.
+
+## Creating a stream
+
+```typescript
+const stream = call.replyStream(turn);
+```
+
+Pass the `turn` object from `turn.end` so the stream is tied to that specific user turn. If the user keeps talking, the stream auto-aborts.
+
+## Writing tokens
+
+```typescript
+for await (const chunk of llm.stream(prompt)) {
+  if (stream.aborted) break;
+  const token = chunk.choices[0]?.delta?.content;
+  if (token) stream.write(token);
+}
+stream.end();
+```
+
+| Method | Description |
+|---|---|
+| `stream.write(token)` | Append a token to the stream |
+| `stream.end()` | Mark the stream complete — server flushes remaining TTS |
+| `stream.aborted` | `true` if the user interrupted or kept talking |
+
+Always call `stream.end()` when done, even on error — otherwise the server keeps waiting.
+
+## Handling interruptions
+
+The `aborted` flag flips to `true` when:
+
+- The user starts speaking again (`turn.continued`)
+- The user explicitly cancels (`bot.interrupted`)
+- The call ends (`call.ended`)
+
+Always check `aborted` in your token loop:
+
+```typescript
+for await (const chunk of openai.chat.completions.create({ /* ... */ })) {
+  if (stream.aborted) break;
+  const token = chunk.choices[0]?.delta?.content;
+  if (token) stream.write(token);
+}
+stream.end();
+```
+
+If you don't, you'll keep computing tokens (and paying for them) after the user has moved on.
+
+## Full client-side LLM pattern
+
+```typescript
+import OpenAI from "openai";
+const openai = new OpenAI();
+
+agent.on("turn.end", async (turn, call) => {
+  const stream = call.replyStream(turn);
+
+  try {
+    const history = await call.getHistory();
+    const completion = await openai.chat.completions.create({
+      llm: "openai/gpt-5-chat-latest",
+      messages: [
+        { role: "system", content: "You are helpful. Be concise." },
+        ...history,
+        { role: "user", content: turn.text },
+      ],
+      stream: true,
+    });
+
+    for await (const chunk of completion) {
+      if (stream.aborted) break;
+      const token = chunk.choices[0]?.delta?.content;
+      if (token) stream.write(token);
+    }
+  } catch (err) {
+    console.error("LLM error:", err);
+  } finally {
+    stream.end();
+  }
+});
+```
+
+## With Anthropic
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+const anthropic = new Anthropic();
+
+agent.on("turn.end", async (turn, call) => {
+  const stream = call.replyStream(turn);
+
+  try {
+    const response = await anthropic.messages.stream({
+      model: "claude-opus-4-7",
+      max_tokens: 1024,
+      system: "You are helpful. Be concise.",
+      messages: [{ role: "user", content: turn.text }],
+    });
+
+    for await (const event of response) {
+      if (stream.aborted) break;
+      if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
+        stream.write(event.delta.text);
+      }
+    }
+  } finally {
+    stream.end();
+  }
+});
+```
+
+## With LangChain
+
+```typescript
+import { ChatOpenAI } from "@langchain/openai";
+const model = new ChatOpenAI({ model: "gpt-5-chat-latest", streaming: true });
+
+agent.on("turn.end", async (turn, call) => {
+  const stream = call.replyStream(turn);
+
+  const llmStream = await model.stream([
+    { role: "system", content: "You are helpful." },
+    { role: "user", content: turn.text },
+  ]);
+
+  for await (const chunk of llmStream) {
+    if (stream.aborted) break;
+    if (chunk.content) stream.write(chunk.content.toString());
+  }
+  stream.end();
+});
+```
+
+## What's next
+
+- [Server-side vs client-side LLM](/concepts/server-vs-client-llm) — when to use each
+- [Events reference](/reference/events) — `turn.end`, `turn.continued`, `bot.interrupted`

package/skills/pinecall-security/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: pinecall-security
+description: >-
+  Security Use when the user is building, configuring, or debugging with @pinecall/sdk. Keywords: .
+license: MIT
+---
+
+# Security
+
+Security
+
+This skill bundles the official Pinecall documentation for **Security**. 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 |
+|------|----------------|------|
+| **Security** | Token security model and best practices for production deployments. | [`references/security.md`](references/security.md) · [docs](https://docs.pinecall.io/security) |
+
+
+## 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-security/references/security.md

@@ -0,0 +1,138 @@
+---
+title: "Security"
+description: "Token security model and best practices for production deployments."
+---
+
+# Security
+
+This page covers how Pinecall handles browser security: the token model, why tokens are safe to expose, and when to use the convenience `allowedOrigins` mode vs full backend auth.
+
+## Token security model
+
+Browser connections (WebRTC and chat) use **short-lived tokens** generated by the voice server. The recommended model:
+
+> **Your backend generates tokens using your API key, and distributes them to browsers through your own auth layer.**
+
+This is the same model used by LiveKit, Twilio, Daily.co, and every major real-time platform.
+
+![Token security flow](/assets/diagrams/token-security-flow.png)
+
+### Backend (Express, Next.js, Hono, etc.)
+
+```typescript
+import { Pinecall } from "@pinecall/sdk";
+
+const pc = new Pinecall();
+
+const agent = pc.agent("florencia", { /* config */ });
+
+// Token endpoint — protected by YOUR auth
+app.get("/api/token", authMiddleware, async (req, res) => {
+  const channel = req.query.channel as "webrtc" | "chat";
+  const token = await agent.createToken(channel);
+  res.json(token);
+});
+```
+
+If the agent is in a separate process (you only have `pc` in the web server):
+
+```typescript
+app.get("/api/token", authMiddleware, async (req, res) => {
+  const token = await pc.createToken("webrtc", "florencia");
+  res.json(token);
+});
+```
+
+### Frontend (VoiceWidget)
+
+```tsx
+<VoiceWidget
+  agent="florencia"
+  tokenProvider={async () => {
+    const res = await fetch("/api/token?channel=webrtc", {
+      credentials: "include", // send your session cookie
+    });
+    return res.json();
+  }}
+/>
+```
+
+## Why tokens are safe
+
+Tokens have three security properties that make them safe to pass to browsers:
+
+| Property | Value | Effect |
+|---|---|---|
+| **Single-use** | Consumed on first connection | Can't be reused by an attacker |
+| **Short-lived** | 60 second TTL | Expires before anyone can steal it |
+| **Scoped** | Locked to agent + org | Can't be used for a different agent |
+
+The token is **not** the security boundary — **your backend is**. The token is a short-lived capability that proves "someone authorized gave me permission to connect." The security question is: who can call your `/api/token` endpoint?
+
+- **Requires login** → only authenticated users get tokens
+- **Rate limited** → can't bulk-generate tokens
+- **Permission-checked** → only authorized users connect
+
+Think of it like a movie ticket: the theater (your backend) verifies your identity and gives you a ticket. The ticket works once, for one screen, for a limited time. Even if someone steals the ticket, they get one session — and they'd need to break TLS to intercept it.
+
+## `allowedOrigins` (convenience mode)
+
+For simple deployments without a backend (demos, prototypes, CodePen), you can opt-in to public token access by configuring `allowedOrigins`:
+
+```typescript
+const agent = pc.agent("demo-bot", {
+  allowedOrigins: [
+    "https://demo.mysite.com",      // exact match
+    "https://*.mysite.com",          // subdomain wildcard
+    "http://localhost:*",            // any port (dev)
+  ],
+});
+```
+
+When `allowedOrigins` is set, the token endpoint accepts browser requests from matching origins **without** an API key. The `Origin` header is browser-enforced (real browsers can't spoof it).
+
+```tsx
+<VoiceWidget agent="demo-bot" />
+```
+
+> **Warning:** `allowedOrigins` protects against casual embedding but **not** against a determined attacker — Origin headers can be spoofed from scripts/curl. For production with real users, always use `tokenProvider` with your backend auth.
+
+## Mode comparison
+
+| Mode | Security level | Use case |
+|---|---|---|
+| `tokenProvider` (backend) | ✅ Full auth control | Production apps |
+| `allowedOrigins` (public) | ⚠️ Origin-based only | Demos, prototypes |
+| Neither (default) | ❌ Rejected | — |
+
+## API key handling
+
+Your `PINECALL_API_KEY` is the master credential. Treat it like a database password:
+
+- **Never** ship it in browser code, mobile apps, or public repos
+- **Always** load it from environment variables on the server
+- **Rotate** it if you suspect exposure (via the dashboard)
+- **Scope** it per-environment (separate keys for dev, staging, prod)
+
+The SDK never exposes the API key over the wire in browser-bound responses — `createToken` returns only the short-lived token.
+
+## Webhook signature verification (WhatsApp)
+
+For WhatsApp, set `appSecret` so the server verifies the HMAC signature on every incoming webhook:
+
+```typescript
+agent.addWhatsapp({
+  phoneNumberId: "...",
+  accessToken: "...",
+  verifyToken: "...",
+  appSecret: process.env.WA_APP_SECRET, // HMAC verification
+});
+```
+
+Without `appSecret`, the webhook accepts any request — anyone who finds your endpoint URL can inject fake messages. Always set it in production.
+
+## What's next
+
+- [WebRTC in the browser](/guides/webrtc-browser) — full setup
+- [Multi-tenant](/guides/multi-tenant) — per-tenant token isolation
+- [WhatsApp](/guides/whatsapp) — webhook verification

package/skills/pinecall-web-chat/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: pinecall-web-chat
+description: >-
+  @pinecall/web/chat — browser text chat (ChatSession, ChatView). Use when the user is building, configuring, or debugging with @pinecall/sdk. Keywords: chat, chatsession, text chat, @pinecall/web/chat.
+license: MIT
+---
+
+# @pinecall/web/chat (Chat)
+
+@pinecall/web/chat — browser text chat (ChatSession, ChatView).
+
+This skill bundles the official Pinecall documentation for **@pinecall/web/chat (Chat)**. 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 |
+|------|----------------|------|
+| **@pinecall/web/chat** | Text chat client for Pinecall voice agents. Framework-agnostic core + React hook. | [`references/web/chat/overview.md`](references/web/chat/overview.md) · [docs](https://docs.pinecall.io/web/chat/overview) |
+| **ChatSession API** | Full reference for ChatSession (vanilla) and usePinecallChat (React). | [`references/web/chat/chat-session.md`](references/web/chat/chat-session.md) · [docs](https://docs.pinecall.io/web/chat/chat-session) |
+
+
+## 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`.*