@dudousxd/nestjs-agent-core 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -98,6 +98,16 @@ interface ToolSpec {
     targetAgent?: string;
     /** Roles allowed to invoke. Undefined → defaults applied by RolesPolicy (e.g. ADMIN-only). */
     roles?: string[];
+    /**
+     * Whether the tool exists in this deployment. `false` (or a predicate returning `false`) drops it
+     * before the role filter, so it is never offered to the model and cannot be invoked. Undefined →
+     * enabled.
+     *
+     * A predicate is re-evaluated every turn, so a flag flipped at runtime takes effect on the next
+     * message with nothing re-registered. For availability that depends on injected services, put
+     * `isEnabled()` on the handler instead — a spec is data, a handler is a provider.
+     */
+    enabled?: boolean | (() => boolean | Promise<boolean>);
     /**
      * An authorization ability name (e.g. 'cache.purge'). Consumed by an ability-aware RolesPolicy
      * such as the `@dudousxd/nestjs-agent-authz` Gate adapter. Apps that don't use authz ignore it
@@ -465,6 +475,33 @@ interface AiToolCtx {
 /** A tool implementation. `I` is the parsed (Zod-validated) input. */
 interface ToolHandler<I = unknown> {
     execute(input: I, ctx: AiToolCtx): Promise<unknown>;
+    /**
+     * Whether this tool exists in this deployment at all — evaluated per turn, BEFORE the roles
+     * policy, so a `false` here means the model is never shown the tool rather than being shown one
+     * it will be refused. Omit → always enabled.
+     *
+     * This is the seam for a feature flag or a licensing tier: the handler is an ordinary provider,
+     * so it can read injected config (`this.config.featureX`) that a decorator, evaluated at import
+     * time, cannot. Answering "does this capability exist here?"; `roles`/`RolesPolicy` answers the
+     * separate question "may THIS actor use it?", and both still run.
+     *
+     * Prefer this over conditionally registering the provider: registration happens while the
+     * `@Module` metadata is built, which in most apps is before configuration is loaded.
+     */
+    isEnabled?(): boolean | Promise<boolean>;
+    /**
+     * Whether THIS actor may use the tool, decided per turn. Omit → the role gate alone decides.
+     *
+     * The three existing gates all answer the question somewhere else: `roles` is static data,
+     * `RolesPolicy` is one app-wide rule for every tool, and an agent's `tools` allow-list is fixed
+     * when the agent is declared. This one lives on the tool and runs with DI, so it can ask the
+     * questions only the tool knows to ask — is this user's org on the plan that includes it, does
+     * this actor own the base being queried, is the per-user override in the DB set today.
+     *
+     * Runs AFTER {@link isEnabled} and the `RolesPolicy`, and all of them must pass. Applied both
+     * when the turn's tool list is built (a denied actor is never shown it) and again on invoke.
+     */
+    canUse?(actor: Actor): boolean | Promise<boolean>;
 }
 
 /**
@@ -1404,6 +1441,36 @@ declare function dayBoundsUtc(range: GovernanceRange): {
     end: Date;
 };
 
+/**
+ * Is this tool part of this deployment right now? `ToolSpec.enabled` and the handler's
+ * `isEnabled()` are ANDed — either one saying no is enough — and both default to yes.
+ *
+ * Resolved per turn rather than at registration, so the answer can come from configuration that
+ * did not exist when the module was built.
+ */
+declare function isToolEnabled(spec: ToolSpec, handler?: ToolHandler): Promise<boolean>;
+/**
+ * Zeroth filter layer: drop tools this deployment has turned off, before anyone asks who may call
+ * them. A disabled tool is absent, not forbidden — the difference matters, because "forbidden"
+ * tells the model (and the user reading a refusal) that the capability exists.
+ */
+declare function filterToolsByEnabled<T extends {
+    spec: ToolSpec;
+    handler?: ToolHandler;
+}>(entries: T[]): Promise<T[]>;
+/**
+ * May this actor use this tool, per the tool's OWN gate? Tools without a `canUse` say yes and are
+ * governed by the `RolesPolicy` alone.
+ */
+declare function canActorUseTool(actor: Actor, handler?: ToolHandler): Promise<boolean>;
+/**
+ * Third filter layer: drop tools whose own `canUse` refuses this actor. Runs after the app-wide
+ * `RolesPolicy`, and is additive to it — a tool can narrow who reaches it, never widen.
+ */
+declare function filterToolsByCanUse<T extends {
+    spec: ToolSpec;
+    handler?: ToolHandler;
+}>(entries: T[], actor: Actor): Promise<T[]>;
 /** First filter layer: drop tools the actor's role may not invoke. `can` may be async (authz). */
 declare function filterToolsByRole(tools: ToolSpec[], actor: Actor, policy: RolesPolicy): Promise<ToolSpec[]>;
 /** Second filter layer: if the agent pins an allow-list, keep only those tool names. */
@@ -1423,6 +1490,19 @@ declare class ToolForbiddenError extends Error {
     readonly toolName: string;
     constructor(toolName: string);
 }
+/**
+ * Thrown when a registered tool is invoked while this deployment has it turned off (`enabled` /
+ * `isEnabled()`). Distinct from {@link ToolForbiddenError}, which is about the actor, and from
+ * {@link ToolNotFoundError}, which is about a name nobody registered — an operator reading a log
+ * needs to tell "you flipped the flag" apart from "that tool does not exist in this build".
+ *
+ * Reachable in normal operation, not just from a forged call: a HITL `action` approved before the
+ * flag was turned off runs its tool afterwards.
+ */
+declare class ToolDisabledError extends Error {
+    readonly toolName: string;
+    constructor(toolName: string);
+}
 /** Thrown when a tool is invoked that was never registered. */
 declare class ToolNotFoundError extends Error {
     readonly toolName: string;
@@ -1447,9 +1527,19 @@ declare class ToolRegistry {
     has(name: string): boolean;
     spec(name: string): ToolSpec | undefined;
     allSpecs(): ToolSpec[];
-    /** The tools to offer the model for this actor+agent, after the two filter layers. */
+    /**
+     * The tools to offer the model for this actor+agent, after the four filter layers: what this
+     * deployment has enabled, what this actor's role allows, what each tool's own `canUse` allows
+     * this actor, and finally what this agent pinned.
+     *
+     * Every layer only ever removes tools, so no arrangement of them can widen what a turn reaches.
+     */
     definitionsFor(actor: Actor, policy: RolesPolicy, allowedTools?: string[]): Promise<ToolDefinition[]>;
-    /** Run a tool. Re-checks the role (defense-in-depth) and re-parses the input via Zod. */
+    /**
+     * Run a tool. Re-checks that the tool is enabled and that the role allows it (defense-in-depth —
+     * a call can reach here from a replayed durable step or an approval granted before the flag
+     * moved, neither of which went through `definitionsFor` again) and re-parses the input via Zod.
+     */
     invoke(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy): Promise<unknown>;
 }
 /** Default gate: one of the actor's roles must be in spec.roles (defaulting to ADMIN-only). */
@@ -1745,4 +1835,4 @@ type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
  */
 declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSpanEvent, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, type AiToolCtx, type AppendMessageInput, type ApprovalWhere, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, type Decision, DefaultRolesPolicy, type DetailThreadRef, type EmbeddingProvider, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, type InvokeWithTransientRetryOptions, type LlmStepEnvelope, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PendingApprovalRow, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, type ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolCallWhere, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type ToolStatRow, type ToolStepCtx, type ToolStepEnvelope, type ToolTransientRetryNumbers, type ToolTransientRetryOptions, type ToolTransientRetrySetting, type UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, agentDiagnosticKey, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, invokeWithTransientRetry, isTransientToolError, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, publishAgentToolRetry, resolveToolTransientRetryNumbers, rollupThreadUsage, runAgentLoop, seedModelPrices, traceLlmTurn, traceToolExecution, truncateDetailContent, withToolTimeout };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSpanEvent, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, type AiToolCtx, type AppendMessageInput, type ApprovalWhere, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, type Decision, DefaultRolesPolicy, type DetailThreadRef, type EmbeddingProvider, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, type InvokeWithTransientRetryOptions, type LlmStepEnvelope, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PendingApprovalRow, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, type ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolCallWhere, type ToolDefinition, ToolDisabledError, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type ToolStatRow, type ToolStepCtx, type ToolStepEnvelope, type ToolTransientRetryNumbers, type ToolTransientRetryOptions, type ToolTransientRetrySetting, type UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, agentDiagnosticKey, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, canActorUseTool, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, invokeWithTransientRetry, isToolEnabled, isTransientToolError, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, publishAgentToolRetry, resolveToolTransientRetryNumbers, rollupThreadUsage, runAgentLoop, seedModelPrices, traceLlmTurn, traceToolExecution, truncateDetailContent, withToolTimeout };

package/dist/index.d.ts

@@ -98,6 +98,16 @@ interface ToolSpec {
     targetAgent?: string;
     /** Roles allowed to invoke. Undefined → defaults applied by RolesPolicy (e.g. ADMIN-only). */
     roles?: string[];
+    /**
+     * Whether the tool exists in this deployment. `false` (or a predicate returning `false`) drops it
+     * before the role filter, so it is never offered to the model and cannot be invoked. Undefined →
+     * enabled.
+     *
+     * A predicate is re-evaluated every turn, so a flag flipped at runtime takes effect on the next
+     * message with nothing re-registered. For availability that depends on injected services, put
+     * `isEnabled()` on the handler instead — a spec is data, a handler is a provider.
+     */
+    enabled?: boolean | (() => boolean | Promise<boolean>);
     /**
      * An authorization ability name (e.g. 'cache.purge'). Consumed by an ability-aware RolesPolicy
      * such as the `@dudousxd/nestjs-agent-authz` Gate adapter. Apps that don't use authz ignore it
@@ -465,6 +475,33 @@ interface AiToolCtx {
 /** A tool implementation. `I` is the parsed (Zod-validated) input. */
 interface ToolHandler<I = unknown> {
     execute(input: I, ctx: AiToolCtx): Promise<unknown>;
+    /**
+     * Whether this tool exists in this deployment at all — evaluated per turn, BEFORE the roles
+     * policy, so a `false` here means the model is never shown the tool rather than being shown one
+     * it will be refused. Omit → always enabled.
+     *
+     * This is the seam for a feature flag or a licensing tier: the handler is an ordinary provider,
+     * so it can read injected config (`this.config.featureX`) that a decorator, evaluated at import
+     * time, cannot. Answering "does this capability exist here?"; `roles`/`RolesPolicy` answers the
+     * separate question "may THIS actor use it?", and both still run.
+     *
+     * Prefer this over conditionally registering the provider: registration happens while the
+     * `@Module` metadata is built, which in most apps is before configuration is loaded.
+     */
+    isEnabled?(): boolean | Promise<boolean>;
+    /**
+     * Whether THIS actor may use the tool, decided per turn. Omit → the role gate alone decides.
+     *
+     * The three existing gates all answer the question somewhere else: `roles` is static data,
+     * `RolesPolicy` is one app-wide rule for every tool, and an agent's `tools` allow-list is fixed
+     * when the agent is declared. This one lives on the tool and runs with DI, so it can ask the
+     * questions only the tool knows to ask — is this user's org on the plan that includes it, does
+     * this actor own the base being queried, is the per-user override in the DB set today.
+     *
+     * Runs AFTER {@link isEnabled} and the `RolesPolicy`, and all of them must pass. Applied both
+     * when the turn's tool list is built (a denied actor is never shown it) and again on invoke.
+     */
+    canUse?(actor: Actor): boolean | Promise<boolean>;
 }
 
 /**
@@ -1404,6 +1441,36 @@ declare function dayBoundsUtc(range: GovernanceRange): {
     end: Date;
 };
 
+/**
+ * Is this tool part of this deployment right now? `ToolSpec.enabled` and the handler's
+ * `isEnabled()` are ANDed — either one saying no is enough — and both default to yes.
+ *
+ * Resolved per turn rather than at registration, so the answer can come from configuration that
+ * did not exist when the module was built.
+ */
+declare function isToolEnabled(spec: ToolSpec, handler?: ToolHandler): Promise<boolean>;
+/**
+ * Zeroth filter layer: drop tools this deployment has turned off, before anyone asks who may call
+ * them. A disabled tool is absent, not forbidden — the difference matters, because "forbidden"
+ * tells the model (and the user reading a refusal) that the capability exists.
+ */
+declare function filterToolsByEnabled<T extends {
+    spec: ToolSpec;
+    handler?: ToolHandler;
+}>(entries: T[]): Promise<T[]>;
+/**
+ * May this actor use this tool, per the tool's OWN gate? Tools without a `canUse` say yes and are
+ * governed by the `RolesPolicy` alone.
+ */
+declare function canActorUseTool(actor: Actor, handler?: ToolHandler): Promise<boolean>;
+/**
+ * Third filter layer: drop tools whose own `canUse` refuses this actor. Runs after the app-wide
+ * `RolesPolicy`, and is additive to it — a tool can narrow who reaches it, never widen.
+ */
+declare function filterToolsByCanUse<T extends {
+    spec: ToolSpec;
+    handler?: ToolHandler;
+}>(entries: T[], actor: Actor): Promise<T[]>;
 /** First filter layer: drop tools the actor's role may not invoke. `can` may be async (authz). */
 declare function filterToolsByRole(tools: ToolSpec[], actor: Actor, policy: RolesPolicy): Promise<ToolSpec[]>;
 /** Second filter layer: if the agent pins an allow-list, keep only those tool names. */
@@ -1423,6 +1490,19 @@ declare class ToolForbiddenError extends Error {
     readonly toolName: string;
     constructor(toolName: string);
 }
+/**
+ * Thrown when a registered tool is invoked while this deployment has it turned off (`enabled` /
+ * `isEnabled()`). Distinct from {@link ToolForbiddenError}, which is about the actor, and from
+ * {@link ToolNotFoundError}, which is about a name nobody registered — an operator reading a log
+ * needs to tell "you flipped the flag" apart from "that tool does not exist in this build".
+ *
+ * Reachable in normal operation, not just from a forged call: a HITL `action` approved before the
+ * flag was turned off runs its tool afterwards.
+ */
+declare class ToolDisabledError extends Error {
+    readonly toolName: string;
+    constructor(toolName: string);
+}
 /** Thrown when a tool is invoked that was never registered. */
 declare class ToolNotFoundError extends Error {
     readonly toolName: string;
@@ -1447,9 +1527,19 @@ declare class ToolRegistry {
     has(name: string): boolean;
     spec(name: string): ToolSpec | undefined;
     allSpecs(): ToolSpec[];
-    /** The tools to offer the model for this actor+agent, after the two filter layers. */
+    /**
+     * The tools to offer the model for this actor+agent, after the four filter layers: what this
+     * deployment has enabled, what this actor's role allows, what each tool's own `canUse` allows
+     * this actor, and finally what this agent pinned.
+     *
+     * Every layer only ever removes tools, so no arrangement of them can widen what a turn reaches.
+     */
     definitionsFor(actor: Actor, policy: RolesPolicy, allowedTools?: string[]): Promise<ToolDefinition[]>;
-    /** Run a tool. Re-checks the role (defense-in-depth) and re-parses the input via Zod. */
+    /**
+     * Run a tool. Re-checks that the tool is enabled and that the role allows it (defense-in-depth —
+     * a call can reach here from a replayed durable step or an approval granted before the flag
+     * moved, neither of which went through `definitionsFor` again) and re-parses the input via Zod.
+     */
     invoke(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy): Promise<unknown>;
 }
 /** Default gate: one of the actor's roles must be in spec.roles (defaulting to ADMIN-only). */
@@ -1745,4 +1835,4 @@ type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
  */
 declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSpanEvent, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, type AiToolCtx, type AppendMessageInput, type ApprovalWhere, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, type Decision, DefaultRolesPolicy, type DetailThreadRef, type EmbeddingProvider, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, type InvokeWithTransientRetryOptions, type LlmStepEnvelope, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PendingApprovalRow, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, type ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolCallWhere, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type ToolStatRow, type ToolStepCtx, type ToolStepEnvelope, type ToolTransientRetryNumbers, type ToolTransientRetryOptions, type ToolTransientRetrySetting, type UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, agentDiagnosticKey, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, invokeWithTransientRetry, isTransientToolError, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, publishAgentToolRetry, resolveToolTransientRetryNumbers, rollupThreadUsage, runAgentLoop, seedModelPrices, traceLlmTurn, traceToolExecution, truncateDetailContent, withToolTimeout };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSpanEvent, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, type AiToolCtx, type AppendMessageInput, type ApprovalWhere, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, type Decision, DefaultRolesPolicy, type DetailThreadRef, type EmbeddingProvider, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, type InvokeWithTransientRetryOptions, type LlmStepEnvelope, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PendingApprovalRow, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, type ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolCallWhere, type ToolDefinition, ToolDisabledError, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type ToolStatRow, type ToolStepCtx, type ToolStepEnvelope, type ToolTransientRetryNumbers, type ToolTransientRetryOptions, type ToolTransientRetrySetting, type UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, agentDiagnosticKey, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, canActorUseTool, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, invokeWithTransientRetry, isToolEnabled, isTransientToolError, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, publishAgentToolRetry, resolveToolTransientRetryNumbers, rollupThreadUsage, runAgentLoop, seedModelPrices, traceLlmTurn, traceToolExecution, truncateDetailContent, withToolTimeout };

package/dist/index.js

@@ -223,6 +223,34 @@ function dayBoundsUtc(range) {
 __name(dayBoundsUtc, "dayBoundsUtc");
 
 // src/tool-filters.ts
+async function isToolEnabled(spec, handler) {
+  const declared = typeof spec.enabled === "function" ? await spec.enabled() : spec.enabled ?? true;
+  if (!declared) {
+    return false;
+  }
+  return handler?.isEnabled === void 0 ? true : await handler.isEnabled();
+}
+__name(isToolEnabled, "isToolEnabled");
+async function filterToolsByEnabled(entries) {
+  const checked = await Promise.all(entries.map(async (entry) => ({
+    entry,
+    enabled: await isToolEnabled(entry.spec, entry.handler)
+  })));
+  return checked.filter((row) => row.enabled).map((row) => row.entry);
+}
+__name(filterToolsByEnabled, "filterToolsByEnabled");
+async function canActorUseTool(actor, handler) {
+  return handler?.canUse === void 0 ? true : await handler.canUse(actor);
+}
+__name(canActorUseTool, "canActorUseTool");
+async function filterToolsByCanUse(entries, actor) {
+  const checked = await Promise.all(entries.map(async (entry) => ({
+    entry,
+    allowed: await canActorUseTool(actor, entry.handler)
+  })));
+  return checked.filter((row) => row.allowed).map((row) => row.entry);
+}
+__name(filterToolsByCanUse, "filterToolsByCanUse");
 async function filterToolsByRole(tools, actor, policy) {
   const checked = await Promise.all(tools.map(async (tool) => ({
     tool,
@@ -273,6 +301,16 @@ var ToolForbiddenError = class extends Error {
     this.name = "ToolForbiddenError";
   }
 };
+var ToolDisabledError = class extends Error {
+  static {
+    __name(this, "ToolDisabledError");
+  }
+  toolName;
+  constructor(toolName) {
+    super(`Tool "${toolName}" is disabled in this deployment`), this.toolName = toolName;
+    this.name = "ToolDisabledError";
+  }
+};
 var ToolNotFoundError = class extends Error {
   static {
     __name(this, "ToolNotFoundError");
@@ -316,10 +354,21 @@ var ToolRegistry = class {
       ...this.entries.values()
     ].map((entry) => entry.spec);
   }
-  /** The tools to offer the model for this actor+agent, after the two filter layers. */
+  /**
+  * The tools to offer the model for this actor+agent, after the four filter layers: what this
+  * deployment has enabled, what this actor's role allows, what each tool's own `canUse` allows
+  * this actor, and finally what this agent pinned.
+  *
+  * Every layer only ever removes tools, so no arrangement of them can widen what a turn reaches.
+  */
   async definitionsFor(actor, policy, allowedTools) {
-    const roleScoped = await filterToolsByRole(this.allSpecs(), actor, policy);
-    const allowScoped = filterToolsByAllowList(roleScoped, allowedTools);
+    const live = await filterToolsByEnabled([
+      ...this.entries.values()
+    ]);
+    const allowedByRole = new Set((await filterToolsByRole(live.map((entry) => entry.spec), actor, policy)).map((spec) => spec.name));
+    const roleScoped = live.filter((entry) => allowedByRole.has(entry.spec.name));
+    const actorScoped = await filterToolsByCanUse(roleScoped, actor);
+    const allowScoped = filterToolsByAllowList(actorScoped.map((entry) => entry.spec), allowedTools);
     return allowScoped.map((spec) => ({
       name: spec.name,
       kind: spec.kind,
@@ -327,15 +376,25 @@ var ToolRegistry = class {
       inputSchema: spec.inputSchema
     }));
   }
-  /** Run a tool. Re-checks the role (defense-in-depth) and re-parses the input via Zod. */
+  /**
+  * Run a tool. Re-checks that the tool is enabled and that the role allows it (defense-in-depth —
+  * a call can reach here from a replayed durable step or an approval granted before the flag
+  * moved, neither of which went through `definitionsFor` again) and re-parses the input via Zod.
+  */
   async invoke(name, input, ctx, policy) {
     const entry = this.entries.get(name);
     if (entry === void 0) {
       throw new ToolNotFoundError(name);
     }
+    if (!await isToolEnabled(entry.spec, entry.handler)) {
+      throw new ToolDisabledError(name);
+    }
     if (!await policy.can(ctx.actor, entry.spec)) {
       throw new ToolForbiddenError(name);
     }
+    if (!await canActorUseTool(ctx.actor, entry.handler)) {
+      throw new ToolForbiddenError(name);
+    }
     const validation = await entry.spec.inputSchema["~standard"].validate(input);
     if (validation.issues !== void 0) {
       throw new ToolInputInvalidError(name, validation.issues);
@@ -1213,6 +1272,7 @@ export {
   DefaultRolesPolicy,
   QuotaExceededError,
   THREAD_DETAIL_CONTENT_CHARS,
+  ToolDisabledError,
   ToolForbiddenError,
   ToolInputInvalidError,
   ToolNotFoundError,
@@ -1222,12 +1282,16 @@ export {
   bucketByModel,
   bucketByThread,
   bucketUsageTrend,
+  canActorUseTool,
   dayBoundsUtc,
   encodeStreamEvent,
   estimateCost,
   filterToolsByAllowList,
+  filterToolsByCanUse,
+  filterToolsByEnabled,
   filterToolsByRole,
   invokeWithTransientRetry,
+  isToolEnabled,
   isTransientToolError,
   publishAgentDelegated,
   publishAgentMessage,