@pinecall/skills 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinecall/skills",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Agent Skills for the Pinecall SDK — installable into Claude Code, Antigravity, Cursor, Copilot and any agent that supports the open Skills format.",
   "type": "module",
   "license": "MIT",

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

@@ -69,6 +69,40 @@ The response shape:
 
 Tokens are single-use, scoped to the agent, and expire in 60 seconds. See [Security](/security) for the full security model.
 
+### Sealed session metadata (trusted context)
+
+Your token endpoint already knows who the user is — it's behind your auth. Bake that
+identity into the token by passing a metadata object as the last argument to
+`createToken`. It's **sealed into the signed token on your server**, so the browser
+cannot forge or change it:
+
+```typescript
+app.get("/api/token", authMiddleware, async (req, res) => {
+  const token = await mara.createToken("webrtc", {
+    userId: req.user.id,
+    plan: req.user.plan,
+    tenantId: req.user.orgId,
+  });
+  res.json(token);
+});
+```
+
+It surfaces — trusted — as `call.metadata` in your agent:
+
+```typescript
+agent.on("call.started", (call) => {
+  console.log(call.metadata.userId, call.metadata.plan); // straight from the sealed token
+});
+```
+
+The same applies to **chat** tokens — mint with `createToken("chat", { ... })` and read
+`call.metadata` in the chat session. (With the `Pinecall` client instead of an `Agent`
+instance, it's `pc.createToken("webrtc", "mara", { ... })`.)
+
+> **Trusted vs client-supplied.** The widget also accepts a `metadata` prop set in the
+> browser — handy, but a user can forge it. For anything you'll act on (identity, plan,
+> entitlements, tenant), seal it in the token here instead of trusting the client prop.
+
 ## 3. Drop in the widget
 
 ```bash

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

@@ -21,7 +21,7 @@ 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.metadata        // sealed token metadata (createToken), dial() metadata, or channel context
 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)
@@ -31,6 +31,22 @@ call.endedAt         // epoch seconds
 call.reason          // "hangup" | "timeout" | ...
 ```
 
+### `metadata`
+
+Arbitrary context attached to the session, available in `call.started` and throughout the call. It comes from one of:
+
+- **Sealed token metadata** (browser WebRTC / chat) — passed to [`createToken(channel, agentId, metadata)`](/api/pinecall) on your server and sealed into the signed token. **Trusted**: the browser can't forge it, so it's safe for identity / plan / tenant.
+- **`dial()` metadata** (outbound calls) — passed when you place the call.
+- **Channel context** — provider-supplied fields for the transport.
+
+```typescript
+agent.on("call.started", (call) => {
+  if (call.metadata?.plan === "pro") enablePremiumTools(call);
+});
+```
+
+The client-supplied `metadata` prop on the browser widget / `VoiceSession` also lands here, but is set in the browser — don't trust it for authorization; seal that in the token instead.
+
 ### `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`.

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

@@ -132,15 +132,27 @@ Unregister an agent. Returns `boolean` indicating whether the agent existed.
 const removed = pc.removeAgent("mara");
 ```
 
-### `createToken(channel, agentId)`
+### `createToken(channel, agentId, metadata?)`
 
-Generate a short-lived, single-use token for browser WebRTC or chat connections. Used to mint tokens for browsers.
+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 }
 ```
 
+**Sealed session metadata** — pass a third argument to bake trusted context into the token:
+
+```typescript
+const token = await pc.createToken("chat", "mara", { userId: "u_123", plan: "pro" });
+```
+
+The metadata is **sealed into the signed token on your server**, so the browser cannot forge or alter it. It surfaces as [`call.metadata`](/api/call) in your `call.started` handler — use it for per-user / multi-tenant context you can trust (auth identity, plan, tenant id). Works identically for `"webrtc"` and `"chat"`.
+
+> With an `Agent` instance, use `agent.createToken(channel, metadata?)` (the `agentId` is implicit).
+
+> ⚠️ This is **not** the client-supplied `metadata` prop on the widget / `VoiceSession` — that is set in the browser and can be forged. For anything used in authorization, seal it in the token here.
+
 See [Security](/security) for the full token model.
 
 ### `stream(res?, options?)`