@codeany/open-agent-sdk 0.1.0 → 0.2.0

package/src/skills/bundled/debug.ts

@@ -0,0 +1,48 @@
+/**
+ * Bundled Skill: debug
+ *
+ * Systematic debugging of an issue using structured investigation.
+ */
+
+import { registerSkill } from '../registry.js'
+import type { SkillContentBlock } from '../types.js'
+
+const DEBUG_PROMPT = `Debug the described issue using a systematic approach:
+
+1. **Reproduce**: Understand and reproduce the issue
+   - Read relevant error messages or logs
+   - Identify the failing component
+
+2. **Investigate**: Trace the root cause
+   - Read the relevant source code
+   - Add logging or use debugging tools if needed
+   - Check recent changes that might have introduced the issue (\`git log --oneline -20\`)
+
+3. **Hypothesize**: Form a theory about the cause
+   - State your hypothesis clearly before attempting a fix
+
+4. **Fix**: Implement the minimal fix
+   - Make the smallest change that resolves the issue
+   - Don't refactor unrelated code
+
+5. **Verify**: Confirm the fix works
+   - Run relevant tests
+   - Check for regressions`
+
+export function registerDebugSkill(): void {
+  registerSkill({
+    name: 'debug',
+    description: 'Systematic debugging of an issue using structured investigation.',
+    aliases: ['investigate', 'diagnose'],
+    userInvocable: true,
+    async getPrompt(args): Promise<SkillContentBlock[]> {
+      let prompt = DEBUG_PROMPT
+      if (args.trim()) {
+        prompt += `\n\n## Issue Description\n${args}`
+      } else {
+        prompt += `\n\nAsk the user to describe the issue they're experiencing.`
+      }
+      return [{ type: 'text', text: prompt }]
+    },
+  })
+}

package/src/skills/bundled/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Bundled Skills Initialization
+ *
+ * Registers all built-in skills at SDK startup.
+ */
+
+import { registerSimplifySkill } from './simplify.js'
+import { registerCommitSkill } from './commit.js'
+import { registerReviewSkill } from './review.js'
+import { registerDebugSkill } from './debug.js'
+import { registerTestSkill } from './test.js'
+
+let initialized = false
+
+/**
+ * Initialize all bundled skills.
+ * Safe to call multiple times (idempotent).
+ */
+export function initBundledSkills(): void {
+  if (initialized) return
+  initialized = true
+
+  registerSimplifySkill()
+  registerCommitSkill()
+  registerReviewSkill()
+  registerDebugSkill()
+  registerTestSkill()
+}

package/src/skills/bundled/review.ts

@@ -0,0 +1,41 @@
+/**
+ * Bundled Skill: review
+ *
+ * Review code changes (PR or local diff) for issues and improvements.
+ */
+
+import { registerSkill } from '../registry.js'
+import type { SkillContentBlock } from '../types.js'
+
+const REVIEW_PROMPT = `Review the current code changes for potential issues. Follow these steps:
+
+1. Run \`git diff\` to see uncommitted changes, or \`git diff main...HEAD\` for branch changes
+2. For each changed file, analyze:
+   - **Correctness**: Logic errors, edge cases, off-by-one errors
+   - **Security**: Injection vulnerabilities, auth issues, data exposure
+   - **Performance**: N+1 queries, unnecessary allocations, blocking I/O
+   - **Style**: Naming, consistency with surrounding code, readability
+   - **Testing**: Are the changes adequately tested?
+3. Provide a summary with:
+   - Critical issues (must fix)
+   - Suggestions (nice to have)
+   - Questions (need clarification)
+
+Be specific: reference file names, line numbers, and suggest fixes.`
+
+export function registerReviewSkill(): void {
+  registerSkill({
+    name: 'review',
+    description: 'Review code changes for correctness, security, performance, and style issues.',
+    aliases: ['review-pr', 'cr'],
+    allowedTools: ['Bash', 'Read', 'Glob', 'Grep'],
+    userInvocable: true,
+    async getPrompt(args): Promise<SkillContentBlock[]> {
+      let prompt = REVIEW_PROMPT
+      if (args.trim()) {
+        prompt += `\n\nFocus area: ${args}`
+      }
+      return [{ type: 'text', text: prompt }]
+    },
+  })
+}

package/src/skills/bundled/simplify.ts

@@ -0,0 +1,51 @@
+/**
+ * Bundled Skill: simplify
+ *
+ * Reviews changed code for reuse opportunities, code quality issues,
+ * and efficiency improvements, then fixes any issues found.
+ */
+
+import { registerSkill } from '../registry.js'
+import type { SkillContentBlock } from '../types.js'
+
+const SIMPLIFY_PROMPT = `Review the recently changed code for three categories of improvements. Launch 3 parallel Agent sub-tasks:
+
+## Task 1: Reuse Analysis
+Look for:
+- Duplicated code that could be consolidated
+- Existing utilities or helpers that could replace new code
+- Patterns that should be extracted into shared functions
+- Re-implementations of functionality that already exists elsewhere
+
+## Task 2: Code Quality
+Look for:
+- Overly complex logic that could be simplified
+- Poor naming or unclear intent
+- Missing edge case handling
+- Unnecessary abstractions or over-engineering
+- Dead code or unused imports
+
+## Task 3: Efficiency
+Look for:
+- Unnecessary allocations or copies
+- N+1 query patterns or redundant I/O
+- Blocking operations that could be async
+- Inefficient data structures for the access pattern
+- Unnecessary re-computation
+
+After all three analyses complete, fix any issues found. Prioritize by impact.`
+
+export function registerSimplifySkill(): void {
+  registerSkill({
+    name: 'simplify',
+    description: 'Review changed code for reuse, quality, and efficiency, then fix any issues found.',
+    userInvocable: true,
+    async getPrompt(args): Promise<SkillContentBlock[]> {
+      let prompt = SIMPLIFY_PROMPT
+      if (args.trim()) {
+        prompt += `\n\n## Additional Focus\n${args}`
+      }
+      return [{ type: 'text', text: prompt }]
+    },
+  })
+}

package/src/skills/bundled/test.ts

@@ -0,0 +1,43 @@
+/**
+ * Bundled Skill: test
+ *
+ * Run tests and analyze failures.
+ */
+
+import { registerSkill } from '../registry.js'
+import type { SkillContentBlock } from '../types.js'
+
+const TEST_PROMPT = `Run the project's test suite and analyze the results:
+
+1. **Discover**: Find the test runner configuration
+   - Look for package.json scripts, jest.config, vitest.config, pytest.ini, etc.
+   - Identify the appropriate test command
+
+2. **Execute**: Run the tests
+   - Run the full test suite or specific tests if specified
+   - Capture output including failures and errors
+
+3. **Analyze**: If tests fail:
+   - Read the failing test to understand what it expects
+   - Read the source code being tested
+   - Identify why the test is failing
+   - Fix the issue (in tests or source as appropriate)
+
+4. **Re-verify**: Run the failing tests again to confirm the fix`
+
+export function registerTestSkill(): void {
+  registerSkill({
+    name: 'test',
+    description: 'Run tests and analyze failures, fixing any issues found.',
+    aliases: ['run-tests'],
+    allowedTools: ['Bash', 'Read', 'Write', 'Edit', 'Glob', 'Grep'],
+    userInvocable: true,
+    async getPrompt(args): Promise<SkillContentBlock[]> {
+      let prompt = TEST_PROMPT
+      if (args.trim()) {
+        prompt += `\n\nSpecific test target: ${args}`
+      }
+      return [{ type: 'text', text: prompt }]
+    },
+  })
+}

package/src/skills/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Skills Module - Public API
+ */
+
+// Types
+export type {
+  SkillDefinition,
+  SkillContentBlock,
+  SkillResult,
+} from './types.js'
+
+// Registry
+export {
+  registerSkill,
+  getSkill,
+  getAllSkills,
+  getUserInvocableSkills,
+  hasSkill,
+  unregisterSkill,
+  clearSkills,
+  formatSkillsForPrompt,
+} from './registry.js'
+
+// Bundled skills
+export { initBundledSkills } from './bundled/index.js'

package/src/skills/registry.ts

@@ -0,0 +1,133 @@
+/**
+ * Skill Registry
+ *
+ * Central registry for managing skill definitions.
+ * Skills can be registered programmatically or loaded from bundled definitions.
+ */
+
+import type { SkillDefinition } from './types.js'
+
+/** Internal skill store */
+const skills: Map<string, SkillDefinition> = new Map()
+
+/** Alias -> skill name mapping */
+const aliases: Map<string, string> = new Map()
+
+/**
+ * Register a skill definition.
+ */
+export function registerSkill(definition: SkillDefinition): void {
+  skills.set(definition.name, definition)
+
+  // Register aliases
+  if (definition.aliases) {
+    for (const alias of definition.aliases) {
+      aliases.set(alias, definition.name)
+    }
+  }
+}
+
+/**
+ * Get a skill by name or alias.
+ */
+export function getSkill(name: string): SkillDefinition | undefined {
+  // Direct lookup
+  const direct = skills.get(name)
+  if (direct) return direct
+
+  // Alias lookup
+  const resolved = aliases.get(name)
+  if (resolved) return skills.get(resolved)
+
+  return undefined
+}
+
+/**
+ * Get all registered skills.
+ */
+export function getAllSkills(): SkillDefinition[] {
+  return Array.from(skills.values())
+}
+
+/**
+ * Get all user-invocable skills (for /command listing).
+ */
+export function getUserInvocableSkills(): SkillDefinition[] {
+  return getAllSkills().filter(
+    (s) => s.userInvocable !== false && (!s.isEnabled || s.isEnabled()),
+  )
+}
+
+/**
+ * Check if a skill exists.
+ */
+export function hasSkill(name: string): boolean {
+  return skills.has(name) || aliases.has(name)
+}
+
+/**
+ * Remove a skill.
+ */
+export function unregisterSkill(name: string): boolean {
+  const skill = skills.get(name)
+  if (!skill) return false
+
+  // Remove aliases
+  if (skill.aliases) {
+    for (const alias of skill.aliases) {
+      aliases.delete(alias)
+    }
+  }
+
+  return skills.delete(name)
+}
+
+/**
+ * Clear all skills (for testing).
+ */
+export function clearSkills(): void {
+  skills.clear()
+  aliases.clear()
+}
+
+/**
+ * Format skills listing for system prompt injection.
+ *
+ * Uses a budget system: skills listing gets a limited character budget
+ * to avoid bloating the context window.
+ */
+export function formatSkillsForPrompt(
+  contextWindowTokens?: number,
+): string {
+  const invocable = getUserInvocableSkills()
+  if (invocable.length === 0) return ''
+
+  // Budget: 1% of context window in characters (4 chars per token)
+  const CHARS_PER_TOKEN = 4
+  const DEFAULT_BUDGET = 8000
+  const MAX_DESC_CHARS = 250
+  const budget = contextWindowTokens
+    ? Math.floor(contextWindowTokens * 0.01 * CHARS_PER_TOKEN)
+    : DEFAULT_BUDGET
+
+  const lines: string[] = []
+  let used = 0
+
+  for (const skill of invocable) {
+    const desc = skill.description.length > MAX_DESC_CHARS
+      ? skill.description.slice(0, MAX_DESC_CHARS) + '...'
+      : skill.description
+
+    const trigger = skill.whenToUse
+      ? ` TRIGGER when: ${skill.whenToUse}`
+      : ''
+
+    const line = `- ${skill.name}: ${desc}${trigger}`
+
+    if (used + line.length > budget) break
+    lines.push(line)
+    used += line.length
+  }
+
+  return lines.join('\n')
+}

package/src/skills/types.ts

@@ -0,0 +1,99 @@
+/**
+ * Skill System Types
+ *
+ * Skills are reusable prompt templates that extend agent capabilities.
+ * They can be invoked by the model via the Skill tool or by users via /skillname.
+ */
+
+import type { ToolContext } from '../types.js'
+import type { HookConfig } from '../hooks.js'
+
+/**
+ * Content block for skill prompts (compatible with Anthropic API).
+ */
+export type SkillContentBlock =
+  | { type: 'text'; text: string }
+  | { type: 'image'; source: { type: 'base64'; media_type: string; data: string } }
+
+/**
+ * Bundled skill definition.
+ *
+ * Inspired by Claude Code's skill system. Skills provide specialized
+ * capabilities by injecting context-specific prompts with optional
+ * tool restrictions and model overrides.
+ */
+export interface SkillDefinition {
+  /** Unique skill name (e.g., 'simplify', 'commit') */
+  name: string
+
+  /** Human-readable description */
+  description: string
+
+  /** Alternative names for the skill */
+  aliases?: string[]
+
+  /** When the model should invoke this skill (used in system prompt) */
+  whenToUse?: string
+
+  /** Hint for expected arguments */
+  argumentHint?: string
+
+  /** Tools the skill is allowed to use (empty = all tools) */
+  allowedTools?: string[]
+
+  /** Model override for this skill */
+  model?: string
+
+  /** Whether the skill can be invoked by users via /command */
+  userInvocable?: boolean
+
+  /** Runtime check for availability */
+  isEnabled?: () => boolean
+
+  /** Hook overrides while skill is active */
+  hooks?: HookConfig
+
+  /** Execution context: 'inline' runs in current context, 'fork' spawns a subagent */
+  context?: 'inline' | 'fork'
+
+  /** Subagent type for forked execution */
+  agent?: string
+
+  /**
+   * Generate the prompt content blocks for this skill.
+   *
+   * @param args - User-provided arguments (e.g., from "/simplify focus on error handling")
+   * @param context - Tool execution context (cwd, etc.)
+   * @returns Content blocks to inject into the conversation
+   */
+  getPrompt: (
+    args: string,
+    context: ToolContext,
+  ) => Promise<SkillContentBlock[]>
+}
+
+/**
+ * Result of executing a skill.
+ */
+export interface SkillResult {
+  /** Whether execution succeeded */
+  success: boolean
+
+  /** Skill name that was executed */
+  skillName: string
+
+  /** Execution status */
+  status: 'inline' | 'forked'
+
+  /** Allowed tools override (for inline execution) */
+  allowedTools?: string[]
+
+  /** Model override */
+  model?: string
+
+  /** Result text (for forked execution) */
+  result?: string
+
+  /** Error message */
+  error?: string
+}

package/src/tools/agent-tool.ts

@@ -8,7 +8,7 @@
 import type { ToolDefinition, ToolContext, ToolResult, AgentDefinition } from '../types.js'
 import { QueryEngine } from '../engine.js'
 import { getAllBaseTools, filterTools } from './index.js'
-import { toApiTool } from './types.js'
+import { createProvider, type ApiType } from '../providers/index.js'
 
 // Store for registered agent definitions
 let registeredAgents: Record<string, AgentDefinition> = {}
@@ -101,10 +101,21 @@ export const AgentTool: ToolDefinition = {
     const systemPrompt = agentDef?.prompt ||
       'You are a helpful assistant. Complete the given task using the available tools.'
 
+    // Inherit provider and model from parent agent context, fall back to env vars
+    const subModel = input.model || context.model || process.env.CODEANY_MODEL || 'claude-sonnet-4-6'
+    const provider = context.provider ?? createProvider(
+      (context.apiType || process.env.CODEANY_API_TYPE as ApiType) || 'anthropic-messages',
+      {
+        apiKey: process.env.CODEANY_API_KEY,
+        baseURL: process.env.CODEANY_BASE_URL,
+      },
+    )
+
     // Create subagent engine
     const engine = new QueryEngine({
       cwd: context.cwd,
-      model: input.model || process.env.CODEANY_MODEL || 'claude-sonnet-4-6',
+      model: subModel,
+      provider,
       tools,
       systemPrompt,
       maxTurns: agentDef?.maxTurns || 10,

package/src/tools/index.ts

@@ -62,6 +62,9 @@ import { ConfigTool } from './config-tool.js'
 // Todo
 import { TodoWriteTool } from './todo-tool.js'
 
+// Skill
+import { SkillTool } from './skill-tool.js'
+
 /**
  * All built-in tools (30+).
  */
@@ -125,6 +128,9 @@ const ALL_TOOLS: ToolDefinition[] = [
 
   // Todo
   TodoWriteTool,
+
+  // Skill
+  SkillTool,
 ]
 
 /**
@@ -226,6 +232,8 @@ export {
   ConfigTool,
   // Todo
   TodoWriteTool,
+  // Skill
+  SkillTool,
 }
 
 // Re-export helpers

package/src/tools/skill-tool.ts

@@ -0,0 +1,133 @@
+/**
+ * Skill Tool
+ *
+ * Allows the model to invoke registered skills by name.
+ * Skills are prompt templates that provide specialized capabilities.
+ */
+
+import type { ToolDefinition, ToolResult, ToolContext } from '../types.js'
+import { getSkill, getUserInvocableSkills } from '../skills/registry.js'
+
+export const SkillTool: ToolDefinition = {
+  name: 'Skill',
+  description:
+    'Execute a skill within the current conversation. ' +
+    'Skills provide specialized capabilities and domain knowledge. ' +
+    'Use this tool with the skill name and optional arguments. ' +
+    'Available skills are listed in system-reminder messages.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      skill: {
+        type: 'string',
+        description: 'The skill name to execute (e.g., "commit", "review", "simplify")',
+      },
+      args: {
+        type: 'string',
+        description: 'Optional arguments for the skill',
+      },
+    },
+    required: ['skill'],
+  },
+
+  isReadOnly: () => false,
+  isConcurrencySafe: () => false,
+  isEnabled: () => getUserInvocableSkills().length > 0,
+
+  async prompt(): Promise<string> {
+    const skills = getUserInvocableSkills()
+    if (skills.length === 0) return ''
+
+    const lines = skills.map((s) => {
+      const desc =
+        s.description.length > 200
+          ? s.description.slice(0, 200) + '...'
+          : s.description
+      return `- ${s.name}: ${desc}`
+    })
+
+    return (
+      'Execute a skill within the main conversation.\n\n' +
+      'Available skills:\n' +
+      lines.join('\n') +
+      '\n\nWhen a skill matches the user\'s request, invoke it using the Skill tool.'
+    )
+  },
+
+  async call(input: any, context: ToolContext): Promise<ToolResult> {
+    const skillName: string = input.skill
+    const args: string = input.args || ''
+
+    if (!skillName) {
+      return {
+        type: 'tool_result',
+        tool_use_id: '',
+        content: 'Error: skill name is required',
+        is_error: true,
+      }
+    }
+
+    const skill = getSkill(skillName)
+    if (!skill) {
+      const available = getUserInvocableSkills()
+        .map((s) => s.name)
+        .join(', ')
+      return {
+        type: 'tool_result',
+        tool_use_id: '',
+        content: `Error: Unknown skill "${skillName}". Available skills: ${available || 'none'}`,
+        is_error: true,
+      }
+    }
+
+    // Check if skill is enabled
+    if (skill.isEnabled && !skill.isEnabled()) {
+      return {
+        type: 'tool_result',
+        tool_use_id: '',
+        content: `Error: Skill "${skillName}" is currently disabled`,
+        is_error: true,
+      }
+    }
+
+    try {
+      // Get skill prompt
+      const contentBlocks = await skill.getPrompt(args, context)
+
+      // Convert content blocks to text
+      const promptText = contentBlocks
+        .filter((b): b is { type: 'text'; text: string } => b.type === 'text')
+        .map((b) => b.text)
+        .join('\n\n')
+
+      // Build result with metadata
+      const result: Record<string, unknown> = {
+        success: true,
+        commandName: skill.name,
+        status: skill.context === 'fork' ? 'forked' : 'inline',
+        prompt: promptText,
+      }
+
+      if (skill.allowedTools) {
+        result.allowedTools = skill.allowedTools
+      }
+
+      if (skill.model) {
+        result.model = skill.model
+      }
+
+      return {
+        type: 'tool_result',
+        tool_use_id: '',
+        content: JSON.stringify(result),
+      }
+    } catch (err: any) {
+      return {
+        type: 'tool_result',
+        tool_use_id: '',
+        content: `Error executing skill "${skillName}": ${err.message}`,
+        is_error: true,
+      }
+    }
+  },
+}

package/src/tools/types.ts

@@ -3,7 +3,6 @@
  */
 
 import type { ToolDefinition, ToolInputSchema, ToolContext, ToolResult } from '../types.js'
-import type Anthropic from '@anthropic-ai/sdk'
 
 /**
  * Helper to create a tool definition with sensible defaults.
@@ -52,11 +51,16 @@ export function defineTool(config: {
 
 /**
  * Convert a ToolDefinition to API-compatible tool format.
+ * Returns the normalized tool format used by providers.
  */
-export function toApiTool(tool: ToolDefinition): Anthropic.Tool {
+export function toApiTool(tool: ToolDefinition): {
+  name: string
+  description: string
+  input_schema: ToolInputSchema
+} {
   return {
     name: tool.name,
     description: tool.description,
-    input_schema: tool.inputSchema as Anthropic.Tool.InputSchema,
+    input_schema: tool.inputSchema,
   }
 }