@kirosnn/mosaic 0.0.7

package/src/agent/tools/explore.ts

@@ -0,0 +1,18 @@
+import { tool, type CoreTool } from 'ai';
+import { z } from 'zod';
+import { executeExploreTool } from './exploreExecutor';
+
+export const explore: CoreTool = tool({
+  description: `Explore the codebase autonomously to gather information.
+This tool launches an exploration agent that will use read, glob, grep, and list tools iteratively.
+The agent will continue exploring until it has gathered enough information to answer the purpose.
+Use this for open-ended exploration tasks like understanding code structure, finding implementations, etc.`,
+  parameters: z.object({
+    purpose: z.string().describe('The goal of the exploration - what information you need to gather'),
+  }),
+  execute: async (args) => {
+    const result = await executeExploreTool(args.purpose);
+    if (!result.success) return { error: result.error || 'Unknown error occurred' };
+    return result.result;
+  },
+});

package/src/agent/tools/exploreExecutor.ts

@@ -0,0 +1,320 @@
+import { streamText, tool as createTool } from 'ai';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+import { createMistral } from '@ai-sdk/mistral';
+import { createXai } from '@ai-sdk/xai';
+import { z } from 'zod';
+import { readConfig } from '../../utils/config';
+import { executeTool } from './executor';
+import { getExploreAbortSignal, isExploreAborted, notifyExploreTool } from '../../utils/exploreBridge';
+
+interface ExploreLog {
+  tool: string;
+  args: Record<string, unknown>;
+  success: boolean;
+  resultPreview?: string;
+}
+
+let exploreLogs: ExploreLog[] = [];
+
+const EXPLORE_TIMEOUT = 8 * 60 * 1000;
+
+const EXPLORE_SYSTEM_PROMPT = `You are an exploration agent that gathers information from a codebase.
+
+Your goal is to explore the codebase to fulfill the given purpose. You have access to these tools:
+- read: Read file contents
+- glob: Find files by pattern
+- grep: Search for text in files
+- list: List directory contents
+
+IMPORTANT RULES:
+1. Be thorough but efficient - don't repeat the same searches
+2. When you have gathered enough information to answer the purpose, call the "done" tool with a comprehensive summary
+3. If you cannot find the information after reasonable exploration, call "done" with what you found
+4. Focus on the purpose - don't explore unrelated areas
+5. Summarize findings clearly and include relevant file paths and code snippets
+6. You MUST call the "done" tool when finished - this is the only way to complete the exploration`;
+
+const MAX_STEPS = 50;
+
+interface ExploreResult {
+  success: boolean;
+  result?: string;
+  error?: string;
+}
+
+function createModelProvider(config: { provider: string; model: string; apiKey?: string }) {
+  const cleanApiKey = config.apiKey?.trim().replace(/[\r\n]+/g, '');
+  const cleanModel = config.model.trim().replace(/[\r\n]+/g, '');
+
+  switch (config.provider) {
+    case 'anthropic': {
+      const anthropic = createAnthropic({ apiKey: cleanApiKey });
+      return anthropic(cleanModel);
+    }
+    case 'openai': {
+      const openai = createOpenAI({ apiKey: cleanApiKey });
+      return openai(cleanModel);
+    }
+    case 'google': {
+      const google = createGoogleGenerativeAI({ apiKey: cleanApiKey });
+      return google(cleanModel);
+    }
+    case 'mistral': {
+      const mistral = createMistral({ apiKey: cleanApiKey });
+      return mistral(cleanModel);
+    }
+    case 'xai': {
+      const xai = createXai({ apiKey: cleanApiKey });
+      return xai(cleanModel);
+    }
+    case 'ollama':
+      throw new Error('Ollama provider is not supported for explore tool');
+    default:
+      throw new Error(`Unknown provider: ${config.provider}`);
+  }
+}
+
+let exploreDoneResult: string | null = null;
+
+function getResultPreview(result: string | undefined): string {
+  if (!result) return '';
+  const lines = result.split('\n');
+  if (lines.length <= 3) return result.substring(0, 200);
+  return lines.slice(0, 3).join('\n').substring(0, 200) + '...';
+}
+
+function createExploreTools() {
+  return {
+    read: createTool({
+      description: 'Read the contents of a file',
+      parameters: z.object({
+        path: z.string().describe('Path to the file to read'),
+      }),
+      execute: async (args) => {
+        if (isExploreAborted()) return { error: 'Exploration aborted' };
+        const result = await executeTool('read', args);
+        const resultLen = result.result?.length || 0;
+        const preview = result.success ? `${(result.result || '').split('\n').length} lines` : (result.error || 'error');
+        exploreLogs.push({ tool: 'read', args, success: result.success, resultPreview: preview });
+        notifyExploreTool('read', args, { success: result.success, preview }, resultLen);
+        if (!result.success) return { error: result.error };
+        return result.result;
+      },
+    }),
+    glob: createTool({
+      description: 'Find files matching a glob pattern',
+      parameters: z.object({
+        pattern: z.string().describe('Glob pattern to match files (e.g., "**/*.ts", "src/**/*.tsx")'),
+        path: z.string().optional().describe('Directory to search in (default: workspace root)'),
+      }),
+      execute: async (args) => {
+        if (isExploreAborted()) return { error: 'Exploration aborted' };
+        const result = await executeTool('glob', args);
+        const resultLen = result.result?.length || 0;
+        let preview = result.error || 'error';
+        if (result.success && result.result) {
+          try {
+            const files = JSON.parse(result.result);
+            preview = `${Array.isArray(files) ? files.length : 0} files`;
+          } catch { preview = 'ok'; }
+        }
+        exploreLogs.push({ tool: 'glob', args, success: result.success, resultPreview: preview });
+        notifyExploreTool('glob', args, { success: result.success, preview }, resultLen);
+        if (!result.success) return { error: result.error };
+        return result.result;
+      },
+    }),
+    grep: createTool({
+      description: 'Search for text content within files',
+      parameters: z.object({
+        pattern: z.string().describe('Glob pattern to match files'),
+        query: z.string().describe('Text to search for'),
+        path: z.string().optional().describe('Directory to search in'),
+        case_sensitive: z.boolean().optional().describe('Case-sensitive search'),
+        max_results: z.number().optional().describe('Maximum results'),
+      }),
+      execute: async (args) => {
+        if (isExploreAborted()) return { error: 'Exploration aborted' };
+        const result = await executeTool('grep', args);
+        const resultLen = result.result?.length || 0;
+        let preview = result.error || 'error';
+        if (result.success && result.result) {
+          try {
+            const matches = JSON.parse(result.result);
+            preview = `${Array.isArray(matches) ? matches.length : 0} matches`;
+          } catch { preview = 'ok'; }
+        }
+        exploreLogs.push({ tool: 'grep', args, success: result.success, resultPreview: preview });
+        notifyExploreTool('grep', args, { success: result.success, preview }, resultLen);
+        if (!result.success) return { error: result.error };
+        return result.result;
+      },
+    }),
+    list: createTool({
+      description: 'List files and directories',
+      parameters: z.object({
+        path: z.string().describe('Path to list'),
+        recursive: z.boolean().optional().describe('List recursively'),
+        filter: z.string().optional().describe('Filter pattern'),
+        include_hidden: z.boolean().optional().describe('Include hidden files'),
+      }),
+      execute: async (args) => {
+        if (isExploreAborted()) return { error: 'Exploration aborted' };
+        const result = await executeTool('list', args);
+        const resultLen = result.result?.length || 0;
+        let preview = result.error || 'error';
+        if (result.success && result.result) {
+          try {
+            const items = JSON.parse(result.result);
+            preview = `${Array.isArray(items) ? items.length : 0} items`;
+          } catch { preview = 'ok'; }
+        }
+        exploreLogs.push({ tool: 'list', args, success: result.success, resultPreview: preview });
+        notifyExploreTool('list', args, { success: result.success, preview }, resultLen);
+        if (!result.success) return { error: result.error };
+        return result.result;
+      },
+    }),
+    done: createTool({
+      description: 'Call this when you have gathered enough information. Provide a comprehensive summary of your findings. This MUST be called to complete the exploration.',
+      parameters: z.object({
+        summary: z.string().describe('Comprehensive summary of what was found during exploration'),
+      }),
+      execute: async (args) => {
+        exploreDoneResult = args.summary;
+        return { done: true, summary: args.summary };
+      },
+    }),
+  };
+}
+
+function formatExploreLogs(): string {
+  if (exploreLogs.length === 0) return '';
+
+  const lines = ['Tools used:'];
+  for (const log of exploreLogs) {
+    const argStr = log.args.path || log.args.pattern || log.args.query || '';
+    const status = log.success ? '+' : '-';
+    lines.push(`  ${status} ${log.tool}(${argStr}) -> ${log.resultPreview || 'ok'}`);
+  }
+  return lines.join('\n');
+}
+
+function formatDuration(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+  return `${minutes}m ${remainingSeconds}s`;
+}
+
+export async function executeExploreTool(purpose: string): Promise<ExploreResult> {
+  const startTime = Date.now();
+  const userConfig = readConfig();
+
+  if (!userConfig.provider || !userConfig.model) {
+    return {
+      success: false,
+      error: 'No provider or model configured',
+    };
+  }
+
+  exploreDoneResult = null;
+  exploreLogs = [];
+
+  const abortSignal = getExploreAbortSignal();
+  const timeoutId = setTimeout(() => {
+    if (!exploreDoneResult) {
+      exploreDoneResult = '[Exploration timed out after 8 minutes]';
+    }
+  }, EXPLORE_TIMEOUT);
+
+  try {
+    const model = createModelProvider({
+      provider: userConfig.provider,
+      model: userConfig.model,
+      apiKey: userConfig.apiKey,
+    });
+
+    const tools = createExploreTools();
+
+    const result = streamText({
+      model,
+      messages: [
+        {
+          role: 'user',
+          content: `Explore the codebase to: ${purpose}`,
+        },
+      ],
+      system: EXPLORE_SYSTEM_PROMPT,
+      tools,
+      maxSteps: MAX_STEPS,
+      abortSignal,
+    });
+
+    let lastError: string | null = null;
+
+    for await (const chunk of result.fullStream as any) {
+      if (isExploreAborted()) {
+        break;
+      }
+      const c: any = chunk;
+      if (c.type === 'error') {
+        lastError = c.error instanceof Error ? c.error.message : String(c.error);
+      }
+      if (exploreDoneResult !== null) {
+        break;
+      }
+    }
+
+    clearTimeout(timeoutId);
+    const duration = formatDuration(Date.now() - startTime);
+
+    if (isExploreAborted()) {
+      const logsStr = formatExploreLogs();
+      return {
+        success: false,
+        error: `Exploration interrupted (${duration})${logsStr ? '\n\n' + logsStr : ''}`,
+      };
+    }
+
+    if (lastError && exploreLogs.length === 0) {
+      return {
+        success: false,
+        error: lastError,
+      };
+    }
+
+    const logsStr = formatExploreLogs();
+
+    if (exploreDoneResult !== null) {
+      return {
+        success: true,
+        result: `Completed in ${duration}\n${logsStr}\n\nSummary:\n${exploreDoneResult}`,
+      };
+    }
+
+    return {
+      success: true,
+      result: `Completed in ${duration}\n${logsStr}\n\nExploration completed after ${MAX_STEPS} steps without explicit summary.`,
+    };
+  } catch (error) {
+    clearTimeout(timeoutId);
+    const duration = formatDuration(Date.now() - startTime);
+    const logsStr = formatExploreLogs();
+
+    if (isExploreAborted()) {
+      return {
+        success: false,
+        error: `Exploration interrupted (${duration})${logsStr ? '\n\n' + logsStr : ''}`,
+      };
+    }
+
+    return {
+      success: false,
+      error: `${error instanceof Error ? error.message : 'Unknown error'} (${duration})${logsStr ? '\n\n' + logsStr : ''}`,
+    };
+  }
+}

package/src/agent/tools/glob.ts

@@ -0,0 +1,16 @@
+import { tool, type CoreTool } from 'ai';
+import { z } from 'zod';
+import { executeTool } from './executor';
+
+export const glob: CoreTool = tool({
+  description: 'Find files matching a glob pattern. Fast pattern-based file discovery.',
+  parameters: z.object({
+    pattern: z.string().describe('Glob pattern to match files (e.g., "*.ts", "**/*.tsx", "src/**/*.js")'),
+    path: z.string().nullable().optional().describe('Directory to search in (use null for workspace root)'),
+  }),
+  execute: async (args) => {
+    const result = await executeTool('glob', args);
+    if (!result.success) return { error: result.error || 'Unknown error occurred' };
+    return result.result;
+  },
+});

package/src/agent/tools/grep.ts

@@ -0,0 +1,19 @@
+import { tool, type CoreTool } from 'ai';
+import { z } from 'zod';
+import { executeTool } from './executor';
+
+export const grep: CoreTool = tool({
+  description: 'Search for text content within files matching a glob pattern. Combines pattern matching with content search.',
+  parameters: z.object({
+    pattern: z.string().describe('Glob pattern to match files (e.g., "*.ts", "**/*.tsx", "src/**/*.js")'),
+    query: z.string().describe('Text content to search for within the matched files'),
+    path: z.string().nullable().optional().describe('Directory to search in (use null for workspace root)'),
+    case_sensitive: z.boolean().nullable().optional().describe('Whether text search should be case-sensitive (use null for false)'),
+    max_results: z.number().nullable().optional().describe('Maximum number of results to return (use null for 100)'),
+  }),
+  execute: async (args) => {
+    const result = await executeTool('grep', args);
+    if (!result.success) return { error: result.error || 'Unknown error occurred' };
+    return result.result;
+  },
+});

package/src/agent/tools/index.ts

@@ -0,0 +1,4 @@
+export { tools } from './definitions';
+export type { CoreTool } from 'ai';
+export { executeTool } from './executor';
+export type { ToolResult } from './executor';

package/src/agent/tools/list.ts

@@ -0,0 +1,20 @@
+import { tool, type CoreTool } from 'ai';
+import { z } from 'zod';
+import { executeTool } from './executor';
+
+export const list: CoreTool = tool({
+  description: 'List files and directories in a directory with optional recursive listing and filtering',
+  parameters: z.object({
+    path: z
+      .string()
+      .describe('The path to the directory relative to the workspace root. Use "." for the root directory.'),
+    recursive: z.boolean().nullable().optional().describe('If true, list files recursively in all subdirectories (use null for false)'),
+    filter: z.string().nullable().optional().describe('Optional glob pattern to filter results (use null for no filter)'),
+    include_hidden: z.boolean().nullable().optional().describe('If true, include hidden files (starting with .) (use null for false)'),
+  }),
+  execute: async (args) => {
+    const result = await executeTool('list', args);
+    if (!result.success) return { error: result.error || 'Unknown error occurred' };
+    return result.result;
+  },
+});

package/src/agent/tools/question.ts

@@ -0,0 +1,20 @@
+import { tool, type CoreTool } from 'ai';
+import { z } from 'zod';
+import { askQuestion } from '../../utils/questionBridge';
+
+export const question: CoreTool = tool({
+  description: 'Ask the user a question with predefined options and wait for their selection. The user can select one of the options OR type a custom response directly in the text input field below the options. The returned answer includes: index (selected option index), label (option label), value (option value if set), and customText (if user provided a custom text response).',
+  parameters: z.object({
+    prompt: z.string().describe('The question to show to the user.'),
+    options: z.array(
+      z.object({
+        label: z.string().describe('The option label shown to the user.'),
+        value: z.string().nullable().optional().describe('Optional value returned for the selected option. Use null if not needed.'),
+      })
+    ).describe('List of options the user can pick from. A text input field is automatically displayed below the options where the user can type a custom response instead.'),
+  }),
+  execute: async (args) => {
+    const answer = await askQuestion(args.prompt, args.options);
+    return answer;
+  },
+});

package/src/agent/tools/read.ts

@@ -0,0 +1,15 @@
+import { tool, type CoreTool } from 'ai';
+import { z } from 'zod';
+import { executeTool } from './executor';
+
+export const read: CoreTool = tool({
+  description: 'Read the contents of a file from the workspace',
+  parameters: z.object({
+    path: z.string().describe('The path to the file relative to the workspace root'),
+  }),
+  execute: async (args) => {
+    const result = await executeTool('read', args);
+    if (!result.success) return { error: result.error || 'Unknown error occurred' };
+    return result.result;
+  },
+});

package/src/agent/tools/write.ts

@@ -0,0 +1,21 @@
+import { tool, type CoreTool } from 'ai';
+import { z } from 'zod';
+import { executeTool } from './executor';
+
+export const write: CoreTool = tool({
+  description: 'Write or overwrite a file in the workspace. Creates parent directories automatically if they do not exist. IMPORTANT: This operation requires user approval - the user will see a preview and must approve before the file is written. If rejected, ask the user for clarification using the question tool.',
+  parameters: z.object({
+    path: z.string().describe('The path to the file relative to the workspace root'),
+    content: z.string().nullable().optional().transform((v) => v ?? '').describe('The content to write to the file (use null for empty string)'),
+    append: z.boolean().nullable().optional().transform((v) => v ?? false).describe('If true, append to the file instead of overwriting (use null for false)'),
+  }),
+  execute: async (args) => {
+    const result = await executeTool('write', args);
+    if (!result.success) {
+      return result.userMessage
+        ? { error: result.error, userMessage: result.userMessage }
+        : { error: result.error };
+    }
+    return result;
+  },
+});

package/src/agent/types.ts

@@ -0,0 +1,155 @@
+import { CoreMessage, CoreTool } from 'ai';
+
+export type AgentEventType =
+  | 'text-delta'
+  | 'reasoning-start'
+  | 'reasoning-delta'
+  | 'reasoning-end'
+  | 'tool-input-start'
+  | 'tool-input-delta'
+  | 'tool-input-end'
+  | 'tool-call-start'
+  | 'tool-call-end'
+  | 'tool-result'
+  | 'step-start'
+  | 'step-finish'
+  | 'finish'
+  | 'error';
+
+export interface BaseEvent {
+  type: AgentEventType;
+}
+
+export interface TextDeltaEvent extends BaseEvent {
+  type: 'text-delta';
+  content: string;
+}
+
+export interface ReasoningStartEvent extends BaseEvent {
+  type: 'reasoning-start';
+}
+
+export interface ReasoningDeltaEvent extends BaseEvent {
+  type: 'reasoning-delta';
+  content: string;
+}
+
+export interface ReasoningEndEvent extends BaseEvent {
+  type: 'reasoning-end';
+}
+
+export interface ToolInputStartEvent extends BaseEvent {
+  type: 'tool-input-start';
+  toolCallId: string;
+  toolName: string;
+}
+
+export interface ToolInputDeltaEvent extends BaseEvent {
+  type: 'tool-input-delta';
+  toolCallId: string;
+  delta: string;
+}
+
+export interface ToolInputEndEvent extends BaseEvent {
+  type: 'tool-input-end';
+  toolCallId: string;
+}
+
+export interface ToolCallStartEvent extends BaseEvent {
+  type: 'tool-call-start';
+  toolCallId: string;
+  toolName: string;
+}
+
+export interface ToolCallEndEvent extends BaseEvent {
+  type: 'tool-call-end';
+  toolCallId: string;
+  toolName: string;
+  args: Record<string, unknown>;
+}
+
+export interface ToolResultEvent extends BaseEvent {
+  type: 'tool-result';
+  toolCallId: string;
+  toolName: string;
+  result: unknown;
+}
+
+export interface StepStartEvent extends BaseEvent {
+  type: 'step-start';
+  stepNumber: number;
+}
+
+export interface StepFinishEvent extends BaseEvent {
+  type: 'step-finish';
+  stepNumber: number;
+  finishReason: string;
+}
+
+export interface FinishEvent extends BaseEvent {
+  type: 'finish';
+  finishReason: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+}
+
+export interface ErrorEvent extends BaseEvent {
+  type: 'error';
+  error: string;
+}
+
+export type AgentEvent =
+  | TextDeltaEvent
+  | ReasoningStartEvent
+  | ReasoningDeltaEvent
+  | ReasoningEndEvent
+  | ToolInputStartEvent
+  | ToolInputDeltaEvent
+  | ToolInputEndEvent
+  | ToolCallStartEvent
+  | ToolCallEndEvent
+  | ToolResultEvent
+  | StepStartEvent
+  | StepFinishEvent
+  | FinishEvent
+  | ErrorEvent;
+
+export interface ProviderConfig {
+  provider: string;
+  model: string;
+  apiKey?: string;
+  systemPrompt: string;
+  tools?: Record<string, CoreTool>;
+  maxSteps?: number;
+}
+
+export interface AgentConfig {
+  maxSteps?: number;
+}
+
+export interface AgentContext {
+  messages: CoreMessage[];
+  systemPrompt: string;
+  tools: Record<string, CoreTool>;
+  config: AgentConfig;
+}
+
+export interface AgentMessage {
+  role: 'user' | 'assistant';
+  content: string;
+}
+
+export interface ProviderSendOptions {
+  abortSignal?: AbortSignal;
+}
+
+export interface Provider {
+  sendMessage(
+    messages: CoreMessage[],
+    config: ProviderConfig,
+    options?: ProviderSendOptions
+  ): AsyncGenerator<AgentEvent>;
+}