hci-atrium 0.2.0 → 0.3.1

package/README.md

@@ -57,6 +57,36 @@ function Dashboard() {
 Atrium" button otherwise (pass `fallback` for your own landing page). The callback that Atrium
 redirects back to is handled automatically — no route or effect to wire up.
 
+### useRoomConnection
+
+`useRoomConnection(code, { identity, baseUrl?, onRoom? })` is the connect/reconnect skeleton for a
+component that consumes a [room](#live-rooms) by connect code — loginless, so it needs no provider
+and no sign-in. It joins, classifies failures, and tears the handle down on unmount, returning
+`{ status, room }`: `status` is `"connecting"` → `"connected"`, `"unreachable"` for a join/connect
+failure, or a typed terminal end (`"bad-code"` / `"code-rotated"` / `"room-gone"`); `room` is the
+`Room` handle, `null` before it exists and again after a terminal end. Register signal handlers in
+`onRoom` — it runs the moment the handle exists, **before** `connect()`, so a replayed durable signal
+isn't missed — and return a cleanup from it if you need one. `identity` is the presence name (e.g.
+`"viewer:web"`); `baseUrl` defaults to `location.origin`.
+
+```tsx
+import { useState } from "react"
+import { useRoomConnection } from "hci-atrium/react"
+
+function Scene({ code }: { code: string }) {
+  const [name, setName] = useState("—")
+  const { status, room } = useRoomConnection(code, {
+    identity: "viewer:web",
+    onRoom: (room) => {
+      room.on("scene.change", (e) => setName(String(e.payload.name)))
+    },
+  })
+
+  if (status !== "connected") return <p>{status}</p>
+  return <button onClick={() => void room?.send("applause")}>{name}</button>
+}
+```
+
 ## Core API (no framework)
 
 ```ts
@@ -89,10 +119,10 @@ const atrium = new Atrium({ baseUrl, clientId })
   (retry once) on a 401, and concurrent callers share one refresh. If refresh fails, the SDK drops
   to a signed-out state and emits a change.
 
-## Phase-1 surface
+## The client surface
 
-Beyond auth, the client exposes the library / assets / sources / sessions / rooms namespaces plus
-`chat` and `embed`. Every method takes an **options object** with `filters` kept nested
+Beyond auth, the client exposes the library / assets / sources / sessions / rooms / surveys
+namespaces plus `chat`, `agent` and `embed`. Every method takes an **options object** with `filters` kept nested
 (`search("rain", { modality, filters: { … } })`); names are **camelCase**, translated to the wire's
 snake_case in one place (the shaping layer). Authenticate with an OAuth `clientId` **or** an
 `apiKey` — the latter works in the browser too (a one-time console note points at PKCE for hosted
@@ -108,7 +138,10 @@ apps).
 | `sources.list()` / `sources.search(query, opts?)` / `sources.import(opts)` | External-provider gateway — read-only fan-out search, then import a `Candidate`. |
 | `sessions.start(opts?)` / `sessions.resume(id)` / `sessions.event(id, type, opts?)` | Durable, append-only session logs. |
 | `rooms.open(opts?)` / `rooms.get(id)` / `rooms.list()` / `rooms.join(code)` | Live [`Room`](#live-rooms) handles — `open`/`get`/`list` are authenticated, `join(code)` is a loginless participant. |
-| `chat(messages, opts?)` | Chat completion. Pass `responseFormat` a **Zod** schema for validated structured output (Zod is an optional peer dep). |
+| `surveys.start(template?, opts)` / `surveys.template(name, body, opts?)` / … | [Surveys](#surveys) on a session, and the project's survey templates. |
+| `chat(messages, opts?)` | Chat completion. Pass `responseFormat` a **Zod** schema for validated structured output (Zod is an optional peer dep), or `stream: true` for an [`AsyncIterable<string>`](#streaming-chat) of deltas. |
+| `agent(prompt, { tools, … })` | A [tool-calling loop](#agents-and-tools) over explicit tool descriptors. |
+| `addDirectModel(name, { baseUrl, apiKey? })` | Route one model name straight to an OpenAI-compatible endpoint ([direct models](#direct-models)) instead of Atrium. |
 | `embed(opts)` | Embed exactly one of `text` / `image` / `audio` / `video` into a vector; `model` is required. |
 | `transcribe(audio, opts?)` | Speech-to-text over a multipart audio upload; `opts.verbose` fills `.language` / `.duration` / `.segments`. |
 | `by.*` | Operand grammar for `searchByExamples` / `compare`: `by.asset` / `by.text` / `by.file` / `by.concept`, and `by.vector([…])` — the only way to pass a raw vector. |
@@ -125,15 +158,172 @@ a matching `room.request(...)`); `room.send(type, payload, { to })` fans out; pl
 loudness/spectrum/beat stream. `connect()` opens the socket (every wire method calls it for you);
 `close()` / `await using` / a passed `AbortSignal` tears it down.
 
-Not yet ported (environment- or broker-bound, tracked as parity exceptions): `record(into=session)`
-host bridging, and `audioVectors` / `audioScores` (the embed/chat-broker protocol). Audio-signal
-*consumption* is complete. In Node <22 pass a `WebSocketCtor` (e.g. from `ws`); browsers and Node ≥22
-use the global.
+Host-side surfaces on an **owned** room (`atrium.rooms.open/get/join`, not the loginless `joinRoom`):
+
+| Member | Description |
+| --- | --- |
+| `room.record(into)` / `room.transcribe(opts?)` | Bridge the room into a durable session; run live transcription into `transcript.*` signals. |
+| `room.audioVectors(opts?)` / `room.audioScores(anchors, opts?)` / `room.audioClips()` | Embed / score / take raw the live ~10s audio windows. |
+| `room.audioTranscripts(opts?)` | The raw per-snippet transcript iterator — the speech-to-text sibling of `audioVectors`. Streaming when the backend offers it, per-clip batch otherwise (then each transcript carries its source window under `raw.snippet`). Takes `{ model, language, partials, skipEmpty, signal }`; `break` (or abort) ends the subscription. |
+| `room.dashboard(opts?)` → [`Dashboard`](#observation-dashboard) | Host-side state for the hosted observation dashboard (`/tools/dashboard`). |
+| `room.trace()` → `RoomTrace` | Mirror the SDK's own activity into the room as `trace.*` signals (default off). |
+| `room.offerTranscription()` / `offerAudioCapture()` / `offerEmbeds()` / `offerChat()` | Standing services + capability brokers for code-joined peers. |
+
+This SDK now covers every Python-SDK surface except the documented parity exceptions — the CLI, the
+Home Assistant bridge, a sync surface, and raw-PCM mic input — each with its reason in
+[`PARITY.md`](PARITY.md), alongside the handful of deliberate micro-divergences. In Node <22 pass a
+`WebSocketCtor` (e.g. from `ws`); browsers and Node ≥22 use the global.
+
+### Observation dashboard
+
+`room.dashboard({ title })` returns a `Dashboard`: the app owns its state as a grid of **tiles** and
+retells it — each joining dashboard gets a full `dash.snapshot`, every mutation broadcasts a
+`dash.delta`. All `dash.*` traffic is ephemeral (the room stores nothing — the durable record is the
+session). Tiles: `status(id, label, value, { style })` · `text(id, text)` · `image(id, { assetId,
+url, caption })` · `sound(id, { assetId, playing })` · `decision(id, candidates, { picked,
+reasoning })`, each taking `{ title, colSpan, rowSpan, group }` (spans 1..3). `error(message,
+detail?)` pins the dashboard's sticky error strip — it is *not* a tile. Controls ride the snapshot:
+`button(id, label, handler, { variant, confirm })`, `textInput(id, handler, { label, placeholder })`
+(the handler's `{ ok?, message? }` is toasted), and `onNote(handler)` for researcher notes.
+
+```ts
+const dash = room.dashboard({ title: "Reactive Soundscape" })
+await dash.status("phase", "Phase", "Calibration", { style: "good" })
+await dash.decision("pick", ["Forest Rain", "City Drizzle"], { picked: "Forest Rain" })
+dash.button("advance", "Start next phase", async () => {
+  await dash.status("phase", "Phase", "Running")
+  return { message: "Phase advanced" }
+})
+```
+
+### Tracing
+
+`room.trace()` mirrors what the SDK is doing into the room, so a dashboard shows it without any
+app-side plumbing. Library/model calls on the same client (`library.search` / `searchByExamples` /
+`enrich` / `chat`) and `room.play` surface a `trace.<label>` (a one-line summary plus a capped
+detail); recorder / transcriber / standing-offer transitions surface a `trace.state.<label>`. It is
+**off by default** (it broadcasts app internals to anyone holding the connect code), costs nothing
+while off, never breaks the traced call, and stops with `t.stop()`, `using t = room.trace()`, or the
+room's teardown.
+
+```ts
+using t = room.trace()
+await atrium.library.search("rain") // → trace.library.search on the dashboard
+```
 
 Errors derive from `AtriumError`: HTTP failures are `APIError` (401/403 → `AuthError`, 429/5xx →
 `TransientAuthError`), and caller mistakes (mutually-exclusive inputs, unsupported filters) are
 `InvalidArgumentError`.
 
+### Surveys
+
+A **survey** is a data object on a session, guarded by a per-object capability token: whoever holds
+it can read and write exactly that object, nothing else. `surveys.start()` creates it — pinning the
+template's *current* version, so later edits never change a running survey — and returns the token
+plus the hosted tool's `url`. Hand either to the participant-facing environment, or `survey.open()`
+a tab on the machine itself.
+
+`surveys.template(name, body)` is the code-first **ensure** flow: run it on every start-up. It
+creates the template if it's missing, appends a new immutable version only when the body actually
+changed, and flips `default` when asked — so your templates live in your repo, not in a UI.
+
+```ts
+await atrium.surveys.template("post-study", postStudyBody, { default: true })
+
+const session = await atrium.sessions.start({ participantRef: "p-07" })
+const survey = await atrium.surveys.start("post-study", {
+  into: session,
+  returnTo: "https://study.example/next",
+})
+survey.open() // …or send survey.url / survey.token to the participant's device
+
+const rows = await atrium.surveys.responses("post-study", { submittedOnly: true })
+const csv = await atrium.surveys.responsesCsv("post-study") // Uint8Array, one row per response
+```
+
+Everything project-scoped (`template` / `templates` / `responses` / `responsesCsv` / `uploadFile`)
+takes `project` per call, or inherits the client's. `uploadFile(blob)` stores a write-once project
+file (survey imagery) and returns the `id` a template body's `image` field references.
+
+### Streaming chat
+
+`chat(messages, { stream: true })` returns an `AsyncIterable<string>` of content deltas — **not** a
+promise, so there is nothing to `await` before the loop. It works the same on a direct endpoint, and
+can't be combined with a schema `responseFormat` (structured output validates a complete reply).
+
+```ts
+for await (const piece of atrium.chat("describe a rainy street", { stream: true })) {
+  process.stdout.write(piece)
+}
+```
+
+### Agents and tools
+
+`agent(prompt, { tools })` runs the tool-calling loop: the model may call your tools until it
+answers, or until `maxTurns` (default 6). A tool is an explicit descriptor — TypeScript has no
+runtime signatures or docstrings to derive a schema from, so what you write is what the model sees.
+Pass `responseFormat` a Zod schema to structure the **final** answer (it applies after the loop —
+json-mode conflicts with the tool-calling turns).
+
+```ts
+const reply = await atrium.agent("what should I play for a storm scene?", {
+  tools: [
+    {
+      name: "search_library",
+      description: "Find sounds in the Atrium library.",
+      parameters: {
+        type: "object",
+        properties: { query: { type: "string" } },
+        required: ["query"],
+      },
+      execute: async ({ query }) => {
+        const hits = await atrium.library.search(String(query), { modality: "audio", limit: 3 })
+        return hits.map((h) => h.asset.title)
+      },
+    },
+  ],
+})
+```
+
+`parameters` is plain JSON Schema. To validate the model's arguments as well, pass
+`{ jsonSchema, validate }` where `validate` is any [Standard Schema](https://standardschema.dev)
+object (Zod ≥3.24, Valibot, ArkType): its parsed output is what `execute` receives. A *bare* schema
+object is rejected — deriving JSON Schema from it would mean depending on that library, and this
+package has no runtime dependencies.
+
+```ts
+import { z } from "zod"
+
+const city = z.object({ city: z.string() })
+const tool = {
+  name: "get_weather",
+  parameters: {
+    jsonSchema: { type: "object", properties: { city: { type: "string" } }, required: ["city"] },
+    validate: city,
+  },
+  execute: ({ city }) => forecastFor(String(city)),
+}
+```
+
+### Direct models
+
+Register a model name to route its `chat` / `agent` calls **straight** to an OpenAI-compatible
+endpoint — a local Ollama or LM Studio, or any remote server — instead of Atrium. A registered name
+shadows an Atrium model of the same name (that's the point), and only chat is intercepted:
+embeddings, search, sessions and rooms always go to Atrium.
+
+```ts
+atrium.addDirectModel("gemma3", { baseUrl: "http://localhost:11434/v1" })
+await atrium.chat("hi", { model: "gemma3" }) // → localhost, not Atrium
+
+await atrium.discoverModels("http://localhost:11434/v1") // what's installed? (registers nothing)
+```
+
+Direct calls carry **only** that endpoint's own key (or none) — your Atrium credential is never sent
+to a third-party endpoint. `discoverModels` is subject to browser CORS: a local server that sends no
+`Access-Control-Allow-Origin` blocks the read before the SDK sees it (that's the endpoint's policy to
+change, e.g. Ollama's `OLLAMA_ORIGINS`); from Node it just works.
+
 ## Quickstart (search + play)
 
 ```ts
@@ -166,11 +356,12 @@ room.audioSignals((sig) => {
 
 ## Player
 
-The `hci-atrium/player` subpath ships the audio-layers engine (`LayerEngine`) plus the `play` /
-`layer.*` dialect helpers that back the hosted [Player tool](../../tools) — named, independently
-mixed WebAudio layers (music/ambient/SFX) with crossfades, reverb/echo/distance effects, and 3D
-positioning. It's the code an embedding app drives from resolved room signals; it owns the per-layer
-WebAudio graph and nothing about React or transport.
+The `hci-atrium/player` subpath ships the audio-layers engine (`LayerEngine`), the headless
+[`PlayerRuntime`](#playerruntime), and the `play` / `layer.*` dialect helpers that back the hosted
+[Player tool](../../tools) — named, independently mixed WebAudio layers (music/ambient/SFX) with
+crossfades, reverb/echo/distance effects, and 3D positioning. It's the code an embedding app drives
+from resolved room signals; it owns the per-layer WebAudio graph and nothing about React or
+transport.
 
 ```ts
 import { LayerEngine } from "hci-atrium/player"
@@ -183,6 +374,52 @@ engine.enqueue("music", [{ url: trackUrl }], "now")
 See [`docs/reference/audio-layers-dialect.md`](../../docs/reference/audio-layers-dialect.md) for the
 full wire dialect.
 
+### PlayerRuntime
+
+`PlayerRuntime` is the headless Player — the dialect brain of the hosted tool, lifted out of its
+page. It owns the master chain (gain → limiter) *and* a `LayerEngine`, and dispatches the whole
+`play` / `layer.*` dialect: hand it room frames via `handleSignal(frame)` and give it a `send` sink
+for its outbound traffic (`layer.query` replies and `layer.state` broadcasts to `layer.subscribe`rs).
+It never opens a socket, touches the DOM, or imports React — transport, UI, and
+the intents it can't play itself (Spotify, "open link") stay with the host, the latter arriving
+through the `unhandled` hook.
+
+```ts
+import { joinRoom } from "hci-atrium"
+import { PlayerRuntime } from "hci-atrium/player"
+
+const baseUrl = "https://atrium.example.edu"
+const room = await joinRoom("ABC12345", { baseUrl })
+const context = new AudioContext() // create it on the user's Start gesture — autoplay policy
+
+const runtime = new PlayerRuntime({
+  context,
+  baseUrl, // asset-resolution root for the `asset_id`-only play shape
+  send: (type, payload, opts) => void room.send(type, payload as Record<string, unknown>, opts),
+  onLog: (line) => console.log(line),
+  onSnapshot: (layers) => renderLayers(layers), // engine snapshot → your UI
+})
+
+// Every inbound frame goes to the runtime; types outside the dialect fall through to `unhandled`.
+room.onAny((e) =>
+  runtime.handleSignal({
+    type: e.type,
+    payload: e.payload,
+    from: e.from ?? undefined,
+    ack_id: e.ackId ?? undefined,
+  }),
+)
+await room.connect()
+```
+
+`LayerEngine` is the mixer; `PlayerRuntime` is the mixer *plus* the dialect. It exposes
+`runtime.engine` for listener-side controls (per-layer / master volume, normalization, device-change
+resume) and `runtime.masterGain` as an analyzer tap (pre-limiter); `dispose()` tears down the engine,
+its timers, and the master chain it built, leaving the host's `AudioContext` alone. One caveat on the
+`send` sink: `Room.send` carries `to` and `ephemeral` but not `replyTo`, so a host that must answer a
+peer's `layer.query` builds the envelope itself — `buildSignalEnvelope` from the same subpath does
+exactly that for a `POST /v1/rooms/{id}/signal` transport, which is what the hosted Player runs on.
+
 ## Honest caveat: the guard is UX, not secrecy
 
 For a static single-page app the client-side guard is **user experience, not a security boundary**
@@ -199,3 +436,5 @@ pnpm build   # tsc → dist/ (.js + .d.ts)
 pnpm test    # vitest (mocked fetch, no live server)
 pnpm lint    # biome check
 ```
+
+Releases are published to npm by hand from the maintainer's account — there is no CI publish job.

package/dist/atrium.d.ts

@@ -1,15 +1,18 @@
 /** 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 type { OperandLike } from "./by.js";
+import { DirectEndpoint, type DirectEndpointInit } from "./direct.js";
 import { DEFAULT_BASE_URL } from "./env.js";
 import type { FileSource } from "./files.js";
 import type { Candidate } from "./models.js";
-import { type Asset, type AssetBinder, type AssetPage, type AssetRef, type AssetVector, type AssetVectorsOptions, type ChatReply, type CompareResult, type Filters, type IndexEntry, type SessionEvent as ReadSessionEvent, type SearchByExamplesHit, type SearchHit, type SegmentRef, type Session, type Event as SessionEvent, type SessionInfo, type SourceInfo, type SourceSearchResult, type Space, type TagDefinition, type Transcript } from "./models.js";
+import { type Asset, type AssetBinder, type AssetPage, type AssetRef, type AssetVector, type AssetVectorsOptions, type ChatReply, type CompareResult, type Filters, type IndexEntry, type ProjectFile, type SessionEvent as ReadSessionEvent, type SearchByExamplesHit, type SearchHit, type SegmentRef, type Session, type Event as SessionEvent, type SessionInfo, type SourceInfo, type SourceSearchResult, type Space, type Survey, type SurveyResponse, type SurveyTemplate, type TagDefinition, type Transcript } from "./models.js";
 import { type FetchImpl, Room, type RoomTransportMode, type WebSocketCtor } from "./rooms/index.js";
 import { type ChatMessage, type SessionExportFormat, type ShapedRequest, type ZodLike } from "./shaping/index.js";
 export type { SessionExportFormat } from "./shaping/rooms.js";
+import { type ToolDescriptor } from "./tools.js";
+import { type TraceSink } from "./trace.js";
 import { type AudioChunk, type TranscribeStreamOptions } from "./transcribe.js";
 export { DEFAULT_BASE_URL };
 export interface AtriumOptions {
@@ -27,6 +30,13 @@ export interface AtriumOptions {
     project?: string;
     /** Default collection scope applied to calls that don't pass their own ``collection``. */
     collection?: string;
+    /**
+     * Model names to route **straight** to an OpenAI-compatible endpoint instead of Atrium, e.g.
+     * ``{ gemma3: { baseUrl: "http://localhost:11434/v1" } }``. Only ``chat`` / ``agent`` consult this
+     * registry — embeddings and everything else always go to Atrium. See
+     * {@link Atrium.addDirectModel}.
+     */
+    directModels?: Record<string, DirectEndpoint | DirectEndpointInit>;
 }
 /** The internal transport the namespaces build on. */
 interface ClientInternal {
@@ -54,6 +64,11 @@ interface ClientInternal {
     readonly library: Library;
     /** The shared live-transcription engine — behind ``transcribeLive`` and a room's ``transcribe``. */
     transcribeStream(clips: AsyncIterable<AudioChunk>, opts: TranscribeStreamOptions): AsyncIterable<Transcript>;
+    /** The batch transcription route — a room's ``audioTranscripts`` degraded path POSTs each snippet. */
+    transcribe(audio: FileSource, opts?: TranscribeOptions): Promise<Transcript>;
+    /** Tracing sinks armed by ``room.trace()`` — every traced library/model call on this client mirrors
+     * into each. Empty (the fast path) until a room arms one. */
+    readonly traceSinks: TraceSink[];
 }
 /**
  * A client bound to one Atrium instance and one credential (an OAuth ``clientId`` or an ``apiKey``).
@@ -73,11 +88,18 @@ export declare class Atrium implements ClientInternal, AsyncDisposable {
     readonly sources: Sources;
     readonly sessions: Sessions;
     readonly rooms: Rooms;
+    readonly surveys: 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. */
+    readonly traceSinks: TraceSink[];
     private readonly apiKey;
     private readonly defaultProject;
     private readonly defaultCollection;
     private readonly lifecycle;
     private spacesPromise;
+    /** Model name → OpenAI-compatible endpoint; consulted by ``chat`` / ``agent`` only. */
+    private readonly direct;
     constructor(opts?: AtriumOptions);
     /**
      * ``fetch`` against this instance with the signed-in user's bearer token attached, silent refresh,
@@ -90,16 +112,95 @@ export declare class Atrium implements ClientInternal, AsyncDisposable {
     close(): Promise<void>;
     [Symbol.asyncDispose]: () => Promise<void>;
     /**
-     * Chat completion (``POST /v1/chat/completions``). Pass ``responseFormat`` a **Zod schema** for
-     * structured output: the reply is validated and the parsed value returned (with one repair turn,
-     * then {@link StructuredOutputError}). A raw ``responseFormat`` dict passes through as an OpenAI
-     * param. Streaming is a later pass.
+     * 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: string, endpoint: DirectEndpointInit): void;
+    /**
+     * 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: string[], endpoint: DirectEndpointInit): void;
+    /** Stop routing ``name`` directly — subsequent calls go to Atrium (idempotent). */
+    removeDirectModel(name: string): void;
+    /** A snapshot of the registered direct models: name → {@link DirectEndpoint}. */
+    listDirectModels(): Record<string, DirectEndpoint>;
+    /**
+     * 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.
+     */
+    discoverModels(baseUrl: string, opts?: {
+        apiKey?: string;
+        signal?: AbortSignal;
+    }): Promise<string[]>;
+    /** 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. */
+    private directSignal;
+    /** POST a chat body to a direct endpoint (raw ``fetch``, never the authed transport). */
+    private directChat;
+    /**
+     * Chat completion (``POST /v1/chat/completions``).
+     *
+     * Pass ``responseFormat`` a **Zod schema** for structured output: the reply is validated and the
+     * parsed value returned (with one repair turn, then {@link StructuredOutputError}). A raw
+     * ``responseFormat`` dict passes through as an OpenAI param. ``stream: true`` returns an
+     * ``AsyncIterable<string>`` of content deltas instead of a reply — ``for await`` over it (there is
+     * nothing to ``await`` first); it can't be combined with a schema ``responseFormat``.
+     *
+     * A ``model`` registered via {@link addDirectModel} is served directly by its endpoint,
+     * transparently: same return types and errors as the Atrium path.
      */
     chat<T>(messages: string | ChatMessage[], opts: ChatOptions & {
         responseFormat: ZodLike<T>;
     }): Promise<T>;
+    chat(messages: string | ChatMessage[], opts: ChatOptions & {
+        stream: true;
+    }): AsyncIterable<string>;
     chat(messages: string | ChatMessage[], opts?: ChatOptions): Promise<ChatReply>;
+    /** The chat body for one completion: the caller's passthrough params plus the SDK-owned keys. */
+    private chatParams;
+    private chatOnce;
+    /** 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``. */
+    private chatStream;
     private chatParse;
+    /**
+     * 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.
+     */
+    private parseOrRepair;
+    /**
+     * Run a tool-using agent loop: the model may call the given tools until it answers.
+     *
+     * Each tool is an explicit {@link ToolDescriptor} — ``{ name, description, parameters, execute }``
+     * (TypeScript has no runtime signature/docstring to derive a schema from, unlike Python's
+     * ``@client.tool``). The loop calls the model, runs any requested tool, feeds the result back, and
+     * repeats until the model returns a final message or ``maxTurns`` (default 6) is reached.
+     *
+     * ``responseFormat`` takes a **Zod schema** to structure the **final** answer (json-mode conflicts
+     * with the tool-calling turns, so it applies only after the loop ends): the answer is parsed and
+     * validated — with one repair turn, then {@link StructuredOutputError} — and the value returned.
+     * Any other option (``temperature``, ``strictParams``, …) is forwarded to every ``chat`` call.
+     */
+    agent<T>(prompt: string, opts: AgentOptions & {
+        responseFormat: ZodLike<T>;
+    }): Promise<T>;
+    agent(prompt: string, opts: AgentOptions): Promise<ChatReply>;
     /**
      * 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
@@ -340,9 +441,57 @@ export interface ChatOptions {
     model?: string;
     responseFormat?: ZodLike | Record<string, unknown>;
     strictParams?: boolean;
+    /** Return an ``AsyncIterable<string>`` of content deltas instead of a reply. */
+    stream?: boolean;
     signal?: AbortSignal;
     [key: string]: unknown;
 }
+export interface AgentOptions {
+    /** The tools the model may call this run (see {@link ToolDescriptor}). */
+    tools: ToolDescriptor[];
+    model?: string;
+    /** Cap on model turns before the loop gives up and returns the last reply (default 6). */
+    maxTurns?: number;
+    /** A **Zod schema** structuring the final answer (applied after the tool-calling turns). */
+    responseFormat?: ZodLike;
+    signal?: AbortSignal;
+    /** Extra OpenAI params (``temperature``, ``strictParams``, …) forwarded to every turn. */
+    [key: string]: unknown;
+}
+export interface SurveyStartOptions {
+    /** The session the survey is recorded on — a {@link Session} handle or its id. */
+    into: Session | string;
+    /** The data object's name (defaults to the template name, else ``"survey"``). */
+    name?: string;
+    /** A url the survey's end page can send the participant back to — an ``app``-controlled return
+     * button in the template resolves to it (the button's label stays template-controlled). */
+    returnTo?: string;
+    signal?: AbortSignal;
+}
+export interface SurveyTemplateOptions {
+    project?: string;
+    /** Make this the project's default template (the one ``start()`` picks with no template named). */
+    default?: boolean;
+    signal?: AbortSignal;
+}
+export interface SurveyResponsesOptions {
+    project?: string;
+    /** Filter by the response's session study phase (a string or list; ``""`` matches unset). */
+    phase?: string | string[];
+    /** Drop drafts, keeping only submitted responses. */
+    submittedOnly?: boolean;
+    /** Bound the newest-first result (server ceiling 500, default 200). */
+    limit?: number;
+    signal?: AbortSignal;
+}
+export interface SurveyUploadOptions {
+    project?: string;
+    /** The stored filename (defaults to a ``File``'s own name, else ``"upload"``). */
+    filename?: string;
+    /** The file's role in the project (default ``"attachment"``). */
+    role?: string;
+    signal?: AbortSignal;
+}
 export interface EmbedOptions {
     model: string;
     text?: string;
@@ -501,6 +650,70 @@ export declare class Sessions {
     /** Append a durable event to a session's log (``POST /v1/sessions/{id}/events``). */
     event(sessionId: string, type: string, opts?: SessionEventOptions): Promise<SessionEvent>;
 }
+/**
+ * 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 declare class Surveys {
+    private readonly c;
+    constructor(c: ClientInternal);
+    /** 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). */
+    private projectRef;
+    /**
+     * 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.
+     */
+    start(template: string | undefined, opts: SurveyStartOptions): Promise<Survey>;
+    /**
+     * 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.
+     */
+    template(name: string, body: unknown, opts?: SurveyTemplateOptions): Promise<{
+        name: string;
+        version: number;
+        isDefault: boolean;
+    }>;
+    /** List the project's survey templates (``GET …/survey-templates``). */
+    templates(opts?: {
+        project?: string;
+        signal?: AbortSignal;
+    }): Promise<SurveyTemplate[]>;
+    /**
+     * 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}.
+     */
+    responses(template: string, opts?: SurveyResponsesOptions): Promise<SurveyResponse[]>;
+    /**
+     * 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.
+     */
+    responsesCsv(template: string, opts?: SurveyResponsesOptions): Promise<Uint8Array>;
+    /**
+     * 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``.
+     */
+    uploadFile(file: FileSource, opts?: SurveyUploadOptions): Promise<ProjectFile>;
+}
 /** 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 declare class Rooms {