@theokit/agents 0.28.0 → 0.29.0

package/dist/{bridge-entry-CsUiO2YU.d.ts → bridge-entry-BlS01zM3.d.ts}

@@ -1,9 +1,9 @@
 import { ExecutionContext } from '@theokit/http';
 import { A as AgentOptions, T as ToolOptions, g as MainLoopMeta, a as ApprovalOptions, B as BudgetOptions, f as GatewayOptions, l as MemoryOptions, t as SkillsOptions, e as ContextWindowOptions, q as ProjectContextOptions, j as McpServersMap, b as CompactionDecoratorConfig, R as ReasoningEffort } from './skills-FcUdNDbn.js';
-import { SystemPromptResolver, SkillsSettings, ContextSettings, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition, BudgetTracker, ConversationStorageAdapter, CustomTool, ModelSelection } from '@theokit/sdk';
+import { SystemPromptResolver, SkillsSettings, ContextSettings, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, ConversationStorageAdapter, CustomTool, ModelSelection } from '@theokit/sdk';
 import { UIMessageChunk } from 'ai';
-import { RetryOptions } from '@theokit/sdk/retry';
 import { z } from 'zod';
+import { RetryOptions } from '@theokit/sdk/retry';
 
 /**
  * AgentExecutionContext — extends http-decorators' ExecutionContext with agent-specific methods.
@@ -469,7 +469,7 @@ interface RuntimeOverrides {
     /** Per-run provider routing. */
     providers?: ProviderRoutingSettings;
     /** Per-run sub-agent definitions (opts-only; `compiled.agents` stays deferred — ADR D3). */
-    agents?: Record<string, AgentDefinition>;
+    agents?: Record<string, AgentDefinition$1>;
     /** Per-run SDK budget tracker (inner tool-loop cap; distinct from the loop's USD `budget`). */
     budgetTracker?: BudgetTracker;
     /**
@@ -582,6 +582,91 @@ declare function translateToUIMessageStream(events: AsyncIterable<AgentStreamEve
     textId: string;
 }): AsyncGenerator<UIMessageChunk, void, unknown>;
 
+/**
+ * M2 (theokit-ai-first) — `defineAgent`, the zero-config imperative agent surface.
+ *
+ * ADR-B1: `defineAgent({...})` (default-exported from a top-level `agents/<name>.ts`) is
+ * the canonical zero-config surface; the `@Agent` class decorator stays the advanced/DI
+ * surface. Both compile to {@link CompiledAgentOptions} and run through the same SDK
+ * runtime (`createSdkAgentStream`) — one runtime, two syntaxes.
+ *
+ * This module is PURE metadata (sdk-runtime.md / G2): `defineAgent` describes an agent, it
+ * NEVER calls an LLM. It imports only `zod` (types) + the compiler shape — no `theokit`
+ * core, preserving the agents → (nothing) dependency direction (G1).
+ */
+
+/**
+ * Brand tag for a `defineAgent` value. `Symbol.for` (global registry, not `Symbol()`) so
+ * the brand survives duplicate module instances (dual-package / bundling) — the scanner's
+ * brand-check then works regardless of which copy created the definition.
+ */
+declare const AGENT_BRAND: unique symbol;
+/** Config accepted by {@link defineAgent}. */
+interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
+    /** Zod schema for the request body — lifted into the typed client (M2, {@link InferAgentInput}). */
+    input?: TInput;
+    /** Model id (e.g. `claude-sonnet-4-6`). Falls back to the SDK default when omitted. */
+    model?: string;
+    /** Static system prompt. */
+    system?: string;
+    /** Extended-thinking effort (mirrors `@Agent({ reasoningEffort })`). */
+    reasoningEffort?: ReasoningEffort;
+    /** Pre-built tools (SDK-ready `CompiledTool` shape). */
+    tools?: CompiledTool[];
+}
+/** A branded agent definition — the value {@link defineAgent} returns. */
+type AgentDefinition<TInput extends z.ZodType = z.ZodType> = DefineAgentConfig<TInput> & {
+    readonly [AGENT_BRAND]: true;
+};
+/** Infer the request type of an agent definition from its `input` Zod schema. */
+type InferAgentInput<T> = T extends AgentDefinition<infer S> ? (S extends z.ZodType ? z.infer<S> : never) : never;
+/**
+ * Define a zero-config agent. Identity/normalizer (like `defineRoute`) — returns the config
+ * branded so the scanner recognizes it. Compilation is deferred to {@link compileAgentDefinition}.
+ */
+declare function defineAgent<TInput extends z.ZodType = z.ZodType>(config: DefineAgentConfig<TInput>): AgentDefinition<TInput>;
+/** Brand-check: is `value` a {@link defineAgent} result? */
+declare function isAgentDefinition(value: unknown): value is AgentDefinition;
+/**
+ * Lower a definition to the SDK-ready {@link CompiledAgentOptions} — the same shape
+ * `compileAgent` (decorator path) produces, so both surfaces converge on one runtime.
+ */
+declare function compileAgentDefinition(def: AgentDefinition): CompiledAgentOptions;
+
+/**
+ * M2 (theokit-ai-first) — the file-convention runtime bridge.
+ *
+ * Turns a loaded `agents/<name>.ts` module into the M0/M1 canonical `UIMessageStream`:
+ *
+ *   module (defineAgent value | @Agent class) ──compileAgentModule──▶ CompiledAgentOptions
+ *   CompiledAgentOptions ──createSdkAgentStream──▶ AgentStreamEvent* ──translate──▶ UIMessageChunk*
+ *
+ * Both agent surfaces converge here (ADR-B1): a `defineAgent` value lowers via
+ * `compileAgentDefinition`, an `@Agent`-decorated class lowers via `compileAgent`
+ * (which requires the full `@MainLoop` decoration — its existing errors surface for
+ * DI-heavy classes). Neither runs an LLM directly — `@theokit/sdk` stays the sole
+ * runtime (G2 / sdk-runtime.md); this module only wires its output onto the wire.
+ */
+
+/** Thrown when an `agents/` file default-exports neither a `defineAgent` value nor an `@Agent` class. */
+declare class AgentDefinitionError extends Error {
+    constructor(source: string);
+}
+/**
+ * Compile a loaded `agents/` module to SDK-ready options. Accepts a `defineAgent` value
+ * (zero-config surface) OR an `@Agent`-decorated class (advanced surface). `source` labels
+ * the fail-fast error (typically the file path).
+ */
+declare function compileAgentModule(mod: unknown, source?: string): CompiledAgentOptions;
+/**
+ * Run a compiled agent and yield the M0/M1 `UIMessageStream` chunks. `apiKey` is resolved
+ * by the caller (`resolveProvider`). One `textId` per run (G8: `crypto.randomUUID`).
+ */
+declare function streamAgentUIMessages(compiled: CompiledAgentOptions, apiKey: string, input: {
+    message: string;
+    sessionId: string;
+}): AsyncGenerator<UIMessageChunk>;
+
 /**
  * LoopStrategy — the per-round terminal-decision contract that gives runtime to
  * `@MainLoop({ strategy })`.
@@ -801,7 +886,7 @@ interface DelegateOptions {
     /** Per-run provider routing (e.g. OpenRouter). */
     providers?: ProviderRoutingSettings;
     /** Per-run sub-agent definitions. */
-    agents?: Record<string, AgentDefinition>;
+    agents?: Record<string, AgentDefinition$1>;
     /** Per-run SDK budget tracker (inner tool-loop cap). */
     budgetTracker?: BudgetTracker;
     /** Per-run conversation store (cross-round history). */
@@ -912,4 +997,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { compileTools as $, type AgentExecutionContext as A, BudgetExceededError as B, type CompiledAgentOptions as C, type DelegationResult as D, type ErrorEvent as E, type FileEditEvent as F, type RunStartedEvent as G, type SdkMessage as H, type IterationEvent as I, type Segment as J, type StateUpdateEvent as K, type LoopStrategy as L, type ThinkingEvent as M, type ToolCallEvent as N, type ToolResultEvent as O, type PartialToolCallEvent as P, type ToolWalkResult as Q, type ReflectionStrategy as R, type StreamEvent as S, type TextDeltaEvent as T, type ToolboxWalkResult as U, agentsPlugin as V, buildModelSelection as W, compileAgent as X, compileContextWindow as Y, compileProjectContext as Z, compileSkills as _, type CompiledTool as a, createAgentExecutionContext as a0, createSdkAgentStream as a1, createThinkTagExtractor as a2, delegate as a3, extractThinkTagStream as a4, generateAgentManifest as a5, generateAgentRoutes as a6, isAgentContext as a7, isApprovalRequired as a8, isDone as a9, isError as aa, isPartialToolCall as ab, isTextDelta as ac, isToolCall as ad, isToolResult as ae, ladderReflectionStrategy as af, loopStrategyConfigSchema as ag, noopReflectionStrategy as ah, projectContextMetadataOnlyKnobs as ai, reflectionStrategyConfigSchema as aj, resolveLoopStrategy as ak, streamAgentResponse as al, translateSdkEvent as am, translateToUIMessageStream as an, validateUniqueRoutes as ao, walkAgentMetadata as ap, type AgentManifest as b, type AgentManifestEntry as c, type AgentManifestTool as d, type AgentRoute as e, type AgentRouteContext as f, type AgentRunInfo as g, type AgentStreamEvent as h, type AgentWalkResult as i, AgentWarningCode as j, type AgentsPluginOptions as k, type ApprovalRequiredEvent as l, type ArtifactChunkEvent as m, type ArtifactStartEvent as n, type CheckpointSavedEvent as o, type CompiledContextWindow as p, DEFAULT_MAX_ITERATIONS as q, type DelegateOptions as r, DelegationError as s, type DoneEvent as t, type LoopFinishReason as u, type LoopOutcome as v, type LoopStrategyConfig as w, type ReflectionContext as x, type ReflectionResult as y, type ReflectionStrategyConfig as z };
+export { buildModelSelection as $, AGENT_BRAND as A, BudgetExceededError as B, type CompiledAgentOptions as C, type DelegationResult as D, type ErrorEvent as E, type FileEditEvent as F, type LoopOutcome as G, type LoopStrategyConfig as H, type InferAgentInput as I, type ReflectionContext as J, type ReflectionResult as K, type LoopStrategy as L, type ReflectionStrategyConfig as M, type RunStartedEvent as N, type SdkMessage as O, type PartialToolCallEvent as P, type Segment as Q, type ReflectionStrategy as R, type StreamEvent as S, type StateUpdateEvent as T, type TextDeltaEvent as U, type ThinkingEvent as V, type ToolCallEvent as W, type ToolResultEvent as X, type ToolWalkResult as Y, type ToolboxWalkResult as Z, agentsPlugin as _, type CompiledTool as a, compileAgent as a0, compileAgentDefinition as a1, compileAgentModule as a2, compileContextWindow as a3, compileProjectContext as a4, compileSkills as a5, compileTools as a6, createAgentExecutionContext as a7, createSdkAgentStream as a8, createThinkTagExtractor as a9, defineAgent as aa, delegate as ab, extractThinkTagStream as ac, generateAgentManifest as ad, generateAgentRoutes as ae, isAgentContext as af, isAgentDefinition as ag, isApprovalRequired as ah, isDone as ai, isError as aj, isPartialToolCall as ak, isTextDelta as al, isToolCall as am, isToolResult as an, ladderReflectionStrategy as ao, loopStrategyConfigSchema as ap, noopReflectionStrategy as aq, projectContextMetadataOnlyKnobs as ar, reflectionStrategyConfigSchema as as, resolveLoopStrategy as at, streamAgentResponse as au, streamAgentUIMessages as av, translateSdkEvent as aw, translateToUIMessageStream as ax, validateUniqueRoutes as ay, walkAgentMetadata as az, type AgentDefinition as b, AgentDefinitionError as c, type AgentExecutionContext as d, type AgentManifest as e, type AgentManifestEntry as f, type AgentManifestTool as g, type AgentRoute as h, type AgentRouteContext as i, type AgentRunInfo as j, type AgentStreamEvent as k, type AgentWalkResult as l, AgentWarningCode as m, type AgentsPluginOptions as n, type ApprovalRequiredEvent as o, type ArtifactChunkEvent as p, type ArtifactStartEvent as q, type CheckpointSavedEvent as r, type CompiledContextWindow as s, DEFAULT_MAX_ITERATIONS as t, type DefineAgentConfig as u, type DelegateOptions as v, DelegationError as w, type DoneEvent as x, type IterationEvent as y, type LoopFinishReason as z };

package/dist/bridge.d.ts

@@ -1,4 +1,4 @@
-export { A as AgentExecutionContext, b as AgentManifest, c as AgentManifestEntry, d as AgentManifestTool, e as AgentRoute, f as AgentRouteContext, g as AgentRunInfo, h as AgentStreamEvent, i as AgentWalkResult, j as AgentWarningCode, k as AgentsPluginOptions, l as ApprovalRequiredEvent, m as ArtifactChunkEvent, n as ArtifactStartEvent, B as BudgetExceededError, o as CheckpointSavedEvent, C as CompiledAgentOptions, p as CompiledContextWindow, a as CompiledTool, r as DelegateOptions, s as DelegationError, D as DelegationResult, t as DoneEvent, E as ErrorEvent, F as FileEditEvent, I as IterationEvent, P as PartialToolCallEvent, G as RunStartedEvent, H as SdkMessage, J as Segment, K as StateUpdateEvent, S as StreamEvent, T as TextDeltaEvent, M as ThinkingEvent, N as ToolCallEvent, O as ToolResultEvent, Q as ToolWalkResult, U as ToolboxWalkResult, V as agentsPlugin, W as buildModelSelection, X as compileAgent, Y as compileContextWindow, Z as compileProjectContext, _ as compileSkills, $ as compileTools, a0 as createAgentExecutionContext, a1 as createSdkAgentStream, a2 as createThinkTagExtractor, a3 as delegate, a4 as extractThinkTagStream, a5 as generateAgentManifest, a6 as generateAgentRoutes, a7 as isAgentContext, a8 as isApprovalRequired, a9 as isDone, aa as isError, ab as isPartialToolCall, ac as isTextDelta, ad as isToolCall, ae as isToolResult, ai as projectContextMetadataOnlyKnobs, al as streamAgentResponse, am as translateSdkEvent, an as translateToUIMessageStream, ao as validateUniqueRoutes, ap as walkAgentMetadata } from './bridge-entry-CsUiO2YU.js';
+export { A as AGENT_BRAND, b as AgentDefinition, c as AgentDefinitionError, d as AgentExecutionContext, e as AgentManifest, f as AgentManifestEntry, g as AgentManifestTool, h as AgentRoute, i as AgentRouteContext, j as AgentRunInfo, k as AgentStreamEvent, l as AgentWalkResult, m as AgentWarningCode, n as AgentsPluginOptions, o as ApprovalRequiredEvent, p as ArtifactChunkEvent, q as ArtifactStartEvent, B as BudgetExceededError, r as CheckpointSavedEvent, C as CompiledAgentOptions, s as CompiledContextWindow, a as CompiledTool, u as DefineAgentConfig, v as DelegateOptions, w as DelegationError, D as DelegationResult, x as DoneEvent, E as ErrorEvent, F as FileEditEvent, I as InferAgentInput, y as IterationEvent, P as PartialToolCallEvent, N as RunStartedEvent, O as SdkMessage, Q as Segment, T as StateUpdateEvent, S as StreamEvent, U as TextDeltaEvent, V as ThinkingEvent, W as ToolCallEvent, X as ToolResultEvent, Y as ToolWalkResult, Z as ToolboxWalkResult, _ as agentsPlugin, $ as buildModelSelection, a0 as compileAgent, a1 as compileAgentDefinition, a2 as compileAgentModule, a3 as compileContextWindow, a4 as compileProjectContext, a5 as compileSkills, a6 as compileTools, a7 as createAgentExecutionContext, a8 as createSdkAgentStream, a9 as createThinkTagExtractor, aa as defineAgent, ab as delegate, ac as extractThinkTagStream, ad as generateAgentManifest, ae as generateAgentRoutes, af as isAgentContext, ag as isAgentDefinition, ah as isApprovalRequired, ai as isDone, aj as isError, ak as isPartialToolCall, al as isTextDelta, am as isToolCall, an as isToolResult, ar as projectContextMetadataOnlyKnobs, au as streamAgentResponse, av as streamAgentUIMessages, aw as translateSdkEvent, ax as translateToUIMessageStream, ay as validateUniqueRoutes, az as walkAgentMetadata } from './bridge-entry-BlS01zM3.js';
 import '@theokit/http';
 import './skills-FcUdNDbn.js';
 import '@theokit/sdk';

package/dist/bridge.js

@@ -1,10 +1,14 @@
 import {
+  AGENT_BRAND,
+  AgentDefinitionError,
   AgentWarningCode,
   BudgetExceededError,
   DelegationError,
   agentsPlugin,
   buildModelSelection,
   compileAgent,
+  compileAgentDefinition,
+  compileAgentModule,
   compileContextWindow,
   compileProjectContext,
   compileSkills,
@@ -12,11 +16,13 @@ import {
   createAgentExecutionContext,
   createSdkAgentStream,
   createThinkTagExtractor,
+  defineAgent,
   delegate,
   extractThinkTagStream,
   generateAgentManifest,
   generateAgentRoutes,
   isAgentContext,
+  isAgentDefinition,
   isApprovalRequired,
   isDone,
   isError,
@@ -26,20 +32,25 @@ import {
   isToolResult,
   projectContextMetadataOnlyKnobs,
   streamAgentResponse,
+  streamAgentUIMessages,
   translateSdkEvent,
   translateToUIMessageStream,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-DA7HHFL5.js";
+} from "./chunk-4AN6LDJS.js";
 import "./chunk-GVPUUKKE.js";
 import "./chunk-7QVYU63E.js";
 export {
+  AGENT_BRAND,
+  AgentDefinitionError,
   AgentWarningCode,
   BudgetExceededError,
   DelegationError,
   agentsPlugin,
   buildModelSelection,
   compileAgent,
+  compileAgentDefinition,
+  compileAgentModule,
   compileContextWindow,
   compileProjectContext,
   compileSkills,
@@ -47,11 +58,13 @@ export {
   createAgentExecutionContext,
   createSdkAgentStream,
   createThinkTagExtractor,
+  defineAgent,
   delegate,
   extractThinkTagStream,
   generateAgentManifest,
   generateAgentRoutes,
   isAgentContext,
+  isAgentDefinition,
   isApprovalRequired,
   isDone,
   isError,
@@ -61,6 +74,7 @@ export {
   isToolResult,
   projectContextMetadataOnlyKnobs,
   streamAgentResponse,
+  streamAgentUIMessages,
   translateSdkEvent,
   translateToUIMessageStream,
   validateUniqueRoutes,

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

@@ -1291,6 +1291,71 @@ async function* translateToUIMessageStream(events, opts) {
 }
 __name(translateToUIMessageStream, "translateToUIMessageStream");
 
+// src/bridge/define-agent.ts
+var AGENT_BRAND = /* @__PURE__ */ Symbol.for("theokit.agent.definition");
+function defineAgent(config) {
+  return {
+    ...config,
+    [AGENT_BRAND]: true
+  };
+}
+__name(defineAgent, "defineAgent");
+function isAgentDefinition(value) {
+  return typeof value === "object" && value !== null && value[AGENT_BRAND] === true;
+}
+__name(isAgentDefinition, "isAgentDefinition");
+function compileAgentDefinition(def) {
+  return {
+    model: def.model,
+    reasoningEffort: def.reasoningEffort,
+    systemPrompt: def.system,
+    tools: def.tools ?? [],
+    agents: {},
+    stream: true
+  };
+}
+__name(compileAgentDefinition, "compileAgentDefinition");
+
+// src/bridge/agent-endpoint.ts
+var AgentDefinitionError = class extends Error {
+  static {
+    __name(this, "AgentDefinitionError");
+  }
+  constructor(source) {
+    super(`[@theokit/agents] ${source}: an agents/ file must default-export a defineAgent(...) value or an @Agent-decorated class.`);
+    this.name = "AgentDefinitionError";
+  }
+};
+function extractDefaultExport(mod) {
+  if (typeof mod === "object" && mod !== null && "default" in mod) {
+    return mod.default;
+  }
+  return mod;
+}
+__name(extractDefaultExport, "extractDefaultExport");
+function compileAgentModule(mod, source = "agent module") {
+  const def = extractDefaultExport(mod);
+  if (isAgentDefinition(def)) {
+    return compileAgentDefinition(def);
+  }
+  if (typeof def === "function" && getAgentConfig(def) !== void 0) {
+    return compileAgent(walkAgentMetadata(def));
+  }
+  throw new AgentDefinitionError(source);
+}
+__name(compileAgentModule, "compileAgentModule");
+async function* asAgentStream(events) {
+  for await (const e of events) yield e;
+}
+__name(asAgentStream, "asAgentStream");
+function streamAgentUIMessages(compiled, apiKey, input) {
+  const events = createSdkAgentStream(compiled, compiled.tools, apiKey)(input.message, input.sessionId);
+  return translateToUIMessageStream(asAgentStream(events), {
+    textId: crypto.randomUUID()
+  });
+}
+__name(streamAgentUIMessages, "streamAgentUIMessages");
+
 // src/loop/compaction-strategy.ts
 import { compactTranscript } from "@theokit/sdk/compaction";
 import { z } from "zod";
@@ -2011,6 +2076,13 @@ export {
   extractThinkTagStream,
   createSdkAgentStream,
   translateToUIMessageStream,
+  AGENT_BRAND,
+  defineAgent,
+  isAgentDefinition,
+  compileAgentDefinition,
+  AgentDefinitionError,
+  compileAgentModule,
+  streamAgentUIMessages,
   DEFAULT_KEEP_TOKENS,
   compactionStrategyConfigSchema,
   resolveCompactionStrategy,
@@ -2029,4 +2101,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-DA7HHFL5.js.map
+//# sourceMappingURL=chunk-4AN6LDJS.js.map