@contractspec/module.ai-chat 3.2.0 → 4.0.0

package/README.md

@@ -18,10 +18,15 @@ This module provides a reusable AI chat system that can be integrated into CLI,
 - **Usage Tracking**: Integrated metering and cost tracking
 - **UI Components**: React components for chat interfaces
 
+## Bundle Spec Alignment (07_ai_native_chat)
+
+This module aligns with `specs/contractspec_modules_bundle_spec_2026-03-08`. `useChat` and `ChatContainer` provide the assistant slot UI for bundle surfaces. `AiChatFeature` (key `ai-chat`, version `1.0.0`) matches `ModuleBundleSpec.requires`. The `tools` option on `UseChatOptions` is wired to `streamText`; use `requireApproval: true` for tools that need user confirmation (requires server route for full support).
+
 ## Related Packages
 
 - `@contractspec/lib.ai-providers` — Shared provider abstraction (types, factory, validation)
 - `@contractspec/lib.ai-agent` — Agent orchestration and tool execution
+- `@contractspec/lib.surface-runtime` — Bundle surfaces (optional peer when used in PM workbench)
 
 ## Providers
 
@@ -94,6 +99,71 @@ function VibeCodingChat() {
 }
 ```
 
+### AI SDK Parity
+
+This module aligns with the [Vercel AI SDK](https://sdk.vercel.ai) and AI Elements feature set:
+
+- **fullStream**: Reasoning, tools, and sources from `streamText` fullStream
+- **Tools**: Pass `tools` to `ChatServiceConfig` or `useChat`; supports `requireApproval` for approval workflow
+- **Message parts**: `ChatMessage` renders reasoning (collapsible), sources (citations), and tool invocations
+- **Markdown**: Inline links and code blocks in message content
+
+### Server Route (Full AI SDK + Tool Approval)
+
+For full AI SDK compatibility including tool approval, use `createChatRoute` with `@ai-sdk/react` useChat:
+
+```ts
+// app/api/chat/route.ts (Next.js App Router)
+import { createChatRoute } from '@contractspec/module.ai-chat/core';
+import { createProvider } from '@contractspec/lib.ai-providers';
+
+const provider = createProvider({
+  provider: 'openai',
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4o',
+});
+
+export const POST = createChatRoute({ provider });
+```
+
+```tsx
+// Client: use @ai-sdk/react useChat with DefaultChatTransport
+import { useChat } from '@ai-sdk/react';
+
+const { messages, sendMessage } = useChat({
+  api: '/api/chat',
+});
+```
+
+The custom `useChat` from this module works with `ChatService` for simple deployments (no tools, no approval). For tools with `requireApproval`, use the server route pattern above.
+
+### Optional AI Elements
+
+Apps can optionally use [AI Elements](https://elements.ai-sdk.dev) for UI. This module does not depend on ai-elements; provide an adapter from `ChatMessage` to `UIMessage` when integrating.
+
+### useCompletion (Non-Chat Completion)
+
+For inline suggestions, single-prompt completion, or other non-conversational use cases:
+
+```tsx
+import { useCompletion } from '@contractspec/module.ai-chat/presentation/hooks';
+// or: import { useCompletion } from '@ai-sdk/react';
+
+const { completion, complete, isLoading } = useCompletion({
+  api: '/api/completion',
+});
+```
+
+Use `createCompletionRoute` for the API endpoint (see `createChatRoute` pattern).
+
+### streamObject / generateObject
+
+For structured output (schema-driven generation), use the AI SDK directly: `streamObject` and `generateObject` from `ai`. This module focuses on chat; add `useObject` or equivalent in a separate module when needed.
+
+### Voice / Speech
+
+Speech Input, Transcription, Voice Selector, and related UI are planned as a separate submodule or feature flag. Track via roadmap.
+
 ## Architecture
 
 ```

package/dist/browser/core/index.js

@@ -135,6 +135,9 @@ class ChatService {
   systemPrompt;
   maxHistoryMessages;
   onUsage;
+  tools;
+  sendReasoning;
+  sendSources;
   constructor(config) {
     this.provider = config.provider;
     this.context = config.context;
@@ -142,6 +145,9 @@ class ChatService {
     this.systemPrompt = config.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
     this.maxHistoryMessages = config.maxHistoryMessages ?? 20;
     this.onUsage = config.onUsage;
+    this.tools = config.tools;
+    this.sendReasoning = config.sendReasoning ?? false;
+    this.sendSources = config.sendSources ?? false;
   }
   async send(options) {
     let conversation;
@@ -166,13 +172,14 @@ class ChatService {
       status: "completed",
       attachments: options.attachments
     });
-    const prompt = this.buildPrompt(conversation, options);
+    const messages = this.buildMessages(conversation, options);
     const model = this.provider.getModel();
     try {
       const result = await generateText({
         model,
-        prompt,
-        system: this.systemPrompt
+        messages,
+        system: this.systemPrompt,
+        tools: this.tools
       });
       const assistantMessage = await this.store.appendMessage(conversation.id, {
         role: "assistant",
@@ -228,33 +235,106 @@ class ChatService {
       content: "",
       status: "streaming"
     });
-    const prompt = this.buildPrompt(conversation, options);
+    const messages = this.buildMessages(conversation, options);
     const model = this.provider.getModel();
-    const self = {
-      systemPrompt: this.systemPrompt,
-      store: this.store
-    };
+    const systemPrompt = this.systemPrompt;
+    const tools = this.tools;
+    const store = this.store;
+    const onUsage = this.onUsage;
     async function* streamGenerator() {
       let fullContent = "";
+      let fullReasoning = "";
+      const toolCallsMap = new Map;
+      const sources = [];
       try {
         const result = streamText({
           model,
-          prompt,
-          system: self.systemPrompt
+          messages,
+          system: systemPrompt,
+          tools
         });
-        for await (const chunk of result.textStream) {
-          fullContent += chunk;
-          yield { type: "text", content: chunk };
+        for await (const part of result.fullStream) {
+          if (part.type === "text-delta") {
+            const text = part.text ?? "";
+            if (text) {
+              fullContent += text;
+              yield { type: "text", content: text };
+            }
+          } else if (part.type === "reasoning-delta") {
+            const text = part.text ?? "";
+            if (text) {
+              fullReasoning += text;
+              yield { type: "reasoning", content: text };
+            }
+          } else if (part.type === "source") {
+            const src = part;
+            const source = {
+              id: src.id,
+              title: src.title ?? "",
+              url: src.url,
+              type: "web"
+            };
+            sources.push(source);
+            yield { type: "source", source };
+          } else if (part.type === "tool-call") {
+            const toolCall = {
+              id: part.toolCallId,
+              name: part.toolName,
+              args: part.input ?? {},
+              status: "running"
+            };
+            toolCallsMap.set(part.toolCallId, toolCall);
+            yield { type: "tool_call", toolCall };
+          } else if (part.type === "tool-result") {
+            const tc = toolCallsMap.get(part.toolCallId);
+            if (tc) {
+              tc.result = part.output;
+              tc.status = "completed";
+            }
+            yield {
+              type: "tool_result",
+              toolResult: {
+                toolCallId: part.toolCallId,
+                toolName: part.toolName,
+                result: part.output
+              }
+            };
+          } else if (part.type === "tool-error") {
+            const tc = toolCallsMap.get(part.toolCallId);
+            if (tc) {
+              tc.status = "error";
+              tc.error = part.error ?? "Tool execution failed";
+            }
+          } else if (part.type === "finish") {
+            const usage = part.usage;
+            const inputTokens = usage?.inputTokens ?? 0;
+            const outputTokens = usage?.completionTokens ?? 0;
+            await store.updateMessage(conversation.id, assistantMessage.id, {
+              content: fullContent,
+              status: "completed",
+              reasoning: fullReasoning || undefined,
+              sources: sources.length > 0 ? sources : undefined,
+              toolCalls: toolCallsMap.size > 0 ? Array.from(toolCallsMap.values()) : undefined,
+              usage: usage ? { inputTokens, outputTokens } : undefined
+            });
+            onUsage?.({ inputTokens, outputTokens });
+            yield {
+              type: "done",
+              usage: usage ? { inputTokens, outputTokens } : undefined
+            };
+            return;
+          }
         }
-        await self.store.updateMessage(conversation.id, assistantMessage.id, {
+        await store.updateMessage(conversation.id, assistantMessage.id, {
           content: fullContent,
-          status: "completed"
+          status: "completed",
+          reasoning: fullReasoning || undefined,
+          sources: sources.length > 0 ? sources : undefined,
+          toolCalls: toolCallsMap.size > 0 ? Array.from(toolCallsMap.values()) : undefined
         });
-        yield {
-          type: "done"
-        };
+        yield { type: "done" };
       } catch (error) {
-        await self.store.updateMessage(conversation.id, assistantMessage.id, {
+        await store.updateMessage(conversation.id, assistantMessage.id, {
           content: fullContent,
           status: "error",
           error: {
@@ -289,48 +369,128 @@ class ChatService {
   async deleteConversation(conversationId) {
     return this.store.delete(conversationId);
   }
-  buildPrompt(conversation, options) {
-    let prompt = "";
+  buildMessages(conversation, _options) {
     const historyStart = Math.max(0, conversation.messages.length - this.maxHistoryMessages);
+    const messages = [];
     for (let i = historyStart;i < conversation.messages.length; i++) {
       const msg = conversation.messages[i];
       if (!msg)
         continue;
-      if (msg.role === "user" || msg.role === "assistant") {
-        prompt += `${msg.role === "user" ? "User" : "Assistant"}: ${msg.content}
-
-`;
-      }
-    }
-    let content = options.content;
-    if (options.attachments?.length) {
-      const attachmentInfo = options.attachments.map((a) => {
-        if (a.type === "file" || a.type === "code") {
-          return `
+      if (msg.role === "user") {
+        let content = msg.content;
+        if (msg.attachments?.length) {
+          const attachmentInfo = msg.attachments.map((a) => {
+            if (a.type === "file" || a.type === "code") {
+              return `
 
 ### ${a.name}
 \`\`\`
-${a.content}
+${a.content ?? ""}
 \`\`\``;
-        }
-        return `
+            }
+            return `
 
 [Attachment: ${a.name}]`;
-      }).join("");
-      content += attachmentInfo;
+          }).join("");
+          content += attachmentInfo;
+        }
+        messages.push({ role: "user", content });
+      } else if (msg.role === "assistant") {
+        if (msg.toolCalls?.length) {
+          messages.push({
+            role: "assistant",
+            content: msg.content || "",
+            toolCalls: msg.toolCalls.map((tc) => ({
+              type: "tool-call",
+              toolCallId: tc.id,
+              toolName: tc.name,
+              args: tc.args
+            }))
+          });
+          messages.push({
+            role: "tool",
+            content: msg.toolCalls.map((tc) => ({
+              type: "tool-result",
+              toolCallId: tc.id,
+              toolName: tc.name,
+              output: tc.result
+            }))
+          });
+        } else {
+          messages.push({ role: "assistant", content: msg.content });
+        }
+      }
     }
-    prompt += `User: ${content}
-
-Assistant:`;
-    return prompt;
+    return messages;
   }
 }
 function createChatService(config) {
   return new ChatService(config);
 }
+// src/core/create-chat-route.ts
+import {
+  convertToModelMessages,
+  streamText as streamText2
+} from "ai";
+var DEFAULT_SYSTEM_PROMPT2 = `You are a helpful AI assistant.`;
+function createChatRoute(options) {
+  const { provider, systemPrompt = DEFAULT_SYSTEM_PROMPT2, tools } = options;
+  return async (req) => {
+    if (req.method !== "POST") {
+      return new Response("Method not allowed", { status: 405 });
+    }
+    let body;
+    try {
+      body = await req.json();
+    } catch {
+      return new Response("Invalid JSON body", { status: 400 });
+    }
+    const messages = body.messages ?? [];
+    if (!Array.isArray(messages) || messages.length === 0) {
+      return new Response("messages array required", { status: 400 });
+    }
+    const model = provider.getModel();
+    const result = streamText2({
+      model,
+      messages: await convertToModelMessages(messages),
+      system: systemPrompt,
+      tools
+    });
+    return result.toUIMessageStreamResponse();
+  };
+}
+// src/core/create-completion-route.ts
+import { streamText as streamText3 } from "ai";
+function createCompletionRoute(options) {
+  const { provider, systemPrompt } = options;
+  return async (req) => {
+    if (req.method !== "POST") {
+      return new Response("Method not allowed", { status: 405 });
+    }
+    let body;
+    try {
+      body = await req.json();
+    } catch {
+      return new Response("Invalid JSON body", { status: 400 });
+    }
+    const prompt = body.prompt ?? "";
+    if (!prompt || typeof prompt !== "string") {
+      return new Response("prompt string required", { status: 400 });
+    }
+    const model = provider.getModel();
+    const result = streamText3({
+      model,
+      prompt,
+      system: systemPrompt
+    });
+    return result.toTextStreamResponse();
+  };
+}
 export {
   createInMemoryConversationStore,
+  createCompletionRoute,
   createChatService,
+  createChatRoute,
   InMemoryConversationStore,
   ChatService
 };