@pinecall/skills 0.1.0

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

@@ -0,0 +1,328 @@
+---
+title: "Agent"
+description: "Owns channels, routes call events, stores defaults, dials outbound calls."
+---
+
+# Agent
+
+Created via `pc.agent(id, config?)`. Owns channels, routes call events, stores defaults, dials outbound calls.
+
+## Creation
+
+```typescript
+import { tool } from "@pinecall/sdk";
+import { z } from "zod";
+
+const lookupOrder = tool({
+  name: "lookupOrder",
+  description: "Look up an order by ID",
+  schema: z.object({ id: z.string() }),
+  execute: async ({ id }) => ({ status: "shipped", eta: "today" }),
+});
+
+const agent = pc.agent("my-agent", {
+  voice: "elevenlabs/sarah",
+  language: "es",
+  stt: "deepgram/flux",
+  llm: "openai/gpt-5-chat-latest",
+  prompt: "System prompt with {{template_vars}}.",
+  greeting: "Hello! How can I help you today?",
+  phoneNumber: "+13186330963",
+  tools: [lookupOrder],
+});
+```
+
+| Config field | Type | Description |
+|---|---|---|
+| `voice` | `string \| VoiceConfig` | TTS provider — shortcut or full config |
+| `language` | `string` | BCP-47 language code |
+| `stt` | `string \| STTConfig` | STT provider — shortcut or full config |
+| `llm` | `LLMConfig` | LLM provider, model, prompt, enabled flag |
+| `tools` | `Tool[]` | Declarative tools created with `tool()` + Zod schemas (auto-executed) |
+| `phoneNumber` | `string \| PhoneNumberConfig` | Phone number to register (E.164 or SIP URI) |
+| `phoneNumbers` | `Array<string \| PhoneNumberConfig>` | Multiple numbers with per-number config |
+| `whatsapp` | `WhatsAppChannelConfig[]` | WhatsApp channels to register |
+| `history` | `HistoryStore` | Conversation persistence (see [History](/guides/conversation-history)) |
+| `sessionLimits` | `SessionLimits` | Duration / idle timeout config |
+| `interruption` | `InterruptionConfig` | Energy thresholds for barge-in |
+| `analysis` | `AnalysisConfig` | Audio metrics streaming |
+| `allowedOrigins` | `string[]` | Public token access (see [Security](/security)) |
+
+See [Reference → Providers](/reference/stt-providers) for full provider configs.
+
+## Phone numbers
+
+### `addPhoneNumber(number, config?)`
+
+Register a phone number or SIP URI. Idempotent — calling again with the same number updates its config.
+
+```typescript
+agent.addPhoneNumber("+13186330963");
+agent.addPhoneNumber("sip:bot@trunk.twilio.com");
+
+// Per-number config overrides
+agent.addPhoneNumber("+34911234567", {
+  voice: "elevenlabs/valentina",
+  language: "es",
+});
+```
+
+### `removePhone(number)`
+
+Unregister a phone number.
+
+```typescript
+agent.removePhone("+34911234567");
+```
+
+## WhatsApp
+
+### `addWhatsapp(config)`
+
+Register a WhatsApp channel. Idempotent.
+
+```typescript
+agent.addWhatsapp({
+  phoneNumberId: "123456789012345",
+  accessToken: "EAABx...",
+  verifyToken: "my-secret",
+  appSecret: "abc123...",
+});
+```
+
+See [WhatsApp guide](/guides/whatsapp) for full config.
+
+### `removeWhatsapp(phoneNumberId)`
+
+Unregister a WhatsApp channel.
+
+```typescript
+agent.removeWhatsapp("123456789012345");
+```
+
+## Config & hot-reload
+
+### `update(opts)`
+
+Hot-reload the agent's defaults. Affects all **future** calls — existing calls keep their current config.
+
+```typescript
+agent.update({ voice: "elevenlabs/claire", language: "fr" });
+agent.update({ stt: "gladia" });
+agent.update({ llm: "openai/gpt-5-chat-latest", prompt: "..." });
+```
+
+### `configureSession(callId, opts)`
+
+Update config for a live call (equivalent to `call.update()`).
+
+```typescript
+agent.configureSession("CA7ec...", { language: "es" });
+```
+
+### `getConfig()`
+
+Returns the current `AgentConfig`.
+
+```typescript
+const cfg = agent.getConfig();
+```
+
+## Outbound calls
+
+### `dial(options)`
+
+Make an outbound call. Returns `Promise<Call>`.
+
+```typescript
+const call = await agent.dial({
+  to: "+14155551234",
+  from: "+13186330963",
+  greeting: "Hi! This is a follow-up call.",
+  metadata: { appointmentId: "appt_001" },
+  config: { voice: "cartesia/yumiko", language: "ar" },
+});
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `to` | `string` | ✅ | Destination number (E.164) |
+| `from` | `string` | — | Caller ID — auto-resolved if agent has one phone channel. Required when multiple. |
+| `greeting` | `string` | — | Text the server speaks when callee picks up |
+| `metadata` | `object` | — | Custom data attached to the call |
+| `config` | `object` | — | Per-call config override (voice, STT, language) |
+
+See [Outbound Calls guide](/guides/outbound-calls) for the full pattern.
+
+## Tokens
+
+### `createToken(channel)`
+
+Mint a short-lived token for browser WebRTC or chat. Scoped to this agent.
+
+```typescript
+const token = await agent.createToken("webrtc");
+// { token, server, expiresIn }
+```
+
+## Dev mode
+
+### `routeCallers(numbers)`
+
+Route phone and WhatsApp messages from these numbers to this agent (instead of any other agent registered on the same channel). Used for dev mode isolation.
+
+```typescript
+agent.routeCallers(["+34600123456", "+34612345678"]);
+```
+
+See [Dev mode guide](/guides/dev-mode).
+
+## Human-in-the-loop
+
+Pause the AI so a human can take over the conversation. Works on WhatsApp and (soon) voice/chat channels.
+
+### `pause(target?)`
+
+Pause the agent. While paused, incoming messages are forwarded to the SDK but the LLM doesn't respond.
+
+```typescript
+// Pause a specific session
+agent.pause("wa-abc123");
+
+// Pause all sessions with a contact
+agent.pause({ contact: "+34612345678" });
+
+// Pause the entire agent
+agent.pause();
+```
+
+### `resume(target?)`
+
+Resume the AI after a pause. Global resume clears all session and contact pauses.
+
+```typescript
+agent.resume("wa-abc123");
+agent.resume({ contact: "+34612345678" });
+agent.resume();
+```
+
+### `sendMessage(opts)`
+
+Send a message as the human operator. The message is delivered through the channel (e.g. WhatsApp) and added to LLM history so the AI has context when resumed.
+
+```typescript
+agent.sendMessage({
+  sessionId: "wa-abc123",
+  text: "Hi, I'm taking over this conversation.",
+});
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `sessionId` | `string` | ✅ | Target session ID (e.g. `wa-abc123`) |
+| `text` | `string` | ✅ | Message body |
+
+See [Human Takeover guide](/guides/human-takeover) for the full pattern.
+
+## Calls
+
+### `call(callId)`
+
+Look up a live `Call` by ID. Returns `Call | undefined`.
+
+```typescript
+const call = agent.call("CA7ec...");
+```
+
+## Observability
+
+### `stream(res?)`
+
+Open an SSE stream of this agent's events. Same shape as `pc.stream()` but scoped to one agent.
+
+```typescript
+app.get("/events", () => agent.stream());
+app.get("/events", (req, res) => agent.stream(res));
+```
+
+## Events
+
+Subscribe via `agent.on(event, handler)`. All call-scoped events include `call` as the last argument.
+
+### Lifecycle
+
+| Event | Signature | When |
+|---|---|---|
+| `call.started` | `(call)` | New call connected |
+| `call.ended` | `(call, reason)` | Call disconnected |
+
+### User speech
+
+| Event | Signature | When |
+|---|---|---|
+| `speech.started` | `(event, call)` | User began speaking (VAD) |
+| `speech.ended` | `(event, call)` | User stopped speaking (VAD) |
+| `user.speaking` | `(event, call)` | Interim STT transcript (updates live) |
+| `user.message` | `(event, call)` | Final confirmed user text |
+
+### Turns
+
+| Event | Signature | When |
+|---|---|---|
+| `eager.turn` | `(turn, call)` | Early turn signal (low-latency response) |
+| `turn.end` | `(turn, call)` | Final turn signal |
+| `turn.continued` | `(event, call)` | User kept talking (auto-aborts active streams) |
+
+### Bot speech
+
+| Event | Signature | When |
+|---|---|---|
+| `bot.speaking` | `(event, call)` | Bot started speaking a message |
+| `bot.word` | `(event, call)` | Individual word as TTS plays it |
+| `bot.finished` | `(event, call)` | Bot finished speaking a message |
+| `bot.interrupted` | `(event, call)` | Bot was cut off by user |
+
+### Protocol
+
+| Event | Signature | When |
+|---|---|---|
+| `message.confirmed` | `(event, call)` | Server acknowledged bot message |
+| `llm.toolCall` | `(data, call)` | Server-side LLM requests a tool call |
+| `session.idleWarning` | `(event, call)` | Warning — user hasn't spoken, call will timeout soon |
+| `session.timeout` | `(event, call)` | Session timeout fired (max duration / idle) |
+
+### WhatsApp
+
+| Event | Signature | When |
+|---|---|---|
+| `whatsapp.sessionStarted` | `(event)` | New WhatsApp conversation started |
+| `whatsapp.message` | `(event)` | Incoming WhatsApp message received |
+| `whatsapp.response` | `(event)` | Agent sent a WhatsApp response |
+| `whatsapp.status` | `(event)` | Message delivery status |
+
+See [Events reference](/reference/events) for full event data shapes.
+
+### Human-in-the-loop
+
+| Event | Signature | When |
+|---|---|---|
+| `session.paused` | `(event)` | AI paused for a session, contact, or globally |
+| `session.resumed` | `(event)` | AI resumed |
+
+See [Human Takeover guide](/guides/human-takeover).
+
+## Escape hatch
+
+### `send(data)`
+
+Send a raw protocol message. Use only when no higher-level method covers your case.
+
+```typescript
+agent.send({ type: "custom.command", payload: { /* ... */ } });
+```
+
+## What's next
+
+- [`Call`](/api/call) — per-session methods
+- [Events reference](/reference/events) — full event data shapes
+- [Hot-reload](/concepts/hot-reload) — patterns for `configure()` and `setPrompt()`

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

@@ -0,0 +1,324 @@
+---
+title: "Call"
+description: "Per-session handle. Speak, control, update, read state."
+---
+
+# Call
+
+A live call session. Created automatically and passed to your `call.started` handler. Use it to speak, control the call, update it mid-flight, and read its state.
+
+```typescript
+agent.on("call.started", (call) => {
+  // call is a Call instance
+});
+```
+
+## Properties
+
+```typescript
+call.id              // "CA7ec979f5..." — unique call ID
+call.from            // "+13186330963" or "sip:..."
+call.to              // destination number / URI
+call.direction       // "inbound" | "outbound"
+call.transport       // "phone" | "webrtc" | "chat" | "whatsapp" | "unknown"
+call.metadata        // custom metadata from the channel or dial()
+call.transcript      // [{ role: "user", content: "..." }, ...] — user + assistant only
+call.messages        // full LLM history (populated on call.ended)
+call.currentBotText  // live preview of what the bot is saying (accumulated bot.word events)
+call.duration        // seconds (populated on call.ended)
+call.startedAt       // epoch seconds
+call.endedAt         // epoch seconds
+call.reason          // "hangup" | "timeout" | ...
+```
+
+### `currentBotText`
+
+A live preview of what the bot is currently saying. Built automatically from `bot.word` events — grows word-by-word as TTS plays, resets on each new `bot.speaking`, clears after `bot.finished` or `bot.interrupted`.
+
+```typescript
+agent.on("bot.word", (event, call) => {
+  updateSubtitle(call.currentBotText); // "¡Hola!" → "¡Hola! Estoy" → "¡Hola! Estoy bien,"
+});
+```
+
+## Speech
+
+### `say(text, opts?)`
+
+Speak text immediately. Standalone — no `in_reply_to` tracking. Use for greetings and proactive announcements.
+
+```typescript
+call.say("Hello! How can I help?");
+```
+
+Pass `{ addToHistory: true }` to inject the text into the server-side LLM conversation history as an assistant message. This way the model knows what was said and won't repeat it.
+
+```typescript
+agent.on("call.started", async (call) => {
+  const customer = await db.findByPhone(call.from);
+  call.say(`Hi ${customer.name}! How can I help?`, { addToHistory: true });
+});
+```
+
+> **Tip:** The `greeting` field in `pc.agent()` is syntactic sugar for `call.say(text, { addToHistory })` inside a `call.started` handler. Use `greeting` for convenience, or `call.say()` directly for full control.
+
+### `reply(text)`
+
+Reply to the latest user message. Auto-tracks `in_reply_to`. Use when responding to what the user just said.
+
+```typescript
+call.reply("Sure, let me look that up for you.");
+```
+
+### `replyStream(turn?)`
+
+Open a token-by-token stream for LLM responses. TTS starts as soon as a sentence boundary is detected.
+
+```typescript
+const stream = call.replyStream(turn);
+
+for await (const token of llm.stream(prompt)) {
+  if (stream.aborted) break; // user interrupted
+  stream.write(token);
+}
+stream.end();
+```
+
+See [`ReplyStream`](/api/reply-stream) for details.
+
+### `toolResult(msgId, results)`
+
+Send tool results back to the server-side LLM. When using `tool()`, the SDK calls this automatically — you don't need to call it yourself.
+
+```typescript
+// Auto-called by tool() — you rarely need this directly.
+// Only use for advanced cases where you bypass tool() auto-execution.
+call.toolResult(msgId, [
+  { toolCallId: "tc_abc", result: { status: "shipped" } },
+]);
+```
+
+### `cancel(msgId?)`
+
+Cancel a specific bot message (by ID) or the current one (if no ID).
+
+```typescript
+call.cancel();             // cancel current
+call.cancel("msg_abc123"); // cancel specific
+```
+
+### `clear()`
+
+Flush all queued TTS audio. Stops the bot mid-speech.
+
+```typescript
+call.clear();
+```
+
+## Call control
+
+### `hangup()`
+
+End the call.
+
+```typescript
+call.hangup();
+```
+
+### `forward(to, opts?)`
+
+Transfer the call to another number.
+
+```typescript
+call.forward("+15558675309");
+```
+
+### `sendDTMF(digits)`
+
+Send DTMF tones. Use `0-9`, `*`, `#`.
+
+```typescript
+call.sendDTMF("1234#");
+```
+
+### `hold()` / `unhold()`
+
+Put the call on hold (plays hold music, mutes mic) and resume.
+
+```typescript
+call.hold();
+// ...later
+call.unhold();
+```
+
+### `mute()` / `unmute()`
+
+Mute and unmute the mic. Transcripts are buffered while muted; on `unmute()`, `call.unmuted` fires with the buffered transcript.
+
+```typescript
+call.mute();
+call.unmute();
+```
+
+### `streamSSE(res, opts?)`
+
+Stream call events as Server-Sent Events to an HTTP response. Used for "Call Me" flows where the browser needs a live transcript of an outbound call.
+
+```typescript
+app.post("/api/call-me", async (req, res) => {
+  const call = await agent.dial({
+    to: req.body.phone,
+    greeting: "Hi! You asked me to call you.",
+  });
+  call.streamSSE(res);
+});
+```
+
+Sets SSE headers automatically. Streams: `call.started`, `bot.word`, `bot.confirmed`, `user.speaking`, `user.message`, `tool.call`, `call.ended`. Sends `:ping` keepalives every 25s. Cleans up listeners on client disconnect.
+
+| Option | Type | Description |
+|---|---|---|
+| `greeting` | `string` | Override the greeting text sent as first `bot.confirmed`. Defaults to `call.greeting` (set by `dial()`). |
+
+See [Voice Widget → Call Me](/web/widget/props#callmeendpoint--outbound-calls) for the full pattern.
+
+## Mid-call configuration
+
+### `update(opts)`
+
+Change voice, STT, or language. Takes effect on the next LLM turn or TTS output.
+
+```typescript
+call.update({ voice: "elevenlabs/valentina", language: "es" });
+```
+
+### `setPrompt(text)`
+
+Replace the system prompt for this call only. The agent's default prompt is unchanged.
+
+```typescript
+call.setPrompt("You are now in escalation mode. Be more formal.");
+```
+
+### `setPromptVars(vars)`
+
+Set `{{variable}}` values in the prompt template.
+
+```typescript
+await call.setPromptVars({
+  customer_name: "Maria",
+  tier: "premium",
+});
+```
+
+### `addContext(text)`
+
+Append context after the system prompt. Useful for injecting CRM data, tool results, or live state.
+
+```typescript
+await call.addContext(`Recent orders:\n- ORD-001: shipped\n- ORD-002: pending`);
+```
+
+You can call `addContext` multiple times during a call — each call appends.
+
+### `setPromptFile(path)`
+
+Load a prompt from a file and set it. Equivalent to `readFile + setPrompt`.
+
+```typescript
+await call.setPromptFile("./prompts/escalation.md");
+```
+
+## Conversation history
+
+### `getHistory()`
+
+Fetch the current conversation messages in OpenAI format.
+
+```typescript
+const messages = await call.getHistory();
+// [{ role: "system", content: "..." }, { role: "user", content: "..." }, ...]
+```
+
+### `addHistory(msgs)`
+
+Inject messages into the history. Useful for CRM context or seeding past conversation.
+
+```typescript
+await call.addHistory([
+  { role: "user", content: "I called yesterday about my order" },
+  { role: "assistant", content: "Yes, I see it shipped this morning." },
+]);
+```
+
+### `setHistory(msgs)`
+
+Replace the entire conversation history.
+
+```typescript
+await call.setHistory([
+  { role: "system", content: "You are now in escalation mode." },
+]);
+```
+
+### `clearHistory()`
+
+Clear all messages. The system prompt is preserved.
+
+```typescript
+call.clearHistory();
+```
+
+## Common patterns
+
+### Greet on `call.started`
+
+```typescript
+agent.on("call.started", (call) => {
+  if (call.direction === "inbound") {
+    call.say("Hello! How can I help?");
+  }
+});
+```
+
+### Persist transcripts on `call.ended`
+
+```typescript
+agent.on("call.ended", async (call, reason) => {
+  await db.calls.create({
+    id: call.id,
+    from: call.from,
+    to: call.to,
+    direction: call.direction,
+    transport: call.transport,
+    duration: call.duration,
+    reason,
+    transcript: call.transcript,
+    messages: call.messages,
+  });
+});
+```
+
+### Transfer when escalation requested
+
+```typescript
+import { tool } from "@pinecall/sdk";
+import { z } from "zod";
+
+const transferToHuman = tool({
+  name: "transferToHuman",
+  description: "Escalate to a human agent.",
+  schema: z.object({}),
+  execute: async (_, call) => {
+    call.say("Connecting you now.");
+    call.forward("+15558675309");
+    return { transferred: true };
+  },
+});
+```
+
+## What's next
+
+- [`ReplyStream`](/api/reply-stream) — for client-side LLMs
+- [Events reference](/reference/events) — all events the call emits
+- [Hot-reload](/concepts/hot-reload) — `update`, `setPrompt`, `addContext` patterns