@noodleseed/assistant 1.1.0 → 1.2.0

package/README.md

@@ -3,10 +3,11 @@
 Customer-branded embedded assistant surfaces for Noodle Seed deployments.
 
 The package exports the canonical `<noodle-assistant>` Web Component, a React wrapper from
-`@noodleseed/assistant/react`, and the backend-only `createAssistantSession` helper from
-`@noodleseed/assistant/server`. Light, dark, and automatic themes work without configuration; the component
-inherits the deployed MCP server's brand kit while slots, methods, events, and semantic CSS variables let a
-SaaS developer integrate it without depending on internal DOM selectors.
+`@noodleseed/assistant/react`, a DOM-free client from `@noodleseed/assistant/client`, and the backend-only
+`createAssistantSession` helper from `@noodleseed/assistant/server`. Light, dark, and automatic themes work
+without configuration; the component inherits the deployed MCP server's brand kit while slots, methods,
+events, and semantic CSS variables let a SaaS developer integrate it without depending on internal DOM
+selectors.
 
 Never pass an embed client secret, model key, MCP token, or raw application session into the browser
 component. Exchange the already-authenticated user from the customer backend and return only the short-lived
@@ -74,6 +75,7 @@ export async function POST(request: Request) {
     origin: process.env.PUBLIC_APP_ORIGIN!,
     user: { id: user.id, email: user.email, roles: user.roles },
     context,
+    preferences: { locale: user.locale, timeZone: user.timeZone },
   });
   return Response.json(session);
 }
@@ -97,6 +99,85 @@ import { NoodleAssistant } from '@noodleseed/assistant/react';
 <NoodleAssistant sessionEndpoint="/api/assistant/session" theme="auto" />;
 ```
 
+For a customer-owned renderer, subscribe to the same turn and interaction stream without registering a
+custom element or touching browser storage:
+
+```ts
+import { createAssistantClient } from '@noodleseed/assistant/client';
+
+const assistant = createAssistantClient({
+  sessionEndpoint: '/api/assistant/session',
+  clientContext: () => ({
+    locale: navigator.language,
+    timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+  }),
+});
+
+assistant.updateModelContext({
+  content: [{ type: 'text', text: 'The time-off form is mounted.' }],
+  structuredContent: { widget: { name: 'time-off', lifecycle: 'mounted' } },
+});
+
+const unsubscribe = assistant.subscribe((event) => {
+  renderAssistantEvent(event);
+  if (event.event === 'view_available') {
+    renderRegisteredView(event.data.resourceUri, event.data.result);
+  }
+});
+await assistant.sendMessage('Book next Thursday and Friday off');
+await assistant.respond('interaction_123', { action: 'accept' });
+// Resolve one interaction once; alternatives are { action: 'decline' } or { action: 'cancel' }.
+
+unsubscribe();
+```
+
+`clientContext` contains untrusted locale/timezone presentation hints and is evaluated for every turn.
+The client resolves a turn or interaction only after exactly one valid terminal `done` event followed by
+stream EOF. A truncated or malformed stream, duplicate `done`, or any frame after `done` is
+`invalid_response`; it never emits `message_completed` or `interaction_completed` for that response.
+`updateContext` remains the separate untrusted page-context channel used on the next session exchange.
+`updateModelContext({ content, structuredContent })` replaces the complete renderer snapshot attached to each
+later message turn without starting a turn itself; updates do not merge with prior fields. The same method is
+available on `<noodle-assistant>` for cohesive surface snapshots such as mounted, submitted, cancelled, or
+dismissed. Model context is untrusted, per-turn data: it is not conversation history or authorization input,
+and credential-shaped or unbounded updates are rejected.
+Backend `preferences` are the signed-in user's saved locale/time-zone choices and outrank those hints. Only
+message turns retry once after an expired session; the client never auto-retries interaction decisions. A
+`tool_proposed` event carries a complete schema-projected review of the tool input and collected answers. For
+a connector-backed tool it also identifies the exact connector version, operation, and resolved arguments;
+confirmable flows contain at most that one connector operation. Sensitive fields may be redacted, but any
+other truncation or omission fails closed. Accept is bound to that server-held action and claims one
+execution attempt; drift fails closed, while decline/cancel resolve without execution. Normal terminal
+outcomes scrub private arguments and continuations immediately. Only an accepted action still in the
+`executing` state retains them during its one-hour unknown-outcome recovery window; expiry records a bounded
+`interaction_outcome_unknown` result and scrubs the payload. Without downstream idempotency this is not an
+exactly-once business-effect guarantee. A caller may explicitly repeat the same id and decision to retrieve
+the durable stored outcome without another execution attempt.
+At the manifest/runtime boundary, only `confirm: true` enables this gate; omitted or `false` preserves direct
+execution and standard annotations remain hints. TypeScript action helpers likewise require
+`{ confirm: true }`; action/destructive/open-world hints alone never enforce approval. Capable bidirectional
+MCP transports render the same gate as standard form elicitation and fail closed when that exchange is
+unavailable.
+An `input_requested` event carries the message and portable form schema recorded by `ctx.elicit`. After the
+turn stream completes, a headless renderer answers it with
+`respond(id, { action: 'accept', content })`, or stops it with decline/cancel. The Web Component renders the
+same primitive as native controls. Accepted content is schema-validated before the runtime resumes, and the
+server-held continuation is never exposed to browser code. Schema-invalid content returns `arg_invalid` and
+leaves the same input interaction pending so the renderer can submit a corrected answer. Every interactive
+flow collects all elicited input before its first connector operation.
+
+A completed widget-linked tool emits typed `view_available` data with its call/interaction id, tool,
+`ui://` resource identity, optional title, and bounded/redacted public result. This is an availability
+signal, not proof of rendering. Map the identity to a component already trusted by your application; never
+fetch the `ui://` URI or inject its resource HTML into your page. The standard element does not render it,
+but forwards the same detail as a DOM event:
+
+```ts
+element.addEventListener('assistant-view-available', (event) => {
+  renderRegisteredView(event.detail.resourceUri, event.detail.result);
+});
+```
+
 Assistant text renders as provider deltas arrive. If a turn finds an expired session, the component calls
 the same authenticated session endpoint and retries that unprocessed message once. Confirmations never
 replay across sessions. React applications may observe recovery and structured failures:
@@ -110,7 +191,7 @@ replay across sessions. React applications may observe recovery and structured f
 ```
 
 `createAssistantSession` returns the opaque token, expiry, resolved non-secret configuration, and explicit
-`endpoints.turns` / `endpoints.toolConfirmations` URLs. Forward that response unchanged to the component.
+turn/interaction endpoint URLs. Forward that response unchanged to the component or headless client.
 
 The MCP server's top-level `branding` block provides the shared identity and theme for widgets and the
 assistant. Set semantic CSS variables only for application-level integration overrides:
@@ -128,5 +209,7 @@ radius, typography, and automatic theme. `embeddedAssistant(...)` controls float
 position and dimensions, mobile and launcher/header/avatar/timestamp behavior, visible labels, suggested
 prompts, privacy/terms links, locale, and text direction.
 Named slots cover launcher/header/composer/footer extensions. Public methods include `open`, `close`,
-`toggle`, `focusComposer`, `sendMessage`, `updateContext`, `confirmTool`, and `resetSession`; lifecycle,
-message, tool-proposal, completion, context, and error events support application integration.
+`toggle`, `focusComposer`, `sendMessage`, `updateContext`, `updateModelContext`, `respond`, `confirmTool`, and `resetSession`;
+lifecycle, message, tool-proposal, interaction-resolution, view-availability, context, and error events
+support application integration. `confirmTool(id)` remains the compatibility shorthand for
+`respond(id, { action: 'accept' })`.