@revealui/ai 0.2.9 → 0.4.0

package/README.md

@@ -8,13 +8,211 @@ AI system for RevealUI - memory, LLM, orchestration, and tools.
 ## Features
 
 - **Memory System**: CRDT-based persistent memory (Working, Episodic, Semantic)
-- **LLM Integration**: Provider abstractions for Anthropic, GROQ, Ollama, and more
+- **LLM Integration**: Provider abstractions for Anthropic, GROQ, Ollama, Canonical Inference Snaps, and more
 - **Agent Orchestration**: Runtime and execution engine for AI agents
-- **Tool Calling**: Tool registry and execution system
+- **Tool Calling**: Tool registry + standard-MCP-client integration (Stage 5.1a)
 - **Vector Search**: Semantic search with pgvector
 - **Type-safe**: Full TypeScript support
 - **Performant**: Optimized for low-latency operations
 
+## Reference stack (Ubuntu)
+
+The recommended on-prem / on-device stack pairs `@revealui/ai` with a
+**Canonical Inference Snap** for local LLM inference:
+
+```
+@revealui/ai (this package)
+   │
+   ├── agent runtime + tool-calling loop
+   │
+   ├── MCP client → @revealui/mcp/client → tools/resources/prompts from MCP servers
+   │
+   └── LLM provider → OpenAI-compatible HTTP → localhost:<port>/v1
+                                                    ▲
+                                                    │
+                                         Canonical Inference Snap
+                                         (DeepSeek R1, Qwen 2.5 VL,
+                                          Gemma 3, Nemotron Nano —
+                                          silicon-optimized on Intel/
+                                          Ampere/NVIDIA/NPU)
+```
+
+Quick setup:
+
+```bash
+sudo snap install gemma3               # or deepseek-r1, qwen-vl, etc.
+gemma3 set http.port=9090
+gemma3 status                          # confirms base URL
+```
+
+```typescript
+import { InferenceSnapsProvider, LLMClient } from '@revealui/ai'
+
+const provider = new InferenceSnapsProvider({
+  baseURL: 'http://localhost:9090/v1',
+  model: 'gemma3',
+})
+
+const client = new LLMClient({ provider })
+```
+
+Cloud providers (Anthropic, OpenAI, GROQ) remain supported; the local
+inference path is the documented default for self-hosted deployments.
+
+## MCP tool integration
+
+Standard MCP servers plug into the agent runtime as tool sources. Construct
+an `McpClient` (from `@revealui/mcp/client`), connect it, and pass it to
+`AgentRuntime`:
+
+```typescript
+import { McpClient } from '@revealui/mcp/client'
+import { AgentRuntime } from '@revealui/ai'
+
+const contentClient = new McpClient({
+  clientInfo: { name: 'my-agent', version: '1.0.0' },
+  transport: { kind: 'streamable-http', url: 'https://admin.example.com/api/mcp/content' },
+})
+await contentClient.connect()
+
+const runtime = new AgentRuntime({
+  mcpClients: [{ name: 'content', client: contentClient }],
+})
+```
+
+Tools from each client are namespaced as `mcp_<name>__<toolName>` so multiple
+clients coexist without collisions.
+
+### Resources + prompts (Stage 5.1b)
+
+When an MCP client advertises resources and/or prompts, the adapter
+additionally emits per-server meta-tools so the agent can read them on
+demand without any bespoke wiring:
+
+| Meta-tool | Calls | Returns |
+|---|---|---|
+| `mcp_<ns>__list_resources` | `client.listResources()` | `[{ uri, name?, description?, mimeType? }, …]` |
+| `mcp_<ns>__read_resource({ uri })` | `client.readResource(uri)` | resource contents; text parts flattened into the `content` field for token-efficient LLM context |
+| `mcp_<ns>__list_prompts` | `client.listPrompts()` | `[{ name, description?, arguments? }, …]` |
+| `mcp_<ns>__get_prompt({ name, args? })` | `client.getPrompt(name, args)` | `{ description?, messages }`; text messages flattened to `<role>: <text>` |
+
+All four are opt-out via `include` on `createToolsFromMcpClient()`. Meta-tools
+are silently skipped when the client doesn't implement the underlying
+method (e.g. servers that don't advertise the resources capability).
+
+```typescript
+// Include every primitive (default)
+const tools = await createToolsFromMcpClient(client, { namespace: 'content' })
+
+// Tools only, skip the resources/prompts meta-tools
+const toolsOnly = await createToolsFromMcpClient(client, {
+  namespace: 'content',
+  include: { tools: true, resources: false, prompts: false },
+})
+```
+
+### Elicitation, progress, cancellation (Stage 5.3)
+
+MCP servers can ask the user for structured input mid-flow
+(`elicitation/create`), report progress on long-running tool calls, and
+respect cancellation. `@revealui/ai` wires all three through consumer
+callbacks — the agent package stays UI-agnostic:
+
+```typescript
+import { McpClient } from '@revealui/mcp/client'
+import { createElicitationHandler, createToolsFromMcpClient } from '@revealui/ai'
+
+const controller = new AbortController() // wire to a UI cancel button
+
+const client = new McpClient({
+  clientInfo: { name: 'my-agent', version: '1.0.0' },
+  transport: { kind: 'streamable-http', url: '…' },
+  elicitationHandler: createElicitationHandler({
+    onElicit: async ({ message, requestedSchema }) => {
+      const form = await showFormDialog({ title: message, schema: requestedSchema })
+      if (!form) return { action: 'cancel' }
+      return { action: 'accept', content: form.values }
+    },
+    timeoutMs: 60_000,         // auto-cancel if no response
+    // allowUrlMode: false      // default — URL-mode auto-declines
+  }),
+})
+await client.connect()
+
+const tools = await createToolsFromMcpClient(client, {
+  namespace: 'content',
+  signal: controller.signal,    // cancel all MCP RPC when aborted
+  onProgress: (event) => {      // per-tool-call progress events
+    progressBar.update(event.toolName, event.progress.progress, event.progress.total)
+  },
+})
+```
+
+**Elicitation safety:**
+- `mode: 'url'` (out-of-band consent) is auto-declined unless
+  `allowUrlMode: true`. URL-mode is a phishing vector when users can't
+  easily verify the target domain.
+- `timeoutMs` auto-cancels (not declines) when no response arrives.
+  Useful in headless automation.
+- Errors thrown inside `onElicit` map to `{ action: 'cancel' }` — the
+  server sees a clean non-response, not a crashed protocol.
+
+**Progress events** are forwarded from the server's
+`notifications/progress` stream with the namespace + tool name stamped
+for multi-client attribution. Resource + prompt meta-tools also emit
+(via their own `notifications/progress` flows).
+
+**Cancellation** uses the MCP spec's `notifications/cancelled` — aborting
+the `AbortSignal` propagates to in-flight RPC calls on the wire, so
+long-running operations stop instead of just being ignored.
+
+### Recursive sampling (Stage 5.2)
+
+Some MCP servers need LLM capabilities without bundling a provider. The
+spec lets servers issue `sampling/createMessage` requests — the *client*
+runs the inference, keeps cost + context control, and returns the result.
+On the Ubuntu reference stack, that means servers get LLM access via the
+developer's local Canonical Inference Snap — no cloud round-trip required.
+
+```typescript
+import { McpClient } from '@revealui/mcp/client'
+import { InferenceSnapsProvider, createSamplingHandler } from '@revealui/ai'
+
+const llm = new InferenceSnapsProvider({
+  baseURL: 'http://localhost:9090/v1',
+  model: 'gemma3',
+})
+
+const client = new McpClient({
+  clientInfo: { name: 'my-agent', version: '1.0.0' },
+  transport: { kind: 'streamable-http', url: 'https://example.com/mcp' },
+  samplingHandler: createSamplingHandler({
+    llm,
+    defaultModel: 'gemma3',
+    allowedModels: ['gemma3', 'deepseek-r1'],  // strongly recommended
+    onSamplingRequest: (info) => {
+      // metering / audit trail
+      metrics.incr('mcp.sampling', { model: info.model })
+    },
+  }),
+})
+await client.connect()
+```
+
+`allowedModels` filters `modelPreferences.hints` from the server — hints
+outside the list are ignored so a malicious server can't escalate costs.
+The handler reports the resolved model back in `result.model`.
+
+**Scope in 5.2:** text-only messages (non-text content throws with a clear
+error). Multimodal sampling lands with the provider interface's content
+parts extension. `stopSequences` aren't forwarded to the LLM yet (the
+current `LLMChatOptions` doesn't expose that field); this is advisory per
+spec, so omission is compliant.
+
+The legacy `mcpToolSource` path (hypervisor-backed) still works and is
+kept for backwards compatibility, but new integrations should prefer the
+`mcpClients` path.
+
 ## Installation
 
 ```bash
@@ -118,30 +316,6 @@ const response = await client.chat([
 ])
 ```
 
-#### Vultr (Vultr AI / Serverless Inference)
-
-You can configure the client to use Vultr Serverless Inference by setting `LLM_PROVIDER=vultr` and providing the `VULTR_API_KEY` and optionally `VULTR_BASE_URL` env vars. Example:
-
-```
-LLM_PROVIDER=vultr
-VULTR_API_KEY=your_inference_api_key
-VULTR_BASE_URL=https://api.vultrinference.com/v1  # optional
-```
-
-The `VultrProvider` supports the chat and (if available for the selected model) embeddings endpoints. Streaming is attempted via the chat streaming endpoint when supported by the API.
-
-Demo: quick test script
-
-You can run a quick demo script that exercises chat and embeddings endpoints. From the repository root:
-
-```bash
-# replace with real values
-VULTR_API_KEY=your_key VULTR_MODEL=your-model-id ts-node packages/ai/scripts/test-vultr.ts
-```
-
-The script prints the raw API responses and a simplified assistant output.
-
-
 ### Agent Orchestration
 
 Agent runtime and execution engine for autonomous agents.

package/dist/a2a/handler.d.ts

@@ -21,6 +21,8 @@ declare const RPC_INVALID_REQUEST = -32600;
  * @param agentId - Optional agent ID (from X-Agent-ID header)
  * @param llmClient - Optional LLM client for real inference (BYOK)
  */
-export declare function handleA2AJsonRpc(req: A2AJsonRpcRequest, agentId?: string, llmClient?: LLMClient): Promise<A2AJsonRpcResponse>;
+export declare function handleA2AJsonRpc(req: A2AJsonRpcRequest, agentId?: string, llmClient?: LLMClient, options?: {
+    paymentVerified?: boolean;
+}): Promise<A2AJsonRpcResponse>;
 export { RPC_INVALID_REQUEST, RPC_PARSE_ERROR };
 //# sourceMappingURL=handler.d.ts.map

package/dist/a2a/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/a2a/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAGnB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAgBlD,QAAA,MAAM,eAAe,SAAS,CAAC;AAC/B,QAAA,MAAM,mBAAmB,SAAS,CAAC;AA0JnC;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,iBAAiB,EACtB,OAAO,CAAC,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,SAAS,GACpB,OAAO,CAAC,kBAAkB,CAAC,CAoB7B;AAED,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/a2a/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EAGnB,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAgBlD,QAAA,MAAM,eAAe,SAAS,CAAC;AAC/B,QAAA,MAAM,mBAAmB,SAAS,CAAC;AA6KnC;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,iBAAiB,EACtB,OAAO,CAAC,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,SAAS,EACrB,OAAO,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,GACtC,OAAO,CAAC,kBAAkB,CAAC,CAoB7B;AAED,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,CAAC"}

package/dist/a2a/handler.js

@@ -36,7 +36,7 @@ function err(id, code, message, data) {
 // =============================================================================
 // Method handlers
 // =============================================================================
-async function handleTasksSend(id, params, agentId, llmClient) {
+async function handleTasksSend(id, params, agentId, llmClient, options) {
     const parsed = A2ASendTaskParamsSchema.safeParse(params);
     if (!parsed.success) {
         return err(id, RPC_INVALID_PARAMS, 'Invalid tasks/send params', parsed.error.issues);
@@ -46,6 +46,26 @@ async function handleTasksSend(id, params, agentId, llmClient) {
     if (agentId && !agentCardRegistry.has(agentId)) {
         return err(id, RPC_AGENT_NOT_FOUND, `Agent '${agentId}' not found`);
     }
+    // Resolve agent definition early — needed for the pricing gate below AND
+    // for execution context (system prompt, capabilities) further down.
+    const agentDef = agentId
+        ? agentCardRegistry.getDef(agentId)
+        : agentCardRegistry.getDef('revealui-creator');
+    // x402 payment gate: when an agent has pricing AND payment was not
+    // verified upstream by the route, emit a 'pending-payment' task. The
+    // route layer translates this state into HTTP 402 with a fresh
+    // X-PAYMENT-REQUIRED header. Pricing rides in task.metadata so the
+    // route can build the requirements without re-querying the registry.
+    if (agentDef?.pricing && !options?.paymentVerified) {
+        const task = createTask({
+            id: p.id,
+            sessionId: p.sessionId,
+            message: p.message,
+            metadata: { ...p.metadata, pricing: agentDef.pricing },
+        });
+        const pending = updateTaskState(task.id, 'pending-payment');
+        return ok(id, pending);
+    }
     // Create task in submitted state
     const task = createTask({
         id: p.id,
@@ -59,9 +79,6 @@ async function handleTasksSend(id, params, agentId, llmClient) {
         updateTaskState(task.id, 'working');
         // Execute via orchestration  -  for now, produce a direct text response.
         // Full AgentRuntime integration wires in when an LLM provider is configured.
-        const agentDef = agentId
-            ? agentCardRegistry.getDef(agentId)
-            : agentCardRegistry.getDef('revealui-creator');
         if (signal?.aborted) {
             return ok(id, getTask(task.id));
         }
@@ -151,18 +168,18 @@ function handleTasksCancel(id, params) {
  * @param agentId - Optional agent ID (from X-Agent-ID header)
  * @param llmClient - Optional LLM client for real inference (BYOK)
  */
-export async function handleA2AJsonRpc(req, agentId, llmClient) {
+export async function handleA2AJsonRpc(req, agentId, llmClient, options) {
     const { id, method, params } = req;
     switch (method) {
         case 'tasks/send':
-            return handleTasksSend(id, params, agentId, llmClient);
+            return handleTasksSend(id, params, agentId, llmClient, options);
         case 'tasks/get':
             return handleTasksGet(id, params);
         case 'tasks/cancel':
             return handleTasksCancel(id, params);
         case 'tasks/sendSubscribe':
             // SSE streaming is handled at the Hono route level; return a reference task here
-            return handleTasksSend(id, params, agentId, llmClient);
+            return handleTasksSend(id, params, agentId, llmClient, options);
         default:
             return err(id, RPC_METHOD_NOT_FOUND, `Method '${method}' not found`);
     }

package/dist/a2a/task-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-store.d.ts","sourceRoot":"","sources":["../../src/a2a/task-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAU1F;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GAAG,OAAO,CAeV;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAElD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,GAAG,IAAI,CAehB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,OAAO,GAAG,IAAI,CAUhF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAY9C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAE5D;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAG1C"}
+{"version":3,"file":"task-store.d.ts","sourceRoot":"","sources":["../../src/a2a/task-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAU1F;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,UAAU,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,GAAG,OAAO,CAeV;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAElD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,YAAY,EACnB,OAAO,CAAC,EAAE,UAAU,GACnB,OAAO,GAAG,IAAI,CAehB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,GAAG,OAAO,GAAG,IAAI,CAUhF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAiB9C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAE5D;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAG1C"}

package/dist/a2a/task-store.js

@@ -76,7 +76,11 @@ export function cancelTask(id) {
     const task = _tasks.get(id);
     if (!task)
         return false;
-    const cancelable = task.status.state === 'submitted' || task.status.state === 'working';
+    // 'pending-payment' is cancelable so a requester who decides not to pay
+    // can release the task slot rather than leaving it dangling.
+    const cancelable = task.status.state === 'submitted' ||
+        task.status.state === 'working' ||
+        task.status.state === 'pending-payment';
     if (!cancelable)
         return false;
     // Signal abort to any running execution

package/dist/client/hooks/useAgentStream.d.ts

@@ -7,10 +7,20 @@
  *   - chunks: all received chunks in order
  *   - isStreaming: true while the stream is open
  *   - error: last error message, if any
+ *   - sessionId: agent-run session id from the leading session_info chunk (A.2b)
+ *   - pendingElicitations: outstanding form-mode elicitation requests by id (A.2b)
+ *   - submitElicitation: POST a response to /api/agent-stream/elicit (A.2b)
  *   - abort(): cancels the stream
  */
+/**
+ * Mirror of `AgentStreamChunk` in
+ * `@revealui/ai/orchestration/streaming-runtime`. Duplicated here (rather
+ * than imported) so client bundles don't pull in server-only orchestration
+ * code through the type graph. Keep these in lockstep — when a new chunk
+ * type lands in the runtime, mirror it here.
+ */
 export interface AgentStreamChunk {
-    type: 'text' | 'tool_call_start' | 'tool_call_result' | 'error' | 'done';
+    type: 'text' | 'tool_call_start' | 'tool_call_result' | 'error' | 'done' | 'session_info' | 'sampling_request' | 'elicitation_request';
     content?: string;
     toolCall?: {
         name: string;
@@ -22,23 +32,96 @@ export interface AgentStreamChunk {
         tokensUsed?: number;
         executionTime?: number;
     };
+    /** Present on session_info / sampling_request / elicitation_request. */
+    sessionId?: string;
+    /** MCP server id. Present on sampling_request / elicitation_request. */
+    namespace?: string;
+    /** Present on sampling_request — the request shape sent to the LLM. */
+    sampling?: {
+        model: string;
+        messageCount: number;
+        maxTokens: number;
+    };
+    /** Present on elicitation_request — the form payload for the UI. */
+    elicitation?: {
+        elicitationId: string;
+        requestedSchema: unknown;
+        message?: string;
+    };
 }
 export interface AgentStreamRequest {
     instruction: string;
     boardId?: string;
     workspaceId?: string;
     priority?: 'low' | 'medium' | 'high' | 'critical';
+    /**
+     * Agent mode. `'admin'` (default) gives the agent the admin-tools surface;
+     * `'coding'` adds file-read/write/grep + shell + git tools (Pro-tier;
+     * free-tier sees read-only subset). Mirrors `mode?` in the `/api/agent-stream`
+     * request schema.
+     */
+    mode?: 'admin' | 'coding';
 }
+/**
+ * Outstanding elicitation request awaiting a UI response. The hook keeps
+ * one entry per `elicitationId`; entries are removed when
+ * `submitElicitation()` lands successfully or when the stream ends.
+ */
+export interface PendingElicitation {
+    elicitationId: string;
+    namespace: string;
+    requestedSchema: unknown;
+    message?: string;
+}
+export type ElicitationAction = 'accept' | 'decline' | 'cancel';
+/**
+ * Permitted primitive value types per the MCP spec (`ElicitResult.content`).
+ * The hook is a thin transport — the server-side zod schema at
+ * `apps/server/src/routes/agent-stream-elicit.ts` is the authoritative
+ * validator. We accept a wider input shape so callers can pass
+ * `Record<string, unknown>` from generic form serializers without
+ * up-front narrowing; non-primitive values get rejected by the server.
+ */
+export type ElicitationContentValue = string | number | boolean | string[];
+export type ElicitationContent = Record<string, unknown>;
 export interface UseAgentStreamState {
     text: string;
     chunks: AgentStreamChunk[];
     isStreaming: boolean;
     error: string | null;
+    /** Set when the leading `session_info` chunk arrives. Null otherwise. */
+    sessionId: string | null;
+    /** Map of pending elicitations keyed by elicitationId. */
+    pendingElicitations: PendingElicitation[];
 }
 export interface UseAgentStreamReturn extends UseAgentStreamState {
     start: (request: AgentStreamRequest, apiBase?: string) => Promise<void>;
     abort: () => void;
     reset: () => void;
+    /**
+     * POST an elicitation response to `/api/agent-stream/elicit` and remove
+     * the entry from `pendingElicitations` on success. Throws if the network
+     * call fails or the server returns a non-2xx status.
+     */
+    submitElicitation: (elicitationId: string, action: ElicitationAction, content?: ElicitationContent) => Promise<void>;
 }
 export declare function useAgentStream(): UseAgentStreamReturn;
+/**
+ * Pure reducer applying one SSE chunk to the hook's state. Extracted for
+ * test-friendliness — call sites can simulate `start()` by feeding chunks
+ * to `applyChunk()` against `INITIAL_STATE`.
+ *
+ * @internal
+ */
+declare function applyChunk(s: UseAgentStreamState, chunk: AgentStreamChunk): UseAgentStreamState;
+/**
+ * Pure reducer used internally to apply a chunk to state. Exported for
+ * unit tests so the chunk → state mapping can be verified without
+ * mounting a React component or stubbing `fetch`.
+ *
+ * @internal
+ */
+export declare const _applyChunkForTesting: typeof applyChunk;
+export declare const _initialStateForTesting: UseAgentStreamState;
+export {};
 //# sourceMappingURL=useAgentStream.d.ts.map

package/dist/client/hooks/useAgentStream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAgentStream.d.ts","sourceRoot":"","sources":["../../../src/client/hooks/useAgentStream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,kBAAkB,GAAG,OAAO,GAAG,MAAM,CAAC;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC5D;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;CACnD;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D,KAAK,EAAE,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AASD,wBAAgB,cAAc,IAAI,oBAAoB,CA2FrD"}
+{"version":3,"file":"useAgentStream.d.ts","sourceRoot":"","sources":["../../../src/client/hooks/useAgentStream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EACA,MAAM,GACN,iBAAiB,GACjB,kBAAkB,GAClB,OAAO,GACP,MAAM,GACN,cAAc,GACd,kBAAkB,GAClB,qBAAqB,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3D,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,oEAAoE;IACpE,WAAW,CAAC,EAAE;QACZ,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,OAAO,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IAClD;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEhE;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC;AAC3E,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEzD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,yEAAyE;IACzE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,0DAA0D;IAC1D,mBAAmB,EAAE,kBAAkB,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D,KAAK,EAAE,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;;OAIG;IACH,iBAAiB,EAAE,CACjB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,kBAAkB,KACzB,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAWD,wBAAgB,cAAc,IAAI,oBAAoB,CAgIrD;AAED;;;;;;GAMG;AACH,iBAAS,UAAU,CAAC,CAAC,EAAE,mBAAmB,EAAE,KAAK,EAAE,gBAAgB,GAAG,mBAAmB,CA8CxF;AAMD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,mBAAa,CAAC;AAChD,eAAO,MAAM,uBAAuB,EAAE,mBAAmC,CAAC"}

package/dist/client/hooks/useAgentStream.js

@@ -7,6 +7,9 @@
  *   - chunks: all received chunks in order
  *   - isStreaming: true while the stream is open
  *   - error: last error message, if any
+ *   - sessionId: agent-run session id from the leading session_info chunk (A.2b)
+ *   - pendingElicitations: outstanding form-mode elicitation requests by id (A.2b)
+ *   - submitElicitation: POST a response to /api/agent-stream/elicit (A.2b)
  *   - abort(): cancels the stream
  */
 'use client';
@@ -16,6 +19,8 @@ const INITIAL_STATE = {
     chunks: [],
     isStreaming: false,
     error: null,
+    sessionId: null,
+    pendingElicitations: [],
 };
 export function useAgentStream() {
     const [state, setState] = useState(INITIAL_STATE);
@@ -32,12 +37,13 @@ export function useAgentStream() {
         controllerRef.current?.abort();
         const controller = new AbortController();
         controllerRef.current = controller;
-        setState({ text: '', chunks: [], isStreaming: true, error: null });
+        setState({ ...INITIAL_STATE, isStreaming: true });
         try {
             const response = await fetch(apiBase, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify(request),
+                credentials: 'include',
                 signal: controller.signal,
             });
             if (!response.ok) {
@@ -69,19 +75,15 @@ export function useAgentStream() {
                     if (!dataLine)
                         continue;
                     const jsonStr = dataLine.slice(6);
+                    let chunk;
                     try {
-                        const chunk = JSON.parse(jsonStr);
-                        setState((s) => ({
-                            ...s,
-                            chunks: [...s.chunks, chunk],
-                            text: chunk.type === 'text' ? s.text + (chunk.content ?? '') : s.text,
-                            error: chunk.type === 'error' ? (chunk.error ?? 'Unknown error') : s.error,
-                            isStreaming: chunk.type !== 'done' && chunk.type !== 'error',
-                        }));
+                        chunk = JSON.parse(jsonStr);
                     }
                     catch {
                         // Malformed SSE data  -  skip
+                        continue;
                     }
+                    setState((s) => applyChunk(s, chunk));
                 }
             }
         }
@@ -97,5 +99,99 @@ export function useAgentStream() {
             }));
         }
     }, []);
-    return { ...state, start, abort, reset };
+    const submitElicitation = useCallback(async (elicitationId, action, content) => {
+        const sessionId = stateRef.current.sessionId;
+        if (!sessionId) {
+            throw new Error('useAgentStream: no sessionId — start() must run before submitElicitation()');
+        }
+        const body = { sessionId, elicitationId, action };
+        if (action === 'accept' && content)
+            body.content = content;
+        const response = await fetch('/api/agent-stream/elicit', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+            credentials: 'include',
+        });
+        if (!response.ok) {
+            const errText = await response.text();
+            throw new Error(`elicit response failed: HTTP ${response.status}: ${errText}`);
+        }
+        // Remove the resolved entry from pendingElicitations
+        setState((s) => ({
+            ...s,
+            pendingElicitations: s.pendingElicitations.filter((p) => p.elicitationId !== elicitationId),
+        }));
+    }, []);
+    // submitElicitation needs the *current* sessionId at call time, so we
+    // mirror state into a ref. Avoids stale-closure bugs without making the
+    // callback's dependencies churn on every chunk.
+    const stateRef = useRef(state);
+    stateRef.current = state;
+    return { ...state, start, abort, reset, submitElicitation };
+}
+/**
+ * Pure reducer applying one SSE chunk to the hook's state. Extracted for
+ * test-friendliness — call sites can simulate `start()` by feeding chunks
+ * to `applyChunk()` against `INITIAL_STATE`.
+ *
+ * @internal
+ */
+function applyChunk(s, chunk) {
+    const next = {
+        ...s,
+        chunks: [...s.chunks, chunk],
+    };
+    switch (chunk.type) {
+        case 'session_info':
+            if (chunk.sessionId)
+                next.sessionId = chunk.sessionId;
+            break;
+        case 'text':
+            next.text = s.text + (chunk.content ?? '');
+            break;
+        case 'error':
+            next.error = chunk.error ?? 'Unknown error';
+            next.isStreaming = false;
+            // Cancel all pending elicitations on stream error — the server-side
+            // session is being torn down so any open form is no longer
+            // resolvable.
+            next.pendingElicitations = [];
+            break;
+        case 'done':
+            next.isStreaming = false;
+            next.pendingElicitations = [];
+            break;
+        case 'elicitation_request':
+            if (chunk.elicitation && chunk.namespace) {
+                next.pendingElicitations = [
+                    ...s.pendingElicitations,
+                    {
+                        elicitationId: chunk.elicitation.elicitationId,
+                        namespace: chunk.namespace,
+                        requestedSchema: chunk.elicitation.requestedSchema,
+                        ...(chunk.elicitation.message ? { message: chunk.elicitation.message } : {}),
+                    },
+                ];
+            }
+            break;
+        // tool_call_start / tool_call_result / sampling_request: no state
+        // mutation beyond appending to `chunks`. Consumers render from the
+        // chunk list directly.
+        default:
+            break;
+    }
+    return next;
 }
+// ---------------------------------------------------------------------------
+// Test-only export
+// ---------------------------------------------------------------------------
+/**
+ * Pure reducer used internally to apply a chunk to state. Exported for
+ * unit tests so the chunk → state mapping can be verified without
+ * mounting a React component or stubbing `fetch`.
+ *
+ * @internal
+ */
+export const _applyChunkForTesting = applyChunk;
+export const _initialStateForTesting = INITIAL_STATE;

package/dist/index.d.ts

@@ -45,12 +45,6 @@
  *
  * @packageDocumentation
  */
-/**
- * Check if the AI package is licensed for use.
- * Returns false with a warning log if no Pro/Enterprise license is active.
- * Call at application startup to verify licensing.
- */
-export declare function checkAiLicense(): boolean;
 export * from './a2a/index.js';
 export * from './audit/index.js';
 export * from './embeddings/index.js';
@@ -58,6 +52,7 @@ export * from './ingestion/index.js';
 export * from './llm/client.js';
 export * from './llm/provider-health.js';
 export * from './llm/providers/base.js';
+export * from './llm/providers/inference-snaps.js';
 export * from './llm/providers/openai-compat.js';
 export * from './llm/token-counter.js';
 export * from './llm/workspace-provider-config.js';
@@ -75,6 +70,9 @@ export * from './tools/base.js';
 export * from './tools/deduplicator.js';
 export * from './tools/document-summarizer.js';
 export * from './tools/mcp-adapter.js';
+export * from './tools/mcp-elicitation.js';
+export * from './tools/mcp-events.js';
+export * from './tools/mcp-sampling.js';
 export * from './tools/memory/index.js';
 export * from './tools/registry.js';
 export * from './tools/ticket-tools.js';