hci-atrium 0.1.0 → 0.3.0

package/dist/atrium.js

@@ -1,16 +1,20 @@
 /** The ``Atrium`` client — the entry point that owns auth, an authenticated transport, and the
- * phase-1 namespaces (``library`` / ``assets`` / ``sources`` / ``sessions`` / ``rooms``) plus the
- * ``chat`` and ``embed`` methods. */
+ * namespaces (``library`` / ``assets`` / ``sources`` / ``sessions`` / ``rooms`` / ``surveys``) plus
+ * the ``chat`` / ``agent`` / ``embed`` methods and the direct-model registry. */
 import { Auth } from "./auth.js";
 import { seedAssetId, toOperand } from "./by.js";
+import { DirectEndpoint, DirectRegistry, directFetch, parseModelNames, } from "./direct.js";
 import { DEFAULT_BASE_URL, readEnv } from "./env.js";
-import { AuthError, InvalidArgumentError, raiseForStatus } from "./errors.js";
+import { APIError, AtriumError, AuthError, InvalidArgumentError, raiseForStatus } from "./errors.js";
 import { httpFetch } from "./http.js";
-import { parseAsset, parseAssetPage, parseAssetVector, parseChatReply, parseCompareResult, parseEmbedding, parseIndexEntry, parseRoom, parseSearchByExamplesHit, parseSearchHit, parseSegment, parseSession, parseSessionEvent, parseSessionEventRow, parseSessionInfo, parseSourceInfo, parseSourceSearchResult, parseSpace, parseTagDefinition, parseTranscript, } from "./models.js";
+import { parseAsset, parseAssetPage, parseAssetVector, parseChatReply, parseCompareResult, parseEmbedding, parseIndexEntry, parseRoom, parseSearchByExamplesHit, parseSearchHit, parseSegment, parseSession, parseSessionEvent, parseSessionEventRow, parseSessionInfo, parseSourceInfo, parseSourceSearchResult, parseSpace, parseSurvey, parseSurveyResponse, parseSurveyTemplate, parseTagDefinition, parseTranscript, } from "./models.js";
 import { Room } from "./rooms/index.js";
-import { buildAssetGet, buildAssetIndex, buildAssetList, buildAssetSegments, buildAssetVectors, buildBulkVectors, buildChat, buildCompare, buildEmbed, buildEnrich, buildRoomOpen, buildSearch, buildSearchByExamples, buildSessionEvent, buildSessionEvents, buildSessionExport, buildSessionExportBundle, buildSessionStart, buildSessionsList, buildSourceImport, buildSourcesSearch, buildTagGet, buildTagsList, buildTranscribe, buildUpload, chatBody, distinctExportIds, isZodSchema, JSON_OBJECT, repairMessages, resolveImportTarget, responseFormatParam, structuredError, tryParse, } from "./shaping/index.js";
+import { sseFrames } from "./rooms/sse.js";
+import { buildAssetGet, buildAssetIndex, buildAssetList, buildAssetSegments, buildAssetVectors, buildBulkVectors, buildChat, buildCompare, buildEmbed, buildEnrich, buildProjectFileUpload, buildRoomOpen, buildSearch, buildSearchByExamples, buildSessionEvent, buildSessionEvents, buildSessionExport, buildSessionExportBundle, buildSessionStart, buildSessionsList, buildSourceImport, buildSourcesSearch, buildSurveyResponses, buildSurveyStart, buildTagGet, buildTagsList, buildTemplateCreate, buildTemplateDefault, buildTemplateGet, buildTemplatesList, buildTemplateVersion, buildTranscribe, buildUpload, chatBody, distinctExportIds, isZodSchema, JSON_OBJECT, repairMessages, resolveImportTarget, responseFormatParam, sameJsonBody, structuredError, tryParse, } from "./shaping/index.js";
 import { buildRoomResolve } from "./shaping/rooms.js";
 import { PkceStore, TokenStore } from "./storage.js";
+import { parseToolArguments, readToolCalls, toolSchema } from "./tools.js";
+import { summarizeChat, summarizeEnrich, summarizeSearch, summarizeSearchByExamples, traced, } from "./trace.js";
 import { transcribeEngine } from "./transcribe.js";
 export { DEFAULT_BASE_URL };
 // Emitted at most once per page load: an API key in a browser is readable by anyone on the page.
@@ -67,6 +71,63 @@ function bytesToBase64(bytes) {
     }
     return btoa(binary);
 }
+/** The OpenAI passthrough params of a {@link ChatOptions} — everything the SDK doesn't own itself. */
+function stripChatOptions(opts) {
+    const params = { ...opts };
+    for (const key of ["model", "responseFormat", "strictParams", "signal", "stream"]) {
+        delete params[key];
+    }
+    return params;
+}
+/**
+ * Yield the content deltas of a streamed chat completion. The wire is SSE — ``data:`` frames of
+ * OpenAI chunk JSON, terminated by ``data: [DONE]`` — read through the room transport's
+ * {@link sseFrames} parser. A frame that isn't JSON is skipped (mirror of Python's tolerant loop).
+ */
+async function* chatDeltas(res) {
+    if (!res.body) {
+        throw new AtriumError("chat(stream: true): this runtime's fetch returned no readable body — streaming needs one");
+    }
+    const reader = res.body.getReader();
+    try {
+        for await (const frame of sseFrames(reader)) {
+            const payload = frame.data.trim();
+            if (payload === "[DONE]") {
+                return;
+            }
+            let chunk;
+            try {
+                chunk = JSON.parse(payload);
+            }
+            catch {
+                continue;
+            }
+            const piece = chunk.choices?.[0]?.delta?.content;
+            if (typeof piece === "string" && piece) {
+                yield piece;
+            }
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+    }
+}
+/** A tool's return value as the ``content`` of its tool message. Python sends ``str(result)``; JS's
+ * ``String({})`` is the useless ``"[object Object]"``, so an object is JSON-encoded instead. */
+function toolResultContent(result) {
+    if (typeof result === "string") {
+        return result;
+    }
+    if (result !== null && typeof result === "object") {
+        try {
+            return JSON.stringify(result);
+        }
+        catch {
+            return String(result);
+        }
+    }
+    return String(result);
+}
 /**
  * A client bound to one Atrium instance and one credential (an OAuth ``clientId`` or an ``apiKey``).
  *
@@ -85,11 +146,18 @@ export class Atrium {
     sources;
     sessions;
     rooms;
+    surveys;
+    /** Tracing sinks armed by ``room.trace()`` (shared, mutated by the room handle) — every traced
+     * library/model call mirrors into each. Empty until a room arms one: that emptiness IS the
+     * zero-cost-when-off fast path. */
+    traceSinks = [];
     apiKey;
     defaultProject;
     defaultCollection;
     lifecycle = new AbortController();
     spacesPromise = null;
+    /** Model name → OpenAI-compatible endpoint; consulted by ``chat`` / ``agent`` only. */
+    direct;
     constructor(opts = {}) {
         const baseUrl = (opts.baseUrl ?? readEnv("ATRIUM_BASE_URL") ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
         this.baseUrl = baseUrl;
@@ -97,6 +165,7 @@ export class Atrium {
         this.apiKey = opts.apiKey ?? readEnv("ATRIUM_API_KEY");
         this.defaultProject = opts.project;
         this.defaultCollection = opts.collection;
+        this.direct = new DirectRegistry(opts.directModels);
         if (this.apiKey && typeof window !== "undefined" && !browserKeyWarned) {
             browserKeyWarned = true;
             console.info("Atrium: this page carries an API key — fine for local research setups; " +
@@ -109,6 +178,7 @@ export class Atrium {
         this.sources = new Sources(this);
         this.sessions = new Sessions(this);
         this.rooms = new Rooms(this);
+        this.surveys = new Surveys(this);
     }
     /**
      * ``fetch`` against this instance with the signed-in user's bearer token attached, silent refresh,
@@ -125,50 +195,209 @@ export class Atrium {
     async close() {
         this.lifecycle.abort();
     }
-    async chat(messages, opts = {}) {
-        const { model, responseFormat, strictParams, signal, ...params } = opts;
-        if (isZodSchema(responseFormat)) {
-            return this.chatParse(messages, model, responseFormat, params, signal, strictParams);
+    // --- direct models -----------------------------------------------------------------------------
+    /**
+     * Route ``name`` straight to an OpenAI-compatible endpoint instead of Atrium.
+     *
+     * ``chat`` / ``agent`` calls naming ``name`` POST directly to ``baseUrl`` (bypassing Atrium, and
+     * carrying **only** that endpoint's own key — never the Atrium credential); everything else —
+     * embeddings, library search, sessions, rooms — still goes to Atrium. A registered name
+     * **shadows** an Atrium model of the same name (intentional, opt-in). Idempotent: re-registering
+     * a name overwrites its endpoint.
+     */
+    addDirectModel(name, endpoint) {
+        this.direct.register(name, new DirectEndpoint(endpoint));
+    }
+    /**
+     * Register several model names sharing one endpoint (see {@link addDirectModel}) — the common
+     * "one server, many names" case. Still explicit per name; no auto-enumeration.
+     */
+    addDirectModels(names, endpoint) {
+        const shared = new DirectEndpoint(endpoint);
+        for (const name of names) {
+            this.direct.register(name, shared);
         }
-        const p = { ...params };
-        if (responseFormat !== undefined) {
-            p.response_format = responseFormat;
+    }
+    /** Stop routing ``name`` directly — subsequent calls go to Atrium (idempotent). */
+    removeDirectModel(name) {
+        this.direct.remove(name);
+    }
+    /** A snapshot of the registered direct models: name → {@link DirectEndpoint}. */
+    listDirectModels() {
+        return this.direct.list();
+    }
+    /**
+     * List the model names an OpenAI-compatible endpoint advertises (read-only ``GET {baseUrl}/models``).
+     *
+     * A helper for *choosing* names to register with {@link addDirectModel} — it **never** registers
+     * anything and doesn't touch the registry.
+     *
+     * **In the browser this is subject to CORS**: a local Ollama / LM Studio typically sends no
+     * ``Access-Control-Allow-Origin``, so the fetch is blocked before the SDK sees a response. That is
+     * the endpoint's policy to change (e.g. Ollama's ``OLLAMA_ORIGINS``), not something the SDK can
+     * work around — from Node it just works.
+     */
+    async discoverModels(baseUrl, opts = {}) {
+        const endpoint = new DirectEndpoint({ baseUrl, apiKey: opts.apiKey });
+        const { signal, dispose } = this.directSignal(endpoint, opts.signal);
+        try {
+            const res = await directFetch(endpoint, endpoint.modelsUrl, { method: "GET", signal });
+            return parseModelNames(await res.json());
         }
-        if (strictParams) {
-            p.strict_params = true;
+        finally {
+            dispose();
+        }
+    }
+    /** The abort signal for one direct call: the caller's, the client lifecycle, and the endpoint's
+     * own timeout (``AbortSignal.timeout`` — the stateless-``fetch`` stand-in for Python's per-endpoint
+     * transport timeout), folded into one. */
+    directSignal(endpoint, signal) {
+        const timeoutOf = AbortSignal.timeout;
+        const caller = linkSignals(signal, this.lifecycle.signal);
+        const timeout = timeoutOf ? timeoutOf(endpoint.timeout) : undefined;
+        const linked = linkSignals(caller.signal, timeout);
+        return {
+            signal: linked.signal,
+            dispose: () => {
+                linked.dispose();
+                caller.dispose();
+            },
+        };
+    }
+    /** POST a chat body to a direct endpoint (raw ``fetch``, never the authed transport). */
+    async directChat(endpoint, body, signal) {
+        const linked = this.directSignal(endpoint, signal);
+        try {
+            return await directFetch(endpoint, endpoint.chatUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(body),
+                signal: linked.signal,
+            });
+        }
+        finally {
+            linked.dispose();
         }
-        const data = await this.request(buildChat(chatBody(messages, model, p)), signal);
-        return parseChatReply(data);
     }
-    async chatParse(messages, model, schema, params, signal, strictParams) {
+    chat(messages, opts = {}) {
+        if (opts.stream) {
+            if (isZodSchema(opts.responseFormat)) {
+                throw new InvalidArgumentError("chat(responseFormat: <Zod schema>) cannot be combined with stream: true — structured " +
+                    "output validates a complete reply");
+            }
+            const chunks = this.chatStream(messages, opts);
+            // Python's decorator emits the trace when the generator is handed back (nothing is consumed
+            // yet), so a streamed call has no reply preview and a ~0 duration. Mirror that rather than
+            // deferring the emit until the stream drains — a `trace.chat` should appear when the call is
+            // made. Fire-and-forget: `traced` swallows its own failures and the fn resolves immediately.
+            void traced(this.traceSinks, "chat", { model: opts.model }, summarizeChat, async () => chunks);
+            return chunks;
+        }
+        // One logical call, one `trace.chat` — the structured path recurses through the UNTRACED
+        // `chatOnce` below, which is how TS gets Python's re-entrancy guard for free.
+        return traced(this.traceSinks, "chat", { model: opts.model }, summarizeChat, () => isZodSchema(opts.responseFormat)
+            ? this.chatParse(messages, opts.responseFormat, opts)
+            : this.chatOnce(messages, opts));
+    }
+    /** The chat body for one completion: the caller's passthrough params plus the SDK-owned keys. */
+    chatParams(opts) {
+        const p = stripChatOptions(opts);
+        if (opts.responseFormat !== undefined) {
+            p.response_format = opts.responseFormat;
+        }
+        if (opts.strictParams) {
+            p.strict_params = true;
+        }
+        return p;
+    }
+    // The plain (non-structured) completion — the one HTTP round-trip. Untraced on purpose: the public
+    // `chat` owns the trace, so a structured call's repair turn doesn't emit a second one.
+    async chatOnce(messages, opts = {}) {
+        const body = chatBody(messages, opts.model, this.chatParams(opts));
+        const endpoint = this.direct.resolve(opts.model);
+        if (endpoint) {
+            const res = await this.directChat(endpoint, body, opts.signal);
+            return parseChatReply(await res.json());
+        }
+        return parseChatReply(await this.request(buildChat(body), opts.signal));
+    }
+    /** Content deltas of a streamed completion (SSE, ``[DONE]``-terminated) — the Atrium route or,
+     * for a registered model, the direct endpoint. Mirror of Python's ``_chat_stream``. */
+    async *chatStream(messages, opts) {
+        const body = chatBody(messages, opts.model, { ...this.chatParams(opts), stream: true });
+        const endpoint = this.direct.resolve(opts.model);
+        const res = endpoint
+            ? await this.directChat(endpoint, body, opts.signal)
+            : await this.send(buildChat(body), opts.signal);
+        yield* chatDeltas(res);
+    }
+    async chatParse(messages, schema, opts) {
         const msgs = typeof messages === "string" ? [{ role: "user", content: messages }] : [...messages];
         const rf = await responseFormatParam(schema);
-        const jsonSchema = rf.json_schema.schema;
-        const first = (await this.chat(msgs, {
-            model,
-            responseFormat: rf,
-            strictParams,
-            signal,
-            ...params,
-        }));
-        let [value, detail] = tryParse(schema, first.content);
+        const first = await this.chatOnce(msgs, { ...opts, responseFormat: rf });
+        return this.parseOrRepair(msgs, first, schema, opts);
+    }
+    /**
+     * Validate ``reply`` into ``schema``; on failure run ONE tool-free json-mode repair turn, then give
+     * up. Shared by the ``chat`` and ``agent`` structured paths so the repair policy lives in exactly
+     * one place (mirror of Python's ``_parse_or_repair``). ``opts`` carries the caller's model /
+     * strictness / passthrough params, so the repair turn inherits them.
+     */
+    async parseOrRepair(messages, reply, schema, opts) {
+        let [value, detail] = tryParse(schema, reply.content);
         if (value !== null) {
             return value;
         }
-        const repaired = repairMessages(msgs, first.content, detail, jsonSchema);
-        const second = (await this.chat(repaired, {
-            model,
-            responseFormat: JSON_OBJECT,
-            strictParams,
-            signal,
-            ...params,
-        }));
+        const rf = await responseFormatParam(schema);
+        const jsonSchema = rf.json_schema.schema;
+        const repaired = repairMessages(messages, reply.content, detail, jsonSchema);
+        const second = await this.chatOnce(repaired, { ...opts, responseFormat: JSON_OBJECT });
         [value, detail] = tryParse(schema, second.content);
         if (value !== null) {
             return value;
         }
         throw structuredError(schema.constructor.name, second.content, detail);
     }
+    async agent(prompt, opts) {
+        const { tools, model, maxTurns = 6, responseFormat, signal } = opts;
+        if (responseFormat !== undefined && !isZodSchema(responseFormat)) {
+            // Unlike chat(), a raw dict has nowhere sensible to go: json-mode conflicts with the
+            // tool-calling turns, so forwarding it would break the loop and ignoring it would silently do
+            // nothing. Say so instead.
+            throw new InvalidArgumentError("agent(responseFormat) takes a Zod schema (it structures the final answer); a json-mode " +
+                "dict isn't applied to the tool-calling turns");
+        }
+        const params = { ...opts };
+        for (const key of ["tools", "model", "maxTurns", "responseFormat", "signal"])
+            delete params[key];
+        const byName = new Map(tools.map((tool) => [tool.name, tool]));
+        const schemas = tools.map(toolSchema);
+        const messages = [{ role: "user", content: prompt }];
+        let reply = { content: "", model: "", raw: {} };
+        for (let turn = 0; turn < maxTurns; turn++) {
+            reply = await this.chat(messages, { model, tools: schemas, signal, ...params });
+            const choices = reply.raw.choices;
+            const message = (Array.isArray(choices) ? choices[0] : undefined);
+            const assistant = message?.message;
+            const calls = assistant ? readToolCalls(assistant) : [];
+            if (!calls.length) {
+                break;
+            }
+            messages.push(assistant);
+            for (const call of calls) {
+                const tool = byName.get(call.name);
+                const result = tool
+                    ? await tool.execute(await parseToolArguments(tool, call.arguments))
+                    : `error: unknown tool ${call.name}`;
+                messages.push({ role: "tool", tool_call_id: call.id, content: toolResultContent(result) });
+            }
+        }
+        if (isZodSchema(responseFormat)) {
+            // Structure the FINAL answer only — json-mode conflicts with the tool-calling turns.
+            return this.parseOrRepair(messages, reply, responseFormat, { model, signal, ...params });
+        }
+        return reply;
+    }
     /**
      * Embed text or a media file into a vector (``POST /v1/embeddings``). Pass exactly one of
      * ``text`` / ``image`` / ``audio`` / ``video``. ``model`` is required — an embedding's model is
@@ -457,8 +686,10 @@ export class Library {
             project,
             collection,
         });
-        const data = await this.c.request(req, opts.signal);
-        return (Array.isArray(data) ? data : []).map((d) => parseSearchHit(d, this.c.baseUrl, this.c.assetBinder));
+        return traced(this.c.traceSinks, "library.search", { query, like: opts.like }, summarizeSearch, async () => {
+            const data = await this.c.request(req, opts.signal);
+            return (Array.isArray(data) ? data : []).map((d) => parseSearchHit(d, this.c.baseUrl, this.c.assetBinder));
+        });
     }
     /** Find assets similar to a *set* of example assets (a mood board). */
     async searchByExamples(positives, opts = {}) {
@@ -479,8 +710,10 @@ export class Library {
             project,
             collection,
         });
-        const data = await this.c.request(req, opts.signal);
-        return (Array.isArray(data) ? data : []).map((d) => parseSearchByExamplesHit(d, this.c.baseUrl, this.c.assetBinder));
+        return traced(this.c.traceSinks, "library.search_by_examples", { positives, method: opts.method ?? "cav" }, summarizeSearchByExamples, async () => {
+            const data = await this.c.request(req, opts.signal);
+            return (Array.isArray(data) ? data : []).map((d) => parseSearchByExamplesHit(d, this.c.baseUrl, this.c.assetBinder));
+        });
     }
     /**
      * Compare two operands and return their similarity (raw + calibrated when available). Each operand
@@ -507,7 +740,7 @@ export class Library {
             preview: opts.preview,
             wait: opts.wait,
         });
-        return (await this.c.request(req, opts.signal));
+        return traced(this.c.traceSinks, "library.enrich", { query, modality: opts.modality }, summarizeEnrich, async () => (await this.c.request(req, opts.signal)));
     }
     /**
      * Fetch stored embedding vectors for many assets at once (``POST /v1/library/vectors``,
@@ -744,6 +977,140 @@ export class Sessions {
         return parseSessionEvent(await this.c.request(req, opts.signal));
     }
 }
+/**
+ * Survey templates + starting surveys.
+ *
+ * A **survey** is a data object on a session (``POST /v1/sessions/{id}/data``) guarded by a
+ * per-object capability token: whoever holds the token can read and write exactly that object,
+ * nothing else. {@link Surveys.start} creates it — pinning a template's *current* version, so later
+ * template edits never change a running survey — and returns a {@link Survey} carrying the once-only
+ * ``token`` and the hosted tool ``url``.
+ *
+ * **Templates** are project-scoped JSON documents with immutable, numbered versions. The server
+ * stores the body verbatim — the hosted survey tool's dialect is documented in
+ * ``docs/reference/survey-template-dialect.md``. {@link Surveys.template} is the code-first "ensure"
+ * flow: safe to rerun on every start-up, appending a new version only when the body actually changed.
+ */
+export class Surveys {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    /** The project ref for a ``/v1/projects/{ref}/…`` path — the per-call value or the client's
+     * default scope, passed through **verbatim** (the survey/file routers accept a UUID or a short_id;
+     * resolving a short_id here would issue a projects read a project-scoped key is denied). */
+    projectRef(project) {
+        const { project: ref } = this.c.scope(project, undefined);
+        if (ref === undefined) {
+            throw new InvalidArgumentError("surveys: no project in scope — pass project, or construct the client with one");
+        }
+        return ref;
+    }
+    /**
+     * Start a survey on a session: creates the data object (pinning the template's current version —
+     * or the project's DEFAULT template when ``template`` is omitted) and returns the handle with its
+     * once-only token.
+     */
+    async start(template, opts) {
+        const sessionId = typeof opts.into === "string" ? opts.into : opts.into.id;
+        const req = buildSurveyStart(sessionId, {
+            name: opts.name ?? template ?? "survey",
+            template,
+            useDefault: template === undefined,
+            returnTo: opts.returnTo,
+        });
+        return parseSurvey(await this.c.request(req, opts.signal));
+    }
+    /**
+     * Ensure a template exists with exactly this body (idempotent, code-first).
+     *
+     * Create it if missing; if it exists and the CURRENT version's body differs, append a new
+     * immutable version; flip the default via PATCH when requested and not already set. Returns
+     * ``{name, version, isDefault}``. Safe to rerun on every start-up.
+     */
+    async template(name, body, opts = {}) {
+        const project = this.projectRef(opts.project);
+        const wantDefault = opts.default ?? false;
+        let conflict;
+        try {
+            const created = (await this.c.request(buildTemplateCreate(project, { name, body, isDefault: wantDefault }), opts.signal));
+            return { name: created.name, version: created.version, isDefault: created.is_default };
+        }
+        catch (err) {
+            if (!(err instanceof APIError) || err.status !== 409) {
+                throw err; // only a conflict flows into the ensure path
+            }
+            conflict = err;
+        }
+        let detail;
+        try {
+            detail = (await this.c.request(buildTemplateGet(project, name), opts.signal));
+        }
+        catch (err) {
+            // The create 409 wasn't "name exists" (a default-flip race creates nothing) — the original
+            // conflict is the real story, not a "template not found".
+            throw err instanceof APIError && err.status === 404 ? conflict : err;
+        }
+        if (!sameJsonBody(body, detail.body)) {
+            detail = (await this.c.request(buildTemplateVersion(project, name, body), opts.signal));
+        }
+        let isDefault = Boolean(detail.is_default);
+        if (wantDefault && !isDefault) {
+            const patched = (await this.c.request(buildTemplateDefault(project, name), opts.signal));
+            isDefault = Boolean(patched.is_default);
+        }
+        return { name, version: detail.version, isDefault };
+    }
+    /** List the project's survey templates (``GET …/survey-templates``). */
+    async templates(opts = {}) {
+        const req = buildTemplatesList(this.projectRef(opts.project));
+        const data = await this.c.request(req, opts.signal);
+        return (Array.isArray(data) ? data : []).map(parseSurveyTemplate);
+    }
+    /**
+     * A survey template's responses across the project's sessions, newest first. ``template`` is the
+     * template **name** (not a started {@link Survey}), resolved with ``project`` exactly like
+     * {@link template} / {@link templates}. For the CSV export use {@link responsesCsv}.
+     */
+    async responses(template, opts = {}) {
+        const req = buildSurveyResponses(this.projectRef(opts.project), template, {
+            limit: opts.limit ?? 200,
+            submittedOnly: opts.submittedOnly,
+            phase: opts.phase,
+        });
+        const data = await this.c.request(req, opts.signal);
+        return (Array.isArray(data) ? data : []).map(parseSurveyResponse);
+    }
+    /**
+     * The same responses as the server's CSV export (one row per response, question-id columns),
+     * returned as raw bytes. A separate method rather than a ``format`` union on {@link responses} —
+     * the return types have nothing in common, exactly like ``sessions.export``. The SDK never touches
+     * the filesystem, so a Node caller writes the bytes itself.
+     */
+    async responsesCsv(template, opts = {}) {
+        const req = buildSurveyResponses(this.projectRef(opts.project), template, { limit: opts.limit ?? 200, submittedOnly: opts.submittedOnly, phase: opts.phase }, true);
+        return this.c.requestBytes(req, opts.signal);
+    }
+    /**
+     * Upload a write-once project file (survey imagery) — ``file`` is a ``Blob``/``File`` or a URL
+     * string, never a filesystem path (the core is browser-safe). Returns the file's ``id`` — which a
+     * template body's ``image`` field references — plus its public content ``url``.
+     */
+    async uploadFile(file, opts = {}) {
+        const req = buildProjectFileUpload(this.projectRef(opts.project), {
+            file,
+            filename: opts.filename,
+            role: opts.role ?? "attachment",
+        });
+        const data = (await this.c.request(req, opts.signal));
+        return {
+            id: String(data.id),
+            url: `${this.c.baseUrl}/v1/project-files/${data.id}/content`,
+            filename: data.filename ?? null,
+            contentType: data.content_type ?? null,
+        };
+    }
+}
 /** Open / fetch / join rooms — each returns a live {@link Room} handle (connect, send, on, request,
  * player controls, audio signals). ``connect()`` (called for you by any wire method) opens the socket. */
 export class Rooms {
@@ -769,6 +1136,10 @@ export class Rooms {
                     library: this.c.library,
                     request: (req) => this.c.request(req),
                     transcribeStream: (clips, o) => this.c.transcribeStream(clips, o),
+                    transcribe: (audio, o) => this.c.transcribe(audio, o),
+                    // The client's shared sink list — `room.trace()` registers on it, so the client's own
+                    // library/model calls mirror into this room.
+                    traceSinks: this.c.traceSinks,
                 },
             identity: live.identity,
             announce: live.announce,