@theokit/agents 0.1.0-alpha.0

package/dist/bridge.d.ts

@@ -0,0 +1,374 @@
+import { ExecutionContext } from '@theokit/http-decorators';
+import { A as AgentOptions, T as ToolOptions, c as MainLoopMeta, a as ApprovalOptions, B as BudgetOptions, b as GatewayOptions, h as MemoryOptions, m as SkillsOptions, f as McpServersMap } from './mcp-DmtwLSF-.js';
+import 'zod';
+
+/**
+ * AgentExecutionContext — extends http-decorators' ExecutionContext with agent-specific methods.
+ *
+ * Per ADR D2 (LSP): any guard that accepts ExecutionContext works unchanged with
+ * AgentExecutionContext. Agent-specific guards can narrow via isAgentContext().
+ */
+
+interface AgentRunInfo {
+    id: string;
+    startedAt: Date;
+}
+interface AgentExecutionContext extends ExecutionContext {
+    /** The agent's configuration from @Agent() decorator. */
+    getAgent(): AgentOptions;
+    /** The current run information. */
+    getRun(): AgentRunInfo;
+    /** The tool being called, or null if in the main agent handler. */
+    getToolCall(): ToolOptions | null;
+    /** Type guard — always true for AgentExecutionContext. */
+    isAgentContext(): true;
+}
+/** Create an AgentExecutionContext from a base ExecutionContext + agent state. */
+declare function createAgentExecutionContext(base: ExecutionContext, agent: AgentOptions, run: AgentRunInfo, toolCall?: ToolOptions): AgentExecutionContext;
+/** Narrow an ExecutionContext to AgentExecutionContext if it is one. */
+declare function isAgentContext(ctx: ExecutionContext): ctx is AgentExecutionContext;
+
+/**
+ * Walk decorator metadata on agent + toolbox classes.
+ * Mirrors http-decorators' walkControllerMetadata() pattern.
+ *
+ * EC-1: throws if @Agent class is missing @MainLoop.
+ * EC-4: throws on duplicate routes across agents.
+ */
+
+interface AgentWalkResult {
+    agentConfig: AgentOptions;
+    mainLoop: MainLoopMeta;
+    toolboxes: ToolboxWalkResult[];
+    guards: Function[];
+    interceptors: Function[];
+    filters: Function[];
+    route: string;
+    gateway?: GatewayOptions;
+    subAgentClasses: Function[];
+    memory?: MemoryOptions;
+    skills?: SkillsOptions;
+    mcpServers?: McpServersMap;
+}
+interface ToolboxWalkResult {
+    class: Function;
+    namespace: string;
+    tools: ToolWalkResult[];
+    guards: Function[];
+}
+interface ToolWalkResult {
+    propertyKey: string | symbol;
+    config: ToolOptions;
+    guards: Function[];
+    approval?: ApprovalOptions;
+    capabilities?: string[];
+    budget?: BudgetOptions;
+    trace: boolean;
+    audit: boolean;
+}
+/**
+ * Walk all metadata on an agent class and its toolboxes.
+ * Memoized per AgentClass via WeakMap.
+ *
+ * @throws Error if @Agent is missing @MainLoop (EC-1)
+ */
+declare function walkAgentMetadata(AgentClass: Function, toolboxClasses?: Function[]): AgentWalkResult;
+/**
+ * Validate that no two agents share the same route prefix.
+ *
+ * @throws Error on duplicate routes (EC-4)
+ */
+declare function validateUniqueRoutes(results: AgentWalkResult[]): void;
+
+/** Minimal interface matching defineTool() result shape. */
+interface CompiledTool {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+    handler: (input: unknown) => string | Promise<string>;
+}
+/**
+ * Compile @Tool metadata into tool definitions.
+ *
+ * @param toolboxes - Walked toolbox metadata
+ * @param toolboxInstances - Map of Toolbox class → instantiated object (for `this` binding)
+ */
+declare function compileTools(toolboxes: ToolboxWalkResult[], toolboxInstances: Map<Function, object>): CompiledTool[];
+/** Compiled sub-agent definition matching SDK AgentDefinition shape. */
+interface CompiledSubAgent {
+    model?: string;
+    systemPrompt?: string;
+}
+/** Compiled agent options ready for SDK Agent.create(). */
+interface CompiledAgentOptions {
+    model?: string;
+    systemPrompt?: string;
+    tools: CompiledTool[];
+    agents: Record<string, CompiledSubAgent>;
+    memory?: MemoryOptions;
+    skills?: SkillsOptions;
+    mcpServers?: McpServersMap;
+    maxIterations?: number;
+    timeoutMs?: number;
+    stream: boolean;
+}
+/**
+ * Compile @Agent metadata into SDK-compatible options.
+ *
+ * EC-7: agents without toolboxes produce tools: [].
+ */
+declare function compileAgent(walkResult: AgentWalkResult, toolboxInstances?: Map<Function, object>): CompiledAgentOptions;
+
+/**
+ * SSE streaming handler — Web Standard Response with ReadableStream.
+ *
+ * Per ADR D4: SSE is the v1 transport.
+ * Per EC-2: uses ReadableStream with controller.enqueue() instead of res.write().
+ * Works natively on Node, Bun, Deno, CF Workers.
+ */
+/** Minimal event shape matching SDK's SDKMessage discriminated union. */
+interface StreamEvent {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * Create a Web Standard Response that streams SSE events.
+ * Each event becomes: `event: {type}\ndata: {json}\n\n`
+ */
+declare function streamAgentResponse(eventStream: AsyncIterable<StreamEvent>): Response;
+
+/**
+ * Typed discriminated union for agent SSE stream events.
+ *
+ * Every event has a `type` field for discrimination.
+ * Clients narrow via `if (event.type === 'text_delta') event.content`.
+ */
+/** Partial text content from the LLM. */
+interface TextDeltaEvent {
+    type: 'text_delta';
+    content: string;
+}
+/** Agent started a tool call. */
+interface ToolCallEvent {
+    type: 'tool_call';
+    callId: string;
+    toolName: string;
+    input: unknown;
+}
+/** Tool execution completed. */
+interface ToolResultEvent {
+    type: 'tool_result';
+    callId: string;
+    toolName: string;
+    output: string;
+    durationMs: number;
+    isError: boolean;
+}
+/** Extended thinking / reasoning (when model supports it). */
+interface ThinkingEvent {
+    type: 'thinking';
+    content: string;
+}
+/** Agent loop iteration. */
+interface IterationEvent {
+    type: 'iteration';
+    step: number;
+    totalSteps: number | null;
+}
+/** Human approval required before proceeding. */
+interface ApprovalRequiredEvent {
+    type: 'approval_required';
+    callId: string;
+    toolName: string;
+    question: string;
+    input?: unknown;
+    callbackUrl: string;
+    timeoutMs: number;
+}
+/** Agent encountered an error. */
+interface ErrorEvent {
+    type: 'error';
+    code: string;
+    message: string;
+    retryable: boolean;
+}
+/** Agent completed with a final result. */
+interface DoneEvent {
+    type: 'done';
+    result: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    durationMs: number;
+}
+/** Agent run started. */
+interface RunStartedEvent {
+    type: 'run_started';
+    runId: string;
+    agentName: string;
+    model?: string;
+}
+/** Artifact generation started (code, document, diagram). */
+interface ArtifactStartEvent {
+    type: 'artifact_start';
+    artifactId: string;
+    mimeType: string;
+    filename?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Artifact content chunk (streamable artifacts). */
+interface ArtifactChunkEvent {
+    type: 'artifact_chunk';
+    artifactId: string;
+    chunk: string;
+    isLast: boolean;
+}
+/** Real-time state update from @Observable channels. */
+interface StateUpdateEvent {
+    type: 'state_update';
+    channel: string;
+    data: unknown;
+}
+/** Checkpoint saved (resumable agents). */
+interface CheckpointSavedEvent {
+    type: 'checkpoint_saved';
+    checkpointId: string;
+    step: number;
+    resumeToken: string;
+}
+/** File edit produced by a code assistant tool. */
+interface FileEditEvent {
+    type: 'file_edit';
+    file: string;
+    format: 'search-replace' | 'unified-diff' | 'full-file' | 'line-range';
+    search?: string;
+    replace?: string;
+    content?: string;
+    diff?: string;
+    startLine?: number;
+    endLine?: number;
+}
+/** Discriminated union of all agent stream events. */
+type AgentStreamEvent = RunStartedEvent | TextDeltaEvent | ToolCallEvent | ToolResultEvent | ThinkingEvent | IterationEvent | ApprovalRequiredEvent | ArtifactStartEvent | ArtifactChunkEvent | StateUpdateEvent | CheckpointSavedEvent | FileEditEvent | ErrorEvent | DoneEvent;
+/** Type guard helpers. */
+declare function isTextDelta(e: AgentStreamEvent): e is TextDeltaEvent;
+declare function isToolCall(e: AgentStreamEvent): e is ToolCallEvent;
+declare function isToolResult(e: AgentStreamEvent): e is ToolResultEvent;
+declare function isDone(e: AgentStreamEvent): e is DoneEvent;
+declare function isError(e: AgentStreamEvent): e is ErrorEvent;
+declare function isApprovalRequired(e: AgentStreamEvent): e is ApprovalRequiredEvent;
+
+/**
+ * Auto-generate HTTP routes from @Agent metadata — Web Standard.
+ *
+ * Per ADR D5: @Agent({ route }) auto-generates two endpoints:
+ * - POST {route}/chat  — send message, receive SSE stream
+ * - GET  {route}/runs/:runId — get run status/result
+ *
+ * Routes are convention-based, generated at registration time.
+ */
+
+interface AgentRoute {
+    method: 'POST' | 'GET';
+    path: string;
+    handler: (request: Request) => Promise<Response>;
+}
+interface AgentRouteContext {
+    walkResult: AgentWalkResult;
+    compiledOptions: CompiledAgentOptions;
+    createRun: (message: string, sessionId: string) => AsyncIterable<StreamEvent>;
+    getRun?: (runId: string) => Promise<{
+        id: string;
+        status: string;
+        result?: string;
+    } | null>;
+}
+/** Generate HTTP routes for a single agent. Returns Web Standard handlers. */
+declare function generateAgentRoutes(ctx: AgentRouteContext): AgentRoute[];
+
+/**
+ * Agent manifest generator — build-time JSON describing all agents, tools, guards, policies.
+ *
+ * Feeds: theokit agents list/inspect, TheoCloud deploy, UI agent consoles.
+ */
+
+interface AgentManifest {
+    version: '1.0';
+    generatedAt: string;
+    agents: AgentManifestEntry[];
+}
+interface AgentManifestEntry {
+    name: string;
+    route: string;
+    model?: string;
+    stream: boolean;
+    mainLoop: {
+        method: string;
+        strategy: string;
+    };
+    guards: string[];
+    interceptors: string[];
+    tools: AgentManifestTool[];
+    gateway?: {
+        platforms: string[];
+        sessionStrategy: string;
+    };
+    subAgents: string[];
+    memory?: {
+        provider: string;
+        embeddings: boolean;
+        fts: boolean;
+        scope: string;
+    };
+    skills?: string[];
+    mcpServers?: string[];
+}
+interface AgentManifestTool {
+    name: string;
+    description: string;
+    risk?: string;
+    approval: boolean;
+    capabilities?: string[];
+    trace: boolean;
+    audit: boolean;
+}
+/**
+ * Generate a serializable agent manifest from walked metadata.
+ * All Function references are converted to string names for JSON safety.
+ */
+declare function generateAgentManifest(walkResults: AgentWalkResult[]): AgentManifest;
+
+/**
+ * agentsPlugin() — TheoKit dev-server plugin for agent routes.
+ *
+ * Mirrors httpDecoratorsPlugin() pattern. Registers agent HTTP endpoints
+ * (POST /chat, GET /runs/:id) via the TheoKit plugin hook system.
+ *
+ * Per ADR D6: structural { name, register } shape (no compile-time theokit dep).
+ */
+
+interface AgentsPluginOptions {
+    /** Agent classes decorated with @Agent(). */
+    agents: Function[];
+    /** Toolbox classes (or use @Mixin on agents). */
+    toolboxes?: Function[];
+    /** Factory that creates agent runs — bridges to SDK Agent.create() + agent.send(). */
+    createRunFactory?: (compiled: CompiledAgentOptions, walkResult: AgentWalkResult) => (message: string, sessionId: string) => AsyncIterable<StreamEvent>;
+}
+interface PluginApp {
+    addHook(name: string, fn: (ctx: {
+        request: Request;
+    }) => Promise<Response | void>): void;
+}
+/**
+ * Create a TheoKit plugin that mounts agent routes.
+ * Web Standard Request/Response — runtime-agnostic.
+ */
+declare function agentsPlugin(opts: AgentsPluginOptions): {
+    name: string;
+    register(app: PluginApp): void;
+};
+
+export { type AgentExecutionContext, type AgentManifest, type AgentManifestEntry, type AgentManifestTool, type AgentRoute, type AgentRouteContext, type AgentRunInfo, type AgentStreamEvent, type AgentWalkResult, type AgentsPluginOptions, type ApprovalRequiredEvent, type ArtifactChunkEvent, type ArtifactStartEvent, type CheckpointSavedEvent, type CompiledAgentOptions, type CompiledTool, type DoneEvent, type ErrorEvent, type FileEditEvent, type IterationEvent, type RunStartedEvent, type StateUpdateEvent, type StreamEvent, type TextDeltaEvent, type ThinkingEvent, type ToolCallEvent, type ToolResultEvent, type ToolWalkResult, type ToolboxWalkResult, agentsPlugin, compileAgent, compileTools, createAgentExecutionContext, generateAgentManifest, generateAgentRoutes, isAgentContext, isApprovalRequired, isDone, isError, isTextDelta, isToolCall, isToolResult, streamAgentResponse, validateUniqueRoutes, walkAgentMetadata };

package/dist/bridge.js

@@ -0,0 +1,38 @@
+import {
+  agentsPlugin,
+  compileAgent,
+  compileTools,
+  createAgentExecutionContext,
+  generateAgentManifest,
+  generateAgentRoutes,
+  isAgentContext,
+  isApprovalRequired,
+  isDone,
+  isError,
+  isTextDelta,
+  isToolCall,
+  isToolResult,
+  streamAgentResponse,
+  validateUniqueRoutes,
+  walkAgentMetadata
+} from "./chunk-YK76AQNU.js";
+import "./chunk-3LCIXX3T.js";
+export {
+  agentsPlugin,
+  compileAgent,
+  compileTools,
+  createAgentExecutionContext,
+  generateAgentManifest,
+  generateAgentRoutes,
+  isAgentContext,
+  isApprovalRequired,
+  isDone,
+  isError,
+  isTextDelta,
+  isToolCall,
+  isToolResult,
+  streamAgentResponse,
+  validateUniqueRoutes,
+  walkAgentMetadata
+};
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-3LCIXX3T.js

@@ -0,0 +1,185 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/metadata/index.ts
+import { setMeta, getMeta } from "@theokit/http-decorators";
+
+// src/metadata/keys.ts
+var AGENT_CONFIG = /* @__PURE__ */ Symbol.for("theokit:agents:config");
+var AGENT_MAIN_LOOP = /* @__PURE__ */ Symbol.for("theokit:agents:main-loop");
+var TOOLBOX_CONFIG = /* @__PURE__ */ Symbol.for("theokit:agents:toolbox");
+var TOOL_CONFIG = /* @__PURE__ */ Symbol.for("theokit:agents:tool");
+var TOOL_METHODS = /* @__PURE__ */ Symbol.for("theokit:agents:tool-methods");
+
+// src/decorators/agent.ts
+function Agent(options) {
+  return (target) => {
+    setMeta(AGENT_CONFIG, target, {
+      stream: true,
+      ...options
+    });
+  };
+}
+__name(Agent, "Agent");
+function getAgentConfig(target) {
+  return getMeta(AGENT_CONFIG, target);
+}
+__name(getAgentConfig, "getAgentConfig");
+
+// src/decorators/policies.ts
+import { createDecorator } from "@theokit/http-decorators";
+var RequiresApproval = createDecorator();
+var RequiresCapability = createDecorator();
+var Budget = createDecorator();
+var Policy = createDecorator();
+
+// src/decorators/observability.ts
+import { createDecorator as createDecorator2 } from "@theokit/http-decorators";
+var Trace = createDecorator2();
+var Audit = createDecorator2();
+
+// src/decorators/gateway.ts
+var GATEWAY_CONFIG = /* @__PURE__ */ Symbol.for("theokit:agents:gateway");
+function Gateway(options) {
+  return (target) => {
+    setMeta(GATEWAY_CONFIG, target, {
+      typing: true,
+      sessionStrategy: "per-user",
+      ...options
+    });
+  };
+}
+__name(Gateway, "Gateway");
+function getGatewayConfig(target) {
+  return getMeta(GATEWAY_CONFIG, target);
+}
+__name(getGatewayConfig, "getGatewayConfig");
+function resolveSessionId(strategy, platform, sender, channel) {
+  switch (strategy) {
+    case "per-user":
+      return `${platform}-dm-${sender.id}`;
+    case "per-channel":
+      return `${platform}-grp-${channel.id}`;
+    case "per-thread":
+      return `${platform}-tpc-${channel.id}-${channel.topicId ?? "main"}`;
+  }
+}
+__name(resolveSessionId, "resolveSessionId");
+
+// src/decorators/sub-agents.ts
+var SUB_AGENTS = /* @__PURE__ */ Symbol.for("theokit:agents:sub-agents");
+function SubAgents(agentClasses) {
+  return (target) => {
+    for (const cls of agentClasses) {
+      const config = getAgentConfig(cls);
+      if (!config) {
+        throw new Error(`[@theokit/agents] @SubAgents on ${target.name}: class ${cls.name} is missing @Agent() decorator.`);
+      }
+    }
+    setMeta(SUB_AGENTS, target, agentClasses);
+  };
+}
+__name(SubAgents, "SubAgents");
+function getSubAgents(target) {
+  return getMeta(SUB_AGENTS, target) ?? [];
+}
+__name(getSubAgents, "getSubAgents");
+
+// src/decorators/memory.ts
+var MEMORY_CONFIG = /* @__PURE__ */ Symbol.for("theokit:agents:memory");
+function Memory(options = {}) {
+  return (target) => {
+    setMeta(MEMORY_CONFIG, target, {
+      provider: "built-in",
+      embeddings: false,
+      fts: false,
+      scope: "per-user",
+      ...options
+    });
+  };
+}
+__name(Memory, "Memory");
+function getMemoryConfig(target) {
+  return getMeta(MEMORY_CONFIG, target);
+}
+__name(getMemoryConfig, "getMemoryConfig");
+
+// src/decorators/skills.ts
+var SKILLS_CONFIG = /* @__PURE__ */ Symbol.for("theokit:agents:skills");
+function Skills(namesOrOptions) {
+  return (target) => {
+    const options = Array.isArray(namesOrOptions) ? {
+      include: namesOrOptions,
+      autoDiscover: false
+    } : namesOrOptions;
+    setMeta(SKILLS_CONFIG, target, options);
+  };
+}
+__name(Skills, "Skills");
+function getSkillsConfig(target) {
+  return getMeta(SKILLS_CONFIG, target);
+}
+__name(getSkillsConfig, "getSkillsConfig");
+
+// src/decorators/mcp.ts
+var MCP_CONFIG = /* @__PURE__ */ Symbol.for("theokit:agents:mcp");
+function MCP(servers) {
+  return (target) => {
+    setMeta(MCP_CONFIG, target, servers);
+  };
+}
+__name(MCP, "MCP");
+function getMcpConfig(target) {
+  return getMeta(MCP_CONFIG, target);
+}
+__name(getMcpConfig, "getMcpConfig");
+
+// src/decorators/mixin.ts
+var MIXIN_CLASSES = /* @__PURE__ */ Symbol.for("theokit:agents:mixins");
+function Mixin(...mixinClasses) {
+  return (target) => {
+    const existing = getMeta(MIXIN_CLASSES, target) ?? [];
+    setMeta(MIXIN_CLASSES, target, [
+      ...existing,
+      ...mixinClasses
+    ]);
+  };
+}
+__name(Mixin, "Mixin");
+function getMixins(target) {
+  return getMeta(MIXIN_CLASSES, target) ?? [];
+}
+__name(getMixins, "getMixins");
+
+export {
+  __name,
+  AGENT_CONFIG,
+  AGENT_MAIN_LOOP,
+  TOOLBOX_CONFIG,
+  TOOL_CONFIG,
+  TOOL_METHODS,
+  setMeta,
+  getMeta,
+  Agent,
+  getAgentConfig,
+  RequiresApproval,
+  RequiresCapability,
+  Budget,
+  Policy,
+  Trace,
+  Audit,
+  Gateway,
+  getGatewayConfig,
+  resolveSessionId,
+  SubAgents,
+  getSubAgents,
+  Memory,
+  getMemoryConfig,
+  Skills,
+  getSkillsConfig,
+  MCP,
+  getMcpConfig,
+  Mixin,
+  getMixins
+};
+//# sourceMappingURL=chunk-3LCIXX3T.js.map

package/dist/chunk-3LCIXX3T.js.map

@@ -0,0 +1 @@
+{"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/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-decorators'\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 * Stores AgentOptions metadata. The compiler reads this to call\n * Agent.create() from @theokit/sdk at registration time.\n *\n * @example\n * ```ts\n * @Agent({ name: 'support-agent', route: '/api/agents/support', model: 'claude-sonnet-4-5-20250929' })\n * @UseGuards(AuthGuard)\n * class SupportAgent {\n *   @MainLoop()\n *   async run(ctx: AgentContext) { ... }\n * }\n * ```\n */\nimport { setMeta, getMeta, AGENT_CONFIG } from '../metadata/index.js'\nimport type { AgentOptions } from '../types.js'\n\nexport function Agent(options: AgentOptions): ClassDecorator {\n  return (target: Function) => {\n    setMeta(AGENT_CONFIG, target, { stream: true, ...options })\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-decorators'\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-decorators'\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 * @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","Agent","options","target","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","MIXIN_CLASSES","Symbol","for","Mixin","mixinClasses","target","existing","getMeta","setMeta","getMixins"]}