@ziprack/sdk 0.3.0 → 0.4.0

package/dist/ai/index.d.ts

@@ -4,15 +4,34 @@ export interface Usage {
     input_tokens: number;
     output_tokens: number;
 }
+/**
+ * Where a grounded answer's evidence came from: a passage in one of the
+ * manifest's knowledge slots. Present only on prompts bound to knowledge, and
+ * empty when nothing relevant was found or retrieval was unavailable.
+ */
+export interface Citation {
+    slot: string;
+    title: string | null;
+    ref: string | null;
+    sources: Array<{
+        title: string;
+        ref?: string;
+    }>;
+    url: string | null;
+    t_start: number | null;
+    t_end: number | null;
+}
 export interface ChatReply {
     message_id: string;
     text: string;
     usage: Usage;
+    citations?: Citation[];
 }
 export declare class Chat {
     private readonly link;
     readonly promptId: string;
-    constructor(link: Link, promptId: string);
+    private readonly vars;
+    constructor(link: Link, promptId: string, vars?: JsonObject);
     /**
      * Send a participant message. onDelta receives text as it streams; the
      * resolved result carries the full text.
@@ -30,12 +49,25 @@ export declare class AiApi {
     prompts(): Array<{
         id: string;
         mode: 'analysis' | 'chat';
+        knowledge?: string[];
+    }>;
+    /** The knowledge slots the manifest declares. Their contents stay on the Rack. */
+    knowledge(): Array<{
+        id: string;
+        label: string | null;
     }>;
-    /** Analysis prompt: structured JSON conforming to the declared output_schema. */
+    /**
+     * Analysis prompt: structured JSON conforming to the declared output_schema.
+     * A prompt bound to knowledge also returns the citations it was grounded in.
+     */
     ask<T extends object = JsonObject>(promptId: string, vars?: JsonObject): Promise<AckResult<{
         output: T;
         usage: Usage;
+        citations?: Citation[];
     }>>;
-    /** Chat prompt: conversation history is held by the Rack. */
-    chat(promptId: string): Chat;
+    /**
+     * Chat prompt: conversation history is held by the Rack. `vars` fill the
+     * template's placeholders on every turn, e.g. which persona to speak as.
+     */
+    chat(promptId: string, vars?: JsonObject): Chat;
 }

package/dist/core/mock/MockRack.d.ts

@@ -39,6 +39,13 @@ export interface MockManifest {
         id: string;
         mode: 'analysis' | 'chat';
         output_schema?: JsonObject;
+        knowledge?: Array<{
+            slot: string;
+        }>;
+    }>;
+    knowledge?: Array<{
+        id: string;
+        label?: string;
     }>;
     broadcast?: {
         facilitator_events?: string[];

package/dist/core/types.d.ts

@@ -114,10 +114,16 @@ export interface LaunchData {
             max_bytes: number;
         }>;
     };
+    /** `knowledge` lists the slots a prompt is grounded in (Racks with knowledge support). */
     ai?: {
         prompts: Array<{
             id: string;
             mode: 'analysis' | 'chat';
+            knowledge?: string[];
+        }>;
+        knowledge?: Array<{
+            id: string;
+            label: string | null;
         }>;
     };
     broadcast?: LaunchBroadcast;

package/dist/docs/ai.md

@@ -6,6 +6,7 @@
 - [Chat](#chat)
 - [Budgets](#budgets)
 - [Untrusted Variables](#untrusted-variables)
+- [Knowledge](#knowledge)
 - [Not This Capability](#not-this-capability)
 
 <a name="introduction"></a>
@@ -150,6 +151,89 @@ pass through, and design the template so that it would not matter:
   schema-constrained answer is a much smaller blast radius.
 - Show model output as model output. Do not render it as if it were Rack-authored guidance.
 
+<a name="knowledge"></a>
+## Knowledge
+
+A prompt can be **grounded** in documents the Rack holds: before the model is called, the Rack
+retrieves the most relevant passages and hands them over as quoted reference material. The applet
+still sends only variables — it never sees the documents, the search or the filter.
+
+Declare **slots** (named collections the Rack fills) and bind prompts to them:
+
+```json
+"knowledge": [
+    {
+        "id": "factbook",
+        "label": "Fact Book",
+        "fields": {
+            "stage": { "enum": ["s3_misdiagnosis", "s5_initial_treatment"] },
+            "stakeholders": { "type": "array", "items": { "enum": ["patient", "caregiver", "hepatologist"] } },
+            "persona_eligible": { "type": "boolean" }
+        }
+    }
+],
+"prompts": [
+    {
+        "id": "persona_chat",
+        "mode": "chat",
+        "template": "You are a composite {{persona}} from the fact book...",
+        "vars": { "type": "object", "properties": { "persona": { "enum": ["patient_neuro", "caregiver_parent"] } } },
+        "knowledge": [{
+            "slot": "factbook",
+            "top_k": 6,
+            "filter": { "persona_eligible": true },
+            "filter_by": { "persona": {
+                "patient_neuro":    { "stakeholders": { "contains": "patient" } },
+                "caregiver_parent": { "stakeholders": { "contains": "caregiver" } }
+            } }
+        }]
+    }
+]
+```
+
+| Field | Rules |
+|---|---|
+| `knowledge[].id` | Required. `^[a-z][a-z0-9_]*$`, unique. |
+| `knowledge[].source` | `rack` (the default): documents are loaded after install, from the Rack or over MCP. |
+| `knowledge[].fields` | The metadata a document may tag and a filter may use: `type` (`string`, `number`, `boolean`, `array`) and an optional `enum` (`items.enum` for arrays). `sensitivity`, `content`, `embedding`, `text` and `id` are reserved. |
+| `prompts[].knowledge[].slot` | A declared slot. Up to three per prompt. |
+| `top_k` | Passages to retrieve, up to the Rack's ceiling. |
+| `query` | Analysis prompts: what to search for, with `{{var}}` placeholders. Default: the string variables. Chat prompts search with the participant's message. |
+| `filter` | Fixed conditions: a value (equals), `{ "in": [...] }`, or `{ "contains": value }` for an array field. |
+| `filter_by` | Maps each value of an **enum** variable to more conditions. Every enum value must be mapped. This is how one prompt serves several personas without the applet writing filters. |
+
+```ts
+const coach = Rack.ai.chat('persona_chat', { persona: 'caregiver_parent' });
+const reply = await coach.send('What was the hardest moment?');
+
+reply.data?.citations;   // [{ slot, title, ref: 'slide 105', sources: [...], url, t_start, t_end }]
+Rack.ai.knowledge();     // [{ id: 'factbook', label: 'Fact Book' }]
+```
+
+**Citations** come back on every grounded call — empty when nothing relevant was found or the
+Rack's index was unavailable, in which case the model answered ungrounded. Show them; they are how a
+participant can check an answer.
+
+**Loading documents** happens on the Rack, not in the package: an author uploads to a slot from the
+applet's AI tab or with the `create-knowledge-upload` MCP tool. The Rack accepts prepared JSONL (one
+chunk per line: `id`, `text`, and optionally `context`, `title`, `ref`, `sources`, `url`, `t_start`,
+`t_end`, `sensitivity`, `metadata` using the slot's fields), Markdown, plain text, HTML, and WebVTT or
+SRT transcripts. Heavy sources — slide decks, PDFs, video — are prepared locally and arrive as JSONL
+or a transcript; the Rack never parses them. The `get-knowledge-prep-skill` MCP tool installs an
+agent skill that does that preparation, validation and loading. Chunks above the Rack's sensitivity ceiling are refused
+and never leave the Rack, and each applet can be held to a lower ceiling for retrieval.
+
+A Rack without a knowledge-capable ai package refuses a manifest with a `knowledge` section at
+install, naming the unowned section, rather than answering ungrounded.
+
+### Untrusted Passages
+
+Retrieved text is document content, not Rack instruction. It travels in a quoted `<reference>` block
+of the user message — never the system prompt — and the model is told to use it as evidence and never
+to follow instructions inside it. Delimiting reduces indirect prompt injection; it does not eliminate
+it. Load only documents you would be comfortable having quoted back to a participant, and use
+`sensitivity` to keep anything that must not be quoted out of the index altogether.
+
 <a name="not-this-capability"></a>
 ## Not This Capability
 

package/dist/docs/installation.md

@@ -84,6 +84,7 @@ ones you will actually touch.
 | `allowed_extensions` | static list | Anything else rejects the whole upload. |
 | `asset_token_ttl_hours` | `6` | Lifetime of the signed package-asset token. |
 | `session_ttl_hours` | `6` | Lifetime of a launch session. |
+| `session_cookie` | `ziprack_launch` | HttpOnly cookie that binds launch sessions to the browser that launched them. |
 | `csp.img_hosts`, `csp.media_hosts` | `[]` | Per-deployment allowlist. A bare scheme is rejected. |
 | `player.frame_allow` | `[]` | Features added to the applet iframe's `allow` list, e.g. `microphone`. Bare names from a fixed set only. |
 | `media.providers` | `['vimeo','youtube']` | Drives `frame-src` and manifest validation. |
@@ -126,8 +127,10 @@ validation. Defaults apply when a manifest declares nothing.
 | `GET /r/{code}` | Join a room by code (`broadcast`). |
 | `*` `/ziprack/admin/*` | The headless admin API (`ziprack/admin`). |
 
-Session routes are deliberately stateless: token in the path, no session cookie, no CSRF, rate
-limited by `ziprack.routes.session_rate_limit`.
+Session routes run without the `web` group: no Laravel session, no CSRF, rate limited by
+`ziprack.routes.session_rate_limit`. Each request needs the token in the path **and** the
+`ziprack_launch` cookie the player set when it issued that token, so a token copied out of the page
+or an access log is refused from any other browser.
 
 <a name="participants-and-guests"></a>
 ## Participants and Guests

package/dist/docs/manifest.md

@@ -98,7 +98,8 @@ At most 20 roles.
 | `reporting.metrics[]` | `activity@1` (+ `attempt@1`) | `{key, label, pre, post}` — pairs two declared activities |
 | `collections[]` | `db@1` | `{name, scope, schema, indexed?, quota?, permissions?, seed?}` |
 | `uploads[]` | `storage@1` | `{name, scope, mime[], max_bytes?, max_files?}` |
-| `prompts[]` | `ai@1` | `{id, mode, template, vars?, output_schema?, budget?, model?}` |
+| `prompts[]` | `ai@1` | `{id, mode, template, vars?, output_schema?, budget?, model?, knowledge?}` |
+| `knowledge[]` | `ai@1` | `{id, source?, label?, fields?}` |
 | `broadcast` | `broadcast@1` | `{channels?, facilitator_events?}` |
 
 Each is specified in full on its capability's page. Two cross-cutting rules are worth stating here:

package/dist/docs/mcp.md

@@ -107,6 +107,9 @@ user is no longer an admin.
 | `list-collections`, `list-records` | db | |
 | `list-files` | storage | |
 | `ai-spend` | ai | |
+| `list-knowledge`, `search-knowledge` | ai | Knowledge slots, documents, label counts; try retrieval as a prompt would |
+| `get-knowledge-prep-skill` | ai | The agent skill that prepares decks, PDFs and transcripts as tagged JSONL locally, validates them and loads them |
+| `create-knowledge-upload`, `delete-knowledge-document` | ai | Load a document into a slot via a signed URL; delete one. Need `ziprack.ai.load-knowledge` |
 | `list-rooms`, `get-room` | broadcast | |
 
 Capability tools are only present when their capability package is installed.

package/dist/docs/security.md

@@ -119,12 +119,16 @@ instead of loosening the policy.
   scoped to one version, expiring after `ziprack.asset_token_ttl_hours` (6). The extraction disk is
   never publicly served.
 - **Launch session.** Capability calls go to `/ziprack/s/{session}/messages` with a token in the
-  path — no session cookie, no CSRF, stateless by design, rate limited, expiring after
-  `ziprack.session_ttl_hours` (6). The session is what binds a message to a participant, a version,
+  path — no Laravel session, no CSRF, rate limited, expiring after
+  `ziprack.session_ttl_hours` (6). The token is bound to the launching browser: the launch sets a
+  random host-only, HttpOnly, SameSite=Lax `ziprack_launch` cookie (never shared with sibling subdomains), the token carries its hash, and every
+  session request must present the matching cookie. A token seen in page source, a screenshot or
+  a proxy log cannot be replayed from anywhere else. Logging in or out starts a new cookie, so the next person on a shared
+  browser cannot use the previous user's open sessions. The session is what binds a message to a participant, a version,
   an attempt and a room; nothing in the payload can widen that scope.
 - **Signed file URLs.** `storage@1` hands out short-lived URLs, never object keys.
-- **Channel authentication.** The Rack signs its own WebSocket subscriptions. No token reaches the
-  frame.
+- **Channel authentication.** The Rack signs its own WebSocket subscriptions, and stops signing
+  them for a room once it is closed. No token reaches the frame.
 
 <a name="the-migration-runner"></a>
 ## The Migration Runner

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { HostBridge } from './core/bridge';
 export type { AnswerOptions, StatementInput } from './activity';
 export type { Collection, ListQuery, ListResult, RecordRow, WhereClause, WhereOperator } from './db';
 export type { StoredFile, FileStatus } from './storage';
-export type { Chat, ChatReply, Usage } from './ai';
+export type { Chat, ChatReply, Citation, Usage } from './ai';
 export type { Channel, RoomEventName, RoomEvents } from './broadcast';
 export type { MockManifest, AiMockHandler } from './core/mock/MockRack';
 /** The singleton every applet talks through. */

package/dist/index.js

@@ -1,5 +1,5 @@
-import { n as f, c as h, i as g, a as u, M as l, b as w, L as b } from "./store-DQbG_t2D.js";
-import { F as K, P as V, d as W } from "./store-DQbG_t2D.js";
+import { n as f, c as h, i as g, a as u, M as l, b as w, L as b } from "./store-BHnO2KB3.js";
+import { F as K, P as V, d as W } from "./store-BHnO2KB3.js";
 class v {
   constructor(t) {
     this.link = t;
@@ -32,8 +32,8 @@ class v {
   }
 }
 class y {
-  constructor(t, e) {
-    this.link = t, this.promptId = e;
+  constructor(t, e, s = {}) {
+    this.link = t, this.promptId = e, this.vars = s;
   }
   /**
    * Send a participant message. onDelta receives text as it streams; the
@@ -41,21 +41,22 @@ class y {
    */
   async send(t, e) {
     let s = "";
-    const n = await this.link.send("ai:chat", { prompt: this.promptId, message: t }, {
+    const n = Object.keys(this.vars).length > 0 ? { prompt: this.promptId, message: t, vars: this.vars } : { prompt: this.promptId, message: t }, i = await this.link.send("ai:chat", n, {
       timeoutMs: 6e4,
-      onPartial: (i) => {
-        const a = typeof i.delta == "string" ? i.delta : "";
-        s += a, e?.(a, s);
+      onPartial: (a) => {
+        const o = typeof a.delta == "string" ? a.delta : "";
+        s += o, e?.(o, s);
       }
     });
-    return n.ok ? {
+    return i.ok ? {
       ok: !0,
       data: {
-        message_id: String(n.data?.message_id ?? ""),
-        text: n.data?.text ?? s,
-        usage: n.data?.usage ?? { input_tokens: 0, output_tokens: 0 }
+        message_id: String(i.data?.message_id ?? ""),
+        text: i.data?.text ?? s,
+        usage: i.data?.usage ?? { input_tokens: 0, output_tokens: 0 },
+        ...i.data?.citations ? { citations: i.data.citations } : {}
       }
-    } : n;
+    } : i;
   }
   reset() {
     return this.link.send("ai:chat.reset", { prompt: this.promptId });
@@ -68,13 +69,23 @@ class M {
   prompts() {
     return this.link.launch()?.ai?.prompts ?? [];
   }
-  /** Analysis prompt: structured JSON conforming to the declared output_schema. */
+  /** The knowledge slots the manifest declares. Their contents stay on the Rack. */
+  knowledge() {
+    return this.link.launch()?.ai?.knowledge ?? [];
+  }
+  /**
+   * Analysis prompt: structured JSON conforming to the declared output_schema.
+   * A prompt bound to knowledge also returns the citations it was grounded in.
+   */
   ask(t, e = {}) {
     return this.link.send("ai:ask", { prompt: t, vars: e }, { timeoutMs: 6e4 });
   }
-  /** Chat prompt: conversation history is held by the Rack. */
-  chat(t) {
-    return new y(this.link, t);
+  /**
+   * Chat prompt: conversation history is held by the Rack. `vars` fill the
+   * template's placeholders on every turn, e.g. which persona to speak as.
+   */
+  chat(t, e = {}) {
+    return new y(this.link, t, e);
   }
 }
 class L {
@@ -395,12 +406,12 @@ class P {
       return;
     }
     if (t.partial && !t.done) {
-      const { requestId: F, ok: j, partial: $, ...k } = t;
+      const { requestId: z, ok: F, partial: $, ...k } = t;
       e.onPartial?.(k), clearTimeout(e.timer), e.timer = setTimeout(() => this.expire(t.requestId), e.timeoutMs);
       return;
     }
     clearTimeout(e.timer), this.pending.delete(t.requestId);
-    const { requestId: s, ok: n, data: i, error: a, message: o, details: p, partial: U, done: z, ...c } = t;
+    const { requestId: s, ok: n, data: i, error: a, message: o, details: p, partial: U, done: j, ...c } = t;
     e.resolve({ ok: n, data: i ?? (Object.keys(c).length ? c : void 0), error: a, message: o, details: p });
   }
 }