@happyvertical/smrt-chat 0.51.39 → 0.52.0

package/AGENTS.md

@@ -45,7 +45,7 @@ by the module-local `sendAgentReply` function.
 - **ChatParticipant**: `role` (owner/admin/member/viewer), `onlineStatus`, `lastReadMessageId`, `isMuted`. Tenant-scoped (required).
 - **ChatThread**: `rootMessageId`, `isResolved`, `messageCount`. Created via `ChatService.startThread()` (member-checked). Tenant-scoped (required).
 - **ChatReaction**: `messageId`, `profileId`, `emoji`. Added/removed via `ChatService.addReaction()`/`removeReaction()` (member-checked, self-keyed). Tenant-scoped (required).
-- **AgentSession**: `agentId` (application slug, string ref, not FK), `agentProfileId` (nullable `crossPackageRef` to `Profile` — the `bot` profile the agent AUTHORS as, #2995), `allowedTools` (JSON string array), `sessionContext` (JSON), `systemPrompt`, limits (`maxTokens`/`maxMessages`/`expiresAt`). Optional tenancy.
+- **AgentSession**: `agentId` (application slug, string ref, not FK), `agentProfileId` (nullable `crossPackageRef` to `Profile` — the `bot` profile the agent AUTHORS as, #2995), `allowedTools` (JSON string array), `sessionContext` (JSON, sensitive), `systemPrompt`, limits (`maxTokens`/`maxMessages`/`expiresAt`). Optional tenancy.
 - **VoiceSession**: short-lived voice-gateway binding over `(tenant, actorProfileId, personaId, room/thread/agentSession)` plus a persona snapshot, gateway `session_id`, expiry, replay tracking, and metadata. Tenant-scoped (required). Generated surface is read-only; creation and turns go through `createVoiceChatSession()` / `handleVoiceGatewayTurn()`.
 
 ## ChatService
@@ -102,7 +102,7 @@ bounded query results, and audit authority remain in the authenticated
 The `AgentSession` runtime depends on personas, agents, and users. Keep those
 edges acyclic: none of those packages may depend back on chat.
 
-- **`runToolLoop(options)`** (`tool-loop.ts`) — a bounded `tool_call → observe → respond` loop. Tools are **manifest operations** of installed packages: `buildManifestToolCatalog({ allowedTools })` reads the `PermissionCatalogService` catalog and keeps only the `(collection, action)` entries named in the persona's allow-list (the **offer gate**; absent/empty ⇒ NO tools). The loop runs inside one `executeAsPrincipal` context, and `invokeManifestTool` executes each op **in-process ("side door")** against `run.context.database` (the RLS tx when Postgres RLS is on), after re-asserting the fail-closed allow-list (`run.assertToolAllowed`) AND the catalog permission (`run.assertOperation`) — the **execution gate**. Bounded by a max-steps ceiling (`DEFAULT_MAX_STEPS = 8`): on the ceiling it disables tools for one final completion so the turn always terminates with text.
+- **`runToolLoop(options)`** (`tool-loop.ts`) — a bounded `tool_call → observe → respond` loop. Tools are **manifest operations** of installed packages: `buildManifestToolCatalog({ allowedTools })` reads the `PermissionCatalogService` catalog and keeps only the `(collection, action)` entries named in the persona's allow-list (the **offer gate**; absent/empty ⇒ NO tools). The loop runs inside one `executeAsPrincipal` context, and `invokeManifestTool` executes each op **in-process ("side door")** against `run.context.database` (the RLS tx when Postgres RLS is on), after re-asserting the fail-closed allow-list (`run.assertToolAllowed`) AND the catalog permission (`run.assertOperation`) — the **execution gate**. Bounded by a max-steps ceiling (`DEFAULT_MAX_STEPS = 8`): on the ceiling it disables tools for one final completion so the turn always terminates with text. A thrown tool error is classified (`classifyToolError`): permission denials and 401/403 are `not_permitted`; a `ValidationError` or 400/404/409/422 is `invalid_request` (observation: actionable message, `publicMessage` first, `code`, fix-and-retry hint); else (incl. 429) `execution_error`.
 - **`runPersonaConversationTurn(options)`** (`persona-conversation.ts`) — binds a conversation to an `AgentPersona`/`ResolvedPersona`: runs as its principal (`runAsUserId`), offers only its `allowedTools`, speaks its instructions (`resolvePersonaInstructions`, layering approved learned directives), and injects its **recalled learning memory** (`personaLearningMemory`, isolated per `memoryScope`) into the system prompt. `bindPersonaToSession()` mirrors the persona's `allowedTools`/instructions onto the `AgentSession` so the chat authoring gate agrees with the loop's offer gate. Authors the reply (and each executed tool) via the internal `sendAgentReply` bridge. Tools run with the run-as user's **live** permissions unless the host passes a `permissions` snapshot (#2978), which `runToolLoop` forwards to `executeAsPrincipal` so a narrowed principal (e.g. a shared station) cannot reach grants — such as `readPermission`-gated data-surface fields — beyond that snapshot, including through `agents.invoke` delegation (the snapshot becomes the worker's permission ceiling).
 - **Agent orchestration** (L3, #1892) — the loop accepts non-manifest **`extraTools`** (`PrincipalTool[]`, from `@happyvertical/smrt-agents`), gated by the *same* fail-closed allow-list. The standard **`invoke-agent`** tool (`createInvokeAgentTool`, slug `agents.invoke`) lets a conversational agent delegate to a **worker agent under its own principal** — the worker runs via `executeAsPrincipal` as the originating user (never its own authority), the principal is immutable along the chain, and its completion is surfaced back into the conversation. `runPersonaConversationTurn` filters `extraTools` by the persona's `allowedTools` (offer gate); the tool's `execute` re-asserts `assertToolAllowed` (execution gate). See `@happyvertical/smrt-agents` for the delegation envelope + transports.
 - **Chat feedback capture** (`chat-feedback.ts`) — `captureChatFeedback()` + `acceptAppliedChange`/`rejectAppliedChange`/`correctResponse`/`rateResponse`/`thumbsUp`/`thumbsDown` write a `Feedback` row (personas) carrying the conversation's **correlation-id**, and (by default) reinforce the persona's learning memory (`reinforceFromFeedback`). So an in-chat reject decays a strategy below the reuse floor and it stops being recalled; a correction supersedes its stored value.
@@ -123,6 +123,23 @@ The gateway bearer token proves only "this request came from the gateway"; it ne
 - **Persona path reuses the harness's own gates unchanged** — persona principal, fail-closed `allowedTools` offer+execution gates, tenant binding. `onToken` is best-effort telemetry threaded through `runToolLoop`; it never changes what the loop persists or authorizes.
 - **Custom tools stream via `binding.extraTools`** — the persona binding threads an optional `extraTools?: PrincipalTool[]` down to `runPersonaConversationTurn`, so a *streamed* persona chat can offer non-manifest, service-backed tools (the persona messaging tool `messages.send`, or an assistance-request/lead-ticket tool wrapping a `@smrt({ api:false, mcp:false })` service) and thus *act*, not only answer — matching the non-streaming persona path. It is resolved server-side by `authorize` (trusted), never from request input, and stays fully gated: each tool is filtered by the persona's `allowedTools` (offer gate) and re-asserts the bound principal's authority in `execute` (execution gate). Offering a tool is not authorizing it.
 
+## Streamed assistant turns with browser tools (#2908)
+
+`runAssistantTurn()` (`assistant-turn.ts`) is the host-route engine for the
+AssistantDock: one turn over `runToolLoop` with server tools (offer-gated by
+`principal.allowedTools`), browser tools (validated by
+`sanitizeClientToolDeclarations` + a server allow-list), `maxSteps`, `signal`,
+and `onUsage`. A browser tool call SUSPENDS the turn (`stoppedReason:
+'client_tools'`); the transcript waits in an `AssistantContinuationStore`
+(single-use, 15-minute TTL; `createSessionContinuationStore` keeps it in the
+AgentSession's `sessionContext`) and the browser resumes it with results,
+which reach the model wrapped `untrusted`. `createAssistantTurnResponse`
+serves the events as SSE; `assistant-turn-events.ts` is the browser-safe wire
+contract (`./assistant-turn` subpath, also a vite library entry because the
+Svelte dock imports it). The dock decides whether a browser call runs or waits
+for the user from the page registry, never the server's echo; destructive
+always waits. Details: [`docs/assistant-dock.md`](../../docs/assistant-dock.md).
+
 ## AssistantDock (#2904)
 
 `AssistantDock` (`svelte/components/assistant/`, exported from `./svelte`) is a

package/README.md

@@ -247,6 +247,19 @@ const dmRoom = await chat.getOrCreateDM({
 });
 ```
 
+### Assistant dock and supervised runs
+
+`AssistantDock` / `createAssistantDockController` (`@happyvertical/smrt-chat/svelte`)
+is an in-page assistant over a host transport; `runAssistantTurn` is its
+server engine (model tools, browser tools that suspend and resume, budgets
+`maxSteps` / `maxTurnTokens` / `maxTurnMs`). For "watch it work" hosts the
+controller keeps a supervised `run` (goal, current step, `running | paused |
+waiting | done | failed | cancelled`), with `pauseRun` / `continueRun`,
+`holdForUser` for choices the person makes, a `clientToolFilter`, and a
+`settle` hook so the step after a navigation sees the new page's tools.
+`matchesToolAllowList` is exported browser-safe. Full guide:
+[`docs/assistant-dock.md`](../../docs/assistant-dock.md).
+
 ## API
 
 ### Models

package/dist/assistant-turn-events.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Assistant turn wire contract (#2908): the events one streamed assistant
+ * turn emits, the small generic status a host shell can show while it runs,
+ * and the browser-side SSE reader.
+ *
+ * BROWSER-SAFE and dependency-free, like `client.ts`: the server engine
+ * (`assistant-turn.ts`) imports the types from here, and the AssistantDock
+ * (`svelte/components/assistant/`) imports the reader. Exported under
+ * `@happyvertical/smrt-chat/assistant-turn`.
+ *
+ *   Response: text/event-stream, one `data: <json>` line per event:
+ *     { "type": "status", "status": AssistantStatus }
+ *     { "type": "token", "text": "..." }                 (live preview only)
+ *     { "type": "step", "step": AssistantTurnStep }      ("calling X", "done")
+ *     { "type": "message", "message": {...} }            (a persisted message)
+ *     { "type": "client_tool_calls", "continuationId": "...", "calls": [...] }
+ *     { "type": "done", "message": {...}?, "stoppedReason": "..." }
+ *     { "type": "error", "error": "...", "code": "..." }
+ *   plus `: heartbeat` comment lines, which readers ignore.
+ *
+ * A turn ends with exactly one of `done`, `error`, or `client_tool_calls`.
+ * `client_tool_calls` suspends the turn: the browser runs the calls and
+ * resumes it with their results under `continuationId`.
+ */
+/** The coarse state a host shows ("working strip", status line). */
+export type AssistantStatusState = 'idle' | 'working' | 'done' | 'error';
+/**
+ * The generic assistant status: one plain-language line plus a state.
+ * Emitted by the server engine as `status` events and derived by the dock
+ * controller (`controller.status`, `onStatus`).
+ */
+export interface AssistantStatus {
+    state: AssistantStatusState;
+    /** Plain-language line ("Looking up articles…", "Done"), or null. */
+    label: string | null;
+    /** Changes the user applied during this piece of work (done state). */
+    changes?: number;
+    /** Whether the in-flight work can be stopped (`controller.cancel()`). */
+    cancellable?: boolean;
+}
+/** Where a tool ran. */
+export type AssistantToolLocation = 'server' | 'client';
+/** A browser tool's declared effect (mirrors smrt-web's `WebMcpToolEffect`). */
+export type AssistantToolEffect = 'read' | 'write' | 'destructive';
+/** One progress step of a turn. */
+export type AssistantTurnStep = {
+    kind: 'thinking';
+    step: number;
+} | {
+    kind: 'tool_call';
+    callId: string;
+    tool: string;
+    label: string;
+    location: AssistantToolLocation;
+} | {
+    kind: 'tool_result';
+    callId: string;
+    tool: string;
+    label: string;
+    ok: boolean;
+    error?: string;
+};
+/** A browser tool call the server suspended on. */
+export interface AssistantClientToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+    /** The effect the page declared; the dock re-reads it from its registry. */
+    effect: AssistantToolEffect;
+}
+/** A browser tool declaration sent with a turn (untrusted on the server). */
+export interface AssistantClientToolDeclaration {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    effect: AssistantToolEffect;
+}
+/** The browser's answer to one {@link AssistantClientToolCall}. */
+export interface AssistantClientToolResult {
+    id: string;
+    ok: boolean;
+    result?: string;
+    /** `declined` when the user said no; otherwise a short reason. */
+    error?: string;
+}
+/** Why a turn finished. */
+export type AssistantTurnStopReason = 'stop' | 'max_steps'
+/** The turn's token or time budget ran out (`maxTurnTokens`/`maxTurnMs`). */
+ | 'budget' | 'no_tools' | 'cancelled';
+/** One event of a streamed assistant turn. `M` is the host's message shape. */
+export type AssistantTurnEvent<M = Record<string, unknown>> = {
+    type: 'status';
+    status: AssistantStatus;
+} | {
+    type: 'token';
+    text: string;
+} | {
+    type: 'step';
+    step: AssistantTurnStep;
+} | {
+    type: 'message';
+    message: M;
+} | {
+    type: 'client_tool_calls';
+    continuationId: string;
+    calls: AssistantClientToolCall[];
+} | {
+    type: 'done';
+    message?: M;
+    stoppedReason: AssistantTurnStopReason;
+} | {
+    type: 'error';
+    /**
+     * A message safe to show the user: either a deliberate user-facing
+     * message or a generic one. Server detail is logged, never sent.
+     */
+    error: string;
+    /** A stable machine code (`internal_error` for an unexpected failure). */
+    code?: string;
+};
+/** Serialize one event as an SSE frame. */
+export declare function encodeAssistantTurnEvent(event: AssistantTurnEvent<unknown>): string;
+/** The outcome of reading one streamed turn. */
+export interface AssistantTurnStreamOutcome<M = Record<string, unknown>> {
+    /** Every persisted message the turn reported (tool results, the reply). */
+    messages: M[];
+    /** The terminal `done` event, when the turn finished. */
+    done?: Extract<AssistantTurnEvent<M>, {
+        type: 'done';
+    }>;
+    /** The suspension, when the turn is waiting on browser tools. */
+    clientToolCalls?: Extract<AssistantTurnEvent<M>, {
+        type: 'client_tool_calls';
+    }>;
+}
+/** Thrown by {@link readAssistantTurnStream} for an in-band `error` or a cut stream. */
+export declare class AssistantTurnStreamError extends Error {
+    constructor(message: string);
+}
+/**
+ * Read a streamed assistant turn from a `text/event-stream` response,
+ * reporting each event to `onEvent` as it arrives.
+ *
+ * Resolves once a terminal event (`done` or `client_tool_calls`) arrives;
+ * rejects with {@link AssistantTurnStreamError} on an in-band `error` or when
+ * the stream closes without a terminal event (an intermediary cut it).
+ * Tolerates heartbeat comments and frames split across chunks.
+ */
+export declare function readAssistantTurnStream<M = Record<string, unknown>>(response: Response, onEvent?: (event: AssistantTurnEvent<M>) => void): Promise<AssistantTurnStreamOutcome<M>>;
+/** Tool allow-list matching (browser-safe), re-exported for hosts. */
+export { matchesToolAllowList } from './tool-allow-list.js';
+//# sourceMappingURL=assistant-turn-events.d.ts.map

package/dist/assistant-turn-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-turn-events.d.ts","sourceRoot":"","sources":["../src/assistant-turn-events.ts"],"names":[],"mappings":"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"}

package/dist/assistant-turn-events.js

@@ -0,0 +1,2 @@
+import { i as matchesToolAllowList, n as encodeAssistantTurnEvent, r as readAssistantTurnStream, t as AssistantTurnStreamError } from "./chunks/assistant-turn-events-BbZUf-Ju.js";
+export { AssistantTurnStreamError, encodeAssistantTurnEvent, matchesToolAllowList, readAssistantTurnStream };

package/dist/assistant-turn.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Streamed assistant turn over the bounded tool loop (#2908).
+ *
+ * One call runs one assistant turn — model ↔ tools, up to `maxSteps` rounds —
+ * and yields {@link AssistantTurnEvent}s as it goes: a generic `status` line,
+ * `step`s ("calling X", "X done"), live `token` previews, each persisted
+ * `message`, and one terminal event. It is the engine behind an assistant
+ * dock's send route; the host owns authentication, tenancy, and persistence
+ * of the user message, and hands this module an already-authorized principal.
+ *
+ * Tools come from three places, all fail-closed:
+ *
+ * - **manifest tools** (`tools`) and **server tools** (`extraTools`, e.g.
+ *   `createDataSurfaceTools()`), run in-process by {@link runToolLoop} under
+ *   the principal. `extraTools` is narrowed to `principal.allowedTools` here
+ *   (the offer gate) and each tool re-asserts it (the execution gate).
+ * - **browser tools** (`clientTools`): the page's WebMCP tools and view
+ *   intents, declared by the browser. Validate and allow-list them with
+ *   {@link sanitizeClientToolDeclarations} first. The server never runs them:
+ *   when the model calls one, the turn SUSPENDS — the transcript is saved in
+ *   the host's {@link AssistantContinuationStore} and a `client_tool_calls`
+ *   event ends the stream. The browser runs the calls through its own
+ *   registry (reads run; writes and destructive calls wait for the user's
+ *   confirmation) and resumes the turn with `resume`. Results are fed back to
+ *   the model marked untrusted.
+ *
+ * Suspension instead of an open connection keeps a turn independent of which
+ * server replica receives the resume, and the `maxSteps` bound spans every
+ * leg of the turn.
+ *
+ * @module
+ */
+import type { AIInterface, AIMessage, ChatOptions } from '@happyvertical/ai';
+import type { PrincipalAuditSink, PrincipalBinding, PrincipalTool } from '@happyvertical/smrt-agents';
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
+import type { AssistantTurnEvent, AssistantTurnStopReason } from './assistant-turn-events.js';
+import type { AgentReplyService } from './services/ChatService.js';
+import { type ClientToolDefinition, type ClientToolResultInput, type ManifestTool, type PendingClientToolCall, type ToolInvocation, type ToolLoopResult, type ToolLoopUsage } from './tool-loop.js';
+/** How long a suspended turn waits for the browser's results. */
+export declare const DEFAULT_CONTINUATION_TTL_MS: number;
+/**
+ * A suspended turn: everything needed to resume it once the browser answers
+ * its tool calls. Serializable JSON, so a host can keep it anywhere.
+ */
+export interface AssistantTurnContinuation {
+    version: 1;
+    id: string;
+    /** `Date.now()` when it was saved. */
+    createdAt: number;
+    /** Tool rounds already used; the resumed leg continues the count. */
+    steps: number;
+    /** The loop transcript up to the suspension. */
+    messages: AIMessage[];
+    /** The browser calls the turn is waiting on. */
+    pending: PendingClientToolCall[];
+    /** The browser tools offered when it suspended. */
+    clientTools: ClientToolDefinition[];
+    /** Tokens the turn used so far (for `maxTurnTokens`). Absent: 0. */
+    tokens?: number;
+    /** `Date.now()` when the turn started (for `maxTurnMs`). Absent: `createdAt`. */
+    startedAt?: number;
+}
+/**
+ * Where suspended turns wait. `take` is single-use: it returns the
+ * continuation once and removes it, so a result can never be replayed into a
+ * turn twice. `key` scopes continuations (e.g. to one thread) — a resume
+ * under another key never finds them.
+ */
+export interface AssistantContinuationStore {
+    save(key: string, continuation: AssistantTurnContinuation): Promise<void>;
+    take(key: string, id: string): Promise<AssistantTurnContinuation | null>;
+}
+/** In-memory store, for tests and single-process demos. */
+export declare function createMemoryContinuationStore(options?: {
+    ttlMs?: number;
+    now?: () => number;
+}): AssistantContinuationStore;
+/** The slice of `AgentSession` {@link createSessionContinuationStore} uses. */
+export interface ContinuationSessionLike {
+    getSessionContext(): Record<string, unknown>;
+    updateSessionContext(updates: Record<string, unknown>): Promise<void>;
+}
+/** Reserved `AgentSession.sessionContext` field holding suspended turns. */
+export declare const SESSION_CONTINUATIONS_FIELD = "__assistantContinuations";
+/**
+ * A store kept in an `AgentSession`'s `sessionContext` (reserved field
+ * {@link SESSION_CONTINUATIONS_FIELD}), keyed by `key` — typically the thread
+ * id. Needs no schema: the session is already tenant-bound and
+ * participant-checked by the host that loaded it. Expired entries are pruned
+ * on every write.
+ *
+ * Pass a LOADER rather than a session instance whenever the turn also writes
+ * chat messages: authoring a reply updates the session row, so an instance
+ * loaded at the start of the request is stale by the time the turn suspends,
+ * and saving it fails its revision check. The loader is called before every
+ * read-modify-write so each one starts from the current row.
+ */
+export declare function createSessionContinuationStore(session: ContinuationSessionLike | (() => Promise<ContinuationSessionLike | null | undefined>), options?: {
+    ttlMs?: number;
+    now?: () => number;
+}): AssistantContinuationStore;
+/** A tool invocation the host wants persisted into the conversation. */
+export interface AuthoredToolReply {
+    content: string;
+    messageType?: 'tool_call' | 'tool_result' | 'text';
+    toolCallData?: Record<string, unknown> | null;
+}
+/** Where and how a turn persists its messages (the trusted agent bridge). */
+export interface AssistantTurnAuthor {
+    chatService: AgentReplyService;
+    agentSessionId: string;
+    tenantId: string;
+    threadId?: string | null;
+    /**
+     * Maps a server tool invocation to a persisted message, or `null` to keep
+     * it out of the conversation (the default for every invocation). The
+     * message's `toolCallData` tool name must be on the session's
+     * `allowedTools` — `sendAgentReply`'s gate is unchanged.
+     */
+    authorInvocation?: (invocation: ToolInvocation) => AuthoredToolReply | null;
+}
+/** Options for {@link runAssistantTurn}. */
+export interface AssistantTurnOptions<M = Record<string, unknown>> {
+    ai: AIInterface;
+    /** The already-authorized principal every server tool runs as. */
+    principal: PrincipalBinding;
+    db?: SmrtClassOptions['db'];
+    systemPrompt?: string;
+    /** Earlier turns, oldest first. Ignored on resume. */
+    history?: AIMessage[];
+    /** This turn's user message. Exactly one of `userMessage` / `resume`. */
+    userMessage?: string;
+    /** Resume a suspended turn with the browser's results. */
+    resume?: {
+        continuationId: string;
+        results: ClientToolResultInput[];
+    };
+    tools?: ManifestTool[];
+    /** Server tools, narrowed to `principal.allowedTools`. */
+    extraTools?: PrincipalTool[];
+    /** Validated, allow-listed browser tools (see `sanitizeClientToolDeclarations`). */
+    clientTools?: ClientToolDefinition[];
+    /** Required when `clientTools` are offered or `resume` is used. */
+    continuations?: AssistantContinuationStore;
+    /** Scope for `continuations` (e.g. the thread id). */
+    continuationKey?: string;
+    maxSteps?: number;
+    /**
+     * Token budget for the whole turn, across every browser round trip. Once
+     * spent, the model gets one last round without tools to answer, and the
+     * turn ends with `stoppedReason: 'budget'`. Unset: no budget.
+     */
+    maxTurnTokens?: number;
+    /**
+     * Wall-clock budget for the whole turn (ms from its first leg, including
+     * time spent waiting on the browser). Same ending as `maxTurnTokens`.
+     */
+    maxTurnMs?: number;
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    toolChoice?: ChatOptions['toolChoice'];
+    /** Cancels the turn (e.g. the request's own abort signal). */
+    signal?: AbortSignal;
+    /** Per-round token usage, for the host's usage attribution. */
+    onUsage?: (usage: ToolLoopUsage) => void;
+    permissions?: string[];
+    audit?: PrincipalAuditSink;
+    postgresRls?: boolean;
+    onBehalfOfUserId?: string | null;
+    agentClass?: string;
+    /** Persist tool results and the reply. Without it nothing is persisted. */
+    author?: AssistantTurnAuthor;
+    /** Maps a persisted chat message to the wire. Default: its `toJSON()`. */
+    serializeMessage?: (message: unknown) => M;
+    /**
+     * A plain-language label for a tool, used in steps and the status line.
+     * On a tool call it also gets the call's arguments, so a label can name
+     * the target ("Opening Events"); keep it free of ids and raw values.
+     */
+    describeTool?: (name: string, args?: Record<string, unknown>) => string;
+    /** Mint continuation ids (tests). Default `crypto.randomUUID()`. */
+    createId?: () => string;
+    /**
+     * Server-side log for an unexpected failure (default `console.error`). The
+     * browser only ever gets a generic message and code for these.
+     */
+    onError?: AssistantTurnErrorLogger;
+    now?: () => number;
+}
+/** What {@link runAssistantTurn} returns when its generator completes. */
+export interface AssistantTurnResult {
+    stoppedReason: AssistantTurnStopReason | 'client_tools' | 'error';
+    content: string;
+    loop?: ToolLoopResult;
+}
+/** What the browser is told when a turn fails unexpectedly. */
+export declare const ASSISTANT_TURN_GENERIC_ERROR = "The assistant ran into a problem. Please try again.";
+/**
+ * A failure whose message is deliberately written for the user (an expired
+ * step, an empty message). Only these reach the browser verbatim, with their
+ * `code`; every other error is replaced by {@link ASSISTANT_TURN_GENERIC_ERROR}
+ * and code `internal_error`, and its detail goes to the server-side log.
+ */
+export declare class AssistantTurnUserError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+/** Server-side sink for an unexpected turn failure. */
+export type AssistantTurnErrorLogger = (error: unknown) => void;
+/**
+ * Run one streamed assistant turn. Never throws: a failure is reported as an
+ * in-band `error` event (a streaming response has already committed its
+ * status by then). The generator's return value summarizes the turn.
+ */
+export declare function runAssistantTurn<M = Record<string, unknown>>(options: AssistantTurnOptions<M>): AsyncGenerator<AssistantTurnEvent<M>, AssistantTurnResult>;
+/** Default SSE keep-alive for {@link createAssistantTurnResponse}. */
+export declare const DEFAULT_ASSISTANT_TURN_HEARTBEAT_MS = 15000;
+/**
+ * Wrap a turn's events as a `text/event-stream` `Response`. Heartbeat
+ * comments keep idle intermediaries from cutting a quiet tool round; a
+ * client disconnect ends the generator (the turn still persists what it did).
+ *
+ * The body is pulled by the runtime after the handler returns, outside the
+ * handler's async context. Every `next()` therefore runs in the async context
+ * captured here (`AsyncLocalStorage.snapshot()`), so a turn started inside
+ * `withTenant(...)` keeps its tenant scope for every step, including the
+ * reply it persists at the end.
+ */
+export declare function createAssistantTurnResponse(events: AsyncGenerator<AssistantTurnEvent<unknown>, unknown>, options?: {
+    heartbeatMs?: number;
+    headers?: Record<string, string>;
+    /** Server-side log for a failure while pulling (default `console.error`). */
+    onError?: AssistantTurnErrorLogger;
+}): Response;
+//# sourceMappingURL=assistant-turn.d.ts.map

package/dist/assistant-turn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-turn.d.ts","sourceRoot":"","sources":["../src/assistant-turn.ts"],"names":[],"mappings":"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"}

package/dist/chunks/{ChatService-D48KBDZy.js → ChatService-jJi2JJJi.js}

@@ -162,7 +162,7 @@ __decorateClass$6([crossPackageRef("@happyvertical/smrt-profiles:Profile", { req
 __decorateClass$6([foreignKey("ChatRoom")], AgentSession.prototype, "chatRoomId", 2);
 __decorateClass$6([field({ required: true })], AgentSession.prototype, "status", 2);
 __decorateClass$6([field()], AgentSession.prototype, "allowedTools", 2);
-__decorateClass$6([field()], AgentSession.prototype, "sessionContext", 2);
+__decorateClass$6([field({ sensitive: true })], AgentSession.prototype, "sessionContext", 2);
 __decorateClass$6([field()], AgentSession.prototype, "systemPrompt", 2);
 __decorateClass$6([field()], AgentSession.prototype, "messageCount", 2);
 __decorateClass$6([field()], AgentSession.prototype, "totalTokensUsed", 2);
@@ -2017,4 +2017,4 @@ function sendAgentReply(service, params) {
 //#endregion
 export { VoiceSession as a, ChatReaction as c, AgentSession as d, VoiceSessionCollection as i, ChatParticipant as l, ChatService_exports as n, ChatThread as o, sendAgentReply as r, ChatRoom as s, ChatService as t, ChatMessage as u };
 
-//# sourceMappingURL=ChatService-D48KBDZy.js.map
+//# sourceMappingURL=ChatService-jJi2JJJi.js.map