@theokit/agents 2.0.0 → 3.0.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { G as Guardrail, L as LoopStrategy, R as ReflectionStrategy, C as CompiledAgentOptions, M as MainLoopMeta, a as CompiledTool, b as ReasoningEffort, c as RoundStreamFactory, S as StreamEvent, D as DelegationResult, d as ContextWindowOptions, H as HumanInTheLoopOptions, e as McpServersMap, f as MemoryOptions, P as ProjectContextOptions, g as SkillsOptions, h as SkillsSelection, T as ToolOptions, A as ApprovalOptions, i as AgentManifestEntry } from './bridge-entry-F9kHGaIn.js';
-export { j as AGENT_BRAND, k as AfterToolCallContext, l as AgentBuilder, m as AgentDefinition, n as AgentDefinitionError, o as AgentExecutionContext, p as AgentManifest, q as AgentManifestSource, r as AgentManifestTool, s as AgentOptions, t as AgentRoute, u as AgentRouteContext, v as AgentRunInfo, w as AgentStreamEvent, x as AgentTurnMetadata, y as AgentsPluginOptions, z as ApiErrorContext, B as ApiErrorDecision, E as ApiErrorPolicy, F as ApprovalRequiredEvent, I as ArtifactChunkEvent, J as ArtifactStartEvent, K as BackgroundDelegation, N as BeforeToolCallContext, O as BudgetExceededError, Q as BudgetOptions, U as CheckpointSavedEvent, V as CompiledContextWindow, W as ContextualTool, X as CostBudgetExceededError, Y as DEFAULT_MAX_ITERATIONS, Z as DefineAgentConfig, _ as DelegateFn, $ as DelegateOptions, a0 as DelegationError, a1 as DoneEvent, a2 as ErrorEvent, a3 as FileEditEvent, a4 as GuardrailAction, a5 as GuardrailPhase, a6 as GuardrailResult, a7 as GuardrailViolationError, a8 as HitlDecision, a9 as InferAgentInput, aa as InferAgentToolNames, ab as IterationEvent, ac as LLMCallContext, ad as LoopFinishReason, ae as LoopOutcome, af as LoopStrategyConfig, ag as MainLoopOptions, ah as McpApprovalSpec, ai as McpRegistryConfig, aj as McpRequestContext, ak as McpSelection, al as PartialToolCallEvent, am as PolicyHandler, an as ProcessInputContext, ao as ReflectionContext, ap as ReflectionResult, aq as ReflectionStrategyConfig, ar as RunStartedEvent, as as ScoreVerdict, at as ScoredDelegation, au as Scorer, av as SdkAgentHandle, aw as SdkMessage, ax as Segment, ay as SkillsRequestContext, az as StateUpdateEvent, aA as TextDeltaEvent, aB as ThinkingEvent, aC as TimeoutAction, aD as ToolCallEvent, aE as ToolCallVeto, aF as ToolHooks, aG as ToolHooksPlugin, aH as ToolResultEvent, aI as ToolWalkResult, aJ as ToolboxOptions, aK as ToolboxWalkResult, aL as agent, aM as agentsPlugin, aN as buildModelSelection, aO as compileAgentDefinition, aP as compileAgentModule, aQ as compileContextWindow, aR as compileProjectContext, aS as compileSkills, aT as compileTools, aU as contextualTool, aV as createAgentExecutionContext, aW as createApiErrorHandler, aX as createSdkAgentStream, aY as createThinkTagExtractor, aZ as createToolHooksPlugin, a_ as delegate, a$ as delegateBackground, b0 as delegateWithScoring, b1 as extractThinkTagStream, b2 as generateAgentManifest, b3 as generateAgentRoutes, b4 as isAgentContext, b5 as isAgentDefinition, b6 as isApprovalRequired, b7 as isDone, b8 as isError, b9 as isPartialToolCall, ba as isTextDelta, bb as isToolCall, bc as isToolResult, bd as ladderReflectionStrategy, be as loopStrategyConfigSchema, bf as mcpRegistry, bg as mcpToolApprovals, bh as noopReflectionStrategy, bi as presentUIMessageStream, bj as projectContextMetadataOnlyKnobs, bk as reflectionStrategyConfigSchema, bl as resolveEnabledSkills, bm as resolveLoopStrategy, bn as resolveMcpServers, bo as runWithApiErrorHandling, bp as streamAgentResponse, bq as streamAgentUIMessages, br as toAgentFactory, bs as translateSdkEvent } from './bridge-entry-F9kHGaIn.js';
+import { G as Guardrail, L as LoopStrategy, R as ReflectionStrategy, C as CompiledAgentOptions, M as MainLoopMeta, a as CompiledTool, b as ReasoningEffort, c as RoundStreamFactory, S as StreamEvent, D as DelegationResult, d as ContextWindowOptions, H as HumanInTheLoopOptions, e as McpServersMap, f as MemoryOptions, P as ProjectContextOptions, g as SkillsOptions, h as SkillsSelection, T as ToolOptions, A as ApprovalOptions, i as AgentManifestEntry } from './bridge-entry-8gsH0kVZ.js';
+export { j as AGENT_BRAND, k as AfterToolCallContext, l as AgentBuilder, m as AgentDefinition, n as AgentDefinitionError, o as AgentExecutionContext, p as AgentManifest, q as AgentManifestSource, r as AgentManifestTool, s as AgentOptions, t as AgentRoute, u as AgentRouteContext, v as AgentRunInfo, w as AgentStreamEvent, x as AgentTurnMetadata, y as AgentsPluginOptions, z as ApiErrorContext, B as ApiErrorDecision, E as ApiErrorPolicy, F as ApprovalRequiredEvent, I as ArtifactChunkEvent, J as ArtifactStartEvent, K as BackgroundDelegation, N as BeforeToolCallContext, O as BudgetExceededError, Q as BudgetOptions, U as CheckpointSavedEvent, V as CompiledContextWindow, W as ContextualTool, X as CostBudgetExceededError, Y as DEFAULT_MAX_ITERATIONS, Z as DefineAgentConfig, _ as DelegateFn, $ as DelegateOptions, a0 as DelegationError, a1 as DoneEvent, a2 as ErrorEvent, a3 as FileEditEvent, a4 as GuardrailAction, a5 as GuardrailPhase, a6 as GuardrailResult, a7 as GuardrailViolationError, a8 as HitlDecision, a9 as InferAgentInput, aa as InferAgentToolNames, ab as IterationEvent, ac as LLMCallContext, ad as LoopFinishReason, ae as LoopOutcome, af as LoopStrategyConfig, ag as MainLoopOptions, ah as McpApprovalSpec, ai as McpRegistryConfig, aj as McpRequestContext, ak as McpSelection, al as PartialToolCallEvent, am as PolicyHandler, an as ProcessInputContext, ao as ReflectionContext, ap as ReflectionResult, aq as ReflectionStrategyConfig, ar as RunStartedEvent, as as ScoreVerdict, at as ScoredDelegation, au as Scorer, av as SdkAgentHandle, aw as SdkMessage, ax as Segment, ay as SkillsRequestContext, az as StateUpdateEvent, aA as TextDeltaEvent, aB as ThinkingEvent, aC as TimeoutAction, aD as ToolCallEvent, aE as ToolCallVeto, aF as ToolHooks, aG as ToolHooksPlugin, aH as ToolResultEvent, aI as ToolWalkResult, aJ as ToolboxOptions, aK as ToolboxWalkResult, aL as agent, aM as agentsPlugin, aN as buildModelSelection, aO as compileAgentDefinition, aP as compileAgentModule, aQ as compileContextWindow, aR as compileProjectContext, aS as compileSkills, aT as compileTools, aU as contextualTool, aV as createAgentExecutionContext, aW as createApiErrorHandler, aX as createSdkAgentStream, aY as createThinkTagExtractor, aZ as createToolHooksPlugin, a_ as delegate, a$ as delegateBackground, b0 as delegateWithScoring, b1 as extractThinkTagStream, b2 as generateAgentManifest, b3 as generateAgentRoutes, b4 as isAgentContext, b5 as isAgentDefinition, b6 as isApprovalRequired, b7 as isDone, b8 as isError, b9 as isPartialToolCall, ba as isTextDelta, bb as isToolCall, bc as isToolResult, bd as ladderReflectionStrategy, be as loopStrategyConfigSchema, bf as mcpRegistry, bg as mcpToolApprovals, bh as noopReflectionStrategy, bi as presentUIMessageStream, bj as projectContextMetadataOnlyKnobs, bk as reflectionStrategyConfigSchema, bl as resolveEnabledSkills, bm as resolveLoopStrategy, bn as resolveMcpServers, bo as runWithApiErrorHandling, bp as streamAgentResponse, bq as streamAgentUIMessages, br as toAgentFactory, bs as translateSdkEvent } from './bridge-entry-8gsH0kVZ.js';
 import * as _theokit_sdk from '@theokit/sdk';
 import { PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition, BudgetTracker, CustomTool, InlineSkill } from '@theokit/sdk';
 import { RetryOptions } from '@theokit/sdk/retry';
@@ -294,6 +294,13 @@ interface AgentRunnerState {
     readonly agentName: string;
     /** The resolved terminal-decision strategy (parity with `delegate()`). */
     readonly loopStrategy: LoopStrategy;
+    /**
+     * M54 — true when `loopStrategy` came from `.loopStrategy(custom)` rather than a built-in name.
+     * A custom must NOT be re-resolved by name (its name is outside the `z.enum`); a per-run
+     * `maxIterations` override applies to it as a runner ceiling instead (see `stream`). Optional and
+     * defaults to `false`: a state built directly (tests, `delegate()`) is a by-name built-in.
+     */
+    readonly loopStrategyIsCustom?: boolean;
     /** The resolved between-round reflection (default or `.reflection(custom)` override). */
     readonly reflectionStrategy: ReflectionStrategy;
     /** Recorded streaming preference (see {@link AgentRunner.streamEnabled}). */
@@ -306,6 +313,8 @@ declare class AgentRunner {
     private readonly agentName;
     /** The resolved terminal-decision strategy (parity with `delegate()`). */
     readonly loopStrategy: LoopStrategy;
+    /** M54 — whether {@link loopStrategy} is a caller-injected custom (see {@link AgentRunnerState}). */
+    private readonly loopStrategyIsCustom;
     /** The resolved between-round reflection (default or `.reflection(custom)` override). */
     readonly reflectionStrategy: ReflectionStrategy;
     /**
@@ -336,6 +345,14 @@ declare class AgentRunner {
     /** The core stream path, after input guardrails have run (M9). */
     private streamUnguarded;
     /** Run the agent to a terminal result via the shared reflective loop (collect mode). */
+    /**
+     * Apply a per-call `maxIterations` override (M54 D4). A custom strategy must NOT be re-resolved by
+     * name — its name is outside the `z.enum`, which would throw — and its `shouldContinue` closure
+     * must survive; since the runner enforces the ceiling via `round < loop.maxIterations` (T1.1),
+     * overriding just that field bounds a custom without touching its logic. A built-in keeps the
+     * by-name re-resolution (zod fail-loud on `< 1`) — unchanged, zero-behavior.
+     */
+    private resolvePerRunLoop;
     run(message: string, opts: AgentRunnerRunOptions): Promise<DelegationResult>;
 }
 /**
@@ -364,9 +381,29 @@ declare class AgentRunnerBuilder {
     private reflectionOverride?;
     private streamEnabled;
     private compactionOverride?;
+    private loopStrategyOverride?;
     constructor(spec: AgentRunnerSpec);
     /** Override the default reflection strategy (OCP — plan Drawback #2). No arg ⇒ keep default. */
     reflection(strategy?: ReflectionStrategy): this;
+    /**
+     * M54 — inject a custom terminal-decision strategy (the fourth OCP axis, alongside
+     * `.reflection()`/`.compaction()`/`streamFactory`). WINS over the strategy the spec's name would
+     * resolve to, exactly as `.compaction()` outranks the spec. The runner caps ANY strategy at
+     * `custom.maxIterations` (T1.1), so a `shouldContinue: () => true` still terminates — never an
+     * infinite loop.
+     *
+     * @example
+     * ```ts
+     * // Stop as soon as the confidence in the last round crosses 0.9, else run to the ceiling.
+     * const stopWhenConfident: LoopStrategy = {
+     *   name: 'confident',
+     *   maxIterations: 8,
+     *   shouldContinue: (o) => !o.responseText.includes('confidence: high'),
+     * }
+     * AgentRunner.fromSpec(spec).loopStrategy(stopWhenConfident).build()
+     * ```
+     */
+    loopStrategy(custom: LoopStrategy): this;
     /** Record the streaming preference (see {@link AgentRunner.streamEnabled}). */
     stream(enabled?: boolean): this;
     /**

package/dist/index.js

@@ -70,7 +70,7 @@ import {
   toolRuntimeName,
   translateSdkEvent,
   unicodeNormalizer
-} from "./chunk-K3VX4S65.js";
+} from "./chunk-C2DALG62.js";
 import {
   __name
 } from "./chunk-7QVYU63E.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/agents",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "AI agents as first-class citizens of the TheoKit pipeline. The fluent agent()/tool() builders compile to SDK Agent.create() (M31 builder-only authoring API).",
   "type": "module",
   "sideEffects": false,
@@ -48,8 +48,8 @@
     "typescript": "^5.9.3",
     "vitest": "^3.2.6",
     "zod": "^4.4.3",
-    "@theokit/http": "1.0.0",
-    "@theokit/presenter": "0.3.0"
+    "@theokit/presenter": "0.3.0",
+    "@theokit/http": "1.0.0"
   },
   "engines": {
     "node": ">=22.12.0"