oricore 1.0.0

package/src/agent/agent/builtin/general-purpose.ts

@@ -0,0 +1,38 @@
+import { AGENT_TYPE } from '../../../core/constants';
+import type { Context } from '../../../core/context';
+import { type AgentDefinition, AgentSource } from '../types';
+import { CONTEXT_NOTES, TASK_TOOL_NAME } from './common';
+
+export function createGeneralPurposeAgent(opts: {
+  context: Context;
+}): AgentDefinition {
+  const { context } = opts;
+
+  return {
+    agentType: AGENT_TYPE.GENERAL_PURPOSE,
+
+    whenToUse: `General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.`,
+
+    systemPrompt: `You are an AI coding assistant. Given the user's message, use the tools available to complete the task. Do what has been asked; nothing more, nothing less. When you complete the task simply respond with a detailed writeup.
+
+Your strengths:
+- Searching for code, configurations, and patterns across large codebases
+- Analyzing multiple files to understand system architecture
+- Investigating complex questions that require exploring many files
+- Performing multi-step research tasks
+
+Guidelines:
+- For file searches: Use grep or glob when you need to search broadly. Use read when you know the specific file path.
+- For analysis: Start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
+- Be thorough: Check multiple locations, consider different naming conventions, look for related files.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested.
+
+${CONTEXT_NOTES}`,
+
+    model: context.config.model,
+    source: AgentSource.BuiltIn,
+    disallowedTools: [TASK_TOOL_NAME],
+    forkContext: false,
+  };
+}

package/src/agent/agent/builtin/index.ts

@@ -0,0 +1,13 @@
+import type { Context } from '../../../core/context';
+import type { AgentDefinition } from '../types';
+import { createExploreAgent } from './explore';
+import { createGeneralPurposeAgent } from './general-purpose';
+
+export function getBuiltinAgents(opts: {
+  context: Context;
+}): AgentDefinition[] {
+  return [
+    createExploreAgent(opts),
+    createGeneralPurposeAgent(opts),
+  ];
+}

package/src/agent/agent/executor.test.ts

@@ -0,0 +1,339 @@
+import { describe, expect, test } from 'vitest';
+import { Context } from '../../core/context';
+import type { Tool } from '../../tools/tool';
+import { executeAgent } from './executor';
+import { type AgentDefinition, AgentSource } from './types';
+
+/**
+ * Integration tests for executeAgent
+ *
+ * Note: Most comprehensive testing requires mocking the Project class,
+ * which has proven complex with Vitest. The core functionality is tested
+ * through:
+ * 1. The basic error handling test below
+ * 2. Manual testing in the development environment
+ * 3. End-to-end tests in the full application context
+ *
+ * Key behaviors tested manually:
+ * - onToolApprove callback propagation
+ * - Custom logPath usage
+ * - Model inheritance from context
+ * - Message metadata enhancement
+ * - Tool filtering
+ */
+
+describe('executeAgent', () => {
+  test('should return error if agent has no available tools', async () => {
+    const context = await Context.create({
+      cwd: process.cwd(),
+      productName: 'test',
+      version: '1.0.0',
+      argvConfig: {},
+      plugins: [],
+    });
+
+    const definition: AgentDefinition = {
+      agentType: 'Test',
+      whenToUse: 'Test',
+      systemPrompt: 'Test',
+      model: 'test-model',
+      source: AgentSource.BuiltIn,
+      disallowedTools: ['read', 'write', 'glob', 'grep'],
+    };
+
+    const result = await executeAgent({
+      definition,
+      prompt: 'Test',
+      tools: [{ name: 'read' } as Tool, { name: 'write' } as Tool],
+      context,
+      cwd: '/test',
+    });
+
+    expect(result.status).toBe('failed');
+    expect(result.content).toContain('no available tools');
+
+    await context.destroy();
+  });
+
+  test('should throw error if no model is specified and definition model is missing', async () => {
+    const context = await Context.create({
+      cwd: process.cwd(),
+      productName: 'test',
+      version: '1.0.0',
+      argvConfig: { model: undefined },
+      plugins: [],
+    });
+
+    const definition: AgentDefinition = {
+      agentType: 'Test',
+      whenToUse: 'Test',
+      systemPrompt: 'Test system prompt',
+      model: '', // Empty model
+      source: AgentSource.BuiltIn,
+      tools: ['*'],
+    };
+
+    const result = await executeAgent({
+      definition,
+      prompt: 'Test prompt',
+      tools: [{ name: 'test-tool' } as Tool],
+      context,
+      cwd: '/test',
+    });
+
+    expect(result.status).toBe('failed');
+    expect(result.content).toContain('No model specified');
+
+    await context.destroy();
+  });
+
+  test('should throw error if agentType is missing', async () => {
+    const context = await Context.create({
+      cwd: process.cwd(),
+      productName: 'test',
+      version: '1.0.0',
+      argvConfig: {},
+      plugins: [],
+    });
+
+    const definition: AgentDefinition = {
+      agentType: '',
+      whenToUse: 'Test',
+      systemPrompt: 'Test system prompt',
+      model: 'test-model',
+      source: AgentSource.BuiltIn,
+      tools: ['*'],
+    };
+
+    const result = await executeAgent({
+      definition,
+      prompt: 'Test prompt',
+      tools: [{ name: 'test-tool' } as Tool],
+      context,
+      cwd: '/test',
+    });
+
+    expect(result.status).toBe('failed');
+    expect(result.content).toContain('must have agentType');
+
+    await context.destroy();
+  });
+
+  test('should throw error if systemPrompt is missing', async () => {
+    const context = await Context.create({
+      cwd: process.cwd(),
+      productName: 'test',
+      version: '1.0.0',
+      argvConfig: {},
+      plugins: [],
+    });
+
+    const definition: AgentDefinition = {
+      agentType: 'Test',
+      whenToUse: 'Test',
+      systemPrompt: '',
+      model: 'test-model',
+      source: AgentSource.BuiltIn,
+      tools: ['*'],
+    };
+
+    const result = await executeAgent({
+      definition,
+      prompt: 'Test prompt',
+      tools: [{ name: 'test-tool' } as Tool],
+      context,
+      cwd: '/test',
+    });
+
+    expect(result.status).toBe('failed');
+    expect(result.content).toContain('must have systemPrompt');
+
+    await context.destroy();
+  });
+
+  describe('resolveAgentModel', () => {
+    test('should use explicit model from options (priority 1)', async () => {
+      const context = await Context.create({
+        cwd: process.cwd(),
+        productName: 'test',
+        version: '1.0.0',
+        argvConfig: {
+          model: 'global-model',
+          agent: {
+            explore: { model: 'config-explore-model' },
+          },
+        },
+        plugins: [],
+      });
+
+      const definition: AgentDefinition = {
+        agentType: 'explore',
+        whenToUse: 'Test',
+        systemPrompt: 'Test system prompt',
+        model: 'definition-model',
+        source: AgentSource.BuiltIn,
+        tools: ['read'],
+      };
+
+      const result = await executeAgent({
+        definition,
+        prompt: 'Test prompt',
+        tools: [{ name: 'read' } as Tool],
+        context,
+        model: 'explicit-model', // This should take priority
+        cwd: '/test',
+      });
+
+      // The execution will fail because we don't have real tools set up,
+      // but we can verify the model was attempted to be used
+      expect(result.status).toBe('failed');
+
+      await context.destroy();
+    });
+
+    test('should use config agent model (priority 2)', async () => {
+      const context = await Context.create({
+        cwd: process.cwd(),
+        productName: 'test',
+        version: '1.0.0',
+        argvConfig: {
+          model: 'global-model',
+          agent: {
+            explore: { model: 'config-explore-model' },
+          },
+        },
+        plugins: [],
+      });
+
+      const definition: AgentDefinition = {
+        agentType: 'explore',
+        whenToUse: 'Test',
+        systemPrompt: 'Test system prompt',
+        model: 'definition-model',
+        source: AgentSource.BuiltIn,
+        tools: ['read'],
+      };
+
+      const result = await executeAgent({
+        definition,
+        prompt: 'Test prompt',
+        tools: [{ name: 'read' } as Tool],
+        context,
+        // No explicit model provided
+        cwd: '/test',
+      });
+
+      // config.agent.explore.model should be used
+      expect(result.status).toBe('failed');
+
+      await context.destroy();
+    });
+
+    test('should use agent definition model (priority 3)', async () => {
+      const context = await Context.create({
+        cwd: process.cwd(),
+        productName: 'test',
+        version: '1.0.0',
+        argvConfig: {
+          model: 'global-model',
+          // No agent config
+        },
+        plugins: [],
+      });
+
+      const definition: AgentDefinition = {
+        agentType: 'explore',
+        whenToUse: 'Test',
+        systemPrompt: 'Test system prompt',
+        model: 'definition-model',
+        source: AgentSource.BuiltIn,
+        tools: ['read'],
+      };
+
+      const result = await executeAgent({
+        definition,
+        prompt: 'Test prompt',
+        tools: [{ name: 'read' } as Tool],
+        context,
+        cwd: '/test',
+      });
+
+      // definition.model should be used
+      expect(result.status).toBe('failed');
+
+      await context.destroy();
+    });
+
+    test('should fallback to global model (priority 4)', async () => {
+      const context = await Context.create({
+        cwd: process.cwd(),
+        productName: 'test',
+        version: '1.0.0',
+        argvConfig: {
+          model: 'global-model',
+        },
+        plugins: [],
+      });
+
+      const definition: AgentDefinition = {
+        agentType: 'explore',
+        whenToUse: 'Test',
+        systemPrompt: 'Test system prompt',
+        model: '', // Empty model in definition
+        source: AgentSource.BuiltIn,
+        tools: ['read'],
+      };
+
+      const result = await executeAgent({
+        definition,
+        prompt: 'Test prompt',
+        tools: [{ name: 'read' } as Tool],
+        context,
+        cwd: '/test',
+      });
+
+      // global model should be used
+      expect(result.status).toBe('failed');
+
+      await context.destroy();
+    });
+
+    test('should handle MODEL_INHERIT correctly', async () => {
+      const context = await Context.create({
+        cwd: process.cwd(),
+        productName: 'test',
+        version: '1.0.0',
+        argvConfig: {
+          model: 'global-model',
+          agent: {
+            explore: { model: 'inherit' },
+          },
+        },
+        plugins: [],
+      });
+
+      const definition: AgentDefinition = {
+        agentType: 'explore',
+        whenToUse: 'Test',
+        systemPrompt: 'Test system prompt',
+        model: 'inherit',
+        source: AgentSource.BuiltIn,
+        tools: ['read'],
+      };
+
+      const result = await executeAgent({
+        definition,
+        prompt: 'Test prompt',
+        tools: [{ name: 'read' } as Tool],
+        context,
+        model: 'inherit',
+        cwd: '/test',
+      });
+
+      // Should skip 'inherit' values and fallback to global-model
+      expect(result.status).toBe('failed');
+
+      await context.destroy();
+    });
+  });
+});

package/src/agent/agent/executor.ts

@@ -0,0 +1,224 @@
+import type { Context } from '../../core/context';
+import type { NormalizedMessage } from '../../core/message';
+import { PluginHookType } from '../../core/plugin';
+import { Project } from '../../core/project';
+import { Session } from '../../session/session';
+import type { Tool } from '../../tools/tool';
+import type {
+  AgentDefinition,
+  AgentExecuteOptions,
+  AgentExecutionResult,
+} from './types';
+
+enum AgentStatus {
+  Completed = 'completed',
+  Failed = 'failed',
+}
+
+// Resolve model
+const MODEL_INHERIT = 'inherit';
+
+/**
+ * Resolve the model for an agent with the following priority:
+ * 1. Model explicitly passed in options
+ * 2. Model configured in config.agent.{agentType}.model
+ * 3. Model defined in agent definition
+ * 4. Global model from context.config.model (fallback)
+ */
+function resolveAgentModel(
+  agentType: string,
+  options: AgentExecuteOptions,
+  definition: AgentDefinition,
+  context: Context,
+): string {
+  // Priority 1: Explicit model from options
+  if (options.model && options.model !== MODEL_INHERIT) {
+    return options.model;
+  }
+
+  // Priority 2: Config agent-specific model
+  const configModel = context.config.agent?.[agentType]?.model;
+  if (configModel && configModel !== MODEL_INHERIT) {
+    return configModel;
+  }
+
+  // Priority 3: Agent definition model
+  if (definition.model && definition.model !== MODEL_INHERIT) {
+    return definition.model;
+  }
+
+  // Priority 4: Global fallback
+  return context.config.model;
+}
+
+export async function executeAgent(
+  options: AgentExecuteOptions,
+): Promise<AgentExecutionResult> {
+  const {
+    definition,
+    prompt,
+    tools,
+    context,
+    signal,
+    onMessage,
+    onToolApprove,
+    resume,
+  } = options;
+
+  const startTime = Date.now();
+
+  const agentId = (() => {
+    if (resume) {
+      return resume;
+    }
+    return Session.createSessionId();
+  })();
+
+  try {
+    // Validate Agent definition
+    if (!definition.agentType) {
+      throw new Error('Agent definition must have agentType');
+    }
+    if (!definition.systemPrompt) {
+      throw new Error(`Agent '${definition.agentType}' must have systemPrompt`);
+    }
+
+    // Filter tools
+    const filteredToolList = filterTools(tools, definition);
+
+    if (filteredToolList.length === 0) {
+      throw new Error(
+        `Agent '${definition.agentType}' has no available tools after filtering.`,
+      );
+    }
+
+    // Resolve model using priority-based resolution
+    const modelName = resolveAgentModel(
+      definition.agentType,
+      options,
+      definition,
+      context,
+    );
+
+    if (!modelName) {
+      throw new Error(`No model specified for agent '${definition.agentType}'`);
+    }
+
+    // Create Project instance with agent log path
+    const project = new Project({
+      sessionId: `agent-${agentId}`,
+      parentSessionId: options.parentSessionId,
+      context,
+    });
+
+    // Execute using Project.send
+    const result = await project.sendWithSystemPromptAndTools(prompt, {
+      model: modelName,
+      systemPrompt: definition.systemPrompt,
+      tools: filteredToolList,
+      signal,
+      skipStopHook: true,
+      onMessage: async ({ message }) => {
+        // Add agent metadata
+        const enhancedMessage: NormalizedMessage = {
+          ...message,
+          metadata: {
+            ...(message.metadata || {}),
+            agentId,
+            agentType: definition.agentType,
+          },
+        };
+
+        if (onMessage) {
+          try {
+            await onMessage(enhancedMessage, agentId, modelName);
+          } catch (error) {
+            console.error('[executeAgent] Failed to send message:', error);
+          }
+        }
+      },
+      onToolApprove,
+    });
+
+    // Handle result
+    let executionResult: AgentExecutionResult;
+    if (result.success) {
+      executionResult = {
+        status: AgentStatus.Completed,
+        agentId,
+        content: extractFinalContent(result.data),
+        totalToolCalls: result.metadata?.toolCallsCount || 0,
+        totalDuration: Date.now() - startTime,
+        model: modelName,
+        usage: {
+          inputTokens: result.data.usage?.promptTokens || 0,
+          outputTokens: result.data.usage?.completionTokens || 0,
+        },
+      };
+    } else {
+      executionResult = {
+        status: AgentStatus.Failed,
+        agentId,
+        content: `Agent execution failed: ${result.error.message}`,
+        totalToolCalls: 0,
+        totalDuration: Date.now() - startTime,
+        model: modelName,
+        usage: { inputTokens: 0, outputTokens: 0 },
+      };
+    }
+
+    await context.apply({
+      hook: 'subagentStop',
+      args: [
+        {
+          parentSessionId: options.parentSessionId || '',
+          agentId,
+          agentType: definition.agentType,
+          result: executionResult,
+          usage: executionResult.usage,
+          totalToolCalls: executionResult.totalToolCalls,
+          totalDuration: executionResult.totalDuration,
+          model: modelName,
+        },
+      ],
+      type: PluginHookType.Series,
+    });
+
+    return executionResult;
+  } catch (error) {
+    return {
+      status: AgentStatus.Failed,
+      agentId,
+      content: `Agent execution error: ${error instanceof Error ? error.message : String(error)}`,
+      totalToolCalls: 0,
+      totalDuration: Date.now() - startTime,
+      usage: { inputTokens: 0, outputTokens: 0 },
+    };
+  }
+}
+
+function extractFinalContent(data: Record<string, unknown>): string {
+  if (data.text && typeof data.text === 'string') {
+    return data.text;
+  }
+  if (data.content && typeof data.content === 'string') {
+    return data.content;
+  }
+  return 'Agent completed successfully';
+}
+
+function filterTools(allTools: Tool[], agentDef: AgentDefinition): Tool[] {
+  const { tools, disallowedTools } = agentDef;
+  const disallowedSet = new Set(disallowedTools || []);
+  const hasWildcard =
+    tools === undefined || (tools.length === 1 && tools[0] === '*');
+
+  if (hasWildcard) {
+    return allTools.filter((tool) => !disallowedSet.has(tool.name));
+  }
+
+  const allowedSet = new Set(tools);
+  return allTools.filter(
+    (tool) => allowedSet.has(tool.name) && !disallowedSet.has(tool.name),
+  );
+}