@theokit/agents 4.21.0 → 4.23.0

package/dist/{bridge-entry-BmPk3TPf.d.ts → bridge-entry-DMh--RZ5.d.ts}

@@ -1,5 +1,5 @@
 import { ExecutionContext } from '@theokit/http';
-import { SystemPromptResolver, InlineSkill, SettingSource, MemorySettings, SkillsSettings, ContextSettings, CustomTool, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, ModelSelection } from '@theokit/sdk';
+import { SystemPromptResolver, InlineSkill, SettingSource, MemorySettings, SkillsSettings, ContextSettings, CustomTool, PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition as AgentDefinition$1, BudgetTracker, ModelSelection, PreToolCallContext, PreToolCallDecision, PostToolCallContext, ToolResultTransformContext, TransformContext, SessionLifecycleContext, PreUserSendContext, PreUserSendResult, PostAssistantReplyContext } from '@theokit/sdk';
 import { z } from 'zod';
 import { UIMessageChunk } from 'ai';
 import { RetryOptions } from '@theokit/sdk/retry';
@@ -1058,6 +1058,61 @@ declare function presentUIMessageStream(events: AsyncIterable<AgentStreamEvent>,
     textId: string;
 }): AsyncGenerator<UIMessageChunk, void, unknown>;
 
+/**
+ * M82 — the typed shape of `AgentBuilder.create().hooks({...})`.
+ *
+ * ## Por que este tipo mora aqui
+ *
+ * Até o M82 a assinatura era `Readonly<Record<string, unknown>>`: qualquer chave era aceita e todo
+ * handler recebia `ctx: unknown`. O consumidor que quisesse tipo tinha de declarar o seu — e foi
+ * exatamente o que o agent-builder fez, com um alias local de cinco handlers, quatro deles com
+ * `ctx: unknown` porque não havia de onde importar os contextos.
+ *
+ * É a mesma classe que o M81 fechou com `discoverSubagents`: conhecimento do framework reimplementado
+ * no app porque o framework não o publicava. O tipo nasce onde o conhecimento mora.
+ *
+ * ## Sobre `transform_tool_result`
+ *
+ * Este é o ÚNICO canal de estágio-de-tool cujo retorno o SDK aplica — `#runTransform` dobra o valor
+ * devolvido; `#runFireAndForget`, usado por `post_tool_call`, descarta. Desde o M82 seu contexto
+ * carrega `toolCalls`, de modo que uma política com escopo (por nome de tool) possa AGIR sobre o
+ * resultado em vez de apenas observá-lo.
+ */
+
+/**
+ * Handlers de ciclo de vida chaveados por `HookName`.
+ *
+ * TYPE ALIAS, não interface: só aliases ganham index signature implícita, e é isso que mantém o
+ * valor atribuível ao parâmetro solto de `.hooks()` sem cast no call site (ADR-4 do M82 — o
+ * estreitamento é gradual, não uma quebra).
+ *
+ * Todo campo é opcional: um agente registra só os eventos que lhe interessam.
+ */
+type HookHandlers = {
+    /**
+     * Roda ANTES da tool. Devolver `{ block: true, message }` VETA a chamada — é o único hook com
+     * poder de veto.
+     */
+    pre_tool_call?: (ctx: PreToolCallContext) => Promise<PreToolCallDecision | undefined> | PreToolCallDecision | undefined;
+    /**
+     * Roda DEPOIS da tool, com `{name, args, result}`. Fire-and-forget: o retorno é **descartado**
+     * pelo SDK. Para AGIR sobre o resultado use {@link transform_tool_result}.
+     */
+    post_tool_call?: (ctx: PostToolCallContext) => Promise<void> | void;
+    /**
+     * Dobra os resultados de tool do turn antes de eles subirem ao modelo. Desde o M82 o contexto traz
+     * `toolCalls` — plural, porque o seam recebe o LOTE do turn; correlacione por
+     * `toolUseId === id`.
+     */
+    transform_tool_result?: <T>(results: T, ctx: ToolResultTransformContext) => Promise<T> | T;
+    /** Dobra o texto do modelo antes de ele ser consumido. Sem tool call envolvida. */
+    transform_llm_output?: (output: string, ctx: TransformContext) => Promise<string> | string;
+    on_session_start?: (ctx: SessionLifecycleContext) => Promise<void> | void;
+    on_session_end?: (ctx: SessionLifecycleContext) => Promise<void> | void;
+    pre_user_send?: (ctx: PreUserSendContext) => Promise<PreUserSendResult | undefined> | PreUserSendResult | undefined;
+    post_assistant_reply?: (ctx: PostAssistantReplyContext) => Promise<void> | void;
+};
+
 /**
  * M8 — `AgentBuilder.create()`, the fluent agent builder with accumulative **type-state**.
  *
@@ -1196,7 +1251,7 @@ interface AgentBuilder<TInput extends z.ZodType | UnsetMarker = UnsetMarker, TMo
      * assembling plumbing. Call once — a later call replaces the map. Composes with
      * {@link AgentBuilder.plugins}: hooks and plugins are additive, not exclusive.
      */
-    hooks(map: Readonly<Record<string, unknown>>): AgentBuilder<TInput, TModel, TContext, TTools>;
+    hooks(map: HookHandlers | Readonly<Record<string, unknown>>): AgentBuilder<TInput, TModel, TContext, TTools>;
     /**
      * Register code `Plugin` objects for this agent — the builder-chain equivalent of
      * `Agent.create({ plugins })`. A plugin is an EXTENSION UNIT: it can register tools and commands,
@@ -2056,4 +2111,4 @@ declare function agentsPlugin(opts: AgentsPluginOptions): {
     register(app: PluginApp): void;
 };
 
-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 };
+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, generateAgentRoutes as a$, type GuardrailAction as a0, type GuardrailPhase as a1, type GuardrailResult as a2, GuardrailViolationError as a3, type HitlDecision as a4, type HookHandlers as a5, type InferAgentInput as a6, type InferAgentToolNames as a7, type IterationEvent as a8, type LLMCallContext as a9, type TimeoutAction as aA, type ToolCallEvent as aB, type ToolCallVeto as aC, type ToolHooks as aD, type ToolHooksPlugin as aE, type ToolResultEvent as aF, type ToolWalkResult as aG, type ToolboxOptions as aH, type ToolboxWalkResult as aI, agentsPlugin as aJ, buildModelSelection as aK, compileAgentDefinition as aL, compileAgentModule as aM, compileContextWindow as aN, compileProjectContext as aO, compileSkills as aP, compileTools as aQ, createAgentExecutionContext as aR, createApiErrorHandler as aS, createSdkAgentStream as aT, createThinkTagExtractor as aU, createToolHooksPlugin as aV, delegate as aW, delegateBackground as aX, delegateWithScoring as aY, extractThinkTagStream as aZ, generateAgentManifest as a_, type LoopFinishReason as aa, type LoopOutcome as ab, type LoopStrategyConfig as ac, type MainLoopOptions as ad, type McpApprovalSpec as ae, type McpRegistryConfig as af, type McpRequestContext as ag, type McpSelection as ah, type PartialToolCallEvent as ai, type PolicyHandler as aj, type ProcessInputContext as ak, type ReflectionContext as al, type ReflectionResult as am, type ReflectionStrategyConfig as an, type RunStartedEvent as ao, type ScoreVerdict as ap, type ScoredDelegation as aq, type Scorer as ar, type SdkAgentHandle as as, type SdkMessage as at, type Segment as au, type SkillsRequestContext as av, type SkillsSelection as aw, type StateUpdateEvent as ax, type TextDeltaEvent as ay, type ThinkingEvent as az, type ReasoningEffort as b, isAgentContext as b0, isAgentDefinition as b1, isApprovalRequired as b2, isDone as b3, isError as b4, isPartialToolCall as b5, isTextDelta as b6, isToolCall as b7, isToolResult as b8, ladderReflectionStrategy as b9, loopStrategyConfigSchema as ba, mcpRegistry as bb, mcpToolApprovals as bc, noopReflectionStrategy as bd, presentUIMessageStream as be, projectContextMetadataOnlyKnobs as bf, reflectionStrategyConfigSchema as bg, resolveEnabledSkills as bh, resolveLoopStrategy as bi, resolveMcpServers as bj, runWithApiErrorHandling as bk, streamAgentResponse as bl, streamAgentUIMessages as bm, toAgentFactory as bn, translateSdkEvent as bo, 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 { 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-BmPk3TPf.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, a6 as InferAgentInput, a7 as InferAgentToolNames, a8 as IterationEvent, a9 as LLMCallContext, ae as McpApprovalSpec, af as McpRegistryConfig, ag as McpRequestContext, ah as McpSelection, ai as PartialToolCallEvent, ak as ProcessInputContext, ao as RunStartedEvent, ap as ScoreVerdict, aq as ScoredDelegation, ar as Scorer, as as SdkAgentHandle, at as SdkMessage, au as Segment, ax as StateUpdateEvent, S as StreamEvent, ay as TextDeltaEvent, az as ThinkingEvent, aB as ToolCallEvent, aC as ToolCallVeto, aD as ToolHooks, aE as ToolHooksPlugin, aF as ToolResultEvent, aG as ToolWalkResult, aI as ToolboxWalkResult, aJ as agentsPlugin, aK as buildModelSelection, aL as compileAgentDefinition, aM as compileAgentModule, aN as compileContextWindow, aO as compileProjectContext, aP as compileSkills, aQ as compileTools, aR as createAgentExecutionContext, aS as createApiErrorHandler, aT as createSdkAgentStream, aU as createThinkTagExtractor, aV as createToolHooksPlugin, aW as delegate, aX as delegateBackground, aY as delegateWithScoring, aZ as extractThinkTagStream, a_ as generateAgentManifest, a$ as generateAgentRoutes, b0 as isAgentContext, b1 as isAgentDefinition, b2 as isApprovalRequired, b3 as isDone, b4 as isError, b5 as isPartialToolCall, b6 as isTextDelta, b7 as isToolCall, b8 as isToolResult, bb as mcpRegistry, bc as mcpToolApprovals, be as presentUIMessageStream, bf as projectContextMetadataOnlyKnobs, bj as resolveMcpServers, bk as runWithApiErrorHandling, bl as streamAgentResponse, bm as streamAgentUIMessages, bn as toAgentFactory, bo as translateSdkEvent } from './bridge-entry-DMh--RZ5.js';
 import '@theokit/http';
 import '@theokit/sdk';
 import 'zod';

package/dist/bridge.js

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

package/dist/{chunk-P6FAJGIU.js → chunk-IB7I44PO.js}

@@ -3508,4 +3508,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-P6FAJGIU.js.map
+//# sourceMappingURL=chunk-IB7I44PO.js.map