@contractspec/module.ai-chat 4.0.3 → 4.1.0

package/README.md

@@ -17,6 +17,16 @@ This module provides a reusable AI chat system that can be integrated into CLI,
 - **Streaming Responses**: Real-time token streaming for responsive UX
 - **Usage Tracking**: Integrated metering and cost tracking
 - **UI Components**: React components for chat interfaces
+- **Export**: Export conversations to Markdown, TXT, or JSON; select one or many messages for export
+- **Conversation Management**: New conversation, history sidebar, fork, edit messages, organize with projects and tags
+- **Thinking Levels**: Select reasoning depth (instant, thinking, extra thinking, max); maps to Anthropic budgetTokens and OpenAI reasoningEffort
+- **Workflow Creation Tools**: Create and modify workflows conversationally via `create_workflow_extension`, `compose_workflow`, and `generate_workflow_spec_code` (requires `@contractspec/lib.workflow-composer`)
+- **ModelSelector**: Dynamic model selection by task dimension (reasoning vs latency) when using `@contractspec/lib.ai-providers` ModelSelector
+- **Contracts-Spec Context**: Expose agent, data-views, operations, forms, and presentations to the model via `contractsContext`; agent tools can be wired from `AgentToolConfig[]`
+- **Surface-Runtime Integration**: Full support for `@contractspec/lib.surface-runtime` — pass `surfacePlanConfig` to enable `propose-patch` tool; chat can propose layout changes for user approval
+- **Presentation/Form Rendering**: Pass `presentationRenderer` and `formRenderer` to `ChatWithSidebar`; tool results with `presentationKey` or `formKey` render via host-provided components
+- **MCP Tools**: Pass `mcpServers` (from `@contractspec/lib.ai-agent`) to `useChat`; tools from MCP servers are merged into chat tools
+- **Agent Mode**: Pass `agentMode: { agent }` with a `ChatAgentAdapter` (use `createChatAgentAdapter` to wrap `ContractSpecAgent`); chat uses the agent for generation instead of ChatService
 
 ## Bundle Spec Alignment (07_ai_native_chat)
 
@@ -24,9 +34,10 @@ This module aligns with `specs/contractspec_modules_bundle_spec_2026-03-08`. `us
 
 ## 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)
+- `@contractspec/lib.ai-providers` — Shared provider abstraction (types, factory, validation), ModelSelector for dynamic model selection
+- `@contractspec/lib.workflow-composer` — Workflow composition and validation (optional; required for workflow creation tools)
+- `@contractspec/lib.ai-agent` — Agent orchestration and tool execution; `AgentToolConfig` for agent tools
+- `@contractspec/lib.surface-runtime` — Bundle surfaces, planner tools, `AiSdkBundleAdapter`; full integration when used in PM workbench
 
 ## Providers
 
@@ -78,21 +89,55 @@ const response = await chatService.send({
 
 ### React Components
 
+**With export and message selection** (recommended):
+
 ```tsx
-import { ChatContainer, ChatMessage, ChatInput } from '@contractspec/module.ai-chat/presentation/components';
-import { useChat } from '@contractspec/module.ai-chat/presentation/hooks';
+import { ChatWithExport, ChatInput, useChat } from '@contractspec/module.ai-chat';
 
 function VibeCodingChat() {
-  const { messages, sendMessage, isLoading } = useChat({
+  const { messages, conversation, sendMessage, isLoading } = useChat({
     provider: 'openai',
     mode: 'managed',
   });
 
+  return (
+    <ChatWithExport messages={messages} conversation={conversation}>
+      <ChatInput onSend={sendMessage} disabled={isLoading} />
+    </ChatWithExport>
+  );
+}
+```
+
+`ChatWithExport` provides an export toolbar (Markdown, TXT, JSON, copy to clipboard) and message selection checkboxes. Select messages to export only those, or export all when none are selected.
+
+**With sidebar (history, new, fork, edit, project/tags)**:
+
+```tsx
+import { ChatWithSidebar } from '@contractspec/module.ai-chat';
+
+function FullChat() {
+  return (
+    <ChatWithSidebar
+      systemPrompt="You are a helpful assistant."
+    />
+  );
+}
+```
+
+`ChatWithSidebar` includes a conversation history sidebar (LocalStorage-persisted), New/Fork buttons, message edit, project/tags organization, and a **Thinking Level** picker (instant, thinking, extra thinking, max). Uses `createLocalStorageConversationStore()` by default.
+
+**Basic (no export)**:
+
+```tsx
+import { ChatContainer, ChatMessage, ChatInput } from '@contractspec/module.ai-chat/presentation/components';
+import { useChat } from '@contractspec/module.ai-chat/presentation/hooks';
+
+function BasicChat() {
+  const { messages, sendMessage, isLoading } = useChat();
+
   return (
     <ChatContainer>
-      {messages.map((msg) => (
-        <ChatMessage key={msg.id} message={msg} />
-      ))}
+      {messages.map((msg) => <ChatMessage key={msg.id} message={msg} />)}
       <ChatInput onSend={sendMessage} disabled={isLoading} />
     </ChatContainer>
   );
@@ -104,9 +149,12 @@ function VibeCodingChat() {
 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
+- **Thinking Levels**: `thinkingLevel` option (instant, thinking, extra_thinking, max) maps to Anthropic `budgetTokens` and OpenAI `reasoningEffort`; `ThinkingLevelPicker` in `ChatWithSidebar`
+- **Tools**: Pass `tools` to `ChatServiceConfig` or `useChat`; supports `requireApproval` for approval workflow; optional `workflowToolsConfig` adds workflow creation tools
 - **Message parts**: `ChatMessage` renders reasoning (collapsible), sources (citations), and tool invocations
 - **Markdown**: Inline links and code blocks in message content
+- **Export**: `ChatWithExport` and `ChatExportToolbar` support Markdown (.md), Plain Text (.txt), and JSON (.json); select messages for partial export or export all
+- **Conversation Management**: `ChatWithSidebar` provides history, new conversation, fork, edit messages; `useChat` exposes `createNewConversation`, `editMessage`, `forkConversation`, `updateConversation`; `useConversations` for listing; `createLocalStorageConversationStore()` for persistence
 
 ### Server Route (Full AI SDK + Tool Approval)
 
@@ -137,6 +185,50 @@ const { messages, sendMessage } = useChat({
 
 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.
 
+### Workflow Creation Tools
+
+When `workflowToolsConfig` is provided, the chat can create and modify workflows via AI SDK tools:
+
+```typescript
+import { ChatService, createWorkflowTools } from '@contractspec/module.ai-chat';
+import { WorkflowComposer } from '@contractspec/lib.workflow-composer';
+import { createProvider } from '@contractspec/lib.ai-providers';
+
+const baseWorkflows = [/* your WorkflowSpec[] */];
+const provider = createProvider({ provider: 'anthropic', model: 'claude-sonnet-4' });
+
+const chatService = new ChatService({
+  provider,
+  workflowToolsConfig: {
+    baseWorkflows,
+    composer: new WorkflowComposer(),
+  },
+});
+
+// User can say: "Add a legal review step after validate-invoice"
+// The model will call create_workflow_extension, compose_workflow, generate_workflow_spec_code
+```
+
+Tools: `create_workflow_extension` (validate extensions), `compose_workflow` (apply extensions to base), `generate_workflow_spec_code` (output TypeScript). Export `createWorkflowTools(baseWorkflows, composer)` for manual wiring.
+
+### ModelSelector (Dynamic Model Selection)
+
+Use `modelSelector` to pick models by task dimension (e.g. reasoning vs latency):
+
+```typescript
+import { createModelSelector } from '@contractspec/lib.ai-providers';
+import { ChatService } from '@contractspec/module.ai-chat';
+
+const modelSelector = createModelSelector(/* ranking config */);
+const chatService = new ChatService({
+  provider: createProvider({ /* ... */ }),
+  modelSelector,
+});
+
+// ChatService will call modelSelector.selectAndCreate({ taskDimension: 'reasoning' | 'latency' })
+// based on thinking level when modelSelector is set
+```
+
 ### 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.
@@ -156,6 +248,34 @@ const { completion, complete, isLoading } = useCompletion({
 
 Use `createCompletionRoute` for the API endpoint (see `createChatRoute` pattern).
 
+### Contracts-Spec Context and Surface-Runtime
+
+Pass `contractsContext` to expose agent, data-views, operations, forms, and presentations to the model. Pass `surfacePlanConfig` when embedding chat in a surface-runtime (e.g. PM workbench) to enable the `propose-patch` tool:
+
+```tsx
+import { ChatWithSidebar } from '@contractspec/module.ai-chat';
+import type { ResolvedSurfacePlan } from '@contractspec/lib.surface-runtime/runtime/resolve-bundle';
+
+function PmWorkbench({ plan }: { plan: ResolvedSurfacePlan }) {
+  const [currentPlan, setPlan] = useState(plan);
+  const onPatchProposal = useCallback((proposal) => {
+    setPlan(prev => ({
+      ...prev,
+      ai: { ...prev.ai, proposals: [...(prev.ai?.proposals ?? []), proposal] },
+    }));
+  }, []);
+
+  return (
+    <ChatWithSidebar
+      surfacePlanConfig={{ plan: currentPlan, onPatchProposal }}
+      systemPrompt="You are a PM workbench assistant. Propose layout changes when helpful."
+    />
+  );
+}
+```
+
+`createAiSdkBundleAdapter` from `@contractspec/module.ai-chat/adapters` implements `AiSdkBundleAdapter` for surface-runtime planner integration.
+
 ### 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.

package/dist/adapters/ai-sdk-bundle-adapter.d.ts

@@ -0,0 +1,18 @@
+/**
+ * AiSdkBundleAdapter implementation using ChatService.
+ * Enables surface-runtime to drive chat for planner/requestPatches flows.
+ */
+import type { AiSdkBundleAdapter } from '@contractspec/lib.surface-runtime/adapters/interfaces';
+import type { SurfacePatchProposal } from '@contractspec/lib.surface-runtime/spec/types';
+import type { Provider as ChatProvider } from '@contractspec/lib.ai-providers';
+export interface CreateAiSdkBundleAdapterDeps {
+    /** Provider for creating ChatService (from createProvider) */
+    provider: ChatProvider;
+    /** Called when a patch proposal is produced during requestPatches */
+    onPatchProposal?: (proposal: SurfacePatchProposal) => void;
+}
+/**
+ * Create an AiSdkBundleAdapter that uses ChatService for planner integration.
+ * requestPatches sends the user message to the chat and collects patch proposals from tool calls.
+ */
+export declare function createAiSdkBundleAdapter(deps: CreateAiSdkBundleAdapterDeps): AiSdkBundleAdapter;

package/dist/adapters/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Adapters for integrating ai-chat with external runtimes.
+ */
+export { createAiSdkBundleAdapter, type CreateAiSdkBundleAdapterDeps, } from './ai-sdk-bundle-adapter';