@codeany/open-agent-sdk 0.1.0 → 0.2.1

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,
   }
 }

package/src/types.ts

@@ -2,7 +2,17 @@
  * Core type definitions for the Agent SDK
  */
 
-import type Anthropic from '@anthropic-ai/sdk'
+// Content block types (provider-agnostic, compatible with Anthropic format)
+export type ContentBlockParam =
+  | { type: 'text'; text: string }
+  | { type: 'image'; source: any }
+  | { type: 'tool_use'; id: string; name: string; input: any }
+  | { type: 'tool_result'; tool_use_id: string; content: string | any[]; is_error?: boolean }
+
+export type ContentBlock =
+  | { type: 'text'; text: string }
+  | { type: 'tool_use'; id: string; name: string; input: any }
+  | { type: 'thinking'; thinking: string }
 
 // --------------------------------------------------------------------------
 // Message Types
@@ -12,7 +22,7 @@ export type MessageRole = 'user' | 'assistant'
 
 export interface ConversationMessage {
   role: MessageRole
-  content: string | Anthropic.ContentBlockParam[]
+  content: string | ContentBlockParam[]
 }
 
 export interface UserMessage {
@@ -26,7 +36,7 @@ export interface AssistantMessage {
   type: 'assistant'
   message: {
     role: 'assistant'
-    content: Anthropic.ContentBlock[]
+    content: ContentBlock[]
   }
   uuid: string
   timestamp: string
@@ -57,7 +67,7 @@ export interface SDKAssistantMessage {
   session_id?: string
   message: {
     role: 'assistant'
-    content: Anthropic.ContentBlock[]
+    content: ContentBlock[]
   }
   parent_tool_use_id?: string | null
 }
@@ -181,12 +191,18 @@ export interface ToolInputSchema {
 export interface ToolContext {
   cwd: string
   abortSignal?: AbortSignal
+  /** Parent agent's LLM provider (inherited by subagents) */
+  provider?: import('./providers/types.js').LLMProvider
+  /** Parent agent's model ID */
+  model?: string
+  /** Parent agent's API type */
+  apiType?: import('./providers/types.js').ApiType
 }
 
 export interface ToolResult {
   type: 'tool_result'
   tool_use_id: string
-  content: string | Anthropic.ToolResultBlockParam['content']
+  content: string | any[]
   is_error?: boolean
 }
 
@@ -202,8 +218,10 @@ export type PermissionMode =
   | 'dontAsk'
   | 'auto'
 
+export type PermissionBehavior = 'allow' | 'deny'
+
 export type CanUseToolResult = {
-  behavior: 'allow' | 'deny'
+  behavior: PermissionBehavior
   updatedInput?: unknown
   message?: string
 }
@@ -326,6 +344,11 @@ export interface ModelInfo {
 export interface AgentOptions {
   /** LLM model ID */
   model?: string
+  /**
+   * API type: 'anthropic-messages' or 'openai-completions'.
+   * Falls back to CODEANY_API_TYPE env var. Default: 'anthropic-messages'.
+   */
+  apiType?: import('./providers/types.js').ApiType
   /** API key. Falls back to CODEANY_API_KEY env var. */
   apiKey?: string
   /** API base URL override */
@@ -442,8 +465,8 @@ export interface QueryResult {
 export interface QueryEngineConfig {
   cwd: string
   model: string
-  apiKey?: string
-  baseURL?: string
+  /** LLM provider instance (created from apiType) */
+  provider: import('./providers/types.js').LLMProvider
   tools: ToolDefinition[]
   systemPrompt?: string
   appendSystemPrompt?: string
@@ -456,4 +479,8 @@ export interface QueryEngineConfig {
   includePartialMessages: boolean
   abortSignal?: AbortSignal
   agents?: Record<string, AgentDefinition>
+  /** Hook registry for lifecycle events */
+  hookRegistry?: import('./hooks.js').HookRegistry
+  /** Session ID for hook context */
+  sessionId?: string
 }

package/src/utils/compact.ts

@@ -8,7 +8,8 @@
  * 3. Session memory compaction: consolidates across sessions
  */
 
-import Anthropic from '@anthropic-ai/sdk'
+import type { LLMProvider } from '../providers/types.js'
+import type { NormalizedMessageParam } from '../providers/types.js'
 import {
   estimateMessagesTokens,
   getAutoCompactThreshold,
@@ -38,7 +39,7 @@ export function createAutoCompactState(): AutoCompactState {
  * Check if auto-compaction should trigger.
  */
 export function shouldAutoCompact(
-  messages: Anthropic.MessageParam[],
+  messages: any[],
   model: string,
   state: AutoCompactState,
 ): boolean {
@@ -57,12 +58,12 @@ export function shouldAutoCompact(
  * then replaces the history with a compact summary.
  */
 export async function compactConversation(
-  client: Anthropic,
+  provider: LLMProvider,
   model: string,
-  messages: Anthropic.MessageParam[],
+  messages: any[],
   state: AutoCompactState,
 ): Promise<{
-  compactedMessages: Anthropic.MessageParam[]
+  compactedMessages: NormalizedMessageParam[]
   summary: string
   state: AutoCompactState
 }> {
@@ -73,9 +74,9 @@ export async function compactConversation(
     // Build compaction prompt
     const compactionPrompt = buildCompactionPrompt(strippedMessages)
 
-    const response = await client.messages.create({
+    const response = await provider.createMessage({
       model,
-      max_tokens: 8192,
+      maxTokens: 8192,
       system: 'You are a conversation summarizer. Create a detailed summary of the conversation that preserves all important context, decisions made, files modified, tool outputs, and current state. The summary should allow the conversation to continue seamlessly.',
       messages: [
         {
@@ -86,12 +87,12 @@ export async function compactConversation(
     })
 
     const summary = response.content
-      .filter((b): b is Anthropic.TextBlock => b.type === 'text')
-      .map((b) => b.text)
+      .filter((b) => b.type === 'text')
+      .map((b) => (b as { type: 'text'; text: string }).text)
       .join('\n')
 
     // Replace messages with summary
-    const compactedMessages: Anthropic.MessageParam[] = [
+    const compactedMessages: NormalizedMessageParam[] = [
       {
         role: 'user',
         content: `[Previous conversation summary]\n\n${summary}\n\n[End of summary - conversation continues below]`,
@@ -127,9 +128,9 @@ export async function compactConversation(
  * Strip images from messages for compaction safety.
  */
 function stripImagesFromMessages(
-  messages: Anthropic.MessageParam[],
-): Anthropic.MessageParam[] {
-  return messages.map((msg) => {
+  messages: any[],
+): any[] {
+  return messages.map((msg: any) => {
     if (typeof msg.content === 'string') return msg
 
     const filtered = (msg.content as any[]).filter((block: any) => {
@@ -143,7 +144,7 @@ function stripImagesFromMessages(
 /**
  * Build compaction prompt from messages.
  */
-function buildCompactionPrompt(messages: Anthropic.MessageParam[]): string {
+function buildCompactionPrompt(messages: any[]): string {
   const parts: string[] = ['Please summarize this conversation:\n']
 
   for (const msg of messages) {
@@ -179,10 +180,10 @@ function buildCompactionPrompt(messages: Anthropic.MessageParam[]): string {
  * to fit within token budgets.
  */
 export function microCompactMessages(
-  messages: Anthropic.MessageParam[],
+  messages: any[],
   maxToolResultChars: number = 50000,
-): Anthropic.MessageParam[] {
-  return messages.map((msg) => {
+): any[] {
+  return messages.map((msg: any) => {
     if (typeof msg.content === 'string') return msg
     if (!Array.isArray(msg.content)) return msg