@codeany/open-agent-sdk 0.1.0 → 0.2.1

package/src/engine.ts

@@ -4,7 +4,7 @@
  * Manages the full conversation lifecycle:
  * 1. Take user prompt
  * 2. Build system prompt with context (git status, project context, tools)
- * 3. Call LLM API with tools
+ * 3. Call LLM API with tools (via provider abstraction)
  * 4. Stream response
  * 5. Execute tool calls (concurrent for read-only, serial for mutations)
  * 6. Send results back, repeat until done
@@ -12,7 +12,6 @@
  * 8. Retry with exponential backoff on transient errors
  */
 
-import Anthropic from '@anthropic-ai/sdk'
 import type {
   SDKMessage,
   QueryEngineConfig,
@@ -21,7 +20,12 @@ import type {
   ToolContext,
   TokenUsage,
 } from './types.js'
-import { toApiTool } from './tools/types.js'
+import type {
+  LLMProvider,
+  CreateMessageResponse,
+  NormalizedMessageParam,
+  NormalizedTool,
+} from './providers/types.js'
 import {
   estimateMessagesTokens,
   estimateCost,
@@ -37,10 +41,34 @@ import {
 import {
   withRetry,
   isPromptTooLongError,
-  formatApiError,
 } from './utils/retry.js'
 import { getSystemContext, getUserContext } from './utils/context.js'
 import { normalizeMessagesForAPI } from './utils/messages.js'
+import type { HookRegistry, HookInput, HookOutput } from './hooks.js'
+
+// ============================================================================
+// Tool format conversion
+// ============================================================================
+
+/** Convert a ToolDefinition to the normalized provider tool format. */
+function toProviderTool(tool: ToolDefinition): NormalizedTool {
+  return {
+    name: tool.name,
+    description: tool.description,
+    input_schema: tool.inputSchema,
+  }
+}
+
+// ============================================================================
+// ToolUseBlock (internal type for extracted tool_use blocks)
+// ============================================================================
+
+interface ToolUseBlock {
+  type: 'tool_use'
+  id: string
+  name: string
+  input: any
+}
 
 // ============================================================================
 // System Prompt Builder
@@ -113,23 +141,43 @@ async function buildSystemPrompt(config: QueryEngineConfig): Promise<string> {
 
 export class QueryEngine {
   private config: QueryEngineConfig
-  private client: Anthropic
-  public messages: Anthropic.MessageParam[] = []
+  private provider: LLMProvider
+  public messages: NormalizedMessageParam[] = []
   private totalUsage: TokenUsage = { input_tokens: 0, output_tokens: 0 }
   private totalCost = 0
   private turnCount = 0
   private compactState: AutoCompactState
   private sessionId: string
   private apiTimeMs = 0
+  private hookRegistry?: HookRegistry
 
   constructor(config: QueryEngineConfig) {
     this.config = config
-    this.client = new Anthropic({
-      apiKey: config.apiKey,
-      baseURL: config.baseURL,
-    })
+    this.provider = config.provider
     this.compactState = createAutoCompactState()
-    this.sessionId = crypto.randomUUID()
+    this.sessionId = config.sessionId || crypto.randomUUID()
+    this.hookRegistry = config.hookRegistry
+  }
+
+  /**
+   * Execute hooks for a lifecycle event.
+   * Returns hook outputs; never throws.
+   */
+  private async executeHooks(
+    event: import('./hooks.js').HookEvent,
+    extra?: Partial<HookInput>,
+  ): Promise<HookOutput[]> {
+    if (!this.hookRegistry?.hasHooks(event)) return []
+    try {
+      return await this.hookRegistry.execute(event, {
+        event,
+        sessionId: this.sessionId,
+        cwd: this.config.cwd,
+        ...extra,
+      })
+    } catch {
+      return []
+    }
   }
 
   /**
@@ -137,13 +185,34 @@ export class QueryEngine {
    * Yields SDKMessage events as the agent works.
    */
   async *submitMessage(
-    prompt: string | Anthropic.ContentBlockParam[],
+    prompt: string | any[],
   ): AsyncGenerator<SDKMessage> {
+    // Hook: SessionStart
+    await this.executeHooks('SessionStart')
+
+    // Hook: UserPromptSubmit
+    const userHookResults = await this.executeHooks('UserPromptSubmit', {
+      toolInput: prompt,
+    })
+    // Check if any hook blocks the submission
+    if (userHookResults.some((r) => r.block)) {
+      yield {
+        type: 'result',
+        subtype: 'error_during_execution',
+        is_error: true,
+        usage: this.totalUsage,
+        num_turns: 0,
+        cost: 0,
+        errors: ['Blocked by UserPromptSubmit hook'],
+      }
+      return
+    }
+
     // Add user message
-    this.messages.push({ role: 'user', content: prompt })
+    this.messages.push({ role: 'user', content: prompt as any })
 
-    // Build tool definitions for API
-    const tools = this.config.tools.map(toApiTool)
+    // Build tool definitions for provider
+    const tools = this.config.tools.map(toProviderTool)
 
     // Build system prompt
     const systemPrompt = await buildSystemPrompt(this.config)
@@ -176,16 +245,18 @@ export class QueryEngine {
       }
 
       // Auto-compact if context is too large
-      if (shouldAutoCompact(this.messages, this.config.model, this.compactState)) {
+      if (shouldAutoCompact(this.messages as any[], this.config.model, this.compactState)) {
+        await this.executeHooks('PreCompact')
         try {
           const result = await compactConversation(
-            this.client,
+            this.provider,
             this.config.model,
-            this.messages,
+            this.messages as any[],
             this.compactState,
           )
-          this.messages = result.compactedMessages
+          this.messages = result.compactedMessages as NormalizedMessageParam[]
           this.compactState = result.state
+          await this.executeHooks('PostCompact')
         } catch {
           // Continue with uncompacted messages
         }
@@ -193,38 +264,33 @@ export class QueryEngine {
 
       // Micro-compact: truncate large tool results
       const apiMessages = microCompactMessages(
-        normalizeMessagesForAPI(this.messages),
-      )
+        normalizeMessagesForAPI(this.messages as any[]),
+      ) as NormalizedMessageParam[]
 
       this.turnCount++
       turnsRemaining--
 
-      // Make API call with retry
-      let response: Anthropic.Message
+      // Make API call with retry via provider
+      let response: CreateMessageResponse
       const apiStart = performance.now()
       try {
         response = await withRetry(
           async () => {
-            const requestParams: Anthropic.MessageCreateParamsNonStreaming = {
+            return this.provider.createMessage({
               model: this.config.model,
-              max_tokens: this.config.maxTokens,
+              maxTokens: this.config.maxTokens,
               system: systemPrompt,
               messages: apiMessages,
               tools: tools.length > 0 ? tools : undefined,
-            }
-
-            // Add thinking if configured
-            if (
-              this.config.thinking?.type === 'enabled' &&
-              this.config.thinking.budgetTokens
-            ) {
-              (requestParams as any).thinking = {
-                type: 'enabled',
-                budget_tokens: this.config.thinking.budgetTokens,
-              }
-            }
-
-            return this.client.messages.create(requestParams)
+              thinking:
+                this.config.thinking?.type === 'enabled' &&
+                this.config.thinking.budgetTokens
+                  ? {
+                      type: 'enabled',
+                      budget_tokens: this.config.thinking.budgetTokens,
+                    }
+                  : undefined,
+            })
           },
           undefined,
           this.config.abortSignal,
@@ -234,12 +300,12 @@ export class QueryEngine {
         if (isPromptTooLongError(err) && !this.compactState.compacted) {
           try {
             const result = await compactConversation(
-              this.client,
+              this.provider,
               this.config.model,
-              this.messages,
+              this.messages as any[],
               this.compactState,
             )
-            this.messages = result.compactedMessages
+            this.messages = result.compactedMessages as NormalizedMessageParam[]
             this.compactState = result.state
             turnsRemaining++ // Retry this turn
             this.turnCount--
@@ -262,38 +328,38 @@ export class QueryEngine {
       // Track API timing
       this.apiTimeMs += performance.now() - apiStart
 
-      // Track usage
+      // Track usage (normalized by provider)
       if (response.usage) {
         this.totalUsage.input_tokens += response.usage.input_tokens
         this.totalUsage.output_tokens += response.usage.output_tokens
-        if ('cache_creation_input_tokens' in response.usage) {
+        if (response.usage.cache_creation_input_tokens) {
           this.totalUsage.cache_creation_input_tokens =
             (this.totalUsage.cache_creation_input_tokens || 0) +
-            ((response.usage as any).cache_creation_input_tokens || 0)
+            response.usage.cache_creation_input_tokens
         }
-        if ('cache_read_input_tokens' in response.usage) {
+        if (response.usage.cache_read_input_tokens) {
           this.totalUsage.cache_read_input_tokens =
             (this.totalUsage.cache_read_input_tokens || 0) +
-            ((response.usage as any).cache_read_input_tokens || 0)
+            response.usage.cache_read_input_tokens
         }
-        this.totalCost += estimateCost(this.config.model, response.usage as TokenUsage)
+        this.totalCost += estimateCost(this.config.model, response.usage)
       }
 
       // Add assistant message to conversation
-      this.messages.push({ role: 'assistant', content: response.content })
+      this.messages.push({ role: 'assistant', content: response.content as any })
 
       // Yield assistant message
       yield {
         type: 'assistant',
         message: {
           role: 'assistant',
-          content: response.content,
+          content: response.content as any,
         },
       }
 
       // Handle max_output_tokens recovery
       if (
-        response.stop_reason === 'max_tokens' &&
+        response.stopReason === 'max_tokens' &&
         maxOutputRecoveryAttempts < MAX_OUTPUT_RECOVERY
       ) {
         maxOutputRecoveryAttempts++
@@ -307,7 +373,7 @@ export class QueryEngine {
 
       // Check for tool use
       const toolUseBlocks = response.content.filter(
-        (block): block is Anthropic.ToolUseBlock => block.type === 'tool_use',
+        (block): block is ToolUseBlock => block.type === 'tool_use',
       )
 
       if (toolUseBlocks.length === 0) {
@@ -349,9 +415,15 @@ export class QueryEngine {
         })),
       })
 
-      if (response.stop_reason === 'end_turn') break
+      if (response.stopReason === 'end_turn') break
     }
 
+    // Hook: Stop (end of agentic loop)
+    await this.executeHooks('Stop')
+
+    // Hook: SessionEnd
+    await this.executeHooks('SessionEnd')
+
     // Yield enriched final result
     const endSubtype = budgetExceeded
       ? 'error_max_budget_usd'
@@ -380,11 +452,14 @@ export class QueryEngine {
    * Mutation tools run sequentially.
    */
   private async executeTools(
-    toolUseBlocks: Anthropic.ToolUseBlock[],
+    toolUseBlocks: ToolUseBlock[],
   ): Promise<(ToolResult & { tool_name?: string })[]> {
     const context: ToolContext = {
       cwd: this.config.cwd,
       abortSignal: this.config.abortSignal,
+      provider: this.provider,
+      model: this.config.model,
+      apiType: this.provider.apiType,
     }
 
     const MAX_CONCURRENCY = parseInt(
@@ -392,8 +467,8 @@ export class QueryEngine {
     )
 
     // Partition into read-only (concurrent) and mutation (serial)
-    const readOnly: Array<{ block: Anthropic.ToolUseBlock; tool?: ToolDefinition }> = []
-    const mutations: Array<{ block: Anthropic.ToolUseBlock; tool?: ToolDefinition }> = []
+    const readOnly: Array<{ block: ToolUseBlock; tool?: ToolDefinition }> = []
+    const mutations: Array<{ block: ToolUseBlock; tool?: ToolDefinition }> = []
 
     for (const block of toolUseBlocks) {
       const tool = this.config.tools.find((t) => t.name === block.name)
@@ -430,7 +505,7 @@ export class QueryEngine {
    * Execute a single tool with permission checking.
    */
   private async executeSingleTool(
-    block: Anthropic.ToolUseBlock,
+    block: ToolUseBlock,
     tool: ToolDefinition | undefined,
     context: ToolContext,
   ): Promise<ToolResult & { tool_name?: string }> {
@@ -469,7 +544,7 @@ export class QueryEngine {
           }
         }
         if (permission.updatedInput !== undefined) {
-          block = { ...block, input: permission.updatedInput as Record<string, unknown> }
+          block = { ...block, input: permission.updatedInput }
         }
       } catch (err: any) {
         return {
@@ -482,11 +557,46 @@ export class QueryEngine {
       }
     }
 
+    // Hook: PreToolUse
+    const preHookResults = await this.executeHooks('PreToolUse', {
+      toolName: block.name,
+      toolInput: block.input,
+      toolUseId: block.id,
+    })
+    // Check if any hook blocks this tool
+    if (preHookResults.some((r) => r.block)) {
+      const msg = preHookResults.find((r) => r.message)?.message || 'Blocked by PreToolUse hook'
+      return {
+        type: 'tool_result',
+        tool_use_id: block.id,
+        content: msg,
+        is_error: true,
+        tool_name: block.name,
+      }
+    }
+
     // Execute the tool
     try {
       const result = await tool.call(block.input, context)
+
+      // Hook: PostToolUse
+      await this.executeHooks('PostToolUse', {
+        toolName: block.name,
+        toolInput: block.input,
+        toolOutput: typeof result.content === 'string' ? result.content : JSON.stringify(result.content),
+        toolUseId: block.id,
+      })
+
       return { ...result, tool_use_id: block.id, tool_name: block.name }
     } catch (err: any) {
+      // Hook: PostToolUseFailure
+      await this.executeHooks('PostToolUseFailure', {
+        toolName: block.name,
+        toolInput: block.input,
+        toolUseId: block.id,
+        error: err.message,
+      })
+
       return {
         type: 'tool_result',
         tool_use_id: block.id,
@@ -500,7 +610,7 @@ export class QueryEngine {
   /**
    * Get current messages for session persistence.
    */
-  getMessages(): Anthropic.MessageParam[] {
+  getMessages(): NormalizedMessageParam[] {
     return [...this.messages]
   }
 

package/src/index.ts

@@ -6,6 +6,7 @@
  *
  * Features:
  * - 30+ built-in tools (file I/O, shell, web, agents, tasks, teams, etc.)
+ * - Skill system (reusable prompt templates with bundled skills)
  * - MCP server integration (stdio, SSE, HTTP)
  * - Context compression (auto-compact, micro-compact)
  * - Retry with exponential backoff
@@ -14,7 +15,7 @@
  * - Permission system (allow/deny/bypass modes)
  * - Subagent spawning & team coordination
  * - Task management & scheduling
- * - Hook system (pre/post tool use, lifecycle events)
+ * - Hook system with lifecycle integration (pre/post tool use, session, compact)
  * - Token estimation & cost tracking
  * - File state LRU caching
  * - Plan mode for structured workflows
@@ -50,6 +51,26 @@ export type { McpSdkServerConfig } from './sdk-mcp-server.js'
 
 export { QueryEngine } from './engine.js'
 
+// --------------------------------------------------------------------------
+// LLM Providers (Anthropic + OpenAI)
+// --------------------------------------------------------------------------
+
+export {
+  createProvider,
+  AnthropicProvider,
+  OpenAIProvider,
+} from './providers/index.js'
+export type {
+  ApiType,
+  LLMProvider,
+  CreateMessageParams,
+  CreateMessageResponse,
+  NormalizedMessageParam,
+  NormalizedContentBlock,
+  NormalizedTool,
+  NormalizedResponseBlock,
+} from './providers/index.js'
+
 // --------------------------------------------------------------------------
 // Tool System (30+ tools)
 // --------------------------------------------------------------------------
@@ -123,6 +144,9 @@ export {
 
   // Todo
   TodoWriteTool,
+
+  // Skill
+  SkillTool,
 } from './tools/index.js'
 
 // --------------------------------------------------------------------------
@@ -132,6 +156,27 @@ export {
 export { connectMCPServer, closeAllConnections } from './mcp/client.js'
 export type { MCPConnection } from './mcp/client.js'
 
+// --------------------------------------------------------------------------
+// Skill System
+// --------------------------------------------------------------------------
+
+export {
+  registerSkill,
+  getSkill,
+  getAllSkills,
+  getUserInvocableSkills,
+  hasSkill,
+  unregisterSkill,
+  clearSkills,
+  formatSkillsForPrompt,
+  initBundledSkills,
+} from './skills/index.js'
+export type {
+  SkillDefinition,
+  SkillContentBlock,
+  SkillResult,
+} from './skills/index.js'
+
 // --------------------------------------------------------------------------
 // Hook System
 // --------------------------------------------------------------------------
@@ -341,6 +386,7 @@ export type {
 
   // Permission types
   PermissionMode,
+  PermissionBehavior,
   CanUseToolFn,
   CanUseToolResult,
 
@@ -360,6 +406,10 @@ export type {
   // Engine types
   QueryEngineConfig,
 
+  // Content block types
+  ContentBlockParam,
+  ContentBlock,
+
   // Sandbox types
   SandboxSettings,
   SandboxNetworkConfig,

package/src/providers/anthropic.ts

@@ -0,0 +1,60 @@
+/**
+ * Anthropic Messages API Provider
+ *
+ * Wraps the @anthropic-ai/sdk client. Since our internal format is
+ * Anthropic-like, this is mostly a thin pass-through.
+ */
+
+import Anthropic from '@anthropic-ai/sdk'
+import type {
+  LLMProvider,
+  CreateMessageParams,
+  CreateMessageResponse,
+} from './types.js'
+
+export class AnthropicProvider implements LLMProvider {
+  readonly apiType = 'anthropic-messages' as const
+  private client: Anthropic
+
+  constructor(opts: { apiKey?: string; baseURL?: string }) {
+    this.client = new Anthropic({
+      apiKey: opts.apiKey,
+      baseURL: opts.baseURL,
+    })
+  }
+
+  async createMessage(params: CreateMessageParams): Promise<CreateMessageResponse> {
+    const requestParams: Anthropic.MessageCreateParamsNonStreaming = {
+      model: params.model,
+      max_tokens: params.maxTokens,
+      system: params.system,
+      messages: params.messages as Anthropic.MessageParam[],
+      tools: params.tools
+        ? (params.tools as Anthropic.Tool[])
+        : undefined,
+    }
+
+    // Add extended thinking if configured
+    if (params.thinking?.type === 'enabled' && params.thinking.budget_tokens) {
+      (requestParams as any).thinking = {
+        type: 'enabled',
+        budget_tokens: params.thinking.budget_tokens,
+      }
+    }
+
+    const response = await this.client.messages.create(requestParams)
+
+    return {
+      content: response.content as CreateMessageResponse['content'],
+      stopReason: response.stop_reason || 'end_turn',
+      usage: {
+        input_tokens: response.usage.input_tokens,
+        output_tokens: response.usage.output_tokens,
+        cache_creation_input_tokens:
+          (response.usage as any).cache_creation_input_tokens,
+        cache_read_input_tokens:
+          (response.usage as any).cache_read_input_tokens,
+      },
+    }
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,34 @@
+/**
+ * LLM Provider Factory
+ *
+ * Creates the appropriate provider based on API type configuration.
+ */
+
+export type { ApiType, LLMProvider, CreateMessageParams, CreateMessageResponse, NormalizedMessageParam, NormalizedContentBlock, NormalizedTool, NormalizedResponseBlock } from './types.js'
+
+export { AnthropicProvider } from './anthropic.js'
+export { OpenAIProvider } from './openai.js'
+
+import type { ApiType, LLMProvider } from './types.js'
+import { AnthropicProvider } from './anthropic.js'
+import { OpenAIProvider } from './openai.js'
+
+/**
+ * Create an LLM provider based on the API type.
+ *
+ * @param apiType - 'anthropic-messages' or 'openai-completions'
+ * @param opts - API credentials
+ */
+export function createProvider(
+  apiType: ApiType,
+  opts: { apiKey?: string; baseURL?: string },
+): LLMProvider {
+  switch (apiType) {
+    case 'anthropic-messages':
+      return new AnthropicProvider(opts)
+    case 'openai-completions':
+      return new OpenAIProvider(opts)
+    default:
+      throw new Error(`Unsupported API type: ${apiType}. Use 'anthropic-messages' or 'openai-completions'.`)
+  }
+}