@theokit/agents 2.0.0 → 3.0.0

package/dist/{bridge-entry-F9kHGaIn.d.ts → bridge-entry-8gsH0kVZ.d.ts}

@@ -1363,11 +1363,17 @@ interface LoopOutcome {
 }
 /** The terminal-decision contract. `shouldContinue` is the inverted `stopWhen`. */
 interface LoopStrategy {
-    /** The originating `@MainLoop` strategy name. */
-    readonly name: MainLoopMeta['strategy'];
-    /** Hard ceiling on rounds — guarantees termination. */
+    /**
+     * The strategy name, surfaced in `finalize`/logs. M54 relaxes this from
+     * `MainLoopMeta['strategy']` to `string` so a caller-injected `.loopStrategy(custom)` can name
+     * itself freely — the three built-ins keep their names, but the seam is no longer union-locked.
+     * The INTERNAL resolution (`loopStrategyConfigSchema`) still validates the three built-in names
+     * via `z.enum`; a custom never passes through it (it enters by the seam, not by name).
+     */
+    readonly name: string;
+    /** Hard ceiling on rounds — guarantees termination (enforced by the runner since M54). */
     readonly maxIterations: number;
-    /** True ⇒ re-enter for another round; false ⇒ terminate. Never true forever. */
+    /** True ⇒ re-enter for another round; false ⇒ terminate. The runner caps it at `maxIterations`. */
     shouldContinue(outcome: LoopOutcome): boolean;
 }
 /** Default round ceiling when `@MainLoop` declares no `maxIterations` (EC-3: finite, never Infinity). */
@@ -1397,7 +1403,7 @@ type LoopStrategyConfig = z.infer<typeof loopStrategyConfigSchema>;
  *
  * Throws (Zod) when `maxIterations < 1` — fail fast, never a silent infinite loop.
  */
-declare function resolveLoopStrategy(strategy: MainLoopMeta['strategy'], maxIterations?: number): LoopStrategy;
+declare function resolveLoopStrategy(strategy: string, maxIterations?: number): LoopStrategy;
 
 /**
  * Shared delegation value types + typed errors.

package/dist/bridge.d.ts

@@ -1,4 +1,4 @@
-export { j as AGENT_BRAND, k as AfterToolCallContext, l as AgentBuilder, m as AgentDefinition, n as AgentDefinitionError, o as AgentExecutionContext, p as AgentManifest, i as AgentManifestEntry, q as AgentManifestSource, r as AgentManifestTool, 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, U as CheckpointSavedEvent, C as CompiledAgentOptions, V as CompiledContextWindow, a as CompiledTool, W as ContextualTool, Z as DefineAgentConfig, _ as DelegateFn, $ as DelegateOptions, a0 as DelegationError, D as DelegationResult, a1 as DoneEvent, a2 as ErrorEvent, a3 as FileEditEvent, a9 as InferAgentInput, aa as InferAgentToolNames, ab as IterationEvent, ac as LLMCallContext, ah as McpApprovalSpec, ai as McpRegistryConfig, aj as McpRequestContext, ak as McpSelection, al as PartialToolCallEvent, an as ProcessInputContext, ar as RunStartedEvent, as as ScoreVerdict, at as ScoredDelegation, au as Scorer, av as SdkAgentHandle, aw as SdkMessage, ax as Segment, az as StateUpdateEvent, S as StreamEvent, aA as TextDeltaEvent, aB as ThinkingEvent, aD as ToolCallEvent, aE as ToolCallVeto, aF as ToolHooks, aG as ToolHooksPlugin, aH as ToolResultEvent, aI as ToolWalkResult, 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, bf as mcpRegistry, bg as mcpToolApprovals, bi as presentUIMessageStream, bj as projectContextMetadataOnlyKnobs, bn as resolveMcpServers, bo as runWithApiErrorHandling, bp as streamAgentResponse, bq as streamAgentUIMessages, br as toAgentFactory, bs as translateSdkEvent } 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, i as AgentManifestEntry, q as AgentManifestSource, r as AgentManifestTool, 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, U as CheckpointSavedEvent, C as CompiledAgentOptions, V as CompiledContextWindow, a as CompiledTool, W as ContextualTool, Z as DefineAgentConfig, _ as DelegateFn, $ as DelegateOptions, a0 as DelegationError, D as DelegationResult, a1 as DoneEvent, a2 as ErrorEvent, a3 as FileEditEvent, a9 as InferAgentInput, aa as InferAgentToolNames, ab as IterationEvent, ac as LLMCallContext, ah as McpApprovalSpec, ai as McpRegistryConfig, aj as McpRequestContext, ak as McpSelection, al as PartialToolCallEvent, an as ProcessInputContext, ar as RunStartedEvent, as as ScoreVerdict, at as ScoredDelegation, au as Scorer, av as SdkAgentHandle, aw as SdkMessage, ax as Segment, az as StateUpdateEvent, S as StreamEvent, aA as TextDeltaEvent, aB as ThinkingEvent, aD as ToolCallEvent, aE as ToolCallVeto, aF as ToolHooks, aG as ToolHooksPlugin, aH as ToolResultEvent, aI as ToolWalkResult, 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, bf as mcpRegistry, bg as mcpToolApprovals, bi as presentUIMessageStream, bj as projectContextMetadataOnlyKnobs, bn as resolveMcpServers, bo as runWithApiErrorHandling, bp as streamAgentResponse, bq as streamAgentUIMessages, br as toAgentFactory, bs as translateSdkEvent } from './bridge-entry-8gsH0kVZ.js';
 import '@theokit/http';
 import '@theokit/sdk';
 import 'zod';

package/dist/bridge.js

@@ -43,7 +43,7 @@ import {
   streamAgentUIMessages,
   toAgentFactory,
   translateSdkEvent
-} from "./chunk-K3VX4S65.js";
+} from "./chunk-C2DALG62.js";
 import "./chunk-7QVYU63E.js";
 export {
   AGENT_BRAND,

package/dist/{chunk-K3VX4S65.js → chunk-C2DALG62.js}

@@ -2470,14 +2470,22 @@ var tokenBudgetCompactionStrategy = resolveCompactionStrategy("token-budget", {
 // src/loop/loop-strategy.ts
 import { z as z2 } from "zod";
 var DEFAULT_MAX_ITERATIONS = 8;
+var maxIterationsSchema = z2.number().int().min(1);
 var loopStrategyConfigSchema = z2.object({
   name: z2.enum([
     "simple-chat",
     "plan-act-reflect",
     "react"
   ]),
-  maxIterations: z2.number().int().min(1)
+  maxIterations: maxIterationsSchema
 });
+function assertValidCustomLoopStrategy(strategy) {
+  const result = maxIterationsSchema.safeParse(strategy.maxIterations);
+  if (!result.success) {
+    throw new Error(`loopStrategy: maxIterations inv\xE1lido (${String(strategy.maxIterations)}) \u2014 deve ser um inteiro finito \u2265 1 (sen\xE3o o teto round < maxIterations nunca termina)`);
+  }
+}
+__name(assertValidCustomLoopStrategy, "assertValidCustomLoopStrategy");
 function resolveLoopStrategy(strategy, maxIterations = DEFAULT_MAX_ITERATIONS) {
   const cfg = loopStrategyConfigSchema.parse({
     name: strategy,
@@ -2795,7 +2803,7 @@ async function* runReflectiveLoopStream(factory, message, sessionId, config) {
       responseText: r.responseText
     };
     const reflectionResult = reflection.reflect(outcome, reflectionContext);
-    if (!(reflectionResult.continue && loop.shouldContinue(outcome))) {
+    if (!(reflectionResult.continue && loop.shouldContinue(outcome) && round < loop.maxIterations)) {
       const reason = terminalReason(reflectionResult.continue, r.finishReason, round, loop.maxIterations);
       return finalize(acc, round, reason, loop.name);
     }
@@ -2823,6 +2831,8 @@ var AgentRunner = class {
   agentName;
   /** The resolved terminal-decision strategy (parity with `delegate()`). */
   loopStrategy;
+  /** M54 — whether {@link loopStrategy} is a caller-injected custom (see {@link AgentRunnerState}). */
+  loopStrategyIsCustom;
   /** The resolved between-round reflection (default or `.reflection(custom)` override). */
   reflectionStrategy;
   /**
@@ -2843,6 +2853,7 @@ var AgentRunner = class {
     this.compiled = state.compiled;
     this.agentName = state.agentName;
     this.loopStrategy = state.loopStrategy;
+    this.loopStrategyIsCustom = state.loopStrategyIsCustom ?? false;
     this.reflectionStrategy = state.reflectionStrategy;
     this.streamEnabled = state.streamEnabled;
     this.compaction = state.compaction;
@@ -2874,7 +2885,7 @@ var AgentRunner = class {
     const tools = opts.tools ? [
       ...opts.tools
     ] : this.compiled.tools;
-    const loop = opts.maxIterations != null ? resolveLoopStrategy(this.loopStrategy.name, opts.maxIterations) : this.loopStrategy;
+    const loop = this.resolvePerRunLoop(opts.maxIterations);
     const streamFactory = opts.streamFactory ?? createSdkAgentStream(this.compiled, tools, opts.apiKey, {
       model: opts.model,
       reasoningEffort: opts.reasoningEffort,
@@ -2900,6 +2911,23 @@ var AgentRunner = class {
     });
   }
   /** 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.
+  */
+  resolvePerRunLoop(maxIterations) {
+    if (maxIterations == null) return this.loopStrategy;
+    if (this.loopStrategyIsCustom) {
+      const base = this.loopStrategy;
+      return Object.assign(Object.create(Object.getPrototypeOf(base)), base, {
+        maxIterations
+      });
+    }
+    return resolveLoopStrategy(this.loopStrategy.name, maxIterations);
+  }
   async run(message, opts) {
     const gen = this.stream(message, opts);
     let res = await gen.next();
@@ -2915,6 +2943,7 @@ var AgentRunnerBuilder = class {
   reflectionOverride;
   streamEnabled = true;
   compactionOverride;
+  loopStrategyOverride;
   constructor(spec) {
     this.spec = spec;
   }
@@ -2923,6 +2952,29 @@ var AgentRunnerBuilder = class {
     if (strategy) this.reflectionOverride = strategy;
     return 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) {
+    assertValidCustomLoopStrategy(custom);
+    this.loopStrategyOverride = custom;
+    return this;
+  }
   /** Record the streaming preference (see {@link AgentRunner.streamEnabled}). */
   stream(enabled = true) {
     this.streamEnabled = enabled;
@@ -2944,7 +2996,8 @@ var AgentRunnerBuilder = class {
   build() {
     const { spec } = this;
     const strategy = spec.strategy ?? "simple-chat";
-    const loopStrategy = resolveLoopStrategy(strategy, spec.maxIterations);
+    const loopStrategyIsCustom = this.loopStrategyOverride !== void 0;
+    const loopStrategy = this.loopStrategyOverride ?? resolveLoopStrategy(strategy, spec.maxIterations);
     const reflectionStrategy = this.reflectionOverride ?? (strategy === "plan-act-reflect" ? ladderReflectionStrategy : noopReflectionStrategy);
     const compactionDecl = this.compactionOverride ?? spec.compaction;
     const compaction = compactionDecl ? resolveCompactionStrategy(compactionDecl.name, {
@@ -2954,6 +3007,7 @@ var AgentRunnerBuilder = class {
       compiled: spec.compiled,
       agentName: spec.name,
       loopStrategy,
+      loopStrategyIsCustom,
       reflectionStrategy,
       streamEnabled: this.streamEnabled,
       compaction
@@ -3424,4 +3478,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-K3VX4S65.js.map
+//# sourceMappingURL=chunk-C2DALG62.js.map