@theokit/agents 0.39.0 → 0.42.0

package/dist/decorators.d.ts

@@ -60,23 +60,6 @@ declare function Hook(point: HookPoint): MethodDecorator;
 declare function getHooks(target: Function): HookEntry[];
 declare function getHooksByPoint(target: Function, point: HookPoint): HookEntry[];
 
-type ConversationStorage = 'memory' | 'filesystem' | 'drizzle' | 'redis';
-type CompactionStrategy = 'truncate' | 'summarize' | 'sliding-window';
-interface ConversationOptions {
-    /** Storage backend for conversation history. */
-    storage?: ConversationStorage;
-    /** Maximum messages before compaction triggers (0 = no limit). */
-    maxHistory?: number;
-    /** How to compact when maxHistory is exceeded. */
-    compaction?: CompactionStrategy;
-    /** Time-to-live in milliseconds before conversation expires (0 = never). */
-    ttl?: number;
-    /** Number of recent messages to always preserve during compaction. */
-    preserveLastN?: number;
-}
-declare function Conversation(options?: ConversationOptions): ClassDecorator;
-declare function getConversationConfig(target: Function): ConversationOptions | undefined;
-
 /** Override the LLM model for an agent class or a specific tool method. */
 declare const Model: (value: string) => MethodDecorator & ClassDecorator;
 
@@ -190,4 +173,4 @@ declare function applyDecorators(...decorators: AnyDecorator[]): ClassDecorator
 declare function Mixin(...mixinClasses: Function[]): ClassDecorator;
 declare function getMixins(target: Function): Function[];
 
-export { Agent, AgentOptions, ApprovalOptions, Artifact, type ArtifactOptions, type ArtifactResult, Audit, Budget, BudgetOptions, type CommandPermissions, type CompactionStrategy, Conversation, type ConversationOptions, type ConversationStorage, EditFormat, type EditFormatType, type FilesystemPermissions, Guardrails, Hook, type HookEntry, type HookPoint, MainLoop, MainLoopMeta, MainLoopOptions, Mixin, Model, Observable, type ObservableEntry, Policy, PolicyHandler, RequiresApproval, RequiresCapability, Sandbox, type SandboxOptions, SubAgents, Tool, ToolOptions, Toolbox, ToolboxOptions, Trace, applyDecorators, getAgentConfig, getArtifactConfig, getConversationConfig, getGuardrailsConfig, getHooks, getHooksByPoint, getMainLoop, getMixins, getObservableByChannel, getObservables, getSandboxConfig, getSubAgents, getToolConfig, getToolMethods, getToolboxConfig, isCommandAllowed, isPathAllowed };
+export { Agent, AgentOptions, ApprovalOptions, Artifact, type ArtifactOptions, type ArtifactResult, Audit, Budget, BudgetOptions, type CommandPermissions, EditFormat, type EditFormatType, type FilesystemPermissions, Guardrails, Hook, type HookEntry, type HookPoint, MainLoop, MainLoopMeta, MainLoopOptions, Mixin, Model, Observable, type ObservableEntry, Policy, PolicyHandler, RequiresApproval, RequiresCapability, Sandbox, type SandboxOptions, SubAgents, Tool, ToolOptions, Toolbox, ToolboxOptions, Trace, applyDecorators, getAgentConfig, getArtifactConfig, getGuardrailsConfig, getHooks, getHooksByPoint, getMainLoop, getMixins, getObservableByChannel, getObservables, getSandboxConfig, getSubAgents, getToolConfig, getToolMethods, getToolboxConfig, isCommandAllowed, isPathAllowed };

package/dist/decorators.js

@@ -132,26 +132,6 @@ function getHooksByPoint(target, point) {
 }
 __name(getHooksByPoint, "getHooksByPoint");
 
-// src/decorators/conversation.ts
-var CONVERSATION_CONFIG = /* @__PURE__ */ Symbol.for("theokit:agents:conversation");
-function Conversation(options = {}) {
-  return (target) => {
-    setMeta(CONVERSATION_CONFIG, target, {
-      storage: "memory",
-      maxHistory: 0,
-      compaction: "truncate",
-      ttl: 0,
-      preserveLastN: 5,
-      ...options
-    });
-  };
-}
-__name(Conversation, "Conversation");
-function getConversationConfig(target) {
-  return getMeta(CONVERSATION_CONFIG, target);
-}
-__name(getConversationConfig, "getConversationConfig");
-
 // src/decorators/model.ts
 import { createDecorator } from "@theokit/http";
 var Model = createDecorator();
@@ -276,7 +256,6 @@ export {
   Checkpoint,
   Compaction,
   ContextWindow,
-  Conversation,
   EditFormat,
   Gateway,
   Guardrails,
@@ -304,7 +283,6 @@ export {
   getCheckpointConfig,
   getCompactionConfig,
   getContextWindowConfig,
-  getConversationConfig,
   getGatewayConfig,
   getGuardrailsConfig,
   getHooks,

package/dist/decorators.js.map

@@ -1 +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"]}
+{"version":3,"sources":["../src/decorators/main-loop.ts","../src/decorators/tool.ts","../src/decorators/hook.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 * @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","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/index.d.ts

@@ -1,8 +1,8 @@
 import { G as Guardrail, R as ReasoningEffort } from './types-DVA4LQsA.js';
 export { A as AgentOptions, a as ApprovalOptions, B as BudgetOptions, C as CostBudgetExceededError, b as GuardrailAction, c as GuardrailPhase, d as GuardrailResult, e as GuardrailViolationError, H as HumanInTheLoopOptions, M as MainLoopMeta, f as MainLoopOptions, P as PolicyHandler, T as TimeoutAction, g as ToolOptions, h as ToolboxOptions } from './types-DVA4LQsA.js';
-import { L as LoopStrategy, R as ReflectionStrategy, C as CompiledAgentOptions, a as CompiledTool, b as RoundStreamFactory, S as StreamEvent, D as DelegationResult, A as AgentManifestEntry } from './bridge-entry-CAY5JP9z.js';
-export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as AgentWalkResult, p as AgentWarningCode, q as AgentsPluginOptions, r as ApiErrorContext, s as ApiErrorDecision, t as ApiErrorPolicy, u as ApprovalRequiredEvent, v as ArtifactChunkEvent, w as ArtifactStartEvent, B as BackgroundDelegation, x as BeforeToolCallContext, y as BudgetExceededError, z as CheckpointSavedEvent, E as CompiledContextWindow, F as ContextualTool, G as DEFAULT_MAX_ITERATIONS, H as DefineAgentConfig, I as DelegateFn, J as DelegateOptions, K as DelegationError, M as DoneEvent, N as ErrorEvent, O as FileEditEvent, P as HitlDecision, Q as InferAgentInput, T as InferAgentToolNames, U as IterationEvent, V as LLMCallContext, W as LoopFinishReason, X as LoopOutcome, Y as LoopStrategyConfig, Z as McpApprovalSpec, _ as McpRegistryConfig, $ as McpRequestContext, a0 as McpSelection, a1 as PartialToolCallEvent, a2 as ProcessInputContext, a3 as ReflectionContext, a4 as ReflectionResult, a5 as ReflectionStrategyConfig, a6 as RunStartedEvent, a7 as ScoreVerdict, a8 as ScoredDelegation, a9 as Scorer, aa as SdkMessage, ab as Segment, ac as SkillsRequestContext, ad as SkillsSelection, ae as StateUpdateEvent, af as TextDeltaEvent, ag as ThinkingEvent, ah as ToolCallEvent, ai as ToolCallVeto, aj as ToolHooks, ak as ToolHooksPlugin, al as ToolResultEvent, am as ToolWalkResult, an as ToolboxWalkResult, ao as agent, ap as agentsPlugin, aq as buildModelSelection, ar as compileAgent, as as compileAgentDefinition, at as compileAgentModule, au as compileContextWindow, av as compileProjectContext, aw as compileSkills, ax as compileTools, ay as contextualTool, az as createAgentExecutionContext, aA as createApiErrorHandler, aB as createSdkAgentStream, aC as createThinkTagExtractor, aD as createToolHooksPlugin, aE as delegate, aF as delegateBackground, aG as delegateWithScoring, aH as extractThinkTagStream, aI as generateAgentManifest, aJ as generateAgentRoutes, aK as isAgentContext, aL as isAgentDefinition, aM as isApprovalRequired, aN as isDone, aO as isError, aP as isPartialToolCall, aQ as isTextDelta, aR as isToolCall, aS as isToolResult, aT as ladderReflectionStrategy, aU as loopStrategyConfigSchema, aV as mcpRegistry, aW as mcpToolApprovals, aX as noopReflectionStrategy, aY as projectContextMetadataOnlyKnobs, aZ as reflectionStrategyConfigSchema, a_ as resolveEnabledSkills, a$ as resolveLoopStrategy, b0 as resolveMcpServers, b1 as runWithApiErrorHandling, b2 as streamAgentResponse, b3 as streamAgentUIMessages, b4 as translateSdkEvent, b5 as translateToUIMessageStream, b6 as validateUniqueRoutes, b7 as walkAgentMetadata } from './bridge-entry-CAY5JP9z.js';
-import { PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition, BudgetTracker, ConversationStorageAdapter, CustomTool } from '@theokit/sdk';
+import { L as LoopStrategy, R as ReflectionStrategy, C as CompiledAgentOptions, a as CompiledTool, b as RoundStreamFactory, S as StreamEvent, D as DelegationResult, A as AgentManifestEntry } from './bridge-entry-CE3ie8rG.js';
+export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as AgentWalkResult, p as AgentWarningCode, q as AgentsPluginOptions, r as ApiErrorContext, s as ApiErrorDecision, t as ApiErrorPolicy, u as ApprovalRequiredEvent, v as ArtifactChunkEvent, w as ArtifactStartEvent, B as BackgroundDelegation, x as BeforeToolCallContext, y as BudgetExceededError, z as CheckpointSavedEvent, E as CompiledContextWindow, F as ContextualTool, G as DEFAULT_MAX_ITERATIONS, H as DefineAgentConfig, I as DelegateFn, J as DelegateOptions, K as DelegationError, M as DoneEvent, N as ErrorEvent, O as FileEditEvent, P as HitlDecision, Q as InferAgentInput, T as InferAgentToolNames, U as IterationEvent, V as LLMCallContext, W as LoopFinishReason, X as LoopOutcome, Y as LoopStrategyConfig, Z as McpApprovalSpec, _ as McpRegistryConfig, $ as McpRequestContext, a0 as McpSelection, a1 as PartialToolCallEvent, a2 as ProcessInputContext, a3 as ReflectionContext, a4 as ReflectionResult, a5 as ReflectionStrategyConfig, a6 as RunStartedEvent, a7 as ScoreVerdict, a8 as ScoredDelegation, a9 as Scorer, aa as SdkMessage, ab as Segment, ac as SkillsRequestContext, ad as SkillsSelection, ae as StateUpdateEvent, af as TextDeltaEvent, ag as ThinkingEvent, ah as ToolCallEvent, ai as ToolCallVeto, aj as ToolHooks, ak as ToolHooksPlugin, al as ToolResultEvent, am as ToolWalkResult, an as ToolboxWalkResult, ao as agent, ap as agentsPlugin, aq as buildModelSelection, ar as compileAgent, as as compileAgentDefinition, at as compileAgentModule, au as compileContextWindow, av as compileProjectContext, aw as compileSkills, ax as compileTools, ay as contextualTool, az as createAgentExecutionContext, aA as createApiErrorHandler, aB as createSdkAgentStream, aC as createThinkTagExtractor, aD as createToolHooksPlugin, aE as delegate, aF as delegateBackground, aG as delegateWithScoring, aH as extractThinkTagStream, aI as generateAgentManifest, aJ as generateAgentRoutes, aK as isAgentContext, aL as isAgentDefinition, aM as isApprovalRequired, aN as isDone, aO as isError, aP as isPartialToolCall, aQ as isTextDelta, aR as isToolCall, aS as isToolResult, aT as ladderReflectionStrategy, aU as loopStrategyConfigSchema, aV as mcpRegistry, aW as mcpToolApprovals, aX as noopReflectionStrategy, aY as projectContextMetadataOnlyKnobs, aZ as reflectionStrategyConfigSchema, a_ as resolveEnabledSkills, a$ as resolveLoopStrategy, b0 as resolveMcpServers, b1 as runWithApiErrorHandling, b2 as streamAgentResponse, b3 as streamAgentUIMessages, b4 as translateSdkEvent, b5 as translateToUIMessageStream, b6 as validateUniqueRoutes, b7 as walkAgentMetadata } from './bridge-entry-CE3ie8rG.js';
+import { PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition, BudgetTracker, CustomTool } from '@theokit/sdk';
 import { RetryOptions } from '@theokit/sdk/retry';
 import { CompressibleMessage } from '@theokit/sdk/compaction';
 export { CompressibleMessage } from '@theokit/sdk/compaction';
@@ -236,6 +236,11 @@ interface AgentRunnerRunOptions {
      * (read by a `SystemPromptResolver` / `@ProjectContext`). Absent ⇒ no `local.cwd`.
      */
     readonly cwd?: string;
+    /**
+     * SDK 4.0 (SE40): per-run root of the native `.jsonl` session transcript, forwarded into
+     * `Agent.create({ local: { baseDir } })`. Absent ⇒ the SDK default (`~/.theokit`).
+     */
+    readonly baseDir?: string;
     /**
      * V4-L.2 (Axis-A SWAP): per-run loop-ceiling override. When provided, the loop
      * strategy is re-resolved with this ceiling for this call only (zod-validated —
@@ -259,12 +264,6 @@ interface AgentRunnerRunOptions {
      * send. Distinct from {@link AgentRunnerRunOptions.budget} (the OUTER reflective-loop USD ceiling).
      */
     readonly budgetTracker?: BudgetTracker;
-    /**
-     * V4-M: conversation store shared across the loop's rounds so history persists (round N+1
-     * sees rounds 1..N). Default `InMemoryConversationStorage` (per-run, no disk). Pass a
-     * `FileSystemConversationStorage`/custom adapter for durable cross-run history.
-     */
-    readonly conversationStorage?: ConversationStorageAdapter;
     /**
      * V4-Q: pre-built SDK `CustomTool[]` forwarded RAW to `Agent.create.tools` (appended after the
      * agent's compiled tools), bypassing `defineTool`. For an app whose tools come from imperative

package/dist/index.js

@@ -69,7 +69,7 @@ import {
   unicodeNormalizer,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-JID4DOB3.js";
+} from "./chunk-OFPS2N3U.js";
 import "./chunk-NERDIS45.js";
 import {
   __name

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/agents",
-  "version": "0.39.0",
+  "version": "0.42.0",
   "description": "AI agents as first-class citizens of the TheoKit pipeline. The fluent agent()/tool() builders compile to SDK Agent.create() (M31 builder-only authoring API).",
   "type": "module",
   "sideEffects": false,
@@ -27,8 +27,8 @@
   ],
   "peerDependencies": {
     "@theokit/http": ">=0.1.0-alpha.0",
-    "@theokit/sdk": ">=3.5.0",
-    "@theokit/sdk-tools": ">=0.9.1",
+    "@theokit/sdk": "^4.0.1",
+    "@theokit/sdk-tools": "^0.11.0",
     "ai": ">=7.0.0",
     "reflect-metadata": ">=0.2.0",
     "zod": "^4.0.0"
@@ -42,8 +42,8 @@
     }
   },
   "devDependencies": {
-    "@theokit/sdk": "^3.5.0",
-    "@theokit/sdk-tools": "^0.9.1",
+    "@theokit/sdk": "^4.0.1",
+    "@theokit/sdk-tools": "^0.11.0",
     "ai": "^7.0.14",
     "reflect-metadata": "^0.2.2",
     "tsup": "^8.5.1",