@theokit/agents 0.29.0 → 0.30.1

package/dist/chunk-K4MCMREI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/decorators/main-loop.ts","../src/decorators/tool.ts","../src/decorators/hook.ts","../src/decorators/conversation.ts","../src/decorators/model.ts","../src/decorators/artifact.ts","../src/decorators/observable.ts","../src/decorators/sandbox.ts","../src/decorators/edit-format.ts","../src/decorators/apply-decorators.ts"],"sourcesContent":["/**\n * @MainLoop() — marks the execution entry point of an agent.\n *\n * Only one @MainLoop per agent class. Second application overwrites (last-wins, with warning).\n */\nimport { setMeta, getMeta, AGENT_MAIN_LOOP } from '../metadata/index.js'\nimport type { MainLoopOptions, MainLoopMeta } from '../types.js'\n\nexport function MainLoop(options: MainLoopOptions = {}): MethodDecorator {\n  return (target: object, propertyKey: string | symbol) => {\n    const actualTarget = target.constructor\n    const existing = getMeta<MainLoopMeta>(AGENT_MAIN_LOOP, actualTarget)\n    if (existing) {\n      console.warn(\n        `[@theokit/agents] ${actualTarget.name}: @MainLoop() already declared on '${String(existing.propertyKey)}'. Overwriting with '${String(propertyKey)}'.`,\n      )\n    }\n    const meta: MainLoopMeta = {\n      propertyKey,\n      strategy: options.strategy ?? 'simple-chat',\n      maxIterations: options.maxIterations,\n      timeoutMs: options.timeoutMs,\n    }\n    setMeta(AGENT_MAIN_LOOP, actualTarget, meta)\n  }\n}\n\nexport function getMainLoop(target: Function): MainLoopMeta | undefined {\n  return getMeta<MainLoopMeta>(AGENT_MAIN_LOOP, target)\n}\n","/**\n * @Toolbox() + @Tool() — group and define agent tools.\n *\n * @Toolbox({ namespace }) is a class decorator that groups related tools.\n * @Tool({ name, description, input, risk }) is a method decorator compiled to defineTool().\n *\n * @UseGuards on @Toolbox applies to ALL tools (per ADR D7).\n */\nimport { setMeta, getMeta, TOOLBOX_CONFIG, TOOL_CONFIG, TOOL_METHODS } from '../metadata/index.js'\nimport type { ToolboxOptions, ToolOptions } from '../types.js'\n\n/**\n * Convention: TaskTools → namespace: 'tasks', ProjectTools → namespace: 'projects'\n * Strips \"Tools\" suffix, converts to kebab-case.\n */\nfunction inferNamespace(className: string): string {\n  const stripped = className.replace(/Tools$/, '')\n  return stripped\n    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')\n    .replace(/([A-Z])([A-Z][a-z])/g, '$1-$2')\n    .toLowerCase()\n}\n\nexport function Toolbox(options: ToolboxOptions = {}): ClassDecorator {\n  return (target: Function) => {\n    const ns = options.namespace ?? inferNamespace(target.name)\n    setMeta(TOOLBOX_CONFIG, target, { ...options, namespace: ns })\n  }\n}\n\nexport function Tool(options: ToolOptions): MethodDecorator {\n  return (target: object, propertyKey: string | symbol) => {\n    const actualTarget = target.constructor\n    setMeta(TOOL_CONFIG, actualTarget, options, propertyKey)\n    // Accumulate tool methods list\n    const existing = getMeta<(string | symbol)[]>(TOOL_METHODS, actualTarget) ?? []\n    setMeta(TOOL_METHODS, actualTarget, [...existing, propertyKey])\n  }\n}\n\nexport function getToolboxConfig(target: Function): ToolboxOptions | undefined {\n  return getMeta<ToolboxOptions>(TOOLBOX_CONFIG, target)\n}\n\nexport function getToolMethods(target: Function): (string | symbol)[] {\n  return getMeta<(string | symbol)[]>(TOOL_METHODS, target) ?? []\n}\n\nexport function getToolConfig(\n  target: Function,\n  propertyKey: string | symbol,\n): ToolOptions | undefined {\n  return getMeta<ToolOptions>(TOOL_CONFIG, target, propertyKey)\n}\n","/**\n * @Hook() — lifecycle hooks WITHIN the agent loop.\n *\n * Unlike HTTP interceptors (which wrap the entire handler), hooks fire at\n * specific points during the agent's reasoning → tool → response cycle.\n *\n * Hook points:\n * - 'before:llm-call'  — before each LLM API call\n * - 'after:llm-call'   — after each LLM response\n * - 'before:tool-call' — before each tool execution\n * - 'after:tool-call'  — after each tool result\n * - 'on:iteration'     — at each loop iteration\n * - 'on:complete'      — when the agent produces a final answer\n * - 'on:error'         — when the agent encounters an error\n *\n * @example\n * ```ts\n * @Agent({ name: 'support', route: '/support' })\n * class SupportAgent {\n *   @MainLoop()\n *   async run() {}\n *\n *   @Hook('before:llm-call')\n *   async injectContext(ctx: HookContext) {\n *     ctx.appendSystemPrompt(`Time: ${new Date().toISOString()}`)\n *   }\n *\n *   @Hook('after:tool-call')\n *   async trackCost(ctx: HookContext) {\n *     await billing.track(ctx.toolCall!.name, ctx.toolCall!.durationMs)\n *   }\n * }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst HOOKS_CONFIG = Symbol.for('theokit:agents:hooks')\n\nexport type HookPoint =\n  | 'before:llm-call'\n  | 'after:llm-call'\n  | 'before:tool-call'\n  | 'after:tool-call'\n  | 'on:iteration'\n  | 'on:complete'\n  | 'on:error'\n\nexport interface HookEntry {\n  point: HookPoint\n  propertyKey: string | symbol\n}\n\nexport function Hook(point: HookPoint): MethodDecorator {\n  return (target: object, propertyKey: string | symbol) => {\n    const actualTarget = target.constructor\n    const existing = getMeta<HookEntry[]>(HOOKS_CONFIG, actualTarget) ?? []\n    setMeta(HOOKS_CONFIG, actualTarget, [...existing, { point, propertyKey }])\n  }\n}\n\nexport function getHooks(target: Function): HookEntry[] {\n  return getMeta<HookEntry[]>(HOOKS_CONFIG, target) ?? []\n}\n\nexport function getHooksByPoint(target: Function, point: HookPoint): HookEntry[] {\n  return getHooks(target).filter((h) => h.point === point)\n}\n","/**\n * @Conversation() — declares conversation persistence strategy for an agent.\n *\n * Controls how the agent remembers message history across sessions.\n * Compiles to SDK's ConversationStorageAdapter configuration.\n *\n * @example\n * ```ts\n * @Agent({ name: 'support', route: '/support' })\n * @Conversation({\n *   storage: 'drizzle',\n *   maxHistory: 100,\n *   compaction: 'summarize',\n *   ttl: 24 * 60 * 60 * 1000,\n * })\n * class SupportAgent { ... }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst CONVERSATION_CONFIG = Symbol.for('theokit:agents:conversation')\n\nexport type ConversationStorage = 'memory' | 'filesystem' | 'drizzle' | 'redis'\nexport type CompactionStrategy = 'truncate' | 'summarize' | 'sliding-window'\n\nexport interface ConversationOptions {\n  /** Storage backend for conversation history. */\n  storage?: ConversationStorage\n  /** Maximum messages before compaction triggers (0 = no limit). */\n  maxHistory?: number\n  /** How to compact when maxHistory is exceeded. */\n  compaction?: CompactionStrategy\n  /** Time-to-live in milliseconds before conversation expires (0 = never). */\n  ttl?: number\n  /** Number of recent messages to always preserve during compaction. */\n  preserveLastN?: number\n}\n\nexport function Conversation(options: ConversationOptions = {}): ClassDecorator {\n  return (target: Function) => {\n    setMeta(CONVERSATION_CONFIG, target, {\n      storage: 'memory',\n      maxHistory: 0,\n      compaction: 'truncate',\n      ttl: 0,\n      preserveLastN: 5,\n      ...options,\n    })\n  }\n}\n\nexport function getConversationConfig(target: Function): ConversationOptions | undefined {\n  return getMeta<ConversationOptions>(CONVERSATION_CONFIG, target)\n}\n","/**\n * @Model() — override the LLM model at agent or tool level.\n *\n * Hierarchical resolution via Reflector.getAllAndOverride:\n *   tool @Model > agent @Model > @Agent({ model }) > config default\n *\n * This is a MODEL selector, not a PROVIDER selector. Provider routing\n * (which API key, which endpoint, fallback chains) lives in theo.config.ts\n * as runtime configuration — not in decorators.\n *\n * @example\n * ```ts\n * @Agent({ name: 'support', route: '/support' })\n * @Model('claude-sonnet-4-5-20250929')  // default for all tools\n * class SupportAgent {\n *   @MainLoop()\n *   async run() {}\n * }\n *\n * @Toolbox({ namespace: 'code' })\n * class CodeTools {\n *   @Tool({ name: 'generate', description: 'Generate code', input: z.object({...}) })\n *   @Model('claude-opus-4-6')  // this tool needs the most capable model\n *   async generate() { ... }\n *\n *   @Tool({ name: 'lint', description: 'Lint code', input: z.object({...}) })\n *   // no @Model — inherits from agent level\n *   async lint() { ... }\n * }\n * ```\n */\nimport { createDecorator } from '@theokit/http'\n\n/** Override the LLM model for an agent class or a specific tool method. */\nexport const Model = createDecorator<string>()\n","/**\n * @Artifact() — marks a tool as producing structured output artifacts.\n *\n * Artifacts are SEPARATE from text responses. When a tool produces an artifact\n * (code file, document, diagram, JSON data), the SSE stream emits artifact_start\n * + artifact_chunk events alongside text_delta events.\n *\n * Inspired by assistant-ui's A2AArtifact pattern where artifacts have their own\n * lifecycle (start → chunks → complete) independent of message content.\n *\n * @example\n * ```ts\n * @Toolbox({ namespace: 'code' })\n * class CodeTools {\n *   @Tool({ name: 'generate', description: 'Generate code', input: z.object({...}) })\n *   @Artifact({ mimeType: 'text/typescript', streamable: true })\n *   async generate(input: { spec: string }): Promise<ArtifactResult> {\n *     return {\n *       content: generatedCode,\n *       filename: 'component.tsx',\n *       metadata: { language: 'typescript', loc: 42 },\n *     }\n *   }\n * }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst ARTIFACT_CONFIG = Symbol.for('theokit:agents:artifact')\n\nexport interface ArtifactOptions {\n  /** MIME type of the artifact output. */\n  mimeType: string\n  /** Whether the artifact can be streamed in chunks (default: true). */\n  streamable?: boolean\n  /** Maximum size in bytes (0 = no limit). */\n  maxSize?: number\n}\n\n/** Return type for tools decorated with @Artifact. */\nexport interface ArtifactResult {\n  /** The artifact content (string for text, Buffer for binary). */\n  content: string\n  /** Optional filename hint for the client. */\n  filename?: string\n  /** Optional metadata attached to the artifact. */\n  metadata?: Record<string, unknown>\n}\n\nexport function Artifact(options: ArtifactOptions): MethodDecorator {\n  return (target: object, propertyKey: string | symbol) => {\n    const actualTarget = target.constructor\n    setMeta(ARTIFACT_CONFIG, actualTarget, { streamable: true, maxSize: 0, ...options }, propertyKey)\n  }\n}\n\nexport function getArtifactConfig(\n  target: Function,\n  propertyKey: string | symbol,\n): ArtifactOptions | undefined {\n  return getMeta<ArtifactOptions>(ARTIFACT_CONFIG, target, propertyKey)\n}\n","/**\n * @Observable() — exposes agent internal state as a real-time stream.\n *\n * Clients subscribe to named observables to monitor agent execution in real-time:\n * token usage, cost, iteration progress, pending approvals, retrieved facts.\n *\n * Inspired by Liveblocks' Presence pattern and tRPC subscriptions. The agent\n * pushes state updates via SSE alongside response events — clients are never\n * \"blind\" during long-running agent operations.\n *\n * @example\n * ```ts\n * @Agent({ name: 'research', route: '/research' })\n * class ResearchAgent {\n *   @MainLoop()\n *   async run() {}\n *\n *   @Observable('metrics')\n *   getMetrics(ctx: AgentContext): AgentMetrics {\n *     return {\n *       tokensUsed: ctx.tokenCount,\n *       costUsd: ctx.costUsd,\n *       iteration: ctx.iteration,\n *       pendingApprovals: ctx.pendingApprovals.length,\n *     }\n *   }\n * }\n *\n * // SSE emits: { type: 'state_update', channel: 'metrics', data: {...} }\n * // Client: eventSource.addEventListener('state_update', handler)\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst OBSERVABLE_CONFIG = Symbol.for('theokit:agents:observable')\n\nexport interface ObservableEntry {\n  channel: string\n  propertyKey: string | symbol\n}\n\nexport function Observable(channel: string): MethodDecorator {\n  return (target: object, propertyKey: string | symbol) => {\n    const actualTarget = target.constructor\n    const existing = getMeta<ObservableEntry[]>(OBSERVABLE_CONFIG, actualTarget) ?? []\n    setMeta(OBSERVABLE_CONFIG, actualTarget, [...existing, { channel, propertyKey }])\n  }\n}\n\nexport function getObservables(target: Function): ObservableEntry[] {\n  return getMeta<ObservableEntry[]>(OBSERVABLE_CONFIG, target) ?? []\n}\n\nexport function getObservableByChannel(target: Function, channel: string): ObservableEntry | undefined {\n  return getObservables(target).find((o) => o.channel === channel)\n}\n","/**\n * @Sandbox() — declares file/command permission scope for code assistant agents.\n *\n * Controls what the agent can read, write, and execute. The runtime enforces\n * these permissions BEFORE tool execution — a tool that tries to write to a\n * denied path gets a typed error, not a crash.\n *\n * Inspired by Claude Code's permission system (allow/deny per tool + path).\n *\n * @example\n * ```ts\n * @Agent({ name: 'coder', route: '/agents/coder' })\n * @Sandbox({\n *   filesystem: {\n *     read: ['src/**', 'tests/**', 'package.json'],\n *     write: ['src/**', 'tests/**'],\n *     deny: ['node_modules/**', '.env', '*.key'],\n *   },\n *   commands: {\n *     allow: ['npm test', 'tsc --noEmit', 'git diff'],\n *     deny: ['rm -rf', 'git push --force', 'npm publish'],\n *   },\n *   network: false,\n * })\n * class CoderAgent { ... }\n * ```\n */\nimport { resolve } from 'node:path'\n\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst SANDBOX_CONFIG = Symbol.for('theokit:agents:sandbox')\n\nexport interface FilesystemPermissions {\n  /** Glob patterns for allowed read paths. */\n  read?: string[]\n  /** Glob patterns for allowed write paths. */\n  write?: string[]\n  /** Glob patterns for DENIED paths (overrides read/write). */\n  deny?: string[]\n}\n\nexport interface CommandPermissions {\n  /** Command prefixes allowed to execute. */\n  allow?: string[]\n  /** Command prefixes denied (overrides allow). */\n  deny?: string[]\n}\n\nexport interface SandboxOptions {\n  /** Filesystem read/write permissions. */\n  filesystem?: FilesystemPermissions\n  /** Shell command execution permissions. */\n  commands?: CommandPermissions\n  /** Allow outbound network from tools (default: true). */\n  network?: boolean\n  /** Maximum execution time per command in ms (default: 120_000). */\n  commandTimeout?: number\n  /** Working directory root (default: process.cwd()). */\n  cwd?: string\n}\n\nexport function Sandbox(options: SandboxOptions): ClassDecorator {\n  return (target: Function) => {\n    setMeta(SANDBOX_CONFIG, target, {\n      network: true,\n      commandTimeout: 120_000,\n      ...options,\n    })\n  }\n}\n\nexport function getSandboxConfig(target: Function): SandboxOptions | undefined {\n  return getMeta<SandboxOptions>(SANDBOX_CONFIG, target)\n}\n\n/**\n * Check if a file path is allowed for the given operation.\n * Deny patterns always win over allow patterns.\n *\n * Security: normalizes paths to prevent traversal (../) and rejects null bytes.\n */\nexport function isPathAllowed(\n  sandbox: SandboxOptions,\n  filePath: string,\n  operation: 'read' | 'write',\n): boolean {\n  // EC-2: null byte injection — reject before any processing\n  if (filePath.includes('\\x00')) return false\n\n  // Path traversal fix: normalize to remove ../ sequences\n  const normalized = resolve('/', filePath).slice(1)\n\n  const fs = sandbox.filesystem\n  if (!fs) return true // no filesystem restrictions\n\n  // Deny always wins\n  if (fs.deny?.some((pattern) => matchGlob(pattern, normalized))) return false\n\n  const allowList = operation === 'read' ? fs.read : fs.write\n  if (!allowList) return true // no explicit allow = allow all (minus deny)\n\n  return allowList.some((pattern) => matchGlob(pattern, normalized))\n}\n\n/**\n * Shell metacharacters that indicate injection attempts.\n * EC-1: includes redirect operators (>, <) and newlines (\\n, \\r).\n */\nconst SHELL_METACHARS = /[;|&$`(){}<>\\n\\r]/\n\n/**\n * Check if a command is allowed to execute.\n * Deny patterns always win. Rejects shell metacharacters.\n *\n * Security: tokenizes command to match binary name, not arbitrary prefix.\n */\nexport function isCommandAllowed(sandbox: SandboxOptions, command: string): boolean {\n  const cmds = sandbox.commands\n  if (!cmds) return true\n\n  // Reject any command with shell metacharacters (injection prevention)\n  if (SHELL_METACHARS.test(command)) return false\n\n  // Extract binary name (first whitespace-delimited token)\n  const binary = command.split(/\\s+/)[0]\n\n  // Deny always wins — check both exact binary match and full command prefix\n  if (cmds.deny?.some((d) => binary === d || command.startsWith(d + ' ') || command === d))\n    return false\n\n  if (!cmds.allow) return true\n\n  // Allow: match exact binary or full command prefix\n  return cmds.allow.some((a) => binary === a || command.startsWith(a + ' ') || command === a)\n}\n\n/**\n * Glob matcher — converts glob pattern to regex at call time.\n * Uses a pre-built RegExp from a sanitized pattern string.\n * Supports *, **, and ? glob characters.\n */\nfunction matchGlob(pattern: string, filePath: string): boolean {\n  // Escape all regex specials except glob chars (* and ?)\n  const escaped = pattern\n    .replace(/[.+^${}()|[\\]\\\\]/g, '\\\\$&')\n    .replace(/\\*\\*/g, '\\0GLOBSTAR\\0')\n    .replace(/\\*/g, '[^/]*')\n    .replace(/\\?/g, '[^/]')\n    .replace(/\\0GLOBSTAR\\0/g, '.*')\n  // Pre-compile regex outside of hot path (pattern is controlled by developer, not user input)\n  const regex = buildGlobRegex(escaped)\n  return regex.test(filePath)\n}\n\n/** Build a regex from a pre-escaped glob pattern string. */\nfunction buildGlobRegex(escapedPattern: string): RegExp {\n  return RegExp(`^${escapedPattern}$`)\n}\n","/**\n * @EditFormat() — declares how a tool outputs file edits.\n *\n * Code assistants show DIFFS, not entire files. This decorator tells the\n * runtime which format the tool produces so the SSE stream emits the\n * correct `file_edit` event type.\n *\n * @example\n * ```ts\n * @Toolbox({ namespace: 'editor' })\n * class EditorTools {\n *   @Tool({ name: 'edit', description: 'Edit file', input: editSchema })\n *   @EditFormat('search-replace')\n *   async edit(input: { file: string; search: string; replace: string }) {\n *     return { file: input.file, search: input.search, replace: input.replace }\n *   }\n *\n *   @Tool({ name: 'write', description: 'Write file', input: writeSchema })\n *   @EditFormat('full-file')\n *   async write(input: { file: string; content: string }) {\n *     return { file: input.file, content: input.content }\n *   }\n * }\n * ```\n */\nimport { createDecorator } from '@theokit/http'\n\nexport type EditFormatType =\n  | 'search-replace'   // { file, search, replace } — Claude Code Edit pattern\n  | 'unified-diff'     // Standard unified diff format\n  | 'full-file'        // Complete file content (Write pattern)\n  | 'line-range'       // { file, startLine, endLine, content }\n\n/** Declare the edit format a tool produces. */\nexport const EditFormat = createDecorator<EditFormatType>()\n","/**\n * applyDecorators() — compose multiple decorators into a single reusable decorator.\n *\n * NestJS-compatible utility. Enables creating \"preset\" decorators that bundle\n * common configurations (auth + throttle + trace + memory + ...) into one decorator.\n *\n * @example\n * ```ts\n * // Create a reusable preset\n * const ProductionAgent = (name: string, route: string) => applyDecorators(\n *   Agent({ name, route, model: 'claude-sonnet-4-5-20250929' }),\n *   UseGuards(AuthGuard, TenantGuard),\n *   Throttle({ limit: 30, ttl: 60_000 }),\n *   Budget({ maxCostUsd: 5.00 }),\n *   Trace(true),\n * )\n *\n * // Apply preset to any agent\n * @ProductionAgent('support', '/api/agents/support')\n * class SupportAgent {\n *   @MainLoop()\n *   async run() {}\n * }\n * ```\n */\n\ntype AnyDecorator = ClassDecorator | MethodDecorator | PropertyDecorator\n\n/**\n * Compose multiple decorators into a single decorator.\n * Works for both class-level and method-level decorators.\n */\nexport function applyDecorators(\n  ...decorators: AnyDecorator[]\n): ClassDecorator & MethodDecorator {\n  return (\n    target: object | Function,\n    propertyKey?: string | symbol,\n    descriptor?: PropertyDescriptor,\n  ) => {\n    for (const decorator of decorators) {\n      if (propertyKey !== undefined && descriptor !== undefined) {\n        // Method-level\n        ;(decorator as MethodDecorator)(target, propertyKey, descriptor)\n      } else {\n        // Class-level\n        ;(decorator as ClassDecorator)(target as Function)\n      }\n    }\n  }\n}\n"],"mappings":"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","names":["MainLoop","options","target","propertyKey","actualTarget","existing","getMeta","AGENT_MAIN_LOOP","console","warn","name","String","meta","strategy","maxIterations","timeoutMs","setMeta","getMainLoop","inferNamespace","className","stripped","replace","toLowerCase","Toolbox","options","target","ns","namespace","name","setMeta","TOOLBOX_CONFIG","Tool","propertyKey","actualTarget","TOOL_CONFIG","existing","getMeta","TOOL_METHODS","getToolboxConfig","getToolMethods","getToolConfig","HOOKS_CONFIG","Symbol","for","Hook","point","target","propertyKey","actualTarget","existing","getMeta","setMeta","getHooks","getHooksByPoint","filter","h","CONVERSATION_CONFIG","Symbol","for","Conversation","options","target","setMeta","storage","maxHistory","compaction","ttl","preserveLastN","getConversationConfig","getMeta","createDecorator","Model","ARTIFACT_CONFIG","Symbol","for","Artifact","options","target","propertyKey","actualTarget","setMeta","streamable","maxSize","getArtifactConfig","getMeta","OBSERVABLE_CONFIG","Symbol","for","Observable","channel","target","propertyKey","actualTarget","existing","getMeta","setMeta","getObservables","getObservableByChannel","find","o","resolve","SANDBOX_CONFIG","Symbol","for","Sandbox","options","target","setMeta","network","commandTimeout","getSandboxConfig","getMeta","isPathAllowed","sandbox","filePath","operation","includes","normalized","resolve","slice","fs","filesystem","deny","some","pattern","matchGlob","allowList","read","write","SHELL_METACHARS","isCommandAllowed","command","cmds","commands","test","binary","split","d","startsWith","allow","a","escaped","replace","regex","buildGlobRegex","escapedPattern","RegExp","createDecorator","EditFormat","applyDecorators","decorators","target","propertyKey","descriptor","decorator","undefined"]}

package/dist/{chunk-4AN6LDJS.js → chunk-XCQNYAVU.js}

@@ -9,9 +9,11 @@ import {
   TOOL_METHODS,
   Trace,
   getAgentConfig,
+  getCheckpointConfig,
   getCompactionConfig,
   getContextWindowConfig,
   getGatewayConfig,
+  getHumanInTheLoopConfig,
   getMcpConfig,
   getMemoryConfig,
   getMeta,
@@ -19,7 +21,7 @@ import {
   getProjectContextConfig,
   getSkillsConfig,
   getSubAgents
-} from "./chunk-GVPUUKKE.js";
+} from "./chunk-FI6ZG2YP.js";
 import {
   __name
 } from "./chunk-7QVYU63E.js";
@@ -117,7 +119,8 @@ var AgentWarningCode = {
   FILTER_METADATA_ONLY: "THEO_AGENT_FILTER_METADATA_ONLY",
   BUDGET_TOP_LEVEL_METADATA_ONLY: "THEO_AGENT_BUDGET_TOP_LEVEL_METADATA_ONLY",
   CONTEXT_STRATEGY_METADATA_ONLY: "THEO_AGENT_CONTEXT_STRATEGY_METADATA_ONLY",
-  PROJECT_CONTEXT_KNOB_METADATA_ONLY: "THEO_AGENT_PROJECT_CONTEXT_KNOB_METADATA_ONLY"
+  PROJECT_CONTEXT_KNOB_METADATA_ONLY: "THEO_AGENT_PROJECT_CONTEXT_KNOB_METADATA_ONLY",
+  CHECKPOINT_STORAGE_METADATA_ONLY: "THEO_AGENT_CHECKPOINT_STORAGE_METADATA_ONLY"
 };
 var reflectorInstance = new Reflector();
 function walkToolbox(ToolboxClass) {
@@ -145,7 +148,8 @@ function walkToolbox(ToolboxClass) {
       capabilities: void 0,
       budget: void 0,
       trace: traceVal ?? false,
-      audit: auditVal ?? false
+      audit: auditVal ?? false,
+      hitl: getHumanInTheLoopConfig(ToolboxClass, propertyKey)
     };
   });
   return {
@@ -171,6 +175,12 @@ function warnUnmappedDecoratorKnobs(agentName, contextWindow, projectContext) {
   }
 }
 __name(warnUnmappedDecoratorKnobs, "warnUnmappedDecoratorKnobs");
+function warnNonDurableCheckpoint(agentName, checkpoint) {
+  if (checkpoint && checkpoint.storage !== "filesystem") {
+    console.warn(`[${AgentWarningCode.CHECKPOINT_STORAGE_METADATA_ONLY}] Agent ${agentName}: @Checkpoint({ storage: '${checkpoint.storage ?? "memory"}' }) does NOT resume across requests \u2014 only 'filesystem' selects the SDK's durable conversation store. Use @Checkpoint({ storage: 'filesystem' }) for cross-request resume.`);
+  }
+}
+__name(warnNonDurableCheckpoint, "warnNonDurableCheckpoint");
 var agentWalkCache = /* @__PURE__ */ new WeakMap();
 function walkAgentMetadata(AgentClass, toolboxClasses = []) {
   if (toolboxClasses.length === 0) {
@@ -208,6 +218,8 @@ function walkAgentMetadata(AgentClass, toolboxClasses = []) {
   const projectContext = getProjectContextConfig(AgentClass);
   warnUnmappedDecoratorKnobs(AgentClass.name, contextWindow, projectContext);
   const compaction = getCompactionConfig(AgentClass);
+  const checkpoint = getCheckpointConfig(AgentClass);
+  warnNonDurableCheckpoint(AgentClass.name, checkpoint);
   const result = {
     agentConfig,
     mainLoop,
@@ -223,7 +235,8 @@ function walkAgentMetadata(AgentClass, toolboxClasses = []) {
     contextWindow,
     projectContext,
     mcpServers,
-    compaction
+    compaction,
+    checkpoint
   };
   if (toolboxClasses.length === 0) {
     agentWalkCache.set(AgentClass, result);
@@ -258,6 +271,22 @@ function compileSkills(options) {
 __name(compileSkills, "compileSkills");
 
 // src/bridge/agent-compiler.ts
+function toolRuntimeName(namespace, toolName) {
+  return namespace ? `${namespace}.${toolName}` : toolName;
+}
+__name(toolRuntimeName, "toolRuntimeName");
+function compileHitlGates(toolboxes) {
+  const gates = /* @__PURE__ */ new Map();
+  for (const tb of toolboxes) {
+    for (const tool of tb.tools) {
+      if (tool.hitl) {
+        gates.set(toolRuntimeName(tb.namespace, tool.config.name), tool.hitl);
+      }
+    }
+  }
+  return gates;
+}
+__name(compileHitlGates, "compileHitlGates");
 function compileTools(toolboxes, toolboxInstances) {
   const tools = [];
   for (const tb of toolboxes) {
@@ -270,7 +299,7 @@ function compileTools(toolboxes, toolboxInstances) {
       if (typeof handler !== "function") {
         throw new Error(`[@theokit/agents] Toolbox ${tb.class.name}: '${String(tool.propertyKey)}' is not a function.`);
       }
-      const name = tb.namespace ? `${tb.namespace}.${tool.config.name}` : tool.config.name;
+      const name = toolRuntimeName(tb.namespace, tool.config.name);
       tools.push({
         name,
         description: tool.config.description,
@@ -298,6 +327,7 @@ __name(compileSubAgents, "compileSubAgents");
 function compileAgent(walkResult, toolboxInstances = /* @__PURE__ */ new Map()) {
   const tools = compileTools(walkResult.toolboxes, toolboxInstances);
   const agents = compileSubAgents(walkResult.subAgentClasses);
+  const hitl = compileHitlGates(walkResult.toolboxes);
   return {
     model: walkResult.agentConfig.model,
     reasoningEffort: walkResult.agentConfig.reasoningEffort,
@@ -314,7 +344,9 @@ function compileAgent(walkResult, toolboxInstances = /* @__PURE__ */ new Map())
     mcpServers: walkResult.mcpServers,
     maxIterations: walkResult.mainLoop.maxIterations ?? walkResult.agentConfig.maxIterations,
     timeoutMs: walkResult.mainLoop.timeoutMs ?? walkResult.agentConfig.timeoutMs,
-    stream: walkResult.agentConfig.stream ?? true
+    stream: walkResult.agentConfig.stream ?? true,
+    hitl: hitl.size > 0 ? hitl : void 0,
+    checkpoint: walkResult.checkpoint
   };
 }
 __name(compileAgent, "compileAgent");
@@ -940,6 +972,25 @@ function buildExtraCreateOptions(overrides, compiled) {
   return extra;
 }
 __name(buildExtraCreateOptions, "buildExtraCreateOptions");
+async function loadSdkRuntime() {
+  try {
+    const sdk = await import("@theokit/sdk");
+    const InMemory = sdk.InMemoryConversationStorage;
+    return {
+      Agent: sdk.Agent,
+      defineTool: sdk.defineTool,
+      InMemoryConversationStorage: InMemory,
+      FileSystemConversationStorage: "FileSystemConversationStorage" in sdk ? sdk.FileSystemConversationStorage : InMemory
+    };
+  } catch {
+    return null;
+  }
+}
+__name(loadSdkRuntime, "loadSdkRuntime");
+function newConversationStorage(compiled, InMemory, FileSystem) {
+  return compiled.checkpoint?.storage === "filesystem" ? new FileSystem() : new InMemory();
+}
+__name(newConversationStorage, "newConversationStorage");
 function createAsyncQueue() {
   const items = [];
   let wake = null;
@@ -1069,14 +1120,18 @@ function applyTextTransforms(events, opts) {
   return out;
 }
 __name(applyTextTransforms, "applyTextTransforms");
+function hasZodInputSchema(schema) {
+  return typeof schema?.parse === "function";
+}
+__name(hasZodInputSchema, "hasZodInputSchema");
 function buildSdkTools(compiledTools, defineTool, extraSdkTools = []) {
   return [
-    ...compiledTools.map((t) => defineTool({
+    ...compiledTools.map((t) => hasZodInputSchema(t.inputSchema) ? defineTool({
       name: t.name,
       description: t.description,
       inputSchema: t.inputSchema,
       handler: t.handler
-    })),
+    }) : t),
     ...extraSdkTools
   ];
 }
@@ -1090,15 +1145,8 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
     async *[Symbol.asyncIterator]() {
       const runId = `run-${Date.now()}`;
       const t0 = Date.now();
-      let Agent;
-      let defineTool;
-      let InMemoryConversationStorage;
-      try {
-        const sdk = await import("@theokit/sdk");
-        Agent = sdk.Agent;
-        defineTool = sdk.defineTool;
-        InMemoryConversationStorage = sdk.InMemoryConversationStorage;
-      } catch {
+      const rt = await loadSdkRuntime();
+      if (!rt) {
         yield {
           type: "error",
           code: "SDK_NOT_INSTALLED",
@@ -1107,6 +1155,7 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
         };
         return;
       }
+      const { Agent, defineTool, InMemoryConversationStorage, FileSystemConversationStorage } = rt;
       const sdkTools = buildSdkTools(compiledTools, defineTool, overrides.sdkTools);
       let agent;
       try {
@@ -1116,7 +1165,7 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
           cwd: overrides.cwd
         };
         const extra = buildExtraCreateOptions(overrides, compiled);
-        storage ??= new InMemoryConversationStorage();
+        storage ??= newConversationStorage(compiled, InMemoryConversationStorage, FileSystemConversationStorage);
         if (applied.length > 0) {
           console.debug("[THEO_AGENT_M8_RUNTIME_APPLIED]", {
             skills: applied.includes("skills"),
@@ -1220,6 +1269,36 @@ function* emitToolResult(event, seen) {
   }
 }
 __name(emitToolResult, "emitToolResult");
+function* emitApprovalRequest(event, seen) {
+  if (!seen.has(event.callId)) {
+    seen.add(event.callId);
+    yield {
+      type: "tool-input-available",
+      toolCallId: event.callId,
+      toolName: event.toolName,
+      input: event.input ?? {},
+      dynamic: true
+    };
+  }
+  yield {
+    type: "tool-approval-request",
+    approvalId: event.callId,
+    toolCallId: event.callId
+  };
+}
+__name(emitApprovalRequest, "emitApprovalRequest");
+function* emitCheckpointSaved(event) {
+  yield {
+    type: "data-checkpoint",
+    data: {
+      checkpointId: event.checkpointId,
+      resumeToken: event.resumeToken,
+      step: event.step
+    },
+    transient: true
+  };
+}
+__name(emitCheckpointSaved, "emitCheckpointSaved");
 async function* translateToUIMessageStream(events, opts) {
   yield {
     type: "start"
@@ -1265,9 +1344,15 @@ async function* translateToUIMessageStream(events, opts) {
       } else if (event.type === "tool_call") {
         yield* closeOpenBlock(state, opts.textId);
         yield* emitToolCall(event, seenToolCallIds);
+      } else if (event.type === "approval_required") {
+        yield* closeOpenBlock(state, opts.textId);
+        yield* emitApprovalRequest(event, seenToolCallIds);
       } else if (event.type === "tool_result") {
         yield* closeOpenBlock(state, opts.textId);
         yield* emitToolResult(event, seenToolCallIds);
+      } else if (event.type === "checkpoint_saved") {
+        yield* closeOpenBlock(state, opts.textId);
+        yield* emitCheckpointSaved(event);
       } else if (event.type === "error") {
         yield {
           type: "error",
@@ -1316,6 +1401,35 @@ function compileAgentDefinition(def) {
 }
 __name(compileAgentDefinition, "compileAgentDefinition");
 
+// src/bridge/hitl-plugin.ts
+function createHitlPlugin(wiring) {
+  return {
+    name: "theokit-hitl",
+    register(ctx) {
+      ctx.on("pre_tool_call", async (c) => {
+        const opts = wiring.gated.get(c.name);
+        if (!opts) return void 0;
+        const approvalId = crypto.randomUUID();
+        wiring.emit({
+          type: "approval_required",
+          callId: approvalId,
+          toolName: c.name,
+          question: opts.question,
+          input: c.args,
+          callbackUrl: `approve/${approvalId}`,
+          timeoutMs: opts.timeout ?? 3e5
+        });
+        const approved = await wiring.awaitApproval(approvalId, opts);
+        return approved ? void 0 : {
+          block: true,
+          message: `Tool '${c.name}' denied by human approver`
+        };
+      });
+    }
+  };
+}
+__name(createHitlPlugin, "createHitlPlugin");
+
 // src/bridge/agent-endpoint.ts
 var AgentDefinitionError = class extends Error {
   static {
@@ -1339,7 +1453,12 @@ function compileAgentModule(mod, source = "agent module") {
     return compileAgentDefinition(def);
   }
   if (typeof def === "function" && getAgentConfig(def) !== void 0) {
-    return compileAgent(walkAgentMetadata(def));
+    const walk = walkAgentMetadata(def, getMixins(def));
+    const instances = /* @__PURE__ */ new Map();
+    for (const tb of walk.toolboxes) {
+      instances.set(tb.class, new tb.class());
+    }
+    return compileAgent(walk, instances);
   }
   throw new AgentDefinitionError(source);
 }
@@ -1348,10 +1467,106 @@ async function* asAgentStream(events) {
   for await (const e of events) yield e;
 }
 __name(asAgentStream, "asAgentStream");
+var EventQueue = class EventQueue2 {
+  static {
+    __name(this, "EventQueue");
+  }
+  #items = [];
+  #resolvers = [];
+  #closed = false;
+  push(item) {
+    if (this.#closed) return;
+    const r = this.#resolvers.shift();
+    if (r) r({
+      value: item,
+      done: false
+    });
+    else this.#items.push(item);
+  }
+  close() {
+    this.#closed = true;
+    for (const r of this.#resolvers.splice(0)) r({
+      value: void 0,
+      done: true
+    });
+  }
+  async *drain() {
+    for (; ; ) {
+      if (this.#items.length > 0) {
+        yield this.#items.shift();
+        continue;
+      }
+      if (this.#closed) return;
+      const next = await new Promise((resolve) => this.#resolvers.push(resolve));
+      if (next.done) return;
+      yield next.value;
+    }
+  }
+};
+async function* appendCheckpointSaved(source, sessionId) {
+  let emitted = false;
+  const checkpoint = /* @__PURE__ */ __name(() => ({
+    type: "checkpoint_saved",
+    checkpointId: crypto.randomUUID(),
+    step: 0,
+    resumeToken: sessionId
+  }), "checkpoint");
+  for await (const ev of source) {
+    if (ev.type === "done" && !emitted) {
+      emitted = true;
+      yield checkpoint();
+    }
+    yield ev;
+  }
+  if (!emitted) yield checkpoint();
+}
+__name(appendCheckpointSaved, "appendCheckpointSaved");
 function streamAgentUIMessages(compiled, apiKey, input) {
-  const events = createSdkAgentStream(compiled, compiled.tools, apiKey)(input.message, input.sessionId);
-  return translateToUIMessageStream(asAgentStream(events), {
-    textId: crypto.randomUUID()
+  const textId = crypto.randomUUID();
+  const overrides = {};
+  if (input.conversationStorage) overrides.conversationStorage = input.conversationStorage;
+  let source;
+  if (!input.hitl || input.hitl.gated.size === 0) {
+    const events2 = createSdkAgentStream(compiled, compiled.tools, apiKey, overrides)(input.message, input.sessionId);
+    source = asAgentStream(events2);
+  } else {
+    const queue = new EventQueue();
+    input.signal?.addEventListener("abort", () => queue.close(), {
+      once: true
+    });
+    const plugin = createHitlPlugin({
+      gated: input.hitl.gated,
+      emit: /* @__PURE__ */ __name((e) => queue.push(e), "emit"),
+      awaitApproval: input.hitl.awaitApproval
+    });
+    const sdkStream = createSdkAgentStream(compiled, compiled.tools, apiKey, {
+      ...overrides,
+      // The HITL plugin is a structural @theokit/sdk Plugin (createHitlPlugin returns the
+      // { name, register } shape); the RuntimeOverrides.plugins union is widened at the SDK edge.
+      plugins: [
+        plugin
+      ]
+    })(input.message, input.sessionId);
+    void (async () => {
+      try {
+        for await (const e of sdkStream) queue.push(e);
+      } catch (err) {
+        queue.push({
+          type: "error",
+          code: "SDK_STREAM_ERROR",
+          message: err instanceof Error ? err.message : String(err),
+          retryable: false
+        });
+      } finally {
+        queue.close();
+      }
+    })();
+    source = queue.drain();
+  }
+  const durableCheckpoint = compiled.checkpoint?.storage === "filesystem";
+  const events = durableCheckpoint ? appendCheckpointSaved(source, input.sessionId) : source;
+  return translateToUIMessageStream(events, {
+    textId
   });
 }
 __name(streamAgentUIMessages, "streamAgentUIMessages");
@@ -2101,4 +2316,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-4AN6LDJS.js.map
+//# sourceMappingURL=chunk-XCQNYAVU.js.map