@theokit/agents 2.0.0 → 4.0.0

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

@@ -821,7 +821,7 @@ interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
 /**
  * A branded agent definition — the value {@link defineAgent} returns.
  *
- * `TTools` (M8) is a phantom type parameter carrying the tool-name union: the `agent()` builder
+ * `TTools` (M8) is a phantom type parameter carrying the tool-name union: the `AgentBuilder.create()` builder
  * threads its accumulated literal tool names here (`.build()` returns `AgentDefinition<TInput,
  * 'a' | 'b'>`), so the generated client (`.theokit/agents.d.ts`) can expose them via
  * {@link InferAgentToolNames}. `defineAgent` leaves it `string` (its tools array carries no literal
@@ -835,7 +835,7 @@ type AgentDefinition<TInput extends z.ZodType = z.ZodType, TTools extends string
 type InferAgentInput<T> = T extends AgentDefinition<infer S> ? (S extends z.ZodType ? z.infer<S> : never) : never;
 /**
  * Infer the tool-name union of an agent definition (M8). Yields the literal union for agents built
- * with the `agent()` builder (`'read_file' | 'count_lines'`), or `string` for `defineAgent` agents
+ * with the `AgentBuilder.create()` builder (`'read_file' | 'count_lines'`), or `string` for `defineAgent` agents
  * whose tools array carries no literal names.
  */
 type InferAgentToolNames<T> = T extends AgentDefinition<z.ZodType, infer N> ? N : never;
@@ -962,7 +962,7 @@ interface SdkAgentHandle {
 /**
  * #12 — bridge a builder/`defineAgent` {@link TheokitAgentDefinition} to a real `SDKAgent` FACTORY,
  * so surfaces that require an `SDKAgent` (or `(sessionId) => SDKAgent`) — notably `theokit acp`,
- * whose entry default-export must be one — can serve an agent defined with the `agent()` chain.
+ * whose entry default-export must be one — can serve an agent defined with the `AgentBuilder.create()` chain.
  *
  * The factory reuses the SAME projection the streaming path uses (`compileAgentDefinition` → tools /
  * model / `assembleM8CreateOptions`), so the served agent has identical tools, model, system prompt,
@@ -1065,9 +1065,9 @@ declare function presentUIMessageStream(events: AsyncIterable<AgentStreamEvent>,
 }): AsyncGenerator<UIMessageChunk, void, unknown>;
 
 /**
- * M8 — `agent()`, the fluent agent builder with accumulative **type-state**.
+ * M8 — `AgentBuilder.create()`, the fluent agent builder with accumulative **type-state**.
  *
- * `agent().context<C>().tool(t).model(id).system(s).build()` accumulates type parameters the way
+ * `AgentBuilder.create().context<C>().tool(t).model(id).system(s).build()` accumulates type parameters the way
  * the most-loved TS DX does (tRPC `t.procedure.input().query()`, Zod, Hono) and resolves to the
  * **SAME branded `AgentDefinition`** that {@link defineAgent} produces — one runtime, N syntaxes
  * (ADR-B1). The value is entirely at the type level; `.build()` delegates to `defineAgent`, so
@@ -1106,7 +1106,7 @@ type EmptyContext = Record<never, never>;
 /**
  * A tool that MAY declare, at the type level, the run-context shape it needs. A plain
  * {@link CustomTool} (`TRequired = unknown`) is satisfied by any agent context. Build one that
- * carries a literal name + optional required-context via {@link contextualTool}.
+ * carries a literal name + optional required-context via {@link ContextualTool.of}.
  */
 interface ContextualTool<TName extends string = string, TRequired = unknown> extends CustomTool {
     readonly name: TName;
@@ -1114,13 +1114,21 @@ interface ContextualTool<TName extends string = string, TRequired = unknown> ext
     readonly __requiredContext?: TRequired;
 }
 /**
- * Tag a {@link CustomTool} with a literal name (so `.tool()` can accumulate the tool-name union)
- * and, optionally, a required run-context type. The `requiredContext` argument is a type-only
- * witness — pass `undefined as C` or a sample value; it is never read at runtime.
+ * Static factory for {@link ContextualTool}. M57: OO surface (`ContextualTool.of(...)`) aligned with
+ * the SDK's `X.create()` shape — was the free `contextualTool(...)` function. `ContextualTool` is a
+ * TYPE (the interface above) and a VALUE (this const) at once, the same dual-space pattern the SDK
+ * uses for `Tool`/`Agent`. No instance state, so the factory is `static`-style (`of`), not `create`.
  */
-declare function contextualTool<TName extends string, TRequired = unknown>(tool: CustomTool & {
-    name: TName;
-}, _requiredContext?: TRequired): ContextualTool<TName, TRequired>;
+declare const ContextualTool: {
+    /**
+     * Tag a {@link CustomTool} with a literal name (so `.tool()` can accumulate the tool-name union)
+     * and, optionally, a required run-context type. The `requiredContext` argument is a type-only
+     * witness — pass `undefined as C` or a sample value; it is never read at runtime.
+     */
+    of<TName extends string, TRequired = unknown>(tool: CustomTool & {
+        name: TName;
+    }, _requiredContext?: TRequired): ContextualTool<TName, TRequired>;
+};
 /**
  * The fluent builder. Each method returns a NEW builder type with the relevant type parameter
  * advanced (immutable chaining). Runtime state is a plain {@link DefineAgentConfig} accumulator.
@@ -1183,7 +1191,7 @@ interface AgentBuilder<TInput extends z.ZodType | UnsetMarker = UnsetMarker, TMo
      * it runs; the other events are observational.
      *
      * ```ts
-     * agent().hooks({
+     * AgentBuilder.create().hooks({
      *   pre_tool_call: (c) => guard(c.name) ? undefined : { block: true, message: 'not allowed' },
      *   on_session_start: () => log('session up'),
      * })
@@ -1226,10 +1234,18 @@ interface AgentBuilder<TInput extends z.ZodType | UnsetMarker = UnsetMarker, TMo
     readonly __toolNames?: TTools;
 }
 /**
- * Start a fluent agent definition. Chain `.model()` (required) + `.context()` / `.system()` /
- * `.input()` / `.tool()` / `.use()`, then `.build()` to get the branded {@link AgentDefinition}.
+ * Static entry point for the fluent builder. M57: OO surface (`AgentBuilder.create()`) aligned with
+ * the SDK's `X.create()` shape — was the free `agent()` function. `AgentBuilder` is a TYPE (the
+ * generic interface above) and a VALUE (this const) at once; in type position the interface wins, in
+ * value position the const wins — no collision, the same dual-space pattern the SDK uses for `Agent`.
  */
-declare function agent(): AgentBuilder;
+declare const AgentBuilder: {
+    /**
+     * Start a fluent agent definition. Chain `.model()` (required) + `.context()` / `.system()` /
+     * `.input()` / `.tool()` / `.use()`, then `.build()` to get the branded {@link AgentDefinition}.
+     */
+    create(): AgentBuilder;
+};
 
 /**
  * M4 (theokit-ai-first) — the HITL producer: a `pre_tool_call` plugin that pauses the SDK run
@@ -1363,11 +1379,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 +1419,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.
@@ -2040,4 +2062,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-export { type DelegateOptions as $, type ApprovalOptions as A, type ApiErrorDecision as B, type CompiledAgentOptions as C, type DelegationResult as D, type ApiErrorPolicy as E, type ApprovalRequiredEvent as F, type Guardrail as G, type HumanInTheLoopOptions as H, type ArtifactChunkEvent as I, type ArtifactStartEvent as J, type BackgroundDelegation as K, type LoopStrategy as L, type MainLoopMeta as M, type BeforeToolCallContext as N, BudgetExceededError as O, type ProjectContextOptions as P, type BudgetOptions as Q, type ReflectionStrategy as R, type StreamEvent as S, type ToolOptions as T, type CheckpointSavedEvent as U, type CompiledContextWindow as V, type ContextualTool as W, CostBudgetExceededError as X, DEFAULT_MAX_ITERATIONS as Y, type DefineAgentConfig as Z, type DelegateFn as _, type CompiledTool as a, delegateBackground as a$, DelegationError as a0, type DoneEvent as a1, type ErrorEvent as a2, type FileEditEvent as a3, type GuardrailAction as a4, type GuardrailPhase as a5, type GuardrailResult as a6, GuardrailViolationError as a7, type HitlDecision as a8, type InferAgentInput as a9, type TextDeltaEvent as aA, type ThinkingEvent as aB, type TimeoutAction as aC, type ToolCallEvent as aD, type ToolCallVeto as aE, type ToolHooks as aF, type ToolHooksPlugin as aG, type ToolResultEvent as aH, type ToolWalkResult as aI, type ToolboxOptions as aJ, type ToolboxWalkResult as aK, agent as aL, agentsPlugin as aM, buildModelSelection as aN, compileAgentDefinition as aO, compileAgentModule as aP, compileContextWindow as aQ, compileProjectContext as aR, compileSkills as aS, compileTools as aT, contextualTool as aU, createAgentExecutionContext as aV, createApiErrorHandler as aW, createSdkAgentStream as aX, createThinkTagExtractor as aY, createToolHooksPlugin as aZ, delegate as a_, type InferAgentToolNames as aa, type IterationEvent as ab, type LLMCallContext as ac, type LoopFinishReason as ad, type LoopOutcome as ae, type LoopStrategyConfig as af, type MainLoopOptions as ag, type McpApprovalSpec as ah, type McpRegistryConfig as ai, type McpRequestContext as aj, type McpSelection as ak, type PartialToolCallEvent as al, type PolicyHandler as am, type ProcessInputContext as an, type ReflectionContext as ao, type ReflectionResult as ap, type ReflectionStrategyConfig as aq, type RunStartedEvent as ar, type ScoreVerdict as as, type ScoredDelegation as at, type Scorer as au, type SdkAgentHandle as av, type SdkMessage as aw, type Segment as ax, type SkillsRequestContext as ay, type StateUpdateEvent as az, type ReasoningEffort as b, delegateWithScoring as b0, extractThinkTagStream as b1, generateAgentManifest as b2, generateAgentRoutes as b3, isAgentContext as b4, isAgentDefinition as b5, isApprovalRequired as b6, isDone as b7, isError as b8, isPartialToolCall as b9, isTextDelta as ba, isToolCall as bb, isToolResult as bc, ladderReflectionStrategy as bd, loopStrategyConfigSchema as be, mcpRegistry as bf, mcpToolApprovals as bg, noopReflectionStrategy as bh, presentUIMessageStream as bi, projectContextMetadataOnlyKnobs as bj, reflectionStrategyConfigSchema as bk, resolveEnabledSkills as bl, resolveLoopStrategy as bm, resolveMcpServers as bn, runWithApiErrorHandling as bo, streamAgentResponse as bp, streamAgentUIMessages as bq, toAgentFactory as br, translateSdkEvent as bs, type RoundStreamFactory as c, type ContextWindowOptions as d, type McpServersMap as e, type MemoryOptions as f, type SkillsOptions as g, type SkillsSelection as h, type AgentManifestEntry as i, AGENT_BRAND as j, type AfterToolCallContext as k, type AgentBuilder as l, type AgentDefinition as m, AgentDefinitionError as n, type AgentExecutionContext as o, type AgentManifest as p, type AgentManifestSource as q, type AgentManifestTool as r, type AgentOptions as s, type AgentRoute as t, type AgentRouteContext as u, type AgentRunInfo as v, type AgentStreamEvent as w, type AgentTurnMetadata as x, type AgentsPluginOptions as y, type ApiErrorContext as z };
+export { type FileEditEvent as $, type ApprovalOptions as A, type ArtifactChunkEvent as B, type CompiledAgentOptions as C, type DelegationResult as D, type ArtifactStartEvent as E, type BackgroundDelegation as F, type Guardrail as G, type HumanInTheLoopOptions as H, type BeforeToolCallContext as I, BudgetExceededError as J, type BudgetOptions as K, type LoopStrategy as L, type MainLoopMeta as M, type CheckpointSavedEvent as N, type CompiledContextWindow as O, ContextualTool as P, CostBudgetExceededError as Q, type ReflectionStrategy as R, type StreamEvent as S, type ToolOptions as T, DEFAULT_MAX_ITERATIONS as U, type DefineAgentConfig as V, type DelegateFn as W, type DelegateOptions as X, DelegationError as Y, type DoneEvent as Z, type ErrorEvent as _, type CompiledTool as a, isAgentContext as a$, type GuardrailAction as a0, type GuardrailPhase as a1, type GuardrailResult as a2, GuardrailViolationError as a3, type HitlDecision as a4, type InferAgentInput as a5, type InferAgentToolNames as a6, type IterationEvent as a7, type LLMCallContext as a8, type LoopFinishReason as a9, type ToolCallEvent as aA, type ToolCallVeto as aB, type ToolHooks as aC, type ToolHooksPlugin as aD, type ToolResultEvent as aE, type ToolWalkResult as aF, type ToolboxOptions as aG, type ToolboxWalkResult as aH, agentsPlugin as aI, buildModelSelection as aJ, compileAgentDefinition as aK, compileAgentModule as aL, compileContextWindow as aM, compileProjectContext as aN, compileSkills as aO, compileTools as aP, createAgentExecutionContext as aQ, createApiErrorHandler as aR, createSdkAgentStream as aS, createThinkTagExtractor as aT, createToolHooksPlugin as aU, delegate as aV, delegateBackground as aW, delegateWithScoring as aX, extractThinkTagStream as aY, generateAgentManifest as aZ, generateAgentRoutes as a_, type LoopOutcome as aa, type LoopStrategyConfig as ab, type MainLoopOptions as ac, type McpApprovalSpec as ad, type McpRegistryConfig as ae, type McpRequestContext as af, type McpSelection as ag, type PartialToolCallEvent as ah, type PolicyHandler as ai, type ProcessInputContext as aj, type ReflectionContext as ak, type ReflectionResult as al, type ReflectionStrategyConfig as am, type RunStartedEvent as an, type ScoreVerdict as ao, type ScoredDelegation as ap, type Scorer as aq, type SdkAgentHandle as ar, type SdkMessage as as, type Segment as at, type SkillsRequestContext as au, type SkillsSelection as av, type StateUpdateEvent as aw, type TextDeltaEvent as ax, type ThinkingEvent as ay, type TimeoutAction as az, type ReasoningEffort as b, isAgentDefinition as b0, isApprovalRequired as b1, isDone as b2, isError as b3, isPartialToolCall as b4, isTextDelta as b5, isToolCall as b6, isToolResult as b7, ladderReflectionStrategy as b8, loopStrategyConfigSchema as b9, mcpRegistry as ba, mcpToolApprovals as bb, noopReflectionStrategy as bc, presentUIMessageStream as bd, projectContextMetadataOnlyKnobs as be, reflectionStrategyConfigSchema as bf, resolveEnabledSkills as bg, resolveLoopStrategy as bh, resolveMcpServers as bi, runWithApiErrorHandling as bj, streamAgentResponse as bk, streamAgentUIMessages as bl, toAgentFactory as bm, translateSdkEvent as bn, type RoundStreamFactory as c, type ContextWindowOptions as d, type SkillsOptions as e, type AgentManifestEntry as f, AGENT_BRAND as g, type AfterToolCallContext as h, AgentBuilder as i, type AgentDefinition as j, AgentDefinitionError as k, type AgentExecutionContext as l, type AgentManifest as m, type AgentManifestSource as n, type AgentManifestTool as o, type AgentOptions as p, type AgentRoute as q, type AgentRouteContext as r, type AgentRunInfo as s, type AgentStreamEvent as t, type AgentTurnMetadata as u, type AgentsPluginOptions as v, type ApiErrorContext as w, type ApiErrorDecision as x, type ApiErrorPolicy as y, type ApprovalRequiredEvent as z };

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 { g as AGENT_BRAND, h as AfterToolCallContext, i as AgentBuilder, j as AgentDefinition, k as AgentDefinitionError, l as AgentExecutionContext, m as AgentManifest, f as AgentManifestEntry, n as AgentManifestSource, o as AgentManifestTool, q as AgentRoute, r as AgentRouteContext, s as AgentRunInfo, t as AgentStreamEvent, u as AgentTurnMetadata, v as AgentsPluginOptions, w as ApiErrorContext, x as ApiErrorDecision, y as ApiErrorPolicy, z as ApprovalRequiredEvent, B as ArtifactChunkEvent, E as ArtifactStartEvent, F as BackgroundDelegation, I as BeforeToolCallContext, J as BudgetExceededError, N as CheckpointSavedEvent, C as CompiledAgentOptions, O as CompiledContextWindow, a as CompiledTool, P as ContextualTool, V as DefineAgentConfig, W as DelegateFn, X as DelegateOptions, Y as DelegationError, D as DelegationResult, Z as DoneEvent, _ as ErrorEvent, $ as FileEditEvent, a5 as InferAgentInput, a6 as InferAgentToolNames, a7 as IterationEvent, a8 as LLMCallContext, ad as McpApprovalSpec, ae as McpRegistryConfig, af as McpRequestContext, ag as McpSelection, ah as PartialToolCallEvent, aj as ProcessInputContext, an as RunStartedEvent, ao as ScoreVerdict, ap as ScoredDelegation, aq as Scorer, ar as SdkAgentHandle, as as SdkMessage, at as Segment, aw as StateUpdateEvent, S as StreamEvent, ax as TextDeltaEvent, ay as ThinkingEvent, aA as ToolCallEvent, aB as ToolCallVeto, aC as ToolHooks, aD as ToolHooksPlugin, aE as ToolResultEvent, aF as ToolWalkResult, aH as ToolboxWalkResult, aI as agentsPlugin, aJ as buildModelSelection, aK as compileAgentDefinition, aL as compileAgentModule, aM as compileContextWindow, aN as compileProjectContext, aO as compileSkills, aP as compileTools, aQ as createAgentExecutionContext, aR as createApiErrorHandler, aS as createSdkAgentStream, aT as createThinkTagExtractor, aU as createToolHooksPlugin, aV as delegate, aW as delegateBackground, aX as delegateWithScoring, aY as extractThinkTagStream, aZ as generateAgentManifest, a_ as generateAgentRoutes, a$ as isAgentContext, b0 as isAgentDefinition, b1 as isApprovalRequired, b2 as isDone, b3 as isError, b4 as isPartialToolCall, b5 as isTextDelta, b6 as isToolCall, b7 as isToolResult, ba as mcpRegistry, bb as mcpToolApprovals, bd as presentUIMessageStream, be as projectContextMetadataOnlyKnobs, bi as resolveMcpServers, bj as runWithApiErrorHandling, bk as streamAgentResponse, bl as streamAgentUIMessages, bm as toAgentFactory, bn as translateSdkEvent } from './bridge-entry-Ddu3Ug_3.js';
 import '@theokit/http';
 import '@theokit/sdk';
 import 'zod';

package/dist/bridge.js

@@ -1,9 +1,10 @@
 import {
   AGENT_BRAND,
+  AgentBuilder,
   AgentDefinitionError,
   BudgetExceededError,
+  ContextualTool,
   DelegationError,
-  agent,
   agentsPlugin,
   buildModelSelection,
   compileAgentDefinition,
@@ -12,7 +13,6 @@ import {
   compileProjectContext,
   compileSkills,
   compileTools,
-  contextualTool,
   createAgentExecutionContext,
   createApiErrorHandler,
   createSdkAgentStream,
@@ -43,14 +43,15 @@ import {
   streamAgentUIMessages,
   toAgentFactory,
   translateSdkEvent
-} from "./chunk-K3VX4S65.js";
+} from "./chunk-OKG5LRGV.js";
 import "./chunk-7QVYU63E.js";
 export {
   AGENT_BRAND,
+  AgentBuilder,
   AgentDefinitionError,
   BudgetExceededError,
+  ContextualTool,
   DelegationError,
-  agent,
   agentsPlugin,
   buildModelSelection,
   compileAgentDefinition,
@@ -59,7 +60,6 @@ export {
   compileProjectContext,
   compileSkills,
   compileTools,
-  contextualTool,
   createAgentExecutionContext,
   createApiErrorHandler,
   createSdkAgentStream,

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

@@ -249,13 +249,13 @@ function compileTools(toolboxes, toolboxInstances) {
 __name(compileTools, "compileTools");
 
 // src/bridge/agent-execution-context.ts
-function createAgentExecutionContext(base, agent2, run, toolCall) {
+function createAgentExecutionContext(base, agent, run, toolCall) {
   return {
     getRequest: /* @__PURE__ */ __name(() => base.getRequest(), "getRequest"),
     getUrl: /* @__PURE__ */ __name(() => base.getUrl(), "getUrl"),
     getClass: /* @__PURE__ */ __name(() => base.getClass(), "getClass"),
     getMethodName: /* @__PURE__ */ __name(() => base.getMethodName(), "getMethodName"),
-    getAgent: /* @__PURE__ */ __name(() => agent2, "getAgent"),
+    getAgent: /* @__PURE__ */ __name(() => agent, "getAgent"),
     getRun: /* @__PURE__ */ __name(() => run, "getRun"),
     getToolCall: /* @__PURE__ */ __name(() => toolCall ?? null, "getToolCall"),
     isAgentContext: /* @__PURE__ */ __name(() => true, "isAgentContext")
@@ -1254,7 +1254,7 @@ async function* streamSdkAgent(rt, compiled, sdkTools, opts) {
       projectContext: applied.includes("projectContext")
     });
   }
-  const agent2 = await Agent.getOrCreate(sessionId, {
+  const agent = await Agent.getOrCreate(sessionId, {
     apiKey,
     model: buildModelSelection(model, reasoningEffort),
     tools: sdkTools,
@@ -1272,7 +1272,7 @@ async function* streamSdkAgent(rt, compiled, sdkTools, opts) {
       text: message,
       images: overrides.images
     } : message;
-    const sendPromise = agent2.send(sendInput, sendOptions);
+    const sendPromise = agent.send(sendInput, sendOptions);
     const openStream = /* @__PURE__ */ __name(async () => (await sendPromise).stream(), "openStream");
     const merged = mergeDeltaStream(queue, openStream, runId, state);
     for await (const event of applyTextTransforms(merged, {
@@ -1285,7 +1285,7 @@ async function* streamSdkAgent(rt, compiled, sdkTools, opts) {
       yield realUsageDone(await (await sendPromise).wait(), t0);
     }
   } finally {
-    await agent2.dispose();
+    await agent.dispose();
   }
 }
 __name(streamSdkAgent, "streamSdkAgent");
@@ -1315,14 +1315,14 @@ function toAgentFactory(def, opts) {
       baseDir: overrides.baseDir
     };
     const extra = buildExtraCreateOptions(overrides, compiled);
-    const agent2 = await rt.Agent.getOrCreate(sessionId, {
+    const agent = await rt.Agent.getOrCreate(sessionId, {
       apiKey: opts.apiKey,
       model: buildModelSelection(model, reasoningEffort),
       tools: sdkTools,
       ...m8,
       ...extra
     });
-    return agent2;
+    return agent;
   };
 }
 __name(toAgentFactory, "toAgentFactory");
@@ -1962,10 +1962,16 @@ async function* presentUIMessageStream(events, opts) {
 __name(presentUIMessageStream, "presentUIMessageStream");
 
 // src/bridge/agent-builder.ts
-function contextualTool(tool, _requiredContext) {
-  return tool;
-}
-__name(contextualTool, "contextualTool");
+var ContextualTool = {
+  /**
+  * Tag a {@link CustomTool} with a literal name (so `.tool()` can accumulate the tool-name union)
+  * and, optionally, a required run-context type. The `requiredContext` argument is a type-only
+  * witness — pass `undefined as C` or a sample value; it is never read at runtime.
+  */
+  of(tool, _requiredContext) {
+    return tool;
+  }
+};
 function makeBuilder(config) {
   const runtime = {
     input: /* @__PURE__ */ __name((schema) => makeBuilder({
@@ -2047,10 +2053,15 @@ function makeBuilder(config) {
   return runtime;
 }
 __name(makeBuilder, "makeBuilder");
-function agent() {
-  return makeBuilder({});
-}
-__name(agent, "agent");
+var AgentBuilder = {
+  /**
+  * Start a fluent agent definition. Chain `.model()` (required) + `.context()` / `.system()` /
+  * `.input()` / `.tool()` / `.use()`, then `.build()` to get the branded {@link AgentDefinition}.
+  */
+  create() {
+    return makeBuilder({});
+  }
+};
 
 // src/bridge/hitl-plugin.ts
 function createHitlPlugin(wiring) {
@@ -2470,14 +2481,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 +2814,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 +2842,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 +2864,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 +2896,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 +2922,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 +2954,7 @@ var AgentRunnerBuilder = class {
   reflectionOverride;
   streamEnabled = true;
   compactionOverride;
+  loopStrategyOverride;
   constructor(spec) {
     this.spec = spec;
   }
@@ -2923,6 +2963,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 +3007,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 +3018,7 @@ var AgentRunnerBuilder = class {
       compiled: spec.compiled,
       agentName: spec.name,
       loopStrategy,
+      loopStrategyIsCustom,
       reflectionStrategy,
       streamEnabled: this.streamEnabled,
       compaction
@@ -3382,8 +3447,8 @@ export {
   createSdkAgentStream,
   toAgentFactory,
   presentUIMessageStream,
-  contextualTool,
-  agent,
+  ContextualTool,
+  AgentBuilder,
   AgentDefinitionError,
   compileAgentModule,
   streamAgentUIMessages,
@@ -3424,4 +3489,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-K3VX4S65.js.map
+//# sourceMappingURL=chunk-OKG5LRGV.js.map