@codeany/open-agent-sdk 0.1.0

package/src/hooks.ts

@@ -0,0 +1,261 @@
+/**
+ * Hook System
+ *
+ * Lifecycle hooks for intercepting agent behavior.
+ * Supports pre/post tool use, session lifecycle, and custom events.
+ *
+ * Hook events:
+ * - PreToolUse: before tool execution
+ * - PostToolUse: after tool execution
+ * - PostToolUseFailure: after tool failure
+ * - SessionStart: session initialization
+ * - SessionEnd: session cleanup
+ * - Stop: when turn completes
+ * - SubagentStart: subagent spawned
+ * - SubagentStop: subagent completed
+ * - UserPromptSubmit: user sends message
+ * - PermissionRequest: permission check triggered
+ * - TaskCreated: task created
+ * - TaskCompleted: task finished
+ * - ConfigChange: settings changed
+ * - CwdChanged: working directory changed
+ * - FileChanged: file modified
+ * - Notification: system notification
+ */
+
+import { spawn, type ChildProcess } from 'child_process'
+
+/**
+ * All supported hook events.
+ */
+export const HOOK_EVENTS = [
+  'PreToolUse',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'SessionStart',
+  'SessionEnd',
+  'Stop',
+  'SubagentStart',
+  'SubagentStop',
+  'UserPromptSubmit',
+  'PermissionRequest',
+  'PermissionDenied',
+  'TaskCreated',
+  'TaskCompleted',
+  'ConfigChange',
+  'CwdChanged',
+  'FileChanged',
+  'Notification',
+  'PreCompact',
+  'PostCompact',
+  'TeammateIdle',
+] as const
+
+export type HookEvent = typeof HOOK_EVENTS[number]
+
+/**
+ * Hook definition.
+ */
+export interface HookDefinition {
+  /** Shell command or function to execute */
+  command?: string
+  /** Function handler */
+  handler?: (input: HookInput) => Promise<HookOutput | void>
+  /** Tool name matcher (regex pattern) */
+  matcher?: string
+  /** Timeout in milliseconds */
+  timeout?: number
+}
+
+/**
+ * Hook input passed to handlers.
+ */
+export interface HookInput {
+  event: HookEvent
+  toolName?: string
+  toolInput?: unknown
+  toolOutput?: unknown
+  toolUseId?: string
+  sessionId?: string
+  cwd?: string
+  error?: string
+  [key: string]: unknown
+}
+
+/**
+ * Hook output returned by handlers.
+ */
+export interface HookOutput {
+  /** Message to append to conversation */
+  message?: string
+  /** Permission update */
+  permissionUpdate?: {
+    tool: string
+    behavior: 'allow' | 'deny'
+  }
+  /** Whether to block the action */
+  block?: boolean
+  /** Notification */
+  notification?: {
+    title: string
+    body: string
+    level?: 'info' | 'warning' | 'error'
+  }
+}
+
+/**
+ * Hook configuration (from settings).
+ */
+export type HookConfig = Record<string, HookDefinition[]>
+
+/**
+ * Hook registry for managing and executing hooks.
+ */
+export class HookRegistry {
+  private hooks: Map<HookEvent, HookDefinition[]> = new Map()
+
+  /**
+   * Register hooks from configuration.
+   */
+  registerFromConfig(config: HookConfig): void {
+    for (const [event, definitions] of Object.entries(config)) {
+      const hookEvent = event as HookEvent
+      if (!HOOK_EVENTS.includes(hookEvent)) continue
+
+      const existing = this.hooks.get(hookEvent) || []
+      this.hooks.set(hookEvent, [...existing, ...definitions])
+    }
+  }
+
+  /**
+   * Register a single hook.
+   */
+  register(event: HookEvent, definition: HookDefinition): void {
+    const existing = this.hooks.get(event) || []
+    existing.push(definition)
+    this.hooks.set(event, existing)
+  }
+
+  /**
+   * Execute hooks for an event.
+   */
+  async execute(
+    event: HookEvent,
+    input: HookInput,
+  ): Promise<HookOutput[]> {
+    const definitions = this.hooks.get(event) || []
+    const results: HookOutput[] = []
+
+    for (const def of definitions) {
+      // Check matcher for tool-specific hooks
+      if (def.matcher && input.toolName) {
+        const regex = new RegExp(def.matcher)
+        if (!regex.test(input.toolName)) continue
+      }
+
+      try {
+        let output: HookOutput | void = undefined
+
+        if (def.handler) {
+          // Function handler
+          output = await Promise.race([
+            def.handler(input),
+            new Promise<void>((_, reject) =>
+              setTimeout(() => reject(new Error('Hook timeout')), def.timeout || 30000),
+            ),
+          ])
+        } else if (def.command) {
+          // Shell command handler
+          output = await executeShellHook(def.command, input, def.timeout || 30000)
+        }
+
+        if (output) {
+          results.push(output)
+        }
+      } catch (err: any) {
+        // Log but don't fail on hook errors
+        console.error(`[Hook] ${event} hook failed: ${err.message}`)
+      }
+    }
+
+    return results
+  }
+
+  /**
+   * Check if any hooks are registered for an event.
+   */
+  hasHooks(event: HookEvent): boolean {
+    return (this.hooks.get(event)?.length || 0) > 0
+  }
+
+  /**
+   * Clear all hooks.
+   */
+  clear(): void {
+    this.hooks.clear()
+  }
+}
+
+/**
+ * Execute a shell command as a hook.
+ */
+async function executeShellHook(
+  command: string,
+  input: HookInput,
+  timeout: number,
+): Promise<HookOutput | void> {
+  return new Promise((resolve) => {
+    const proc = spawn('bash', ['-c', command], {
+      timeout,
+      env: {
+        ...process.env,
+        HOOK_EVENT: input.event,
+        HOOK_TOOL_NAME: input.toolName || '',
+        HOOK_SESSION_ID: input.sessionId || '',
+        HOOK_CWD: input.cwd || '',
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+
+    // Send input as JSON on stdin
+    proc.stdin?.write(JSON.stringify(input))
+    proc.stdin?.end()
+
+    const chunks: Buffer[] = []
+    proc.stdout?.on('data', (d: Buffer) => chunks.push(d))
+
+    proc.on('close', (code) => {
+      if (code !== 0) {
+        resolve(undefined)
+        return
+      }
+
+      const stdout = Buffer.concat(chunks).toString('utf-8').trim()
+      if (!stdout) {
+        resolve(undefined)
+        return
+      }
+
+      try {
+        const output = JSON.parse(stdout) as HookOutput
+        resolve(output)
+      } catch {
+        // Non-JSON output treated as message
+        resolve({ message: stdout })
+      }
+    })
+
+    proc.on('error', () => resolve(undefined))
+  })
+}
+
+/**
+ * Create a default hook registry.
+ */
+export function createHookRegistry(config?: HookConfig): HookRegistry {
+  const registry = new HookRegistry()
+  if (config) {
+    registry.registerFromConfig(config)
+  }
+  return registry
+}

package/src/index.ts

@@ -0,0 +1,376 @@
+/**
+ * @codeany/open-agent-sdk
+ *
+ * Open-source Agent SDK by CodeAny (https://codeany.ai).
+ * Runs the full agent loop in-process without spawning subprocesses.
+ *
+ * Features:
+ * - 30+ built-in tools (file I/O, shell, web, agents, tasks, teams, etc.)
+ * - MCP server integration (stdio, SSE, HTTP)
+ * - Context compression (auto-compact, micro-compact)
+ * - Retry with exponential backoff
+ * - Git status & project context injection
+ * - Multi-turn session persistence
+ * - Permission system (allow/deny/bypass modes)
+ * - Subagent spawning & team coordination
+ * - Task management & scheduling
+ * - Hook system (pre/post tool use, lifecycle events)
+ * - Token estimation & cost tracking
+ * - File state LRU caching
+ * - Plan mode for structured workflows
+ */
+
+// --------------------------------------------------------------------------
+// High-level Agent API
+// --------------------------------------------------------------------------
+
+export { Agent, createAgent, query } from './agent.js'
+
+// --------------------------------------------------------------------------
+// Tool Helper (Zod-based tool creation, compatible with official SDK)
+// --------------------------------------------------------------------------
+
+export { tool, sdkToolToToolDefinition } from './tool-helper.js'
+export type {
+  ToolAnnotations,
+  CallToolResult,
+  SdkMcpToolDefinition,
+} from './tool-helper.js'
+
+// --------------------------------------------------------------------------
+// In-Process MCP Server
+// --------------------------------------------------------------------------
+
+export { createSdkMcpServer, isSdkServerConfig } from './sdk-mcp-server.js'
+export type { McpSdkServerConfig } from './sdk-mcp-server.js'
+
+// --------------------------------------------------------------------------
+// Core Engine
+// --------------------------------------------------------------------------
+
+export { QueryEngine } from './engine.js'
+
+// --------------------------------------------------------------------------
+// Tool System (30+ tools)
+// --------------------------------------------------------------------------
+
+export {
+  // Registry
+  getAllBaseTools,
+  filterTools,
+  assembleToolPool,
+
+  // Helpers
+  defineTool,
+  toApiTool,
+
+  // Core file I/O & execution
+  BashTool,
+  FileReadTool,
+  FileWriteTool,
+  FileEditTool,
+  GlobTool,
+  GrepTool,
+  NotebookEditTool,
+
+  // Web
+  WebFetchTool,
+  WebSearchTool,
+
+  // Agent & Multi-agent
+  AgentTool,
+  SendMessageTool,
+  TeamCreateTool,
+  TeamDeleteTool,
+
+  // Tasks
+  TaskCreateTool,
+  TaskListTool,
+  TaskUpdateTool,
+  TaskGetTool,
+  TaskStopTool,
+  TaskOutputTool,
+
+  // Worktree
+  EnterWorktreeTool,
+  ExitWorktreeTool,
+
+  // Planning
+  EnterPlanModeTool,
+  ExitPlanModeTool,
+
+  // User interaction
+  AskUserQuestionTool,
+
+  // Discovery
+  ToolSearchTool,
+
+  // MCP Resources
+  ListMcpResourcesTool,
+  ReadMcpResourceTool,
+
+  // Scheduling
+  CronCreateTool,
+  CronDeleteTool,
+  CronListTool,
+  RemoteTriggerTool,
+
+  // LSP
+  LSPTool,
+
+  // Config
+  ConfigTool,
+
+  // Todo
+  TodoWriteTool,
+} from './tools/index.js'
+
+// --------------------------------------------------------------------------
+// MCP Client
+// --------------------------------------------------------------------------
+
+export { connectMCPServer, closeAllConnections } from './mcp/client.js'
+export type { MCPConnection } from './mcp/client.js'
+
+// --------------------------------------------------------------------------
+// Hook System
+// --------------------------------------------------------------------------
+
+export {
+  HookRegistry,
+  createHookRegistry,
+  HOOK_EVENTS,
+} from './hooks.js'
+export type {
+  HookEvent,
+  HookDefinition,
+  HookInput,
+  HookOutput,
+  HookConfig,
+} from './hooks.js'
+
+// --------------------------------------------------------------------------
+// Session Management
+// --------------------------------------------------------------------------
+
+export {
+  saveSession,
+  loadSession,
+  listSessions,
+  forkSession,
+  getSessionMessages,
+  getSessionInfo,
+  renameSession,
+  tagSession,
+  appendToSession,
+  deleteSession,
+} from './session.js'
+export type { SessionMetadata, SessionData } from './session.js'
+
+// --------------------------------------------------------------------------
+// Context Utilities
+// --------------------------------------------------------------------------
+
+export {
+  getSystemContext,
+  getUserContext,
+  getGitStatus,
+  readProjectContextContent,
+  discoverProjectContextFiles,
+  clearContextCache,
+} from './utils/context.js'
+
+// --------------------------------------------------------------------------
+// Message Utilities
+// --------------------------------------------------------------------------
+
+export {
+  createUserMessage,
+  createAssistantMessage,
+  normalizeMessagesForAPI,
+  stripImagesFromMessages,
+  extractTextFromContent,
+  createCompactBoundaryMessage,
+  truncateText,
+} from './utils/messages.js'
+
+// --------------------------------------------------------------------------
+// Token Estimation & Cost
+// --------------------------------------------------------------------------
+
+export {
+  estimateTokens,
+  estimateMessagesTokens,
+  estimateSystemPromptTokens,
+  getTokenCountFromUsage,
+  getContextWindowSize,
+  getAutoCompactThreshold,
+  estimateCost,
+  MODEL_PRICING,
+  AUTOCOMPACT_BUFFER_TOKENS,
+} from './utils/tokens.js'
+
+// --------------------------------------------------------------------------
+// Context Compression
+// --------------------------------------------------------------------------
+
+export {
+  shouldAutoCompact,
+  compactConversation,
+  microCompactMessages,
+  createAutoCompactState,
+} from './utils/compact.js'
+export type { AutoCompactState } from './utils/compact.js'
+
+// --------------------------------------------------------------------------
+// Retry Logic
+// --------------------------------------------------------------------------
+
+export {
+  withRetry,
+  isRetryableError,
+  isPromptTooLongError,
+  isAuthError,
+  isRateLimitError,
+  formatApiError,
+  getRetryDelay,
+  DEFAULT_RETRY_CONFIG,
+} from './utils/retry.js'
+export type { RetryConfig } from './utils/retry.js'
+
+// --------------------------------------------------------------------------
+// File State Cache
+// --------------------------------------------------------------------------
+
+export {
+  FileStateCache,
+  createFileStateCache,
+} from './utils/fileCache.js'
+export type { FileState } from './utils/fileCache.js'
+
+// --------------------------------------------------------------------------
+// Task & Team State (for advanced usage)
+// --------------------------------------------------------------------------
+
+export {
+  getAllTasks,
+  getTask,
+  clearTasks,
+} from './tools/task-tools.js'
+export type { Task, TaskStatus } from './tools/task-tools.js'
+
+export {
+  getAllTeams,
+  getTeam,
+  clearTeams,
+} from './tools/team-tools.js'
+export type { Team } from './tools/team-tools.js'
+
+export {
+  readMailbox,
+  writeToMailbox,
+  clearMailboxes,
+} from './tools/send-message.js'
+export type { AgentMessage } from './tools/send-message.js'
+
+export {
+  isPlanModeActive,
+  getCurrentPlan,
+} from './tools/plan-tools.js'
+
+export {
+  registerAgents,
+  clearAgents,
+} from './tools/agent-tool.js'
+
+export {
+  setQuestionHandler,
+  clearQuestionHandler,
+} from './tools/ask-user.js'
+
+export {
+  setDeferredTools,
+} from './tools/tool-search.js'
+
+export {
+  setMcpConnections,
+} from './tools/mcp-resource-tools.js'
+
+export {
+  getAllCronJobs,
+  clearCronJobs,
+} from './tools/cron-tools.js'
+export type { CronJob } from './tools/cron-tools.js'
+
+export {
+  getConfig,
+  setConfig,
+  clearConfig,
+} from './tools/config-tool.js'
+
+export {
+  getTodos,
+  clearTodos,
+} from './tools/todo-tool.js'
+export type { TodoItem } from './tools/todo-tool.js'
+
+// --------------------------------------------------------------------------
+// Types
+// --------------------------------------------------------------------------
+
+export type {
+  // Message types
+  Message,
+  UserMessage,
+  AssistantMessage,
+  ConversationMessage,
+  MessageRole,
+
+  // SDK message types (streaming events)
+  SDKMessage,
+  SDKAssistantMessage,
+  SDKToolResultMessage,
+  SDKResultMessage,
+  SDKPartialMessage,
+
+  // Tool types
+  ToolDefinition,
+  ToolInputSchema,
+  ToolContext,
+  ToolResult,
+
+  // Permission types
+  PermissionMode,
+  CanUseToolFn,
+  CanUseToolResult,
+
+  // MCP types
+  McpServerConfig,
+  McpStdioConfig,
+  McpSseConfig,
+  McpHttpConfig,
+
+  // Agent types
+  AgentOptions,
+  AgentDefinition,
+  QueryResult,
+  ThinkingConfig,
+  TokenUsage,
+
+  // Engine types
+  QueryEngineConfig,
+
+  // Sandbox types
+  SandboxSettings,
+  SandboxNetworkConfig,
+  SandboxFilesystemConfig,
+
+  // Output format
+  OutputFormat,
+
+  // Setting sources
+  SettingSource,
+
+  // Model info
+  ModelInfo,
+} from './types.js'