@pinecall/skills 0.1.0

package/skills/pinecall-guides/references/guides/tools-and-functions.md

@@ -0,0 +1,254 @@
+---
+title: "Tools and Functions"
+description: "Let your agent take actions: look up data, transfer calls, book appointments."
+---
+
+# Tools and Functions
+
+Tools are how your agent moves beyond conversation into action: looking up an order, checking inventory, booking a slot, transferring to a human. In Pinecall, tools are **local functions in your process**, not webhooks.
+
+## Defining tools
+
+Use the `tool()` helper with a Zod schema. Tools are auto-executed by the SDK when the LLM calls them — no manual event handler needed.
+
+```typescript
+import { Pinecall, tool } from "@pinecall/sdk";
+import { z } from "zod";
+
+const lookupOrder = tool({
+  name: "lookupOrder",
+  description: "Look up an order by its ID.",
+  schema: z.object({
+    orderId: z.string().describe("The order ID, like ORD-12345"),
+  }),
+  execute: async ({ orderId }) => {
+    return await db.orders.findOne(orderId);
+  },
+});
+
+const scheduleCallback = tool({
+  name: "scheduleCallback",
+  description: "Schedule a callback for a specific date and time.",
+  schema: z.object({
+    datetime: z.string().describe("ISO 8601 datetime"),
+    reason: z.string(),
+  }),
+  execute: async ({ datetime, reason }, call) => {
+    return await scheduler.book({
+      phone: call.from,
+      datetime,
+      reason,
+    });
+  },
+});
+
+const agent = pc.agent("support", {
+  prompt: "You are a helpful support agent. Use tools to look up information.",
+  llm: "openai/gpt-5-chat-latest",
+  voice: "elevenlabs/sarah",
+  stt: "deepgram/flux",
+  language: "en",
+  tools: [lookupOrder, scheduleCallback],
+});
+
+agent.on("call.started", (call) => call.say("Hi, how can I help?"));
+```
+
+That's it. When the LLM decides to call `lookupOrder`, the SDK:
+
+1. Parses the arguments through `z.object({ orderId: z.string() })`
+2. Calls your `execute` function with the validated args + the `Call` object
+3. Sends the result back to the LLM via `call.toolResult()`
+
+## Tool call lifecycle
+
+![Tool call lifecycle](/assets/diagrams/tool-call-lifecycle.png)
+
+## Ephemeral tools (don't persist the result)
+
+By default every tool result is saved to the conversation history — it stays in
+the LLM context for the rest of the call and is written to the persisted
+transcript. That's almost always what you want.
+
+Sometimes it isn't. A tool might return a sensitive lookup (a full customer
+record, a one-time code) or a large/noisy payload (a 5 KB JSON blob) that you
+need *for the current reply* but don't want lingering in context or saved to the
+database. Mark such a tool `ephemeral: true`:
+
+```typescript
+const lookupSSN = tool({
+  name: "lookupSSN",
+  description: "Look up the caller's SSN to verify identity.",
+  schema: z.object({ customerId: z.string() }),
+  ephemeral: true, // result is used for this reply, then dropped from history
+  execute: async ({ customerId }) => ({ ssn: await db.getSSN(customerId) }),
+});
+```
+
+How it works: the result is still sent to the model so it can generate the
+current reply (the API requires every tool call to be followed by its result).
+But once that reply is produced, the server **prunes** the ephemeral result —
+and the originating `tool_calls` entry if all of its calls were ephemeral — from
+the history. It never reaches the next turn's context and is never written to
+the saved transcript. The behavior is identical across voice, chat, and
+WhatsApp.
+
+`ephemeral` defaults to `false`, so existing tools are unchanged.
+
+## The `call` parameter
+
+Every `execute` function receives the `Call` object as its second argument. Use it to interact with the call mid-tool-execution:
+
+```typescript
+const transferToHuman = tool({
+  name: "transferToHuman",
+  description: "Escalate to a human agent.",
+  schema: z.object({
+    department: z.enum(["sales", "support", "billing"]),
+  }),
+  execute: async ({ department }, call) => {
+    const numbers = {
+      sales: "+15551110000",
+      support: "+15551110001",
+      billing: "+15551110002",
+    };
+    call.say("Of course, let me connect you to a specialist.");
+    call.forward(numbers[department]);
+    return { transferred: true };
+  },
+});
+```
+
+## Why local functions beat webhooks
+
+Other platforms make tools webhook URLs. You define a tool, expose a public endpoint, the platform POSTs to it. The downsides pile up fast:
+
+- **You expose a public endpoint** — attack surface, rate limiting, auth headaches
+- **You can't reach internal services** — your DB, your Redis, your hardware
+- **Latency** — every tool call is a network roundtrip across the public internet
+- **Debuggability** — tool call goes out, response comes back, what happened in between?
+
+Pinecall tools run in your process. That means:
+
+- `await db.query(...)` works directly
+- `await redis.get(...)` works directly
+- `await hardware.openDoor()` works directly (if your process can reach it)
+- Stack traces, breakpoints, and logs work normally
+- No public surface to attack
+- Sub-millisecond "call" overhead — it's a function call, not an HTTP request
+
+## Common patterns
+
+### Database lookups
+
+```typescript
+const findCustomer = tool({
+  name: "findCustomer",
+  description: "Find a customer by phone number or email.",
+  schema: z.object({
+    query: z.string().describe("Phone or email"),
+  }),
+  execute: async ({ query }) => {
+    const customer = await db.customers.find({
+      or: [{ phone: query }, { email: query }],
+    });
+    return customer ?? { error: "not_found" };
+  },
+});
+```
+
+### Transfer to human
+
+```typescript
+const transferToHuman = tool({
+  name: "transferToHuman",
+  description: "Escalate to a human agent when the customer is angry or has a complex issue.",
+  schema: z.object({
+    department: z.enum(["sales", "support", "billing"]),
+  }),
+  execute: async ({ department }, call) => {
+    const numbers = { sales: "+15551110000", support: "+15551110001", billing: "+15551110002" };
+    call.say("Of course, let me connect you to a specialist.");
+    call.forward(numbers[department]);
+    return { transferred: true };
+  },
+});
+```
+
+### Booking / scheduling
+
+```typescript
+const bookAppointment = tool({
+  name: "bookAppointment",
+  description: "Book an appointment in the doctor's calendar.",
+  schema: z.object({
+    datetime: z.string().describe("ISO 8601 datetime"),
+    durationMinutes: z.number(),
+    patientName: z.string(),
+  }),
+  execute: async ({ datetime, durationMinutes, patientName }) => {
+    const slot = await calendar.book({
+      start: new Date(datetime),
+      duration: durationMinutes,
+      patient: patientName,
+    });
+    return slot.success
+      ? { booked: true, confirmationId: slot.id }
+      : { booked: false, error: slot.conflictReason };
+  },
+});
+```
+
+### End the call
+
+```typescript
+const endCall = tool({
+  name: "endCall",
+  description: "End the call when the customer says goodbye.",
+  schema: z.object({}),
+  execute: async (_, call) => {
+    call.say("Have a great day!");
+    call.once("bot.finished", () => call.hangup());
+    return { ended: true };
+  },
+});
+```
+
+## Returning errors
+
+If a tool call fails, the SDK catches the error and returns `{ error: err.message }` to the LLM automatically. The LLM can then recover (apologize, retry, ask clarifying questions).
+
+You can also return errors explicitly:
+
+```typescript
+const lookupOrder = tool({
+  name: "lookupOrder",
+  description: "Look up an order by ID.",
+  schema: z.object({ orderId: z.string() }),
+  execute: async ({ orderId }) => {
+    const order = await db.orders.findOne(orderId);
+    if (!order) return { error: "Order not found" };
+    return order;
+  },
+});
+```
+
+## Listening to tool calls (optional)
+
+The `llm.toolCall` event still fires for every tool call — useful for logging, metrics, or UI:
+
+```typescript
+agent.on("llm.toolCall", (data, call) => {
+  console.log(`Tools called: ${data.toolCalls.map(t => t.name).join(", ")}`);
+});
+```
+
+## Tools work across all channels
+
+The same tools work for phone, WebRTC, chat, and WhatsApp. The `Call` object is your interface regardless of transport.
+
+## What's next
+
+- [Hot-reload](/concepts/hot-reload) — change the prompt or tools mid-call
+- [Events reference](/reference/events) — all events including `llm.toolCall`
+- [`Call` API reference](/api/call) — `forward`, `hangup`, etc.

package/skills/pinecall-guides/references/guides/webrtc-browser.md

@@ -0,0 +1,200 @@
+---
+title: "WebRTC in the Browser"
+description: "Embed a Pinecall voice agent in your web app using the React widget."
+---
+
+# WebRTC in the Browser
+
+Browser users can talk to your agent directly through WebRTC — no phone number required. This is how voice copilots, in-app assistants, and live demos work.
+
+## Architecture
+
+The browser connects **directly** to `voice.pinecall.io` over WebRTC. Your backend's only job is minting short-lived tokens.
+
+![WebRTC browser architecture](/assets/diagrams/webrtc-browser-arch.png)
+
+Your backend never proxies audio. The audio path is browser ↔ voice server, peer-to-peer over WebRTC.
+
+## 1. Create the agent
+
+WebRTC works automatically for any agent — no channel declaration needed.
+
+```typescript
+import { Pinecall } from "@pinecall/sdk";
+
+const pc = new Pinecall({ apiKey: process.env.PINECALL_API_KEY! });
+
+const mara = pc.agent("mara", {
+  prompt: "You are Mara. Be concise and warm.",
+  llm: "openai/gpt-5-chat-latest",
+  voice: "elevenlabs/sarah",
+  stt: "deepgram/flux",
+  language: "es",
+});
+
+mara.on("call.started", (call) => call.say("¡Hola!"));
+```
+
+## 2. Mint tokens from your backend
+
+Your token endpoint should be behind your existing auth (session cookie, JWT, OAuth — whatever you use). The endpoint calls `createToken()` and returns the result.
+
+```typescript
+// Express
+app.get("/api/token", authMiddleware, async (req, res) => {
+  const token = await mara.createToken("webrtc");
+  res.json(token);
+});
+```
+
+```typescript
+// Next.js App Router
+export async function GET() {
+  const session = await getSession();
+  if (!session) return new Response("Unauthorized", { status: 401 });
+  const token = await mara.createToken("webrtc");
+  return Response.json(token);
+}
+```
+
+The response shape:
+
+```json
+{
+  "token": "wrtc_abc123...",
+  "server": "wss://voice.pinecall.io",
+  "expiresIn": 60
+}
+```
+
+Tokens are single-use, scoped to the agent, and expire in 60 seconds. See [Security](/security) for the full security model.
+
+## 3. Drop in the widget
+
+```bash
+npm install @pinecall/web
+```
+
+```tsx
+import { VoiceWidget } from "@pinecall/web";
+
+export default function App() {
+  return (
+    <VoiceWidget
+      agent="mara"
+      tokenProvider={async () => {
+        const res = await fetch("/api/token", { credentials: "include" });
+        return res.json();
+      }}
+    />
+  );
+}
+```
+
+That's the entire frontend. Click the orb, talk, listen.
+
+## Listening for events in the browser
+
+Events arrive over the WebRTC DataChannel — you don't need SSE for in-browser UIs. The widget renders its own transcript, and exposes session status plus the full live state via the `useVoice()` hook:
+
+```tsx
+import { VoiceWidget, useVoice } from "@pinecall/web";
+
+function Transcript() {
+  const { messages, status } = useVoice();
+  return messages.map((m) => <p key={m.id}>{m.role}: {m.text}</p>);
+}
+
+export default function App() {
+  return (
+    <VoiceWidget
+      agent="mara"
+      tokenProvider={getToken}
+      onStatusChange={(status) => console.log("Status:", status)}
+    >
+      <Transcript />
+    </VoiceWidget>
+  );
+}
+```
+
+For lower-level control, use `@pinecall/web/core` directly — it gives you the raw event stream.
+
+## Custom UI without the widget
+
+If the widget doesn't fit your design, build your own UI with `@pinecall/web/core`:
+
+```typescript
+import { VoiceSession } from "@pinecall/web/core";
+
+const session = new VoiceSession({
+  agent: "mara",
+  // Fetch the token from your backend instead of hitting the voice server directly
+  tokenProvider: () => fetch("/api/token").then((r) => r.json()),
+});
+
+// Re-render whenever the session state changes (messages, status, phase, …)
+session.subscribe(() => {
+  const { status, messages } = session.getState();
+  console.log("Status:", status, "Last:", messages.at(-1)?.text);
+});
+
+// connect() fetches the token (via tokenProvider) and negotiates WebRTC
+await session.connect();
+
+// User clicks "End"
+session.disconnect();
+```
+
+## Skipping the backend for demos
+
+For pure demos or prototypes — no backend, no auth — you can opt in to public token access using `allowedOrigins`:
+
+```typescript
+const demo = pc.agent("demo-bot", {
+  // ...config
+  allowedOrigins: [
+    "https://demo.mysite.com",
+    "https://*.mysite.com",
+    "http://localhost:*",
+  ],
+});
+```
+
+Then the widget can fetch tokens directly from the voice server, no backend needed — omit `tokenProvider` and it hits `/webrtc/token` directly:
+
+```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, always use `tokenProvider` with your backend's auth. See [Security](/security).
+
+## Chat channel (text only)
+
+Same pattern, different token type. Chat gives you typed conversations without audio:
+
+```typescript
+// Backend
+app.get("/api/chat-token", authMiddleware, async (req, res) => {
+  const token = await agent.createToken("chat");
+  res.json(token);
+});
+```
+
+Connect from the browser via WebSocket:
+
+```typescript
+const ws = new WebSocket(`${server}/ws?token=${token}`);
+ws.onmessage = (e) => {
+  const event = JSON.parse(e.data);
+  if (event.event === "chat.token") appendBotToken(event.text);   // streaming token
+  if (event.event === "chat.done") finishBotMessage(event.text);  // final text
+};
+ws.send(JSON.stringify({ event: "message", text: "Hello" }));
+```
+
+## What's next
+
+- [Security](/security) — the full token security model
+- [Multi-tenant](/guides/multi-tenant) — scope tokens per user/tenant
+- [Dev mode](/guides/dev-mode) — slug-based isolation lets every dev have their own agent