@pinecall/skills 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinecall/skills",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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/SKILL.md

@@ -26,7 +26,6 @@ table below indexes every page; open the `references/…` file for the full text
 | **Tools and Functions** | Let your agent take actions: look up data, transfer calls, book appointments. | [`references/guides/tools-and-functions.md`](references/guides/tools-and-functions.md) · [docs](https://docs.pinecall.io/guides/tools-and-functions) |
 | **Knowledge bases (RAG)** | Tutorial — ground a voice or chat agent on your own documents with retrieval-augmented generation. | [`references/guides/knowledge-bases.md`](references/guides/knowledge-bases.md) · [docs](https://docs.pinecall.io/guides/knowledge-bases) |
 | **Multi-Tenant Dashboards** | Host many tenants on one Pinecall instance with scoped event streams. | [`references/guides/multi-tenant.md`](references/guides/multi-tenant.md) · [docs](https://docs.pinecall.io/guides/multi-tenant) |
-| **Self-Hosted LLM Gateway** | Consume Pinecall's hosted open model (Qwen3) for chat and structured analysis over an authenticated, plan-gated streaming endpoint. | [`references/guides/self-hosted-llm.md`](references/guides/self-hosted-llm.md) · [docs](https://docs.pinecall.io/guides/self-hosted-llm) |
 | **SSE Event Streaming** | Stream agent events to your frontend in real time with Server-Sent Events. | [`references/guides/sse-streaming.md`](references/guides/sse-streaming.md) · [docs](https://docs.pinecall.io/guides/sse-streaming) |
 | **WebSocket Event Streaming** | Stream agent events over WebSocket for bidirectional, real-time communication with your frontend. | [`references/guides/ws-streaming.md`](references/guides/ws-streaming.md) · [docs](https://docs.pinecall.io/guides/ws-streaming) |
 | **Dev Mode** | Run dev and production agents on the same phone number, with zero extra Twilio cost. | [`references/guides/dev-mode.md`](references/guides/dev-mode.md) · [docs](https://docs.pinecall.io/guides/dev-mode) |

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?)`

package/skills/pinecall-guides/references/guides/self-hosted-llm.md

@@ -1,148 +0,0 @@
----
-title: "Self-Hosted LLM Gateway"
-description: "Consume Pinecall's hosted open model (Qwen3) for chat and structured analysis over an authenticated, plan-gated streaming endpoint."
----
-
-# Self-Hosted LLM Gateway
-
-Pinecall hosts an open LLM and exposes it through an authenticated streaming
-endpoint on the sdk-server. Use it for any task that wants a cheap, in-house LLM
-instead of a paid per-token provider: **chat / agent loops** and **structured
-analysis** (classification, extraction, summarization, recommendations).
-
-| Model | Size | Best for |
-|-------|------|----------|
-| `qwen3:14b` | ~9 GB | **default** — hybrid model: clean JSON/analysis with thinking off, step-by-step reasoning with thinking on |
-| `deepseek-r1:14b` | ~9 GB | dedicated reasoning — **coming soon** |
-| `qwen2.5-coder:14b` | ~9 GB | code generation, refactors, tool/JSON authoring — **coming soon** |
-| `mistral-nemo:12b` | ~7 GB | strong multilingual + 128k context — **coming soon** |
-
-> Models flagged **coming soon** aren't live yet — `GET /api/llm/models` always
-> returns the currently available set.
-
-## Authentication & access
-
-- **Base URL:** `https://voice.pinecall.io`
-- **Auth:** a Pinecall API key via `X-API-Key: <key>` **or** `Authorization: Bearer <key>`.
-- **Plan gating:** **paid plans only** (`starter`, `pro`, `enterprise`). Both `free`
-  and `free_trial` receive **`402 SUBSCRIPTION_REQUIRED`**.
-
-## `POST /api/llm/chat`
-
-Streams the completion as **Server-Sent Events**.
-
-### Request body
-
-```jsonc
-{
-  "messages":    [{ "role": "user", "content": "..." }],  // required
-  "system":      "optional system prompt",
-  "model":       "qwen3:14b",                             // default: qwen3:14b
-  "mode":        "chat" | "analysis",                     // default: "chat"
-  "think":       false,                                   // reasoning on/off (default false; analysis forces false)
-  "temperature": 0.7,
-  "max_tokens":  512,
-  "format":      { /* JSON schema */ } | "json"           // analysis mode only
-}
-```
-
-Qwen3 is a **hybrid** model: `think: false` (the default) returns a clean, direct
-answer — best for JSON and low latency. `think: true` lets it reason step-by-step
-first (better on hard problems); the reasoning never leaks into the streamed
-answer. `mode: "analysis"` always forces thinking off so JSON stays clean.
-
-### SSE event stream
-
-```
-data: {"type":"token","content":"..."}                 // repeated — incremental text
-data: {"type":"done","usage":{"input_tokens":N,"output_tokens":M}}
-data: {"type":"error","error":"...","code":"UPSTREAM_ERROR|INTERNAL"}
-data: [DONE]                                            // terminator
-```
-
-### Errors
-
-| Status | Code | Meaning |
-|--------|------|---------|
-| 401 | `MISSING_KEY` / `INVALID_KEY` | no or bad API key |
-| 402 | `SUBSCRIPTION_REQUIRED` | tier is `free` or `free_trial` |
-| 400 | `MISSING_MESSAGES` / `BAD_MODEL` / `BAD_REQUEST` | invalid request |
-
-## `GET /api/llm/models`
-
-Same auth + gate. Returns the available models, the default, and the caller's tier —
-handy to probe access before streaming. **This is the source of truth for what's
-currently available** (the list grows over time).
-
-```json
-{ "models": ["qwen3:14b"], "default": "qwen3:14b", "tier": "pro" }
-```
-
-## Chat — streaming agent loop
-
-```ts
-const res = await fetch("https://voice.pinecall.io/api/llm/chat", {
-  method: "POST",
-  headers: {
-    "Content-Type": "application/json",
-    "X-API-Key": process.env.PINECALL_API_KEY!,
-  },
-  body: JSON.stringify({
-    model: "qwen3:14b",
-    system: "You are a concise assistant.",
-    messages: [{ role: "user", content: "Summarize today's bookings." }],
-    // think: true,  // ← opt into step-by-step reasoning for harder questions
-  }),
-});
-
-const reader = res.body!.getReader();
-const dec = new TextDecoder();
-let buf = "";
-for (;;) {
-  const { value, done } = await reader.read();
-  if (done) break;
-  buf += dec.decode(value, { stream: true });
-  for (const line of buf.split("\n\n")) {
-    if (!line.startsWith("data: ")) continue;
-    const data = line.slice(6);
-    if (data === "[DONE]") break;
-    const evt = JSON.parse(data);
-    if (evt.type === "token") process.stdout.write(evt.content);
-  }
-  buf = buf.slice(buf.lastIndexOf("\n\n") + 2);
-}
-```
-
-## Analysis — structured JSON (schema-enforced)
-
-Set `mode: "analysis"` and pass a JSON **schema** in `format`. The gateway routes
-analysis requests through a native path that constrains the output to your schema
-(and forces thinking off) — ideal for recommendations and extraction.
-
-```ts
-const body = {
-  model: "qwen3:14b",
-  mode: "analysis",
-  system: "You are a pricing engine. Return JSON only.",
-  messages: [{ role: "user", content: "Service: deep-tissue massage, $80, 95% utilization, 60% margin. Recommend an optimal price." }],
-  format: {
-    type: "object",
-    properties: {
-      suggestedPrice: { type: "number" },
-      confidence:     { type: "string", enum: ["low", "medium", "high"] },
-      rationale:      { type: "string" },
-    },
-    required: ["suggestedPrice", "confidence", "rationale"],
-  },
-};
-// POST as above, accumulate the `token` chunks into `text`, then:
-const rec = JSON.parse(text); // { suggestedPrice, confidence, rationale }
-```
-
-> **Warning:** Pass a real JSON-schema **object**. The string `"json"` (OpenAI-style
-> `response_format`) only nudges the model toward JSON — it does **not** enforce a shape.
-
-> **Note:** This open model is for **in-app responders, analysis, and
-> recommendations**. For **live voice / WhatsApp agents**, the Pinecall server-side
-> LLM supports OpenAI / Mistral / Google / Anthropic — see
-> [LLM Providers](/reference/llm-providers).