@theokit/agents 0.30.2 → 0.32.0

package/LICENSE

@@ -1,201 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for describing the origin of the Work and
-      reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2026 usetheo.dev
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.

package/dist/chunk-FI6ZG2YP.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/metadata/index.ts","../src/metadata/keys.ts","../src/decorators/agent.ts","../src/decorators/policies.ts","../src/decorators/observability.ts","../src/decorators/gateway.ts","../src/decorators/sub-agents.ts","../src/decorators/memory.ts","../src/decorators/skills.ts","../src/decorators/mcp.ts","../src/decorators/human-in-the-loop.ts","../src/decorators/context-window.ts","../src/decorators/compaction.ts","../src/decorators/checkpoint.ts","../src/decorators/project-context.ts","../src/decorators/mixin.ts"],"sourcesContent":["// Re-export setMeta/getMeta from http-decorators (DRY — single metadata engine)\n// Relative path for workspace-local usage; vitest resolves via alias\nexport { setMeta, getMeta } from '@theokit/http'\n\nexport * from './keys.js'\n","/** Symbol.for metadata keys for agent decorators — cross-module safe with SWC loader. */\n\nexport const AGENT_CONFIG = Symbol.for('theokit:agents:config')\nexport const AGENT_MAIN_LOOP = Symbol.for('theokit:agents:main-loop')\nexport const TOOLBOX_CONFIG = Symbol.for('theokit:agents:toolbox')\nexport const TOOL_CONFIG = Symbol.for('theokit:agents:tool')\nexport const TOOL_METHODS = Symbol.for('theokit:agents:tool-methods')\n","/**\n * @Agent() — marks a class as an AI agent controller.\n *\n * Convention over configuration:\n *   @Agent()                    → name + route inferred from class name\n *   @Agent({ model: '...' })   → name + route inferred, model explicit\n *   @Agent({ name, route, model }) → fully explicit\n *\n * @example\n * ```ts\n * // Convention: SupportAgent → name: 'support', route: '/api/agents/support'\n * @Agent()\n * class SupportAgent { ... }\n *\n * // Partial: infer name + route, set model\n * @Agent({ model: 'claude-sonnet-4-5-20250929' })\n * class SupportAgent { ... }\n *\n * // Explicit: full control\n * @Agent({ name: 'support-agent', route: '/api/agents/support', model: '...' })\n * class SupportAgent { ... }\n * ```\n */\nimport { setMeta, getMeta, AGENT_CONFIG } from '../metadata/index.js'\nimport type { AgentOptions } from '../types.js'\n\n/**\n * Infer agent name and route from class name (Rails-style convention).\n *\n * SupportAgent     → name: 'support',      route: '/api/agents/support'\n * ResearchAgent    → name: 'research',     route: '/api/agents/research'\n * CodeReviewAgent  → name: 'code-review',  route: '/api/agents/code-review'\n */\nfunction inferAgentMeta(className: string): { name: string; route: string } {\n  const stripped = className.replace(/Agent$/, '')\n  const kebab = 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  return { name: kebab, route: `/api/agents/${kebab}` }\n}\n\nexport function Agent(options?: Partial<AgentOptions>): ClassDecorator {\n  return (target: Function) => {\n    const inferred = inferAgentMeta(target.name)\n    setMeta(AGENT_CONFIG, target, {\n      stream: true,\n      name: inferred.name,\n      route: inferred.route,\n      ...options, // explicit values override inferred\n    })\n  }\n}\n\nexport function getAgentConfig(target: Function): AgentOptions | undefined {\n  return getMeta<AgentOptions>(AGENT_CONFIG, target)\n}\n","/**\n * Agent-native policy decorators — built on http-decorators' createDecorator<T>().\n *\n * These decorators work with Reflector.getAllAndOverride() for hierarchical\n * resolution: tool → toolbox → agent (method-level overrides class-level).\n */\nimport { createDecorator } from '@theokit/http'\n\nimport type { ApprovalOptions, BudgetOptions, PolicyHandler } from '../types.js'\n\n/** Mark a tool as requiring human approval before execution. */\nexport const RequiresApproval = createDecorator<ApprovalOptions>()\n\n/** Require specific capabilities (permissions) to execute a tool. */\nexport const RequiresCapability = createDecorator<string[]>()\n\n/** Set a cost budget for an agent or tool scope. */\nexport const Budget = createDecorator<BudgetOptions>()\n\n/** Attach policy handler functions (CASL-style authorization). */\nexport const Policy = createDecorator<PolicyHandler[]>()\n","/**\n * Observability decorators for agent tracing and auditing.\n */\nimport { createDecorator } from '@theokit/http'\n\n/** Enable distributed tracing for a tool/toolbox/agent. */\nexport const Trace = createDecorator<boolean>()\n\n/** Enable audit logging for a tool/toolbox/agent. */\nexport const Audit = createDecorator<boolean>()\n","/**\n * @Gateway() — declares which platform adapters an agent supports.\n *\n * Stores gateway configuration metadata on the agent class.\n * The GatewayRunner reads this to auto-wire adapters without manual plumbing.\n *\n * @example\n * ```ts\n * @Agent({ name: 'support', route: '/api/agents/support' })\n * @Gateway({\n *   platforms: ['telegram', 'discord', 'slack'],\n *   sessionStrategy: 'per-user',\n * })\n * @UseGuards(AuthGuard)\n * class SupportAgent {\n *   @MainLoop()\n *   async run(ctx: AgentContext) { ... }\n * }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst GATEWAY_CONFIG = Symbol.for('theokit:agents:gateway')\n\nexport type PlatformName =\n  | 'telegram'\n  | 'discord'\n  | 'slack'\n  | 'whatsapp'\n  | 'teams'\n  | 'email'\n  | 'sms'\n  | 'mattermost'\n  | 'line'\n  | 'matrix'\n\nexport type SessionStrategy =\n  | 'per-user'       // telegram-dm-{userId}\n  | 'per-channel'    // telegram-grp-{channelId}\n  | 'per-thread'     // telegram-tpc-{channelId}-{topicId}\n\nexport interface GatewayOptions {\n  /** Platform adapters this agent supports. */\n  platforms: PlatformName[]\n  /** How to resolve agentId from inbound events (default: 'per-user'). */\n  sessionStrategy?: SessionStrategy\n  /** Auto-start typing indicator while agent processes (default: true). */\n  typing?: boolean\n}\n\nexport function Gateway(options: GatewayOptions): ClassDecorator {\n  return (target: Function) => {\n    setMeta(GATEWAY_CONFIG, target, { typing: true, sessionStrategy: 'per-user', ...options })\n  }\n}\n\nexport function getGatewayConfig(target: Function): GatewayOptions | undefined {\n  return getMeta<GatewayOptions>(GATEWAY_CONFIG, target)\n}\n\n/**\n * Resolve a stable agentId from a platform event based on the session strategy.\n *\n * Mirrors @theokit/gateway SessionRouter.defaultStrategy() but is configurable\n * via the @Gateway decorator.\n */\nexport function resolveSessionId(\n  strategy: SessionStrategy,\n  platform: string,\n  sender: { id: string },\n  channel: { id: string; type: 'dm' | 'group' | 'thread'; topicId?: string },\n): string {\n  switch (strategy) {\n    case 'per-user':\n      return `${platform}-dm-${sender.id}`\n    case 'per-channel':\n      return `${platform}-grp-${channel.id}`\n    case 'per-thread':\n      return `${platform}-tpc-${channel.id}-${channel.topicId ?? 'main'}`\n  }\n}\n","/**\n * @SubAgents() — declares child agents that a parent agent can handoff to.\n *\n * Compiles to the SDK's `AgentOptions.agents` map. The parent agent\n * can delegate work to sub-agents via the built-in Agent tool.\n *\n * @example\n * ```ts\n * @Agent({ name: 'orchestrator', route: '/api/agents/orchestrator' })\n * @SubAgents([ResearchAgent, CoderAgent, ReviewerAgent])\n * class OrchestratorAgent {\n *   @MainLoop({ strategy: 'plan-act-reflect' })\n *   async run(ctx: AgentContext) { ... }\n * }\n * ```\n *\n * Each referenced class MUST be decorated with @Agent().\n * The compiler reads their metadata to build the SDK agents map.\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nimport { getAgentConfig } from './agent.js'\n\nconst SUB_AGENTS = Symbol.for('theokit:agents:sub-agents')\n\nexport function SubAgents(agentClasses: Function[]): ClassDecorator {\n  return (target: Function) => {\n    // Validate at decoration time: all classes must have @Agent\n    for (const cls of agentClasses) {\n      const config = getAgentConfig(cls)\n      if (!config) {\n        throw new Error(\n          `[@theokit/agents] @SubAgents on ${target.name}: class ${cls.name} is missing @Agent() decorator.`,\n        )\n      }\n    }\n    setMeta(SUB_AGENTS, target, agentClasses)\n  }\n}\n\nexport function getSubAgents(target: Function): Function[] {\n  return getMeta<Function[]>(SUB_AGENTS, target) ?? []\n}\n","/**\n * @Memory() — declares persistent memory configuration for an agent.\n *\n * Compiles to SDK's MemorySettings in Agent.create({ memory }).\n * Memory is per-agent, scoped by session strategy.\n *\n * @example\n * ```ts\n * @Agent({ name: 'support', route: '/api/agents/support' })\n * @Memory({ provider: 'built-in', embeddings: true, fts: true, scope: 'per-user' })\n * class SupportAgent { ... }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst MEMORY_CONFIG = Symbol.for('theokit:agents:memory')\n\nexport type MemoryProvider = 'built-in' | 'honcho' | 'supermemory' | 'mem0'\nexport type MemoryScope = 'per-user' | 'per-agent' | 'per-tenant' | 'global'\n\nexport interface MemoryOptions {\n  /** Memory provider backend. */\n  provider?: MemoryProvider\n  /** Enable semantic search via embeddings. */\n  embeddings?: boolean\n  /** Enable full-text search (FTS5). */\n  fts?: boolean\n  /** Memory isolation scope (default: 'per-user'). */\n  scope?: MemoryScope\n  /** Maximum facts to retain per scope (0 = unlimited). */\n  maxFacts?: number\n}\n\nexport function Memory(options: MemoryOptions = {}): ClassDecorator {\n  return (target: Function) => {\n    setMeta(MEMORY_CONFIG, target, {\n      provider: 'built-in',\n      embeddings: false,\n      fts: false,\n      scope: 'per-user',\n      ...options,\n    })\n  }\n}\n\nexport function getMemoryConfig(target: Function): MemoryOptions | undefined {\n  return getMeta<MemoryOptions>(MEMORY_CONFIG, target)\n}\n","/**\n * @Skills() — declares markdown skill files injected into the agent's system prompt.\n *\n * Compiles to SDK's SkillsSettings in Agent.create({ skills }).\n * Skills are .theokit/skills/<name>/SKILL.md files discovered at agent creation.\n *\n * @example\n * ```ts\n * @Agent({ name: 'support', route: '/api/agents/support' })\n * @Skills(['customer-service', 'refund-policy', 'escalation-protocol'])\n * class SupportAgent { ... }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst SKILLS_CONFIG = Symbol.for('theokit:agents:skills')\n\nexport interface SkillsOptions {\n  /** Skill names to include (resolved from .theokit/skills/<name>/SKILL.md). */\n  include: string[]\n  /** Auto-discover all skills in .theokit/skills/ (default: false). */\n  autoDiscover?: boolean\n}\n\nexport function Skills(namesOrOptions: string[] | SkillsOptions): ClassDecorator {\n  return (target: Function) => {\n    const options: SkillsOptions = Array.isArray(namesOrOptions)\n      ? { include: namesOrOptions, autoDiscover: false }\n      : namesOrOptions\n    setMeta(SKILLS_CONFIG, target, options)\n  }\n}\n\nexport function getSkillsConfig(target: Function): SkillsOptions | undefined {\n  return getMeta<SkillsOptions>(SKILLS_CONFIG, target)\n}\n","/**\n * @MCP() — declares Model Context Protocol servers available to an agent.\n *\n * Compiles to SDK's mcpServers in Agent.create({ mcpServers }).\n * Each key is a server name; the value is the server configuration.\n *\n * @example\n * ```ts\n * @Agent({ name: 'dev', route: '/api/agents/dev' })\n * @MCP({\n *   github: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'] },\n *   filesystem: { command: 'npx', args: ['-y', '@mcp/server-filesystem', '/workspace'] },\n * })\n * class DevAgent { ... }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst MCP_CONFIG = Symbol.for('theokit:agents:mcp')\n\nexport interface McpServerConfig {\n  /** Command to start the MCP server. */\n  command: string\n  /** Arguments passed to the command. */\n  args?: string[]\n  /** Environment variables for the server process. */\n  env?: Record<string, string>\n  /** Working directory for the server process. */\n  cwd?: string\n}\n\nexport type McpServersMap = Record<string, McpServerConfig>\n\nexport function MCP(servers: McpServersMap): ClassDecorator {\n  return (target: Function) => {\n    setMeta(MCP_CONFIG, target, servers)\n  }\n}\n\nexport function getMcpConfig(target: Function): McpServersMap | undefined {\n  return getMeta<McpServersMap>(MCP_CONFIG, target)\n}\n","/**\n * @HumanInTheLoop() — pause agent execution to request human approval.\n *\n * When applied to a @Tool method, the agent pauses before executing the tool\n * and emits an 'approval_required' SSE event. The client must POST to the\n * callback URL to approve or deny. If denied or timed out, the tool is skipped.\n *\n * @example\n * ```ts\n * @Toolbox({ namespace: 'ops' })\n * class OpsTools {\n *   @Tool({ name: 'deploy', description: 'Deploy to prod', input: z.object({...}) })\n *   @HumanInTheLoop({\n *     question: 'Confirm deployment to production?',\n *     timeout: 300_000,\n *     onTimeout: 'abort',\n *   })\n *   async deploy(input: {...}) { ... }\n * }\n * ```\n *\n * SSE event emitted:\n * ```json\n * { \"type\": \"approval_required\", \"toolName\": \"ops.deploy\", \"question\": \"...\", \"callbackUrl\": \"/agents/x/approve/call-123\" }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst HITL_CONFIG = Symbol.for('theokit:agents:human-in-the-loop')\n\nexport type TimeoutAction = 'abort' | 'proceed' | 'retry'\n\nexport interface HumanInTheLoopOptions {\n  /** Question shown to the human approver. */\n  question: string\n  /** Timeout in milliseconds before onTimeout fires (default: 300_000 = 5 min). */\n  timeout?: number\n  /** Action when timeout expires (default: 'abort'). */\n  onTimeout?: TimeoutAction\n  /** Show the tool input to the approver (default: true). */\n  showInput?: boolean\n}\n\nexport function HumanInTheLoop(options: HumanInTheLoopOptions): MethodDecorator {\n  return (target: object, propertyKey: string | symbol) => {\n    const actualTarget = target.constructor\n    setMeta(HITL_CONFIG, actualTarget, {\n      timeout: 300_000,\n      onTimeout: 'abort',\n      showInput: true,\n      ...options,\n    }, propertyKey)\n  }\n}\n\nexport function getHumanInTheLoopConfig(\n  target: Function,\n  propertyKey: string | symbol,\n): HumanInTheLoopOptions | undefined {\n  return getMeta<HumanInTheLoopOptions>(HITL_CONFIG, target, propertyKey)\n}\n","/**\n * @ContextWindow() — declares context window management strategy.\n *\n * Controls how the agent handles context when conversation history grows\n * beyond the LLM's context window. Mirrors Claude Code's PreCompact behavior.\n *\n * @example\n * ```ts\n * @Agent({ name: 'research', route: '/research' })\n * @ContextWindow({\n *   maxTokens: 100_000,\n *   compactionStrategy: 'summarize-oldest',\n *   preserveSystemPrompt: true,\n *   preserveLastN: 10,\n * })\n * class ResearchAgent { ... }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst CONTEXT_WINDOW_CONFIG = Symbol.for('theokit:agents:context-window')\n\nexport type ContextCompactionStrategy =\n  | 'truncate-oldest'      // Drop oldest messages beyond limit\n  | 'summarize-oldest'     // LLM-summarize oldest messages into a single message\n  | 'sliding-window'       // Keep last N messages only\n  | 'priority-based'       // Keep tool results + recent; summarize reasoning\n\nexport interface ContextWindowOptions {\n  /** Maximum tokens before compaction triggers. */\n  maxTokens?: number\n  /** How to compact when maxTokens is exceeded. */\n  compactionStrategy?: ContextCompactionStrategy\n  /** Always preserve the system prompt during compaction (default: true). */\n  preserveSystemPrompt?: boolean\n  /** Number of recent messages to always keep intact (default: 10). */\n  preserveLastN?: number\n  /** Keep all tool results even during compaction (default: true). */\n  preserveToolResults?: boolean\n}\n\nexport function ContextWindow(options: ContextWindowOptions = {}): ClassDecorator {\n  return (target: Function) => {\n    setMeta(CONTEXT_WINDOW_CONFIG, target, {\n      maxTokens: 100_000,\n      compactionStrategy: 'summarize-oldest',\n      preserveSystemPrompt: true,\n      preserveLastN: 10,\n      preserveToolResults: true,\n      ...options,\n    })\n  }\n}\n\nexport function getContextWindowConfig(target: Function): ContextWindowOptions | undefined {\n  return getMeta<ContextWindowOptions>(CONTEXT_WINDOW_CONFIG, target)\n}\n","/**\n * `@Compaction(name, opts)` — declares the agent's transcript-compaction strategy\n * (V4-F). Metadata-only: it records the choice; `AgentRunner.build()` resolves it\n * to a concrete {@link TranscriptCompactionStrategy} via `resolveCompactionStrategy`\n * (EC-5 — an invalid name/budget fails fast at build, not at decoration).\n *\n * Mirrors the `@ContextWindow` metadata pattern (`setMeta`/`getMeta` + a unique\n * Symbol). NOT auto-applied by the loop (ADR D1) — the resolved strategy is exposed\n * as `runner.compaction` for the app to call.\n *\n * @example\n * ```ts\n * @Agent({ model })\n * @Compaction('token-budget', { keepTokens: 8000 })\n * class CodeAgent {}\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst COMPACTION_CONFIG = Symbol.for('theokit:agents:compaction')\n\n/** Stored `@Compaction` declaration (resolved + validated at `AgentRunner.build()`). */\nexport interface CompactionDecoratorConfig {\n  /** Strategy name (e.g. `'token-budget'`). Validated at resolve time. */\n  name: string\n  /** Token budget for `'token-budget'`. Required at resolve time (EC-2). */\n  keepTokens?: number\n}\n\nexport function Compaction(name: string, options: { keepTokens?: number } = {}): ClassDecorator {\n  return (target: Function) => {\n    setMeta(COMPACTION_CONFIG, target, { name, keepTokens: options.keepTokens })\n  }\n}\n\nexport function getCompactionConfig(target: Function): CompactionDecoratorConfig | undefined {\n  return getMeta<CompactionDecoratorConfig>(COMPACTION_CONFIG, target)\n}\n","/**\n * @Checkpoint() — enables resumable agent execution from the last successful step.\n *\n * Long-running agents (research, code review, multi-step workflows) can fail\n * partway through. Without checkpointing, users restart from step 1 — wasting\n * tokens, time, and cost.\n *\n * Inspired by tRPC's tracked() + lastEventId pattern and Dapr's actor state\n * checkpointing. The agent persists a recovery point after each successful\n * tool call or iteration, and can resume from that point on retry.\n *\n * @example\n * ```ts\n * @Agent({ name: 'research', route: '/research' })\n * @Checkpoint({\n *   storage: 'filesystem', // only 'filesystem' resumes across requests in the M2 harness (M4)\n *   strategy: 'after-tool-call',\n *   maxCheckpoints: 20,\n *   ttl: 3_600_000,  // 1h\n * })\n * class ResearchAgent {\n *   @MainLoop({ strategy: 'plan-act-reflect', maxIterations: 15 })\n *   async run() {}\n * }\n *\n * // Resume: a follow-up POST /api/agents/research with the SAME sessionId replays the persisted\n * // history. NOTE (M4): only `storage: 'filesystem'` resumes across requests today — `memory`\n * // (the default below) is per-run; `drizzle`/`redis` are not shipped by the SDK. A non-filesystem\n * // @Checkpoint emits a THEO_AGENT_CHECKPOINT_STORAGE_METADATA_ONLY warning (honest enforcement).\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst CHECKPOINT_CONFIG = Symbol.for('theokit:agents:checkpoint')\n\nexport type CheckpointStrategy =\n  | 'after-tool-call' // checkpoint after every successful tool execution\n  | 'after-iteration' // checkpoint after every loop iteration\n  | 'manual' // only checkpoint when explicitly called via ctx.checkpoint()\n\nexport type CheckpointStorage = 'memory' | 'filesystem' | 'drizzle' | 'redis'\n\nexport interface CheckpointOptions {\n  /** Where to persist checkpoints. */\n  storage?: CheckpointStorage\n  /** When to auto-checkpoint (default: 'after-tool-call'). */\n  strategy?: CheckpointStrategy\n  /** Maximum checkpoints to retain per run (rolling window). */\n  maxCheckpoints?: number\n  /** Time-to-live in ms before checkpoints expire (default: 3_600_000 = 1h). */\n  ttl?: number\n}\n\n/** Serializable checkpoint state. */\nexport interface CheckpointState {\n  id: string\n  runId: string\n  agentName: string\n  step: number\n  messages: unknown[]\n  toolResults: unknown[]\n  createdAt: number\n  resumeToken: string\n}\n\nexport function Checkpoint(options: CheckpointOptions = {}): ClassDecorator {\n  return (target: Function) => {\n    setMeta(CHECKPOINT_CONFIG, target, {\n      storage: 'memory',\n      strategy: 'after-tool-call',\n      maxCheckpoints: 10,\n      ttl: 3_600_000,\n      ...options,\n    })\n  }\n}\n\nexport function getCheckpointConfig(target: Function): CheckpointOptions | undefined {\n  return getMeta<CheckpointOptions>(CHECKPOINT_CONFIG, target)\n}\n","/**\n * @ProjectContext() — declares how the agent understands the codebase.\n *\n * A code assistant needs to know: what's the project root, which files\n * are relevant, how to parse code structure, what to ignore. This\n * metadata feeds the context window management and file discovery.\n *\n * @example\n * ```ts\n * @Agent({ name: 'coder', route: '/agents/coder' })\n * @ProjectContext({\n *   rootMarkers: ['package.json', 'tsconfig.json'],\n *   indexStrategy: 'tree-sitter',\n *   maxFilesInContext: 20,\n *   relevanceStrategy: 'git-history',\n *   ignorePatterns: ['node_modules', 'dist', '.git'],\n * })\n * class CoderAgent { ... }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst PROJECT_CONTEXT_CONFIG = Symbol.for('theokit:agents:project-context')\n\nexport type IndexStrategy =\n  | 'tree-sitter'    // Parse AST for structural understanding\n  | 'regex'          // Simple regex-based symbol extraction\n  | 'none'           // No indexing — rely on grep/glob only\n\nexport type RelevanceStrategy =\n  | 'git-history'     // Prioritize recently-edited files\n  | 'import-graph'    // Follow import chains from entry points\n  | 'semantic'        // Embedding-based similarity search\n  | 'manual'          // Only files explicitly provided\n\nexport interface ProjectContextOptions {\n  /** Files that mark the project root (searched upward from cwd). */\n  rootMarkers?: string[]\n  /** How to index the codebase for structural understanding. */\n  indexStrategy?: IndexStrategy\n  /** Maximum files to include in context per request. */\n  maxFilesInContext?: number\n  /** How to rank file relevance when selecting context. */\n  relevanceStrategy?: RelevanceStrategy\n  /** Glob patterns to exclude from indexing and context. */\n  ignorePatterns?: string[]\n  /** File extensions to include in indexing (default: all text files). */\n  includeExtensions?: string[]\n}\n\nexport function ProjectContext(options: ProjectContextOptions = {}): ClassDecorator {\n  return (target: Function) => {\n    setMeta(PROJECT_CONTEXT_CONFIG, target, {\n      rootMarkers: ['package.json', 'tsconfig.json', 'go.mod', 'Cargo.toml', 'pyproject.toml'],\n      indexStrategy: 'regex',\n      maxFilesInContext: 20,\n      relevanceStrategy: 'git-history',\n      ignorePatterns: ['node_modules', 'dist', 'build', '.git', 'coverage', '__pycache__'],\n      ...options,\n    })\n  }\n}\n\nexport function getProjectContextConfig(target: Function): ProjectContextOptions | undefined {\n  return getMeta<ProjectContextOptions>(PROJECT_CONTEXT_CONFIG, target)\n}\n","/**\n * @Mixin() — compose reusable capability classes into an agent.\n *\n * Mixins are classes with @Tool methods that can be shared across agents.\n * @Mixin copies tool metadata from mixin classes to the decorated agent,\n * making those tools available without inheritance.\n *\n * @example\n * ```ts\n * // Define reusable capabilities\n * class WithSearchCapability {\n *   @Tool({ name: 'web_search', description: 'Search', input: z.object({...}) })\n *   async webSearch(input) { ... }\n * }\n *\n * class WithFileSystem {\n *   @Tool({ name: 'read_file', description: 'Read', input: z.object({...}) })\n *   async readFile(input) { ... }\n * }\n *\n * // Compose into agent\n * @Agent({ name: 'research', route: '/research' })\n * @Mixin(WithSearchCapability, WithFileSystem)\n * class ResearchAgent {\n *   @MainLoop()\n *   async run() {}\n * }\n * ```\n */\nimport { setMeta, getMeta } from '../metadata/index.js'\n\nconst MIXIN_CLASSES = Symbol.for('theokit:agents:mixins')\n\nexport function Mixin(...mixinClasses: Function[]): ClassDecorator {\n  return (target: Function) => {\n    const existing = getMeta<Function[]>(MIXIN_CLASSES, target) ?? []\n    setMeta(MIXIN_CLASSES, target, [...existing, ...mixinClasses])\n  }\n}\n\nexport function getMixins(target: Function): Function[] {\n  return getMeta<Function[]>(MIXIN_CLASSES, target) ?? []\n}\n"],"mappings":"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","names":["setMeta","getMeta","AGENT_CONFIG","Symbol","for","AGENT_MAIN_LOOP","TOOLBOX_CONFIG","TOOL_CONFIG","TOOL_METHODS","inferAgentMeta","className","stripped","replace","kebab","toLowerCase","name","route","Agent","options","target","inferred","setMeta","AGENT_CONFIG","stream","getAgentConfig","getMeta","createDecorator","RequiresApproval","RequiresCapability","Budget","Policy","createDecorator","Trace","Audit","GATEWAY_CONFIG","Symbol","for","Gateway","options","target","setMeta","typing","sessionStrategy","getGatewayConfig","getMeta","resolveSessionId","strategy","platform","sender","channel","id","topicId","SUB_AGENTS","Symbol","for","SubAgents","agentClasses","target","cls","config","getAgentConfig","Error","name","setMeta","getSubAgents","getMeta","MEMORY_CONFIG","Symbol","for","Memory","options","target","setMeta","provider","embeddings","fts","scope","getMemoryConfig","getMeta","SKILLS_CONFIG","Symbol","for","Skills","namesOrOptions","target","options","Array","isArray","include","autoDiscover","setMeta","getSkillsConfig","getMeta","MCP_CONFIG","Symbol","for","MCP","servers","target","setMeta","getMcpConfig","getMeta","HITL_CONFIG","Symbol","for","HumanInTheLoop","options","target","propertyKey","actualTarget","setMeta","timeout","onTimeout","showInput","getHumanInTheLoopConfig","getMeta","CONTEXT_WINDOW_CONFIG","Symbol","for","ContextWindow","options","target","setMeta","maxTokens","compactionStrategy","preserveSystemPrompt","preserveLastN","preserveToolResults","getContextWindowConfig","getMeta","COMPACTION_CONFIG","Symbol","for","Compaction","name","options","target","setMeta","keepTokens","getCompactionConfig","getMeta","CHECKPOINT_CONFIG","Symbol","for","Checkpoint","options","target","setMeta","storage","strategy","maxCheckpoints","ttl","getCheckpointConfig","getMeta","PROJECT_CONTEXT_CONFIG","Symbol","for","ProjectContext","options","target","setMeta","rootMarkers","indexStrategy","maxFilesInContext","relevanceStrategy","ignorePatterns","getProjectContextConfig","getMeta","MIXIN_CLASSES","Symbol","for","Mixin","mixinClasses","target","existing","getMeta","setMeta","getMixins"]}