@theokit/agents 0.2.0 → 0.4.0

package/dist/bridge.d.ts

@@ -1,5 +1,5 @@
-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 { ExecutionContext } from '@theokit/http';
+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-yyfC5u7t.js';
 import 'zod';
 
 /**
@@ -36,6 +36,15 @@ declare function isAgentContext(ctx: ExecutionContext): ctx is AgentExecutionCon
  * EC-4: throws on duplicate routes across agents.
  */
 
+/**
+ * Stable warning codes for agent pipeline metadata-only decorators.
+ * Test by code, not by message string. Document in agent support matrix.
+ */
+declare const AgentWarningCode: {
+    readonly INTERCEPTOR_METADATA_ONLY: "THEO_AGENT_INTERCEPTOR_METADATA_ONLY";
+    readonly FILTER_METADATA_ONLY: "THEO_AGENT_FILTER_METADATA_ONLY";
+    readonly BUDGET_TOP_LEVEL_METADATA_ONLY: "THEO_AGENT_BUDGET_TOP_LEVEL_METADATA_ONLY";
+};
 interface AgentWalkResult {
     agentConfig: AgentOptions;
     mainLoop: MainLoopMeta;
@@ -202,6 +211,8 @@ interface DoneEvent {
         totalTokens: number;
     };
     durationMs: number;
+    /** Total cost in USD for this agent run (EC-2: added for budget tracking). */
+    cost?: number;
 }
 /** Agent run started. */
 interface RunStartedEvent {
@@ -289,18 +300,91 @@ interface AgentRouteContext {
 declare function generateAgentRoutes(ctx: AgentRouteContext): AgentRoute[];
 
 /**
- * Real LLM Agent Runner v1.1 — all 7 dogfood gaps fixed.
+ * SDK Adapter — bridges @theokit/agents decorators → @theokit/sdk runtime.
+ *
+ * Per rule sdk-runtime.md (INQUEBRÁVEL): @theokit/sdk is the ONLY agent runtime.
+ * This adapter replaces llm-runner.ts (which called OpenRouter API directly).
+ *
+ * Flow: @Agent decorator → compileAgent() → createSdkAgentStream() → SDK Agent.create() → Run.stream()
+ */
+
+/**
+ * Creates an agent stream factory using @theokit/sdk as the runtime.
  *
- * 1. Token-by-token streaming (stream: true + SSE delta parsing + EC-1 buffer safety)
- * 2. Multi-turn conversation (session Map + EC-2 TTL eviction)
- * 3. Model from decorator metadata (EC-5 provider prefix auto-detect)
- * 4. Consistent tool names (dot ↔ underscore bidirectional mapping)
- * 5. Robust Zod→JSON Schema via Zod v4 native z.toJSONSchema()
- * 6. Budget enforcement (per-session cost tracking from EC-3 last-chunk usage)
- * 7. AbortController cancel (EC-4 race-safe signal.aborted check)
+ * Returns a function that, given a message + sessionId, yields TheoKit
+ * AgentStreamEvent via the SDK's Agent.create() + Run.stream() pipeline.
  */
+declare function createSdkAgentStream(agentWalk: AgentWalkResult, compiledTools: CompiledTool[], apiKey: string, envModel?: string): (message: string, _sessionId: string) => AsyncIterable<StreamEvent>;
 
-declare function createRealAgentStream(agentWalk: AgentWalkResult, compiledTools: CompiledTool[], apiKey: string, envModel?: string): (message: string, sessionId: string) => AsyncIterable<StreamEvent>;
+/**
+ * Translates @theokit/sdk SDKMessage events → TheoKit AgentStreamEvent.
+ *
+ * The SDK yields SDKMessage (system/assistant/tool_call/thinking/status).
+ * TheoKit devtools + SSE handler expect AgentStreamEvent (run_started/text_delta/tool_call/done).
+ * This module bridges the two — Adapter pattern (per sdk-integration-blueprint ADR-D2).
+ */
+
+/** Minimal SDK message shape — duck-typed to avoid hard import of @theokit/sdk types. */
+interface SdkMessage {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * Translate a single SDK message to zero or more TheoKit stream events.
+ * Returns an array because one SDK message may map to multiple TheoKit events.
+ */
+declare function translateSdkEvent(msg: SdkMessage, runId: string): StreamEvent[];
+
+/**
+ * Multi-agent orchestration runtime.
+ *
+ * Provides `delegate()` — a function that lets a parent agent invoke a
+ * sub-agent and receive its result. Handles budget clamping (D4),
+ * tool sharing, and toolbox auto-instantiation (EC-1).
+ */
+
+interface DelegateOptions {
+    /** Max USD for this sub-agent call. */
+    budget?: number;
+    /** Parent's remaining budget (for clamping). */
+    parentBudgetRemaining?: number;
+    /** Parent's tools (for sharing — sub-agent inherits these). */
+    parentTools?: CompiledTool[];
+    /** LLM API key (inherited from parent). */
+    apiKey?: string;
+    /** Session ID override (default: crypto.randomUUID for isolation). */
+    sessionId?: string;
+}
+interface DelegationResult {
+    response: string;
+    toolCalls: {
+        name: string;
+        input: unknown;
+        output: string;
+    }[];
+    cost: number;
+    tokens: number;
+}
+declare class BudgetExceededError extends Error {
+    readonly agentName: string;
+    readonly actualCost: number;
+    readonly budgetLimit: number;
+    constructor(agentName: string, actualCost: number, budgetLimit: number);
+}
+declare class DelegationError extends Error {
+    readonly agentName: string;
+    readonly cause: unknown;
+    constructor(agentName: string, cause: unknown);
+}
+/**
+ * Delegate a task to a sub-agent and collect its result.
+ *
+ * - Budget clamping: `min(parentBudgetRemaining, budget)` (D4)
+ * - Tool sharing: parent tools merged with sub-agent tools (sub wins on collision)
+ * - Toolbox auto-instantiation: sub-agent toolboxes instantiated without DI (EC-1)
+ * - Session isolation: each delegation gets a unique session ID (EC-4)
+ */
+declare function delegate(SubAgentClass: Function, message: string, opts?: DelegateOptions): Promise<DelegationResult>;
 
 /**
  * Agent manifest generator — build-time JSON describing all agents, tools, guards, policies.
@@ -374,7 +458,7 @@ interface AgentsPluginOptions {
 interface PluginApp {
     addHook(name: string, fn: (ctx: {
         request: Request;
-    }) => Promise<Response | void>): void;
+    }) => Promise<Response | undefined>): void;
 }
 /**
  * Create a TheoKit plugin that mounts agent routes.
@@ -385,4 +469,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     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, createRealAgentStream, generateAgentManifest, generateAgentRoutes, isAgentContext, isApprovalRequired, isDone, isError, isTextDelta, isToolCall, isToolResult, streamAgentResponse, validateUniqueRoutes, walkAgentMetadata };
+export { type AgentExecutionContext, type AgentManifest, type AgentManifestEntry, type AgentManifestTool, type AgentRoute, type AgentRouteContext, type AgentRunInfo, type AgentStreamEvent, type AgentWalkResult, AgentWarningCode, type AgentsPluginOptions, type ApprovalRequiredEvent, type ArtifactChunkEvent, type ArtifactStartEvent, BudgetExceededError, type CheckpointSavedEvent, type CompiledAgentOptions, type CompiledTool, type DelegateOptions, DelegationError, type DelegationResult, type DoneEvent, type ErrorEvent, type FileEditEvent, type IterationEvent, type RunStartedEvent, type SdkMessage, type StateUpdateEvent, type StreamEvent, type TextDeltaEvent, type ThinkingEvent, type ToolCallEvent, type ToolResultEvent, type ToolWalkResult, type ToolboxWalkResult, agentsPlugin, compileAgent, compileTools, createAgentExecutionContext, createSdkAgentStream, delegate, generateAgentManifest, generateAgentRoutes, isAgentContext, isApprovalRequired, isDone, isError, isTextDelta, isToolCall, isToolResult, streamAgentResponse, translateSdkEvent, validateUniqueRoutes, walkAgentMetadata };

package/dist/bridge.js

@@ -1,9 +1,13 @@
 import {
+  AgentWarningCode,
+  BudgetExceededError,
+  DelegationError,
   agentsPlugin,
   compileAgent,
   compileTools,
   createAgentExecutionContext,
-  createRealAgentStream,
+  createSdkAgentStream,
+  delegate,
   generateAgentManifest,
   generateAgentRoutes,
   isAgentContext,
@@ -14,16 +18,22 @@ import {
   isToolCall,
   isToolResult,
   streamAgentResponse,
+  translateSdkEvent,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-YSQAZWGW.js";
-import "./chunk-3LCIXX3T.js";
+} from "./chunk-NC5EE7HN.js";
+import "./chunk-O4UG4RXE.js";
+import "./chunk-7QVYU63E.js";
 export {
+  AgentWarningCode,
+  BudgetExceededError,
+  DelegationError,
   agentsPlugin,
   compileAgent,
   compileTools,
   createAgentExecutionContext,
-  createRealAgentStream,
+  createSdkAgentStream,
+  delegate,
   generateAgentManifest,
   generateAgentRoutes,
   isAgentContext,
@@ -34,6 +44,7 @@ export {
   isToolCall,
   isToolResult,
   streamAgentResponse,
+  translateSdkEvent,
   validateUniqueRoutes,
   walkAgentMetadata
 };

package/dist/chunk-7QVYU63E.js

@@ -0,0 +1,7 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+export {
+  __name
+};
+//# sourceMappingURL=chunk-7QVYU63E.js.map

package/dist/chunk-7QVYU63E.js.map

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