@theokit/agents 4.25.0 → 4.26.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-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, e as SkillsOptions, T as ToolOptions, A as ApprovalOptions, H as HumanInTheLoopOptions, f as AgentManifestEntry, g as HitlDecision, s as streamAgentUIMessages } from './bridge-entry-Cq1aVJ_c.js';
-export { h as AGENT_BRAND, i as AfterToolCallContext, j as AgentBuilder, k as AgentDefinition, l as AgentDefinitionError, m as AgentExecutionContext, n as AgentManifest, o as AgentManifestSource, p as AgentManifestTool, q as AgentOptions, r as AgentRoute, t as AgentRouteContext, u as AgentRunInfo, v as AgentStreamEvent, w as AgentTurnMetadata, x as AgentsPluginOptions, y as ApiErrorContext, z as ApiErrorDecision, B as ApiErrorPolicy, E as ApprovalRequiredEvent, F as ArtifactChunkEvent, I as ArtifactStartEvent, J as BackgroundDelegation, K as BeforeToolCallContext, N as BudgetExceededError, O as BudgetOptions, P as CheckpointSavedEvent, Q as CompiledContextWindow, U as ContextualTool, V as CostBudgetExceededError, W as DEFAULT_MAX_ITERATIONS, X as DefineAgentConfig, Y as DelegateFn, Z as DelegateOptions, _ as DelegationError, $ as DoneEvent, a0 as ErrorEvent, a1 as FileEditEvent, a2 as GuardrailAction, a3 as GuardrailPhase, a4 as GuardrailResult, a5 as GuardrailViolationError, a6 as HookHandlers, a7 as InferAgentInput, a8 as InferAgentToolNames, a9 as IterationEvent, aa as LLMCallContext, ab as LoopFinishReason, ac as LoopOutcome, ad as LoopStrategyConfig, ae as MainLoopOptions, af as McpApprovalSpec, ag as McpRegistryConfig, ah as McpRequestContext, ai as McpSelection, aj as PartialToolCallEvent, ak as PolicyHandler, al as ProcessInputContext, am as ReflectionContext, an as ReflectionResult, ao as ReflectionStrategyConfig, ap as RunStartedEvent, aq as ScoreVerdict, ar as ScoredDelegation, as as Scorer, at as SdkAgentHandle, au as SdkMessage, av as Segment, aw as SkillsRequestContext, ax as SkillsSelection, ay as StateUpdateEvent, az as TextDeltaEvent, aA as ThinkingEvent, aB as TimeoutAction, aC as ToolCallEvent, aD as ToolCallVeto, aE as ToolHooks, aF as ToolHooksPlugin, aG as ToolResultEvent, aH as ToolWalkResult, aI as ToolboxOptions, aJ as ToolboxWalkResult, aK as agentsPlugin, aL as buildModelSelection, aM as compileAgentDefinition, aN as compileAgentModule, aO as compileContextWindow, aP as compileProjectContext, aQ as compileSkills, aR as compileTools, aS as createAgentExecutionContext, aT as createApiErrorHandler, aU as createSdkAgentStream, aV as createThinkTagExtractor, aW as createToolHooksPlugin, aX as delegate, aY as delegateBackground, aZ as delegateWithScoring, a_ as extractThinkTagStream, a$ as generateAgentManifest, b0 as generateAgentRoutes, b1 as isAgentContext, b2 as isAgentDefinition, b3 as isApprovalRequired, b4 as isDone, b5 as isError, b6 as isPartialToolCall, b7 as isTextDelta, b8 as isToolCall, b9 as isToolResult, ba as ladderReflectionStrategy, bb as loopStrategyConfigSchema, bc as mcpRegistry, bd as mcpToolApprovals, be as noopReflectionStrategy, bf as presentUIMessageStream, bg as projectContextMetadataOnlyKnobs, bh as reflectionStrategyConfigSchema, bi as resolveEnabledSkills, bj as resolveLoopStrategy, bk as resolveMcpServers, bl as runWithApiErrorHandling, bm as streamAgentResponse, bn as toAgentFactory, bo as translateSdkEvent } from './bridge-entry-Cq1aVJ_c.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, e as SkillsOptions, T as ToolOptions, A as ApprovalOptions, H as HumanInTheLoopOptions, f as AgentManifestEntry, g as HitlDecision, s as streamAgentUIMessages } from './bridge-entry-DMlHq9gR.js';
+export { h as AGENT_BRAND, i as AfterToolCallContext, j as AgentBuilder, k as AgentDefinition, l as AgentDefinitionError, m as AgentExecutionContext, n as AgentManifest, o as AgentManifestSource, p as AgentManifestTool, q as AgentOptions, r as AgentRoute, t as AgentRouteContext, u as AgentRunInfo, v as AgentStreamEvent, w as AgentTurnMetadata, x as AgentsPluginOptions, y as ApiErrorContext, z as ApiErrorDecision, B as ApiErrorPolicy, E as ApprovalRequiredEvent, F as ArtifactChunkEvent, I as ArtifactStartEvent, J as BackgroundDelegation, K as BeforeToolCallContext, N as BudgetOptions, O as CheckpointSavedEvent, P as CompiledContextWindow, Q as ContextualTool, U as CostBudgetExceededError, V as DEFAULT_MAX_ITERATIONS, W as DefineAgentConfig, X as DefinicaoOuThunk, Y as DelegateFn, Z as DelegateOptions, _ as DelegationBudgetExceededError, $ as DelegationBudgetExceededErrorAlias, 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 HookHandlers, 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 SdkSendOptions, ay as SdkTurnHandle, az as Segment, aA as SkillsRequestContext, aB as SkillsSelection, aC as StateUpdateEvent, aD as TextDeltaEvent, aE as ThinkingEvent, aF as TimeoutAction, aG as ToolCallEvent, aH as ToolCallVeto, aI as ToolHooks, aJ as ToolHooksPlugin, aK as ToolResultEvent, aL as ToolWalkResult, aM as ToolboxOptions, aN as ToolboxWalkResult, aO as agentsPlugin, aP as buildModelSelection, aQ as compileAgentDefinition, aR as compileAgentModule, aS as compileContextWindow, aT as compileProjectContext, aU as compileSkills, aV as compileTools, aW as createAgentExecutionContext, aX as createApiErrorHandler, aY as createSdkAgentStream, aZ as createThinkTagExtractor, a_ as createToolHooksPlugin, a$ as delegate, b0 as delegateBackground, b1 as delegateWithScoring, b2 as extractThinkTagStream, b3 as generateAgentManifest, b4 as generateAgentRoutes, b5 as isAgentContext, b6 as isAgentDefinition, b7 as isApprovalRequired, b8 as isDone, b9 as isError, ba as isPartialToolCall, bb as isTextDelta, bc as isToolCall, bd as isToolResult, be as ladderReflectionStrategy, bf as loopStrategyConfigSchema, bg as mcpRegistry, bh as mcpToolApprovals, bi as noopReflectionStrategy, bj as presentUIMessageStream, bk as projectContextMetadataOnlyKnobs, bl as reflectionStrategyConfigSchema, bm as resolveEnabledSkills, bn as resolveLoopStrategy, bo as resolveMcpServers, bp as runWithApiErrorHandling, bq as streamAgentResponse, br as toAgentFactory, bs as translateSdkEvent } from './bridge-entry-DMlHq9gR.js';
 export * from '@theokit/sdk/errors';
-export { ConfigurationError } from '@theokit/sdk/errors';
+export { BudgetExceededError, ConfigurationError } from '@theokit/sdk/errors';
 import { PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition, BudgetTracker, CustomTool, GoalLoopAgent, GoalOptions, runGoalLoop, GoalEvent, GoalResult, InlineSkill } from '@theokit/sdk';
 export { Agent, CustomTool, GoalEvent, GoalLoopAgent, GoalOptions, GoalResult, JudgeCredentialError, JudgeResult, Provider, SDKAgent, SessionRecord, Squad, Tool, Verdict } from '@theokit/sdk';
 import { RetryOptions } from '@theokit/sdk/retry';
@@ -790,6 +790,64 @@ declare class ToolboxCapability implements Capability {
     apply(draft: CompiledAgentOptionsDraft): void;
 }
 
+/**
+ * M91 — `Toolset`: coleção nomeada e imutável de tools, com política de resolução que falha alto.
+ *
+ * ## Por que na camada
+ *
+ * A camada já publica as costuras de `sandbox` e `interactive`; esta é a contraparte que faltava. Sem
+ * ela, o consumidor escreveu a sua — `agents/tools/registry.ts` do agent-builder, 170 LoC — e a
+ * política que importa (falhar alto em nome desconhecido **e** duplicado) ficou fora do framework,
+ * onde o próximo consumidor teria de redescobri-la.
+ *
+ * ## O que ela NÃO faz, e por quê
+ *
+ * **Não prefixa namespace.** Foi isso que desqualificou o `ToolboxCapability` deste mesmo diretório
+ * para este papel: o nome de uma tool é **contrato com o modelo**, e prefixar muda o que o modelo vê.
+ *
+ * **Não constrói tools.** Quais tools, com quais opções e sob qual escopo é decisão do consumidor —
+ * a camada não sabe o `projectRoot` nem a postura de sandbox de ninguém. O `Toolset` recebe as
+ * entradas já construídas e é dono só da **política de resolução**. É a divisão que impede a
+ * primitiva de virar uma segunda cópia do registry do consumidor.
+ *
+ * ## Por que falhar alto nos dois casos
+ *
+ * Nome **desconhecido**: um role que declara `run_shell` numa whitelist e recebe silêncio fica sem a
+ * tool sem ninguém notar. Nome **duplicado**: registra a mesma tool duas vezes no `Agent.create`, sem
+ * sinal nenhum. Nos dois, o resultado é uma mudança de autoridade **não observável** — que é
+ * exatamente o que uma whitelist existe para impedir.
+ */
+/** O mínimo que o `Toolset` precisa saber de uma tool: que ela tem nome. */
+interface ToolComNome {
+    readonly name: string;
+}
+declare class ToolsetError extends Error {
+    readonly code: 'unknown_tool' | 'duplicate_tool';
+    constructor(message: string, code: 'unknown_tool' | 'duplicate_tool');
+}
+declare class Toolset<T extends ToolComNome> {
+    #private;
+    private constructor();
+    /**
+     * Constrói a partir das tools já instanciadas. Falha alto em nome duplicado **na construção** — não
+     * na resolução: um descritor com duas tools de mesmo nome está errado no momento em que é escrito, e
+     * adiar o erro para o primeiro `resolve` esconde metade dos casos.
+     */
+    static from<T extends ToolComNome>(tools: readonly T[]): Toolset<T>;
+    /** Uma tool pelo nome. Lança com o nome no erro — nunca devolve `undefined` em silêncio. */
+    get(name: string): T;
+    /**
+     * Resolve uma whitelist. Falha alto em desconhecido **e** em duplicado dentro da própria lista:
+     * um time nunca concede em silêncio uma tool que o role não declarou, nem descarta em silêncio uma
+     * que declarou.
+     */
+    resolve(names: readonly string[]): readonly T[];
+    /** Os nomes conhecidos, na ordem de registro. */
+    names(): readonly string[];
+    /** Todas as tools, na ordem de registro. */
+    all(): readonly T[];
+}
+
 /**
  * M15 (theokit-ai-first) — A2A agent card generation (ADR-0040 § D2, home/discovery concern).
  *
@@ -1050,4 +1108,4 @@ declare class InProcessApprovalRequiredError extends Error {
  */
 declare function streamAgentTurnInProcess(mod: unknown, apiKey: string, input: StreamAgentTurnInProcessInput, deps?: StreamAgentTurnDeps): AsyncGenerator<UIMessageChunk>;
 
-export { type A2AAuth, type A2ACapabilities, type A2ASkill, type A2AToolConfig, AcpClient, AcpMessageDecoder, type AcpTransport, type AgentCard, type AgentConfig, AgentConfigCapability, AgentManifestEntry, AgentRunner, AgentRunnerBuilder, type AgentRunnerRunOptions, ApprovalOptions, type BuildAgentCardOptions, type Capability, CapabilityConflictError, CapabilityPreset, CapabilityRegistry, CheckpointCapability, type CompactionCallOptions, type CompactionStrategyConfig, CompiledAgentOptions, type CompiledAgentOptionsDraft, CompiledTool, ContextWindowCapability, type CostGuardOptions, DEFAULT_KEEP_TOKENS, DelegationResult, FieldCapability, type FinalizedDraft, GoalRunner, type GoalRunnerDeps, Guardrail, GuardrailsCapability, HitlDecision, HumanInTheLoopCapability, HumanInTheLoopOptions, type InProcessApprovalRequest, InProcessApprovalRequiredError, type InProcessAwaitApproval, LoopStrategy, MCP_PROTOCOL_VERSION, MainLoopCapability, MainLoopMeta, type McpJsonSchema, type McpServerInfo, McpServersCapability, type McpToolDescriptor, MemoryCapability, ModelCapability, type OutputModerationOptions, type PiiOptions, PluginsCapability, ProjectContextCapability, type PromptInjectionOptions, type ProvenanceEntry, ReasoningEffort, ReflectionStrategy, RoundStreamFactory, RunContextCapability, SettingSourcesCapability, SkillsCapability, SkillsOptionsCapability, SkillsResolverCapability, type StreamAgentTurnDeps, type StreamAgentTurnInProcessInput, StreamEvent, SubAgentsCapability, type Summarize, type ToolDeclaration, ToolOptions, ToolboxCapability, type ToolboxSource, ToolsCapability, type TranscriptCompactionStrategy, UnknownCapabilityError, applyCapabilities, buildAgentCard, buildMcpToolDescriptors, compactionStrategyConfigSchema, costGuard, createA2ATool, createDraft, deriveConversationId, encodeAcpMessage, estimateTokens, mcpServerInfo, moderateOutputStream, outputModeration, parseConversationId, piiDetector, promptInjectionDetector, resolveCompactionStrategy, runInputGuards, runOutputGuards, setOnce, streamAgentTurnInProcess, streamAgentUIMessages, tokenBudgetCompactionStrategy, unicodeNormalizer, wellKnownCardPath };
+export { type A2AAuth, type A2ACapabilities, type A2ASkill, type A2AToolConfig, AcpClient, AcpMessageDecoder, type AcpTransport, type AgentCard, type AgentConfig, AgentConfigCapability, AgentManifestEntry, AgentRunner, AgentRunnerBuilder, type AgentRunnerRunOptions, ApprovalOptions, type BuildAgentCardOptions, type Capability, CapabilityConflictError, CapabilityPreset, CapabilityRegistry, CheckpointCapability, type CompactionCallOptions, type CompactionStrategyConfig, CompiledAgentOptions, type CompiledAgentOptionsDraft, CompiledTool, ContextWindowCapability, type CostGuardOptions, DEFAULT_KEEP_TOKENS, DelegationResult, FieldCapability, type FinalizedDraft, GoalRunner, type GoalRunnerDeps, Guardrail, GuardrailsCapability, HitlDecision, HumanInTheLoopCapability, HumanInTheLoopOptions, type InProcessApprovalRequest, InProcessApprovalRequiredError, type InProcessAwaitApproval, LoopStrategy, MCP_PROTOCOL_VERSION, MainLoopCapability, MainLoopMeta, type McpJsonSchema, type McpServerInfo, McpServersCapability, type McpToolDescriptor, MemoryCapability, ModelCapability, type OutputModerationOptions, type PiiOptions, PluginsCapability, ProjectContextCapability, type PromptInjectionOptions, type ProvenanceEntry, ReasoningEffort, ReflectionStrategy, RoundStreamFactory, RunContextCapability, SettingSourcesCapability, SkillsCapability, SkillsOptionsCapability, SkillsResolverCapability, type StreamAgentTurnDeps, type StreamAgentTurnInProcessInput, StreamEvent, SubAgentsCapability, type Summarize, type ToolComNome, type ToolDeclaration, ToolOptions, ToolboxCapability, type ToolboxSource, ToolsCapability, Toolset, ToolsetError, type TranscriptCompactionStrategy, UnknownCapabilityError, applyCapabilities, buildAgentCard, buildMcpToolDescriptors, compactionStrategyConfigSchema, costGuard, createA2ATool, createDraft, deriveConversationId, encodeAcpMessage, estimateTokens, mcpServerInfo, moderateOutputStream, outputModeration, parseConversationId, piiDetector, promptInjectionDetector, resolveCompactionStrategy, runInputGuards, runOutputGuards, setOnce, streamAgentTurnInProcess, streamAgentUIMessages, tokenBudgetCompactionStrategy, unicodeNormalizer, wellKnownCardPath };

package/dist/index.js

@@ -10,6 +10,7 @@ import {
   CostBudgetExceededError,
   DEFAULT_KEEP_TOKENS,
   DEFAULT_MAX_ITERATIONS,
+  DelegationBudgetExceededError,
   DelegationError,
   GoalRunner,
   GuardrailViolationError,
@@ -72,7 +73,7 @@ import {
   toolRuntimeName,
   translateSdkEvent,
   unicodeNormalizer
-} from "./chunk-2L5DI75P.js";
+} from "./chunk-QEWP7GRM.js";
 import {
   __name
 } from "./chunk-7QVYU63E.js";
@@ -590,6 +591,78 @@ var ToolboxCapability = class {
   }
 };
 
+// src/capability/toolset.ts
+var ToolsetError = class extends Error {
+  static {
+    __name(this, "ToolsetError");
+  }
+  code;
+  constructor(message, code) {
+    super(message), this.code = code;
+    this.name = "ToolsetError";
+  }
+};
+var Toolset = class _Toolset {
+  static {
+    __name(this, "Toolset");
+  }
+  #porNome;
+  constructor(porNome) {
+    this.#porNome = porNome;
+    Object.freeze(this);
+  }
+  /**
+  * Constrói a partir das tools já instanciadas. Falha alto em nome duplicado **na construção** — não
+  * na resolução: um descritor com duas tools de mesmo nome está errado no momento em que é escrito, e
+  * adiar o erro para o primeiro `resolve` esconde metade dos casos.
+  */
+  static from(tools) {
+    const porNome = /* @__PURE__ */ new Map();
+    for (const tool of tools) {
+      if (porNome.has(tool.name)) {
+        throw new ToolsetError(`duplicate tool "${tool.name}" in toolset`, "duplicate_tool");
+      }
+      porNome.set(tool.name, tool);
+    }
+    return new _Toolset(porNome);
+  }
+  /** Uma tool pelo nome. Lança com o nome no erro — nunca devolve `undefined` em silêncio. */
+  get(name) {
+    const tool = this.#porNome.get(name);
+    if (tool === void 0) {
+      throw new ToolsetError(`unknown tool "${name}"`, "unknown_tool");
+    }
+    return tool;
+  }
+  /**
+  * Resolve uma whitelist. Falha alto em desconhecido **e** em duplicado dentro da própria lista:
+  * um time nunca concede em silêncio uma tool que o role não declarou, nem descarta em silêncio uma
+  * que declarou.
+  */
+  resolve(names) {
+    const vistos = /* @__PURE__ */ new Set();
+    return names.map((name) => {
+      if (vistos.has(name)) {
+        throw new ToolsetError(`duplicate tool "${name}" in a whitelist`, "duplicate_tool");
+      }
+      vistos.add(name);
+      return this.get(name);
+    });
+  }
+  /** Os nomes conhecidos, na ordem de registro. */
+  names() {
+    return [
+      ...this.#porNome.keys()
+    ];
+  }
+  /** Todas as tools, na ordem de registro. */
+  all() {
+    return [
+      ...this.#porNome.values()
+    ];
+  }
+};
+
 // src/a2a/agent-card.ts
 function trimTrailingSlash(url) {
   return url.endsWith("/") ? url.slice(0, -1) : url;
@@ -873,6 +946,7 @@ export * from "@theokit/sdk/concurrency";
 export * from "@theokit/sdk/messages";
 export * from "@theokit/sdk/models";
 import { discoverSubagents, loadSubagentDefinition } from "@theokit/sdk/subagents-loader";
+import { BudgetExceededError as BudgetExceededError2 } from "@theokit/sdk/errors";
 
 // src/in-process-turn.ts
 var InProcessApprovalRequiredError = class extends Error {
@@ -935,7 +1009,7 @@ export {
   AgentDefinitionError,
   AgentRunner,
   AgentRunnerBuilder,
-  BudgetExceededError,
+  BudgetExceededError2 as BudgetExceededError,
   CONTEXT_WINDOW_FLOOR,
   CONTEXT_WINDOW_MARGIN,
   CapabilityConflictError,
@@ -949,6 +1023,8 @@ export {
   CostBudgetExceededError,
   DEFAULT_KEEP_TOKENS,
   DEFAULT_MAX_ITERATIONS,
+  DelegationBudgetExceededError,
+  BudgetExceededError as DelegationBudgetExceededErrorAlias,
   DelegationError,
   FieldCapability,
   GoalRunner,
@@ -976,6 +1052,8 @@ export {
   Tool,
   ToolboxCapability,
   ToolsCapability,
+  Toolset,
+  ToolsetError,
   UnknownCapabilityError,
   agentsPlugin,
   applyCapabilities,