@alquimia-ai/tools 2.5.0 → 2.7.0

package/README.md

@@ -1,44 +1,548 @@
 # @alquimia-ai/tools
 
-Tools for Alquimia SDK.
+The runtime half of the Alquimia frontend SDK. It turns the Alquimia Runtime's HTTP + SSE API into React state: a chat hook, a builder-style SDK class, URL adapters, a server-side proxy, a generative-UI protocol, and a normalized execution trace.
 
-## Table of Contents
+It ships no UI. Pair it with [`@alquimia-ai/ui`](../ui) for the component library, or wire its return values to your own components.
 
-- [Installation](#installation)
-- [Usage](#usage)
-- [Available Components](#available-components)
+- **Runtime compatibility:** Alquimia Runtime **v0.5.2** / alquimia-core **v0.5.3**
+- **Peer deps:** React ≥ 18. `next` ≥ 14 only if you use the Next.js helpers.
+
+---
+
+## Table of contents
+
+- [Install](#install)
+- [The mental model](#the-mental-model)
+- [Quick start](#quick-start)
+- [`useAlquimia`](#usealquimia)
+- [`AlquimiaSDK`](#alquimiasdk)
+- [Anatomy of a turn](#anatomy-of-a-turn)
+- [Version-pinned agents](#version-pinned-agents)
+- [Multimodal and audio input](#multimodal-and-audio-input)
+- [Attachments and blobs](#attachments-and-blobs)
+- [Client tools and GenUI](#client-tools-and-genui)
+- [Worklog](#worklog)
+- [Providers](#providers)
+- [Server proxy](#server-proxy)
+- [Distributed tracing](#distributed-tracing)
+- [Types](#types)
+- [Export map](#export-map)
 - [Development](#development)
-- [Contributing](#contributing)
-- [License](#license)
 
-## Installation
+---
 
-To install the `@alquimia-ai/tools` package, use the following command:
+## Install
 
 ```sh
-yarn add @alquimia-ai/tools
+npm install @alquimia-ai/tools
 ```
 
-Or with npm:
+Environment variables live on the **server**, never in the browser:
 
-```sh
-npm install @alquimia-ai/tools
+```bash
+ASSISTANT_BASEURL=https://your-runtime.example.com
+ALQUIMIA_ASSISTANT_API_KEY=your-secret-key
+```
+
+---
+
+## The mental model
+
+Two pieces decide where every request goes and who holds the credentials.
+
+**The adapter** resolves URLs on the client. It never adds an `Authorization` header.
+
+**The proxy** runs on your server, injects the API key, and forwards to the runtime.
+
+```
+browser                          your server                    alquimia runtime
+───────                          ───────────                    ────────────────
+useAlquimia / AlquimiaSDK
+  └─ adapter.resolveInferUrl() ──→ handleInfer ────────────────→ POST /event/infer/{assistantId}
+  └─ adapter.resolveStreamUrl() ─→ handleStream ───────────────→ GET  /event/stream/{taskId}
+  └─ adapter.resolveBlobUploadUrl() → handleBlobUpload ────────→ POST /context/blob/upload
+  └─ adapter.resolveToolCompletionUrl() → handleToolCompletion → POST /event/tool-completion
+                                   ↑
+                          Authorization: Bearer <apiKey>
+```
+
+The proxy exists for two reasons. The obvious one is that the API key must not reach the browser. The load-bearing one is that the stream leg uses `EventSource`, and **`EventSource` cannot set request headers** — so `getHeaders()` is honoured on infer, blob upload and tool-completion (all axios POSTs) and silently ignored on the stream. If your runtime or its gateway requires auth on every request, a server hop on the stream is not optional.
+
+Three supported topologies:
+
+| Topology | Adapter | Server side |
+|---|---|---|
+| Next.js App Router | `createNextJsAdapter()` | `createNextJsRouteHandlers()` |
+| SPA + your own server (Express/Hono/Fastify/Bun/Deno) | `createFetchAdapter({ baseUrl })` | `createAlquimiaProxyHandler()` |
+| SPA, no server | custom `AlquimiaAdapter` | a ~30-line proxy for the stream leg only |
+
+---
+
+## Quick start
+
+### Next.js App Router
+
+Four route files, five lines each:
+
+```ts
+// app/api/chat/[...path]/route.ts
+import { createNextJsRouteHandlers } from '@alquimia-ai/tools/next';
+
+const handlers = createNextJsRouteHandlers({
+  assistantBaseUrl: process.env.ASSISTANT_BASEURL!,
+  apiKey: process.env.ALQUIMIA_ASSISTANT_API_KEY!,
+});
+
+export const POST = handlers.handleInfer;
+```
+
+```ts
+// app/api/stream/[...path]/route.ts  → export const GET = handlers.handleStream;
+// app/api/blob/upload/route.ts       → export const POST = handlers.handleBlobUpload;
+// app/api/tool-completion/route.ts   → export const POST = handlers.handleToolCompletion;
+```
+
+The last two take no `[...path]` segment: identity travels in headers, and the pending tool call is correlated by `control_id` in the body.
+
+```tsx
+'use client';
+import { useAlquimia } from '@alquimia-ai/tools/hooks';
+import { createNextJsAdapter } from '@alquimia-ai/tools/adapters/next';
+
+const adapter = createNextJsAdapter();
+
+export function Chat({ assistantId }: { assistantId: string }) {
+  const alquimia = useAlquimia({ assistantId, adapter });
+
+  return (
+    <form onSubmit={(e) => alquimia.handleSubmit(e)}>
+      {alquimia.messages.map((m) => <p key={m.id}>{m.content}</p>)}
+      <input value={alquimia.input} onChange={alquimia.handleInputChange} />
+    </form>
+  );
+}
+```
+
+### Any server
+
+```ts
+import { createAlquimiaProxyHandler } from '@alquimia-ai/tools/proxy';
+
+const handler = createAlquimiaProxyHandler({
+  assistantBaseUrl: process.env.ASSISTANT_BASEURL!,
+  apiKey: process.env.ALQUIMIA_ASSISTANT_API_KEY!,
+});
+
+// Hono
+app.post('/chat/:path{.+}', (c) => handler.handleInfer(c.req.raw, c.req.param('path')));
+app.get('/stream/:path{.+}', (c) => handler.handleStream(c.req.raw, c.req.param('path')));
+app.post('/blob/upload', (c) => handler.handleBlobUpload(c.req.raw));
+app.post('/tool-completion', (c) => handler.handleToolCompletion(c.req.raw));
+```
+
+The handlers speak the Web Fetch API (`Request` → `Response`), so any modern runtime works.
+
+```ts
+import { createFetchAdapter } from '@alquimia-ai/tools/adapters/fetch';
+const adapter = createFetchAdapter({ baseUrl: 'https://my-api.example.com' });
+```
+
+### Custom adapter
+
+Implement the interface directly to split legs across hosts:
+
+```ts
+import type { AlquimiaAdapter } from '@alquimia-ai/tools/adapters';
+
+const adapter: AlquimiaAdapter = {
+  resolveInferUrl: (assistantId) => `${BACKEND}/event/infer/${assistantId}`,
+  resolveStreamUrl: (taskId) => `${STREAM_PROXY}/event/stream/${taskId}`,
+  resolveBlobUploadUrl: () => `${BACKEND}/context/blob/upload`,
+  resolveToolCompletionUrl: () => `${BACKEND}/event/tool-completion`,
+  getHeaders: () => ({ Authorization: `Bearer ${API_KEY}` }),
+};
+```
+
+`busMode: true` on either built-in adapter appends `?bus_mode=true` to the stream URL, which makes the runtime emit granular worklog frames instead of only assistant deltas.
+
+---
+
+## `useAlquimia`
+
+One hook owns the whole chat: message list, input, streaming flags, attachments, audio state, worklog, and the GenUI loop.
+
+```ts
+const alquimia = useAlquimia({
+  assistantId: 'support-agent',   // required
+  adapter,                        // required
+  providers: {                    // all optional
+    whisper, stableDiffusion, characterization, ratings, logger,
+  },
+  options: {
+    enforceCharacterization: false,
+    userId: user?.email,
+    extraInstructions: { tone: 'formal' },  // injected as runtime prompt clauses
+    worklog: true,                           // build the execution trace
+  },
+  genui: {
+    catalog: coreCatalog,        // default: the built-in ~40-component catalog
+    allow: 'all',                // or an explicit component allowlist
+    source: 'agent',             // 'agent' | 'client'
+  },
+});
+```
+
+### What it returns
+
+**Messages and input**
+
+| Key | Type | Notes |
+|---|---|---|
+| `messages` | `AlquimiaMessage[]` | full conversation |
+| `cleanMessages` | `AlquimiaMessage[]` | without system/internal entries |
+| `input` | `string` | controlled input value |
+| `handleInputChange` | `(e) => void` | textarea change handler |
+| `handleReplaceInput` | `(text: string) => void` | used by speech-to-text |
+| `populateMessages` | `(messages) => void` | hydrate from history |
+| `createMessageId` | `() => string` | id helper |
+
+**Sending**
+
+| Key | Notes |
+|---|---|
+| `handleSubmit(event, traceParentId?, sessionId?, additionalInfo?)` | the normal path |
+| `sendMessage` | lower-level send |
+| `handleSystemMessage(text, opts)` | inject a system turn |
+| `handleLoadingCancel()` | abort an in-flight turn and close the stream |
+| `lastRequest` / `setLastRequest` | for retry UX |
+
+**Status flags**
+
+`isLoading`, `isMessageLoading`, `isMessageStreaming`, `isStreamingLoading`, `streamingMessageId`, `hasThinkings`, `isUploadingAttachments`.
+
+**Attachments**
+
+`attachments`, `addAttachment`, `addAttachments`, `removeAttachment`, `clearAttachments`.
+
+**Audio**
+
+`isAudioRecording`, `setIsAudioRecording`.
+
+**Tools and GenUI**
+
+`activeTool`, `setActiveTool`, `pendingClientTool`, `completeToolExecution`, `genui`.
+
+**Trace**
+
+`worklog` — a `WorklogState`, or `undefined` unless `options.worklog` is on.
+
+**Escape hatch**
+
+`sdk` — the underlying `AlquimiaSDK` instance.
+
+---
+
+## `AlquimiaSDK`
+
+A builder. Every `with*` returns `this`, so configuration chains; the getters read back what the runtime resolved.
+
+```ts
+import { AlquimiaSDK } from '@alquimia-ai/tools/sdk';
+
+const sdk = new AlquimiaSDK('support-agent', adapter)
+  .withConversationId(conversationId)
+  .withUserId('user-42')
+  .withExtraInstructions({ tone: 'formal' });
+
+await sdk.sendMessage('hello');
+const streamUrl = sdk.getUrlStream();
+```
+
+### Configuration
+
+| Method | Purpose |
+|---|---|
+| `withConversationId(id)` | **required before `sendMessage`** — the runtime `session_id` |
+| `withUserId(id)` | `user_id` on the payload and the `user-id` header |
+| `withExtraInstructions(record)` | `extra_instructions` — prompt clauses merged by the runtime |
+| `withAssistantConfig(config)` | full `AssistantConfig` override for the turn |
+| `withTools(schemas)` | client-side tool schemas — sent as a `native` evaluation strategy |
+| `withAttachments(payloads)` | attachment metadata for the next turn |
+| `withVersionTag(tag)` | pin a registry version (see below) |
+| `withWhisperProvider` / `withStableDiffusionProvider` / `withAnalyzeCharacterizationProvider` / `withRatingsProvider` / `withLoggerProvider` | inject optional providers |
+
+### Turn
+
+| Method | Purpose |
+|---|---|
+| `sendMessage(query?, options?)` | POST infer. `options` is `{ traceParent?, inputAudio?, outputAudio? }`, or a bare traceparent string for backwards compatibility |
+| `getUrlStream()` | SSE URL for the task, with the traceparent appended as a query param |
+| `getStreamId()` / `getTaskId()` | the runtime `taskid` |
+| `getVersionTag()` | the registry version the runtime resolved |
+| `submitToolResult(response)` | POST tool-completion for a pending client tool |
+
+### Side channels
+
+| Method | Requires |
+|---|---|
+| `uploadAttachment(file)` → `RuntimeBlob` | — |
+| `getAttachmentResponses()` | — |
+| `textToSpeech(text)` / `speechToText(audio)` | a whisper provider |
+| `generateImage(query)` | a stable-diffusion provider |
+| `analyzeCharacterization(text)` | a characterization provider |
+| `rate(data)` | a ratings provider |
+| `logInfo` / `logError` | a logger provider |
+
+---
+
+## Anatomy of a turn
+
+```
+1. POST /event/infer/{assistantId}
+     body    { query, session_id, user_id, ... }
+     headers assistant-id, session-id, user-id, task-id, x-trace-parent
+     →       CommonAttributes { taskid, versiontag, attachments }
+
+2. GET /event/stream/{taskid}          (EventSource)
+     ← assistant deltas, thinkings, tool events
+     ← granular worklog frames when bus_mode=true
+
+3. POST /event/tool-completion          (only if the agent called a client tool)
+     body    ToolExecutionResponse { control_id, tool_name, status, result }
+     headers taskid, sessionid, userid, assistantid, versiontag
+     → the run resumes on the same stream
+```
+
+Step 3 is what makes client tools and GenUI work: the runtime parks the task, the browser answers, the run continues. The correlation headers are not decoration — the runtime looks the parked task up by them, and rejects a completion whose `control_id` it is not awaiting with a `409`.
+
+---
+
+## Version-pinned agents
+
+The runtime keeps cached registry versions of an agentspace. Two ways to target one:
+
+**A versioned assistant ref**, which works on every runtime version:
+
+```ts
+const sdk = new AlquimiaSDK('prod/support-agent:v1.2', adapter);
+```
+
+The runtime parses `<agentspace>/<assistant>[:<tag>]` out of the path itself.
+
+**`withVersionTag()`**, which sends `?version_tag=` on infer and needs **runtime ≥ 0.5.2** — older runtimes ignore the parameter:
+
+```ts
+sdk.withVersionTag('v1.2');
+```
+
+Either way, the runtime answers with the version it actually resolved in `CommonAttributes.versiontag`. The SDK stores it and echoes it as the `versiontag` header on tool-completion, so both halves of a turn land on the same snapshot even when "latest" moves underneath a live conversation. Read it with `getVersionTag()`.
+
+The tag is a header **only** on tool-completion and tool-approval, where the runtime binds it through a `CommonAttributes` header model. On infer it is a query parameter. Sending it as a header there does nothing.
+
+---
+
+## Multimodal and audio input
+
+`query` accepts the runtime's full `Content` shape — plain text, or an OpenAI-style list of content parts:
+
+```ts
+await sdk.sendMessage([
+  { type: 'text', text: 'what is in this picture?' },
+  { type: 'image_url', image_url: { url: imageUrl, detail: 'low' } },
+]);
+```
+
+Audio input is a two-step flow, because `input_audio` is a **blob reference**, not raw bytes:
+
+```ts
+const blob = await sdk.uploadAttachment(audioFile);   // POST /context/blob/upload → RuntimeBlob
+await sdk.sendMessage(undefined, { inputAudio: blob }); // audio-only turn
+```
+
+`query` is optional when audio is supplied, and both can be sent together. A turn with neither throws before any request is made.
+
+Audio **output** is on by default server-side for an agent with a TTS adapter. To force a text-only reply:
+
+```ts
+await sdk.sendMessage('hello', { outputAudio: false });
+```
+
+The field is only sent when you set it, so leaving it alone preserves the runtime's own default.
+
+---
+
+## Attachments and blobs
+
+```ts
+const blob = await sdk.uploadAttachment(file);
+// { blob_id, filename, content_size, content_type, checksum, ... }
+```
+
+Identity travels in kebab-case headers (`assistant-id`, `session-id`, `user-id`, `task-id`), which the proxy forwards; the path carries nothing. The infer response echoes the blob ids the runtime associated with the turn — read them with `getAttachmentResponses()`.
+
+Through the hook, `addAttachments(files)` queues them and they upload automatically after the turn's infer call resolves.
+
+---
+
+## Client tools and GenUI
+
+A client tool is a tool the **browser** executes. The agent calls it, the runtime parks the task, the SDK surfaces it as `pendingClientTool`, and `completeToolExecution` posts the result back.
+
+GenUI is that mechanism with one specific tool, `render_ui`, whose arguments are a declarative component tree. The agent never emits markup — only component names and props from a catalog you authorize.
+
+```ts
+const alquimia = useAlquimia({
+  assistantId, adapter,
+  genui: { allow: ['Stack', 'TextField', 'Button'] },
+});
 ```
 
-## Runtime compatibility
+The `/genui` module holds the protocol, independent of any renderer:
+
+| Export | Purpose |
+|---|---|
+| `coreCatalog`, `CORE_CATALOG_ID` | the default ~40-component catalog with Zod prop schemas |
+| `coreCatalogJson` | the published A2UI catalog artifact, as a value |
+| `buildRenderUiSchema(manifest, allow)` | the JSON-schema the agent sees |
+| `buildGenuiClause(manifest, allow)` | the prompt clause describing the catalog |
+| `validateSurface(input, manifest)` | validates an agent-authored tree before render |
+| `validateProps(node, def)` | per-component prop validation |
+| `resolveDynamic`, `getPointer`, `setPointer`, `isPathRef` | data-binding against the surface's data model |
+| `classifyAction`, `assertSafeActionName` | agent-bound vs local action handling |
+| `buildSurfaceResult`, `buildDismissResult` | the payloads posted back on submit or dismiss |
+| `emitA2uiCatalog` | export a manifest as an A2UI catalog artifact |
 
-This release targets **Alquimia Runtime v0.5.0**. The proxy and adapters route to the `/event/*` and `/worklog/*` endpoints introduced in that version, and the SDK exposes the matching request/response types.
+Components come from `@alquimia-ai/ui/components/genui` (`A2uiRenderer`, `coreUiRegistry`, `AssistantChat`), or from your own registry — pass your catalog to the hook and your components to the renderer, and the same agent composes your design system.
 
-## Available Features
+---
 
-- **Context**: Session and user context.
-- **Hooks**: Main hook that applies the SDK and most important chat behaviour.
-- **SDK Class and providers**: Main SDK class with its providers.
-- **Worklog**: Runtime worklog reducer, SSE frame normalization, and audit API types.
-- **Runtime event types**: TypeScript schemas for the `/event/*` payloads.
+## Worklog
 
+The worklog is the agent's execution trace, normalized into a tree you can render as "show your work".
 
-## License
+```ts
+const alquimia = useAlquimia({ assistantId, adapter, options: { worklog: true } });
+alquimia.worklog?.nodes;   // WorklogNode[]
+alquimia.worklog?.status;  // 'idle' | 'running' | 'success' | 'error'
+alquimia.worklog?.answer;
+```
 
-This project is licensed under the MIT License. See the LICENSE file for more details.
+Each runtime event class maps to an interpreter that says which bucket it belongs to (`NodeKind`) and whether it opens or closes a node. Commands and responses are merged by `control_id`.
+
+| Bucket | Event classes |
+|---|---|
+| `answer` | `AssistantInference(+Response)` — the run envelope |
+| `safeguard` | `ShieldInference(+Response)`, `ShieldBlockedResponse` |
+| `reasoning` | `ResponseInference(+Response)` |
+| `tool` | `ServerToolExecution`, `BuiltinToolExecution`, `ClientToolExecution`, `UnknownToolExecution`, `ToolSchema`, `HumanApprovalRequired`, and their responses |
+| `a2a` | `A2AInference`, `AgentDiscovery(+Response)` |
+| `memory` | `ContextPersistence`, `ContextFlush(+Response)` |
+| `knowledge` | `KnowledgeRetrieval(+Response)` |
+| `speech` | `SpeechTranscription(+Response)`, `SpeechSynthesis(+Response)` |
+| `unknown` | anything unregistered — rendered by class name rather than dropped |
+
+Standalone API, usable without the chat hook:
+
+```ts
+import { foldWorklog, reduceWorklog, frameToRecord, useWorklog } from '@alquimia-ai/tools/worklog';
+
+const state = foldWorklog(records);           // fold a full history
+const next = reduceWorklog(state, record);    // fold one frame at a time
+const record = frameToRecord(sseFrame);       // normalize a raw SSE frame
+```
+
+The module also types the runtime's worklog REST API — `WorklogSummary`, `WorklogDetail`, `WorklogEventDetail`, `WorklogPage`, `WorklogEventPage`, `WorklogVerificationResult` — for reading `/worklog/*` from a backend. Those endpoints are audit surface; this package does not call them.
+
+---
+
+## Providers
+
+Providers are abstract classes with swappable implementations, so the app picks its vendor without the SDK depending on one.
+
+| Abstract | Implementations |
+|---|---|
+| `WhisperProvider` (TTS + STT) | `AlquimiaWhisperProvider`, `OpenAIWhisperProvider`, `ElevenLabsWhisperProvider`, `OrpheusWhisperProvider` |
+| `StableDiffusionProvider` | `OpenAIStableDiffusionProvider`, `StabilityProvider` |
+| `CharacterizationProvider` | `OpenAIAnalyzeCharProvider` |
+| `RatingsProvider` | `AlquimiaRatingsProvider` |
+| `LoggerProvider` | `ElasticLoggerProvider` (`@alquimia-ai/tools/providers/elastic`) |
+
+These are **client-side integrations**, separate from the runtime's own audio pipeline. An agent configured with a runtime STT/TTS adapter transcribes and synthesizes server-side — that path is `input_audio` / `output_audio` on infer, not a provider.
+
+---
+
+## Server proxy
+
+```ts
+createAlquimiaProxyHandler({
+  assistantBaseUrl,                          // required
+  apiKey,                                    // required
+  inferRoute: 'event/infer',                 // defaults shown
+  streamRoute: 'event/stream',
+  blobUploadRoute: 'context/blob/upload',
+  toolCompletionRoute: 'event/tool-completion',
+})
+```
+
+Returns `handleInfer`, `handleStream`, `handleBlobUpload`, `handleToolCompletion`.
+
+What it does beyond adding the bearer token:
+
+- Forwards identity headers on infer/stream/blob upload: `session-id`, `user-id`, `assistant-id`, `task-id`, `parent-task-id`, `agentspace-id`, `channel-id`, `depth`.
+- Forwards correlation headers on tool-completion: `taskid`, `sessionid`, `userid`, `assistantid`, `parenttaskid`, `agentspaceid`, `channelid`, `depth`, `versiontag`.
+- Preserves the infer query string, so `?version_tag=` and `?agentspace_id=` survive the hop.
+- Streams the SSE body through untouched.
+- Turns the stream's `?trace_parent=` query param back into an `x-trace-parent` header, and does not pass the param upstream.
+
+---
+
+## Distributed tracing
+
+Infer and stream are two HTTP calls that must land in **one** trace, and `EventSource` cannot set headers. So the SDK sends `x-trace-parent` on infer, remembers the traceparent for the turn, and appends it to the stream URL as `?trace_parent=`; the proxy converts it back to a header and strips the param. When a turn has no trace context, the header is omitted entirely rather than sent empty.
+
+`@alquimia-ai/tools/services` exposes the Elastic APM RUM integration, and `handleApmRequest` in `/actions` proxies the APM ingest endpoint.
+
+---
+
+## Types
+
+`@alquimia-ai/tools/types` covers both the wire and the view model.
+
+**Wire:** `CommonAttributes` (with `versiontag`), `InferInitResponse`, `Content` / `ContentPart` / `TextContentPart` / `ImageContentPart` / `NonStandardContentPart`, `RuntimeBlob`, `AttachmentPayload`, `NativeToolsEvaluationStrategy`, `RuntimeEvent` and the `/event/*` payload union, `TTSResult`, `RatingData`.
+
+**View:** `AlquimiaMessage`, `AlquimiaEventData`, `AIMessageChunk`, `AssistantInferenceResponse`, `ToolEvent`, `Tooler`, `ThinkingsInferenceResponse`, `GenuiSurfaceItem`, `ActionResponse`.
+
+---
+
+## Export map
+
+| Entry | Contents |
+|---|---|
+| `/adapters` | `AlquimiaAdapter`, `AlquimiaSDKOptions` |
+| `/adapters/next` | `createNextJsAdapter` |
+| `/adapters/fetch` | `createFetchAdapter` |
+| `/sdk` | `AlquimiaSDK` |
+| `/hooks` | `useAlquimia`, `useRatings` |
+| `/proxy` | `createAlquimiaProxyHandler`, `ProxyConfig` |
+| `/next` | `createNextJsRouteHandlers`, `handleChatRequest`, `handleStreamRequest`, `initConversation` |
+| `/providers` | provider base classes and implementations |
+| `/providers/elastic` | `ElasticLoggerProvider` |
+| `/genui` | the GenUI protocol |
+| `/worklog` | reducer, registry, types, `useWorklog` |
+| `/actions` | `initConversation`, CRUD helpers, `handleApmRequest` |
+| `/services` | Elastic APM RUM |
+| `/types` | wire + view types |
+| `/utils` | header/cookie/formatting helpers |
+
+---
+
+## Development
+
+```sh
+yarn test          # vitest
+yarn lint          # eslint --max-warnings 0
+yarn build         # tsup
+yarn genui:catalog # regenerate the published A2UI catalog artifact
+```
 
+Changes to published behaviour need a changeset — see [`docs/how-to-use-changeset.md`](../../docs/how-to-use-changeset.md).

package/dist/actions/index.d.mts

@@ -1,4 +1,4 @@
-import { B as BaseAPIConfig } from '../type-DqX3-9QS.mjs';
+import { B as BaseAPIConfig } from '../type-61gaZga-.mjs';
 export { i as initConversation } from '../session.action-DirvOWt0.mjs';
 import '@elastic/apm-rum';
 import 'ai';

package/dist/actions/index.d.ts

@@ -1,4 +1,4 @@
-import { B as BaseAPIConfig } from '../type-xksRnBUW.js';
+import { B as BaseAPIConfig } from '../type-D-JaSMkV.js';
 export { i as initConversation } from '../session.action-DirvOWt0.js';
 import '@elastic/apm-rum';
 import 'ai';

package/dist/hooks/index.d.mts

@@ -1,10 +1,10 @@
 import * as react from 'react';
 import { AlquimiaSDK } from '../sdk/index.mjs';
 import { AlquimiaAdapter } from '../adapters/index.mjs';
-import { W as WhisperProvider, S as StableDiffusionProvider, C as CharacterizationProvider, R as RatingsProvider, L as LoggerProvider } from '../providers-DiR9cgyo.mjs';
-import { G as GenuiSurfaceItem, e as AlquimiaMessage, u as ToolEvent, a as AIMessageChunk, R as RatingData } from '../type-DqX3-9QS.mjs';
+import { W as WhisperProvider, S as StableDiffusionProvider, C as CharacterizationProvider, R as RatingsProvider, L as LoggerProvider } from '../providers-B4IOiGfr.mjs';
+import { G as GenuiSurfaceItem, e as AlquimiaMessage, F as ToolEvent, a as AIMessageChunk, R as RatingData } from '../type-61gaZga-.mjs';
 import { T as ToolExecutionResponse } from '../types-CMVbyEv8.mjs';
-import { a as WorklogState } from '../types-C-6fgK1_.mjs';
+import { a as WorklogState } from '../types-lOliroPw.mjs';
 import { createMessageId } from '../utils/index.mjs';
 import { C as CatalogManifest } from '../registry-Bcu_ZYL1.mjs';
 import { U as UIAction } from '../actions-BjDPJdyA.mjs';

package/dist/hooks/index.d.ts

@@ -1,10 +1,10 @@
 import * as react from 'react';
 import { AlquimiaSDK } from '../sdk/index.js';
 import { AlquimiaAdapter } from '../adapters/index.js';
-import { W as WhisperProvider, S as StableDiffusionProvider, C as CharacterizationProvider, R as RatingsProvider, L as LoggerProvider } from '../providers-b5_yMyMo.js';
-import { G as GenuiSurfaceItem, e as AlquimiaMessage, u as ToolEvent, a as AIMessageChunk, R as RatingData } from '../type-xksRnBUW.js';
+import { W as WhisperProvider, S as StableDiffusionProvider, C as CharacterizationProvider, R as RatingsProvider, L as LoggerProvider } from '../providers-mx21gNgZ.js';
+import { G as GenuiSurfaceItem, e as AlquimiaMessage, F as ToolEvent, a as AIMessageChunk, R as RatingData } from '../type-D-JaSMkV.js';
 import { T as ToolExecutionResponse } from '../types-CMVbyEv8.js';
-import { a as WorklogState } from '../types-C-6fgK1_.js';
+import { a as WorklogState } from '../types-lOliroPw.js';
 import { createMessageId } from '../utils/index.js';
 import { C as CatalogManifest } from '../registry-Bcu_ZYL1.js';
 import { U as UIAction } from '../actions-CP1d4Ye1.js';