@dudousxd/nestjs-agent-core 0.10.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>;
 }
 
 /**
@@ -1044,6 +1081,13 @@ interface ToolStatRow {
     calls: number;
     failed: number;
     rejected: number;
+    /**
+     * p50 (median) of executionMs across calls that recorded one; null when none carry it. Reported
+     * alongside p95 rather than a mean: tool latency is long-tailed (a retry or a slow upstream drags
+     * an average somewhere no single call ever was), so the pair "typical / tail" is what an operator
+     * can actually act on.
+     */
+    p50ExecutionMs: number | null;
     /** p95 of executionMs across executed calls; null when none carry it. */
     p95ExecutionMs: number | null;
 }
@@ -1095,6 +1139,115 @@ interface RunWhere {
     fromDay?: string;
     toDay?: string;
 }
+/** Filters for {@link AgentGovernanceQueries.approvalsPage}. */
+interface ApprovalWhere {
+    toolName?: string;
+    threadId?: string;
+    /** The requesting thread's owner. */
+    actorRef?: string;
+    agentName?: string;
+    /** Inclusive UTC day bounds on when the approval was requested, `YYYY-MM-DD`. */
+    fromDay?: string;
+    toDay?: string;
+}
+/** One tool call inside a {@link GovernanceRunDetail}, with the execution outcome a list row can't afford to carry. */
+interface RunToolCallRow {
+    toolCallId: string;
+    toolName: string;
+    toolType: string;
+    status: string;
+    /** Wall time of the execution; null for a call that never executed (rejected/still pending). */
+    executionMs: number | null;
+    /** Who executed/decided it, when the store recorded an attribution. */
+    executedByRef: string | null;
+    /** The failure text for a `failed` call; null otherwise. */
+    error: string | null;
+    /** ISO timestamp. */
+    createdAt: string;
+}
+/** The owning thread's headline, carried on a drill-down so it can be named without a second read. */
+interface DetailThreadRef {
+    threadId: string;
+    title: string;
+    actorRef: string;
+    /** True when the thread is soft-deleted — its history is still readable, the thread is not. */
+    deleted: boolean;
+}
+/**
+ * Everything a run drill-down renders: the run row itself, its owning thread's headline, and the
+ * tool calls attributed to it.
+ *
+ * `toolCalls` is empty for a run recorded before tool calls carried a `runId` (the column is
+ * nullable and pre-rollout rows have none) — indistinguishable, from here, from a run that called
+ * no tools. There is deliberately no cost figure: the token ledger has no run column, so per-run
+ * spend is not attributable without a store migration.
+ */
+interface GovernanceRunDetail {
+    run: RecentRunRow;
+    thread: DetailThreadRef;
+    /** The run's tool calls, oldest first — the order they were requested in. */
+    toolCalls: RunToolCallRow[];
+}
+/** One message inside a {@link GovernanceThreadDetail}. `content` is capped server-side. */
+interface ThreadMessageRow {
+    messageId: string;
+    role: string;
+    /** Message text, cut to {@link THREAD_DETAIL_CONTENT_CHARS}; see `truncated`. */
+    content: string;
+    /** True when `content` was cut — the console shows an explicit "…" rather than implying the tail. */
+    truncated: boolean;
+    agentName: string | null;
+    /** How many tool calls this message requested. */
+    toolCallCount: number;
+    /** ISO timestamp. */
+    createdAt: string;
+}
+/** Token/cost rollup across a thread's whole ledger (not range-scoped — a thread's lifetime). */
+interface ThreadUsageRollup {
+    /** Ledger rows, i.e. billed turns. */
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    costUsd: number;
+}
+/** Everything a thread drill-down renders, in one call. */
+interface GovernanceThreadDetail {
+    /** The thread's own activity row (`messageCount` is the thread total, not the page below). */
+    thread: ThreadActivityRow;
+    /** True when the thread is soft-deleted. */
+    deleted: boolean;
+    usage: ThreadUsageRollup;
+    /** The thread's runs, newest first, capped at the query's `runLimit`. */
+    runs: RecentRunRow[];
+    /** Runs on this thread in total — `runs.length < runTotal` means the cap bit. */
+    runTotal: number;
+    /** The thread's messages, newest first, capped at the query's `messageLimit`. */
+    messages: ThreadMessageRow[];
+}
+/** Row caps for {@link AgentGovernanceQueries.threadDetail}, already clamped by the caller. */
+interface GovernanceThreadDetailQuery {
+    threadId: string;
+    /** Max messages returned, newest first. */
+    messageLimit: number;
+    /** Max runs returned, newest first. */
+    runLimit: number;
+}
+/**
+ * Per-message content cap for {@link ThreadMessageRow.content}. A drill-down is a triage view, not a
+ * transcript reader: capping here keeps one response bounded regardless of how long an assistant
+ * turn ran. Shared by every adapter so the cut is identical wherever the console is served from.
+ */
+declare const THREAD_DETAIL_CONTENT_CHARS = 2000;
+/**
+ * Cut a message body to {@link THREAD_DETAIL_CONTENT_CHARS}, reporting whether it was cut. Lives
+ * next to the cap so every adapter truncates at the same boundary — a console comparing two stores
+ * must not see two different "…".
+ */
+declare function truncateDetailContent(content: string): {
+    content: string;
+    truncated: boolean;
+};
 /**
  * The governance read-model. Cost is `inputTokens/1e6 * inputPricePer1m + outputTokens/1e6 *
  * outputPricePer1m` against the current pricing row per model; an unpriced model contributes 0 cost
@@ -1113,8 +1266,19 @@ interface AgentGovernanceQueries {
     runErrors(range: GovernanceRange): Promise<RunErrorBreakdownRow[]>;
     runTrend(range: GovernanceRange): Promise<RunTrendPoint[]>;
     recentRuns(limit: number): Promise<RecentRunRow[]>;
-    /** Tool calls sitting `pending_approval`, oldest first — an inbox drains from the back. Capped at `limit`. */
+    /**
+     * Tool calls sitting `pending_approval`, oldest first — an inbox drains from the back. Capped at
+     * `limit`, with NO total: a caller that needs to know whether the cap hid anything wants
+     * {@link approvalsPage} instead.
+     */
     pendingApprovals(limit: number): Promise<PendingApprovalRow[]>;
+    /**
+     * Paged, filterable approvals inbox, oldest first (same ordering as `pendingApprovals`). Unlike
+     * that method this reports `total`, so a console can page a backlog and say how much of it is
+     * off-screen — the one failure this surface cannot afford is a pending approval nobody sees.
+     * An adapter without the backing data returns an empty page (`total: 0`) rather than throwing.
+     */
+    approvalsPage(query: GovernancePageQuery<ApprovalWhere>): Promise<GovernancePage<PendingApprovalRow>>;
     /** Per-tool call/failure/rejection/latency rollup over the range, highest call count first. */
     toolStats(range: GovernanceRange): Promise<ToolStatRow[]>;
     /**
@@ -1132,6 +1296,21 @@ interface AgentGovernanceQueries {
      * by a store without run recording (no `recordRunStart`) returns an empty page (`total: 0`).
      */
     runsPage(query: GovernancePageQuery<RunWhere>): Promise<GovernancePage<RecentRunRow>>;
+    /**
+     * One run with its owning thread and its tool calls — the drill-down behind a row in the runs
+     * table. `null` when no run has that id. ONE call, not one per tool call: a failed run is the
+     * thing an operator opens first and it should not cost a query per step.
+     *
+     * An adapter backed by a store without run recording returns `null` for every id.
+     */
+    runDetail(runId: string): Promise<GovernanceRunDetail | null>;
+    /**
+     * One thread with its lifetime usage rollup, its recent runs and its recent messages — the
+     * drill-down behind a row in the threads table. `null` when no thread has that id; a soft-deleted
+     * thread IS returned (with `deleted: true`), because "what did the thread we just deleted do" is
+     * exactly the question an audit asks.
+     */
+    threadDetail(query: GovernanceThreadDetailQuery): Promise<GovernanceThreadDetail | null>;
 }
 
 /**
@@ -1248,6 +1427,12 @@ declare function bucketByThread(rows: GovernanceUsageInput[], prices: ReadonlyMa
     limit: number;
     includeUnknownThreads: boolean;
 }): ThreadSpendRow[];
+/**
+ * Sum an already-scoped set of usage rows into one rollup — the thread drill-down's headline. Same
+ * `rowCost` as every bucketer above (provider-reported cost wins, else the cache-aware estimate), so
+ * a thread's detail cost and its row in the by-thread ranking can never disagree.
+ */
+declare function rollupThreadUsage(rows: GovernanceUsageInput[], prices: ReadonlyMap<string, ModelPrice>): ThreadUsageRollup;
 /** Aggregate usage rows into a daily token/cost trend, ascending by day. */
 declare function bucketUsageTrend(rows: GovernanceUsageInput[], prices: ReadonlyMap<string, ModelPrice>): UsageTrendPoint[];
 /** Turn an inclusive `YYYY-MM-DD` day range into the UTC datetime bounds used to filter usage rows. */
@@ -1256,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. */
@@ -1275,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;
@@ -1299,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). */
@@ -1597,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 AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernancePage, type GovernancePageQuery, type GovernanceRange, 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 RunTrendPoint, type RunWhere, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, 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, runAgentLoop, seedModelPrices, traceLlmTurn, traceToolExecution, 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>;
 }
 
 /**
@@ -1044,6 +1081,13 @@ interface ToolStatRow {
     calls: number;
     failed: number;
     rejected: number;
+    /**
+     * p50 (median) of executionMs across calls that recorded one; null when none carry it. Reported
+     * alongside p95 rather than a mean: tool latency is long-tailed (a retry or a slow upstream drags
+     * an average somewhere no single call ever was), so the pair "typical / tail" is what an operator
+     * can actually act on.
+     */
+    p50ExecutionMs: number | null;
     /** p95 of executionMs across executed calls; null when none carry it. */
     p95ExecutionMs: number | null;
 }
@@ -1095,6 +1139,115 @@ interface RunWhere {
     fromDay?: string;
     toDay?: string;
 }
+/** Filters for {@link AgentGovernanceQueries.approvalsPage}. */
+interface ApprovalWhere {
+    toolName?: string;
+    threadId?: string;
+    /** The requesting thread's owner. */
+    actorRef?: string;
+    agentName?: string;
+    /** Inclusive UTC day bounds on when the approval was requested, `YYYY-MM-DD`. */
+    fromDay?: string;
+    toDay?: string;
+}
+/** One tool call inside a {@link GovernanceRunDetail}, with the execution outcome a list row can't afford to carry. */
+interface RunToolCallRow {
+    toolCallId: string;
+    toolName: string;
+    toolType: string;
+    status: string;
+    /** Wall time of the execution; null for a call that never executed (rejected/still pending). */
+    executionMs: number | null;
+    /** Who executed/decided it, when the store recorded an attribution. */
+    executedByRef: string | null;
+    /** The failure text for a `failed` call; null otherwise. */
+    error: string | null;
+    /** ISO timestamp. */
+    createdAt: string;
+}
+/** The owning thread's headline, carried on a drill-down so it can be named without a second read. */
+interface DetailThreadRef {
+    threadId: string;
+    title: string;
+    actorRef: string;
+    /** True when the thread is soft-deleted — its history is still readable, the thread is not. */
+    deleted: boolean;
+}
+/**
+ * Everything a run drill-down renders: the run row itself, its owning thread's headline, and the
+ * tool calls attributed to it.
+ *
+ * `toolCalls` is empty for a run recorded before tool calls carried a `runId` (the column is
+ * nullable and pre-rollout rows have none) — indistinguishable, from here, from a run that called
+ * no tools. There is deliberately no cost figure: the token ledger has no run column, so per-run
+ * spend is not attributable without a store migration.
+ */
+interface GovernanceRunDetail {
+    run: RecentRunRow;
+    thread: DetailThreadRef;
+    /** The run's tool calls, oldest first — the order they were requested in. */
+    toolCalls: RunToolCallRow[];
+}
+/** One message inside a {@link GovernanceThreadDetail}. `content` is capped server-side. */
+interface ThreadMessageRow {
+    messageId: string;
+    role: string;
+    /** Message text, cut to {@link THREAD_DETAIL_CONTENT_CHARS}; see `truncated`. */
+    content: string;
+    /** True when `content` was cut — the console shows an explicit "…" rather than implying the tail. */
+    truncated: boolean;
+    agentName: string | null;
+    /** How many tool calls this message requested. */
+    toolCallCount: number;
+    /** ISO timestamp. */
+    createdAt: string;
+}
+/** Token/cost rollup across a thread's whole ledger (not range-scoped — a thread's lifetime). */
+interface ThreadUsageRollup {
+    /** Ledger rows, i.e. billed turns. */
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    costUsd: number;
+}
+/** Everything a thread drill-down renders, in one call. */
+interface GovernanceThreadDetail {
+    /** The thread's own activity row (`messageCount` is the thread total, not the page below). */
+    thread: ThreadActivityRow;
+    /** True when the thread is soft-deleted. */
+    deleted: boolean;
+    usage: ThreadUsageRollup;
+    /** The thread's runs, newest first, capped at the query's `runLimit`. */
+    runs: RecentRunRow[];
+    /** Runs on this thread in total — `runs.length < runTotal` means the cap bit. */
+    runTotal: number;
+    /** The thread's messages, newest first, capped at the query's `messageLimit`. */
+    messages: ThreadMessageRow[];
+}
+/** Row caps for {@link AgentGovernanceQueries.threadDetail}, already clamped by the caller. */
+interface GovernanceThreadDetailQuery {
+    threadId: string;
+    /** Max messages returned, newest first. */
+    messageLimit: number;
+    /** Max runs returned, newest first. */
+    runLimit: number;
+}
+/**
+ * Per-message content cap for {@link ThreadMessageRow.content}. A drill-down is a triage view, not a
+ * transcript reader: capping here keeps one response bounded regardless of how long an assistant
+ * turn ran. Shared by every adapter so the cut is identical wherever the console is served from.
+ */
+declare const THREAD_DETAIL_CONTENT_CHARS = 2000;
+/**
+ * Cut a message body to {@link THREAD_DETAIL_CONTENT_CHARS}, reporting whether it was cut. Lives
+ * next to the cap so every adapter truncates at the same boundary — a console comparing two stores
+ * must not see two different "…".
+ */
+declare function truncateDetailContent(content: string): {
+    content: string;
+    truncated: boolean;
+};
 /**
  * The governance read-model. Cost is `inputTokens/1e6 * inputPricePer1m + outputTokens/1e6 *
  * outputPricePer1m` against the current pricing row per model; an unpriced model contributes 0 cost
@@ -1113,8 +1266,19 @@ interface AgentGovernanceQueries {
     runErrors(range: GovernanceRange): Promise<RunErrorBreakdownRow[]>;
     runTrend(range: GovernanceRange): Promise<RunTrendPoint[]>;
     recentRuns(limit: number): Promise<RecentRunRow[]>;
-    /** Tool calls sitting `pending_approval`, oldest first — an inbox drains from the back. Capped at `limit`. */
+    /**
+     * Tool calls sitting `pending_approval`, oldest first — an inbox drains from the back. Capped at
+     * `limit`, with NO total: a caller that needs to know whether the cap hid anything wants
+     * {@link approvalsPage} instead.
+     */
     pendingApprovals(limit: number): Promise<PendingApprovalRow[]>;
+    /**
+     * Paged, filterable approvals inbox, oldest first (same ordering as `pendingApprovals`). Unlike
+     * that method this reports `total`, so a console can page a backlog and say how much of it is
+     * off-screen — the one failure this surface cannot afford is a pending approval nobody sees.
+     * An adapter without the backing data returns an empty page (`total: 0`) rather than throwing.
+     */
+    approvalsPage(query: GovernancePageQuery<ApprovalWhere>): Promise<GovernancePage<PendingApprovalRow>>;
     /** Per-tool call/failure/rejection/latency rollup over the range, highest call count first. */
     toolStats(range: GovernanceRange): Promise<ToolStatRow[]>;
     /**
@@ -1132,6 +1296,21 @@ interface AgentGovernanceQueries {
      * by a store without run recording (no `recordRunStart`) returns an empty page (`total: 0`).
      */
     runsPage(query: GovernancePageQuery<RunWhere>): Promise<GovernancePage<RecentRunRow>>;
+    /**
+     * One run with its owning thread and its tool calls — the drill-down behind a row in the runs
+     * table. `null` when no run has that id. ONE call, not one per tool call: a failed run is the
+     * thing an operator opens first and it should not cost a query per step.
+     *
+     * An adapter backed by a store without run recording returns `null` for every id.
+     */
+    runDetail(runId: string): Promise<GovernanceRunDetail | null>;
+    /**
+     * One thread with its lifetime usage rollup, its recent runs and its recent messages — the
+     * drill-down behind a row in the threads table. `null` when no thread has that id; a soft-deleted
+     * thread IS returned (with `deleted: true`), because "what did the thread we just deleted do" is
+     * exactly the question an audit asks.
+     */
+    threadDetail(query: GovernanceThreadDetailQuery): Promise<GovernanceThreadDetail | null>;
 }
 
 /**
@@ -1248,6 +1427,12 @@ declare function bucketByThread(rows: GovernanceUsageInput[], prices: ReadonlyMa
     limit: number;
     includeUnknownThreads: boolean;
 }): ThreadSpendRow[];
+/**
+ * Sum an already-scoped set of usage rows into one rollup — the thread drill-down's headline. Same
+ * `rowCost` as every bucketer above (provider-reported cost wins, else the cache-aware estimate), so
+ * a thread's detail cost and its row in the by-thread ranking can never disagree.
+ */
+declare function rollupThreadUsage(rows: GovernanceUsageInput[], prices: ReadonlyMap<string, ModelPrice>): ThreadUsageRollup;
 /** Aggregate usage rows into a daily token/cost trend, ascending by day. */
 declare function bucketUsageTrend(rows: GovernanceUsageInput[], prices: ReadonlyMap<string, ModelPrice>): UsageTrendPoint[];
 /** Turn an inclusive `YYYY-MM-DD` day range into the UTC datetime bounds used to filter usage rows. */
@@ -1256,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. */
@@ -1275,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;
@@ -1299,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). */
@@ -1597,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 AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernancePage, type GovernancePageQuery, type GovernanceRange, 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 RunTrendPoint, type RunWhere, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, 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, runAgentLoop, seedModelPrices, traceLlmTurn, traceToolExecution, 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 };