@contractspec/module.ai-chat 4.0.2 → 4.1.0

package/dist/core/agent-adapter.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Adapter interface for agent mode in ai-chat.
+ * Allows ContractSpecAgent or UnifiedAgent to be used as the chat backend.
+ */
+export interface ChatAgentAdapter {
+    generate(params: {
+        prompt: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        text: string;
+        toolCalls?: Array<{
+            toolCallId: string;
+            toolName: string;
+            args: unknown;
+        }>;
+        toolResults?: Array<{
+            toolCallId: string;
+            toolName: string;
+            output: unknown;
+        }>;
+        usage?: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+    }>;
+}
+/**
+ * Wraps a ContractSpecAgent or similar agent for use with useChat agent mode.
+ * Maps AgentGenerateResult to ChatAgentAdapter format.
+ */
+export declare function createChatAgentAdapter(agent: {
+    generate(params: {
+        prompt: string;
+        systemOverride?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        text: string;
+        toolCalls?: Array<{
+            toolCallId: string;
+            toolName: string;
+            args: unknown;
+        }>;
+        toolResults?: Array<{
+            toolCallId: string;
+            toolName: string;
+            output: unknown;
+        }>;
+        usage?: {
+            inputTokens: number;
+            outputTokens: number;
+        };
+    }>;
+}): ChatAgentAdapter;

package/dist/core/agent-tools-adapter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Converts AgentToolConfig from ai-agent to AI SDK ToolSet.
+ * Handlers are optional; when missing, execute returns unimplemented stub.
+ */
+import { type ToolSet } from 'ai';
+import type { AgentToolConfig } from '@contractspec/lib.ai-agent';
+export type ToolHandler = (input: Record<string, unknown>) => Promise<unknown> | unknown;
+/**
+ * Convert AgentToolConfig array to AI SDK ToolSet.
+ * When handler is missing, execute returns { status: 'unimplemented', message: 'Wire handler in host' }.
+ */
+export declare function agentToolConfigsToToolSet(configs: AgentToolConfig[], handlers?: Record<string, ToolHandler>): ToolSet;

package/dist/core/chat-service.d.ts

@@ -3,9 +3,15 @@
  */
 import { type ToolSet } from 'ai';
 import type { Provider as ChatProvider } from '@contractspec/lib.ai-providers';
+import type { ModelSelector } from '@contractspec/lib.ai-providers/selector-types';
+import type { WorkflowComposer } from '@contractspec/lib.workflow-composer';
+import type { WorkflowSpec } from '@contractspec/lib.contracts-spec/workflow';
 import type { WorkspaceContext } from '../context/workspace-context';
 import type { ConversationStore } from './conversation-store';
-import type { ChatConversation, SendMessageOptions, SendMessageResult, StreamMessageResult } from './message-types';
+import { type ThinkingLevel } from './thinking-levels';
+import { type ContractsContextConfig } from './contracts-context';
+import type { ResolvedSurfacePlan } from '@contractspec/lib.surface-runtime/runtime/resolve-bundle';
+import type { ChatConversation, ChatMessage, SendMessageOptions, SendMessageResult, StreamMessageResult } from './message-types';
 /**
  * Configuration for ChatService
  */
@@ -33,10 +39,28 @@ export interface ChatServiceConfig {
     authHeaders?: Record<string, string>;
     /** Tools for the model to call (AI SDK ToolSet) */
     tools?: ToolSet;
+    /** Thinking level: instant, thinking, extra_thinking, max. Maps to provider reasoning options. */
+    thinkingLevel?: ThinkingLevel;
     /** Enable reasoning parts in stream (Deepseek R1, Claude extended thinking) */
     sendReasoning?: boolean;
     /** Enable source citations in stream (e.g. Perplexity Sonar) */
     sendSources?: boolean;
+    /** Workflow creation tools: base workflows and optional composer */
+    workflowToolsConfig?: {
+        baseWorkflows: WorkflowSpec[];
+        composer?: WorkflowComposer;
+    };
+    /** Optional model selector for dynamic model selection by task dimension */
+    modelSelector?: ModelSelector;
+    /** Contracts-spec context: agent, data-views, operations, forms, presentations */
+    contractsContext?: ContractsContextConfig;
+    /** Surface plan config: enables propose-patch tool when used in surface-runtime */
+    surfacePlanConfig?: {
+        plan: ResolvedSurfacePlan;
+        onPatchProposal?: (proposal: import('@contractspec/lib.surface-runtime/spec/types').SurfacePatchProposal) => void;
+    };
+    /** MCP tools (from createMcpToolsets); merged when provided */
+    mcpTools?: ToolSet;
 }
 /**
  * Main chat service for AI-powered conversations
@@ -49,9 +73,15 @@ export declare class ChatService {
     private readonly maxHistoryMessages;
     private readonly onUsage?;
     private readonly tools?;
+    private readonly thinkingLevel?;
     private readonly sendReasoning;
     private readonly sendSources;
+    private readonly modelSelector?;
     constructor(config: ChatServiceConfig);
+    private buildSystemPrompt;
+    private mergeTools;
+    private resolveModel;
+    private thinkingLevelToDimension;
     /**
      * Send a message and get a complete response
      */
@@ -68,9 +98,27 @@ export declare class ChatService {
      * List conversations
      */
     listConversations(options?: {
+        projectId?: string;
+        tags?: string[];
         limit?: number;
         offset?: number;
     }): Promise<ChatConversation[]>;
+    /**
+     * Update conversation properties (title, project, tags, etc.)
+     */
+    updateConversation(conversationId: string, updates: Parameters<ConversationStore['update']>[1]): Promise<ChatConversation | null>;
+    /**
+     * Fork a conversation, optionally up to a specific message
+     */
+    forkConversation(conversationId: string, upToMessageId?: string): Promise<ChatConversation>;
+    /**
+     * Update a message in a conversation
+     */
+    updateMessage(conversationId: string, messageId: string, updates: Partial<ChatMessage>): Promise<ChatMessage | null>;
+    /**
+     * Truncate messages after the given message (for edit/regenerate)
+     */
+    truncateAfter(conversationId: string, messageId: string): Promise<ChatConversation | null>;
     /**
      * Delete a conversation
      */

package/dist/core/contracts-context.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Contracts-spec context for ai-chat.
+ * Exposes agent, data-views, operations, forms, and presentations to the model.
+ */
+import type { AgentToolConfig } from '@contractspec/lib.ai-agent';
+export interface ContractsContextConfig {
+    /** Agent specs (for tool schemas, instructions) */
+    agentSpecs?: Array<{
+        key: string;
+        tools?: AgentToolConfig[];
+    }>;
+    /** Data view specs (for query suggestions, filters) */
+    dataViewSpecs?: Array<{
+        key: string;
+        meta: {
+            title?: string;
+        };
+        source?: unknown;
+    }>;
+    /** Form specs (for rendering or generating form configs) */
+    formSpecs?: Array<{
+        key: string;
+        meta: {
+            title?: string;
+        };
+        fields?: unknown[];
+    }>;
+    /** Presentation specs (for rendering tool outputs) */
+    presentationSpecs?: Array<{
+        key: string;
+        meta: {
+            title?: string;
+        };
+        targets?: string[];
+    }>;
+    /** Operation refs the chat can invoke via tools */
+    operationRefs?: Array<{
+        key: string;
+        version: string;
+    }>;
+}
+/**
+ * Builds a prompt section describing available contracts-spec resources.
+ * Append to system prompt when contractsContext is set.
+ */
+export declare function buildContractsContextPrompt(config: ContractsContextConfig): string;

package/dist/core/contracts-context.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/conversation-store.d.ts

@@ -17,7 +17,7 @@ export interface ConversationStore {
     /**
      * Update conversation properties
      */
-    update(conversationId: string, updates: Partial<Pick<ChatConversation, 'title' | 'status' | 'summary' | 'metadata'>>): Promise<ChatConversation | null>;
+    update(conversationId: string, updates: Partial<Pick<ChatConversation, 'title' | 'status' | 'summary' | 'metadata' | 'projectId' | 'projectName' | 'tags'>>): Promise<ChatConversation | null>;
     /**
      * Append a message to a conversation
      */
@@ -35,9 +35,19 @@ export interface ConversationStore {
      */
     list(options?: {
         status?: ConversationStatus;
+        projectId?: string;
+        tags?: string[];
         limit?: number;
         offset?: number;
     }): Promise<ChatConversation[]>;
+    /**
+     * Fork a conversation, optionally up to a specific message
+     */
+    fork(conversationId: string, upToMessageId?: string): Promise<ChatConversation>;
+    /**
+     * Remove all messages after the given message (for edit/regenerate flow)
+     */
+    truncateAfter(conversationId: string, messageId: string): Promise<ChatConversation | null>;
     /**
      * Search conversations by content
      */
@@ -50,15 +60,19 @@ export declare class InMemoryConversationStore implements ConversationStore {
     private readonly conversations;
     get(conversationId: string): Promise<ChatConversation | null>;
     create(conversation: Omit<ChatConversation, 'id' | 'createdAt' | 'updatedAt'>): Promise<ChatConversation>;
-    update(conversationId: string, updates: Partial<Pick<ChatConversation, 'title' | 'status' | 'summary' | 'metadata'>>): Promise<ChatConversation | null>;
+    update(conversationId: string, updates: Partial<Pick<ChatConversation, 'title' | 'status' | 'summary' | 'metadata' | 'projectId' | 'projectName' | 'tags'>>): Promise<ChatConversation | null>;
     appendMessage(conversationId: string, message: Omit<ChatMessage, 'id' | 'conversationId' | 'createdAt' | 'updatedAt'>): Promise<ChatMessage>;
     updateMessage(conversationId: string, messageId: string, updates: Partial<ChatMessage>): Promise<ChatMessage | null>;
     delete(conversationId: string): Promise<boolean>;
     list(options?: {
         status?: ConversationStatus;
+        projectId?: string;
+        tags?: string[];
         limit?: number;
         offset?: number;
     }): Promise<ChatConversation[]>;
+    fork(conversationId: string, upToMessageId?: string): Promise<ChatConversation>;
+    truncateAfter(conversationId: string, messageId: string): Promise<ChatConversation | null>;
     search(query: string, limit?: number): Promise<ChatConversation[]>;
     /**
      * Clear all conversations (for testing)

package/dist/core/create-chat-route.d.ts

@@ -15,6 +15,7 @@
  */
 import { type ToolSet } from 'ai';
 import type { Provider as ChatProvider } from '@contractspec/lib.ai-providers';
+import type { ThinkingLevel } from './thinking-levels';
 export interface CreateChatRouteOptions {
     /** LLM provider (from createProvider) */
     provider: ChatProvider;
@@ -22,6 +23,8 @@ export interface CreateChatRouteOptions {
     systemPrompt?: string;
     /** Tools for the model */
     tools?: ToolSet;
+    /** Default thinking level (can be overridden by request body) */
+    thinkingLevel?: ThinkingLevel;
 }
 /**
  * Create a route handler that streams chat using streamText + toUIMessageStreamResponse.

package/dist/core/export-formatters.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Export formatters for chat conversations
+ * Pure functions to convert ChatMessage[] to Markdown, TXT, or JSON.
+ */
+import type { ChatMessage, ChatConversation } from './message-types';
+/**
+ * Format messages as Markdown
+ */
+export declare function formatMessagesAsMarkdown(messages: ChatMessage[]): string;
+/**
+ * Format messages as plain text
+ */
+export declare function formatMessagesAsTxt(messages: ChatMessage[]): string;
+/**
+ * Format messages as JSON with optional conversation metadata
+ */
+export declare function formatMessagesAsJson(messages: ChatMessage[], conversation?: ChatConversation | null): string;
+/**
+ * Generate export filename
+ */
+export declare function getExportFilename(format: 'markdown' | 'txt' | 'json', conversation?: ChatConversation | null): string;
+/**
+ * Download content as a file
+ */
+export declare function downloadAsFile(content: string, filename: string, mimeType: string): void;
+/**
+ * Export messages to a file (convenience helper)
+ */
+export declare function exportToFile(messages: ChatMessage[], format: 'markdown' | 'txt' | 'json', conversation?: ChatConversation | null): void;

package/dist/core/export-formatters.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/index.d.ts

@@ -6,3 +6,11 @@ export * from './conversation-store';
 export * from './chat-service';
 export * from './create-chat-route';
 export * from './create-completion-route';
+export * from './export-formatters';
+export * from './local-storage-conversation-store';
+export * from './thinking-levels';
+export * from './workflow-tools';
+export * from './contracts-context';
+export * from './agent-tools-adapter';
+export * from './surface-planner-tools';
+export * from './agent-adapter';