@dudousxd/nestjs-agent-core 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -1,6 +1,74 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { ChannelRegistry } from '@dudousxd/nestjs-diagnostics';
 
+/**
+ * Transient tool-error classification + the retry loop that wraps a tool's own invocation. A
+ * classified-transient error (a DB deadlock, a lock-wait timeout, a serialization failure) means
+ * the server rolled the tool's work back — retrying THAT class is safe, unlike a tool's general
+ * business failure, which stays a one-shot outcome (no durable step retries: a tool may not be
+ * idempotent). See `runAgentLoop`'s `tool:<call.id>` step body and `AgentRunSteps.tool` — both wrap
+ * `registry.invoke(...)` with {@link invokeWithTransientRetry} so a retry never becomes a new
+ * checkpoint; history still shows exactly one step per tool call.
+ */
+/**
+ * Default transient-tool-error classifier: true for a recognized MySQL/Postgres/SQLite
+ * lock-contention shape (by driver `code`/`errno`/`sqlState`, or a matching message), checked on
+ * the error itself and one level of `cause` (drivers commonly wrap the original error). A plain
+ * `Error` with none of these markers — any other business failure — is `false`.
+ */
+declare function isTransientToolError(error: unknown): boolean;
+/** Total attempts (initial try + retries) when `toolTransientRetry` doesn't set `attempts`. */
+declare const DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS = 2;
+/** Backoff base in ms — the wait between attempt N and N+1 is `backoffMs * N`. */
+declare const DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS = 150;
+/** The host-configurable half of the policy — everything except the (non-wire-safe) `classify` fn. */
+interface ToolTransientRetryOptions {
+    /** Total attempts (initial try + retries). Defaults to {@link DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS}. */
+    attempts?: number;
+    /** Backoff base in ms. Defaults to {@link DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS}. */
+    backoffMs?: number;
+    /** Overrides the default classifier — widen or narrow which errors are treated as transient. */
+    classify?: (error: unknown) => boolean;
+}
+/** `false` disables transient retry entirely — a tool's own thrown error surfaces immediately. */
+type ToolTransientRetrySetting = ToolTransientRetryOptions | false;
+/** Just the wire-safe (numeric) half of a resolved policy — what a dispatched envelope carries. */
+interface ToolTransientRetryNumbers {
+    attempts: number;
+    backoffMs: number;
+}
+/**
+ * Resolves the numeric half of `toolTransientRetry` for the dispatched wire envelope: `false` when
+ * explicitly disabled, else concrete `{ attempts, backoffMs }` (defaults filled in) — never
+ * `undefined`, so the dispatched handler always gets a definite answer instead of re-deriving its
+ * own default. The `classify` function never rides this — it isn't wire-safe; the dispatched
+ * handler resolves its own `classify` from its local module options (see `AgentRunSteps.tool`).
+ */
+declare function resolveToolTransientRetryNumbers(setting: ToolTransientRetrySetting | undefined): ToolTransientRetryNumbers | false;
+interface InvokeWithTransientRetryOptions {
+    /**
+     * Recognizes the runner's control-flow signals (durable suspend / continue-as-new) so a retry
+     * never swallows one — same rule the loop's tool catch already applies. Undefined for a call site
+     * with no such notion (e.g. the dispatched step handler, which has no workflow ctx of its own).
+     */
+    isControlFlowError?: (error: unknown) => boolean;
+    /**
+     * Called before each wait-and-retry, with the 1-based ordinal of the attempt that just failed and
+     * the error it threw. The call site uses this to emit the `tool.retry` diagnostics point event —
+     * `invokeWithTransientRetry` itself carries no tool identity (name/callId), only the thunk.
+     */
+    onRetry?: (attempt: number, error: unknown) => void;
+}
+/**
+ * Retries `fn` in place — never a new durable step/checkpoint, just repeated attempts inside
+ * whichever step body already wraps this call. `setting: false` runs `fn` once, unwrapped (no
+ * classify/backoff bookkeeping at all). Otherwise: try; on a thrown error, rethrow immediately if
+ * it's a recognized control-flow signal, else if the (possibly custom) classifier calls it
+ * transient AND attempts remain, wait `backoffMs * attemptNumber` and retry; otherwise rethrow the
+ * error as-is.
+ */
+declare function invokeWithTransientRetry<T>(fn: () => Promise<T>, setting: ToolTransientRetrySetting, options?: InvokeWithTransientRetryOptions): Promise<T>;
+
 /** Who is driving the turn. Roles + tenant come from the host app (nestjs-context/authz). */
 interface Actor {
     id: string;
@@ -312,6 +380,15 @@ interface ToolStepEnvelope {
     ctx: ToolStepCtx;
     /** Applied INSIDE the handler (`withToolTimeout`) — never as a durable step `timeoutMs`. */
     timeoutMs?: number;
+    /**
+     * The numeric half of `toolTransientRetry` (resolved by the loop from `AgentLoopDeps`, always a
+     * definite value — `false` when disabled, else concrete `{ attempts, backoffMs }` with defaults
+     * already filled in) — never `undefined`, so the dispatched handler gets the SAME policy the
+     * loop would have used locally. The `classify` function is deliberately absent: it isn't
+     * wire-safe, so the handler resolves its own from its local module options (see
+     * `AgentRunSteps.tool`) instead of trying to serialize a function.
+     */
+    transientRetry: ToolTransientRetryNumbers | false;
 }
 
 /**
@@ -967,6 +1044,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;
 }
@@ -1018,6 +1102,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
@@ -1036,8 +1229,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[]>;
     /**
@@ -1055,6 +1259,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>;
 }
 
 /**
@@ -1171,6 +1390,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. */
@@ -1266,6 +1491,16 @@ interface AgentLoopDeps {
      * Undefined → no timeout.
      */
     toolTimeoutMs?: number;
+    /**
+     * Retries a tool's own invocation, in place, when it throws a classified-transient error (a DB
+     * deadlock, a lock-wait timeout, a serialization failure — see `isTransientToolError`) — never a
+     * new durable step/checkpoint, just repeated attempts inside the same `tool:<call.id>` step body.
+     * Default ON (`{ attempts: 2, backoffMs: 150 }` with the default classifier) when undefined; set
+     * `{ classify }` to widen/narrow which errors count as transient, or `false` to disable entirely.
+     * A tool's other (non-transient) failures are unaffected — they remain a one-shot business
+     * outcome, exactly as before.
+     */
+    toolTransientRetry?: ToolTransientRetrySetting;
     /**
      * When set, after the final turn the loop makes one extra model call to propose up to this many
      * short follow-up questions, stored on the assistant message's `followUps`. Costs an extra call
@@ -1406,6 +1641,18 @@ interface AgentRetrieved {
     /** How many passages the retriever returned. */
     count: number;
 }
+/**
+ * A transient-classified tool error being retried in place (no new checkpoint) — see
+ * `invokeWithTransientRetry`. Emitted once per retry (not for the final, non-retried outcome).
+ */
+interface AgentToolRetry {
+    toolName: string;
+    toolCallId: string;
+    /** 1-based ordinal of the attempt that just failed and is about to be retried. */
+    attempt: number;
+    /** The failed attempt's error message. */
+    message: string;
+}
 /** START payload of an `aviary:agent:llm.turn:*` span — one model call within a run. */
 interface AgentLlmTurnSpan {
     runId: string;
@@ -1446,6 +1693,7 @@ declare module '@dudousxd/nestjs-diagnostics' {
             'run.failed': AgentRunFailed;
             delegated: AgentDelegated;
             retrieved: AgentRetrieved;
+            'tool.retry': AgentToolRetry;
             'llm.turn': AgentLlmTurnSpan;
             'tool.execution': AgentToolExecutionSpan;
             retrieval: AgentRetrievalSpan;
@@ -1461,6 +1709,7 @@ declare function publishAgentRunFinished(payload: AgentRunFinished): void;
 declare function publishAgentRunFailed(payload: AgentRunFailed): void;
 declare function publishAgentDelegated(payload: AgentDelegated): void;
 declare function publishAgentRetrieved(payload: AgentRetrieved): void;
+declare function publishAgentToolRetry(payload: AgentToolRetry): void;
 /**
  * Events published ONLY as spans — via `trace('agent', ...)` on the five `:start`/`:end`/
  * `:asyncStart`/`:asyncEnd`/`:error` sub-channels — never as point events on the base channel.
@@ -1474,7 +1723,7 @@ declare const AGENT_SPAN_EVENTS: readonly AgentSpanEvent[];
 /** Every POINT event key declared on `ChannelRegistry['agent']` above — derived, not hand-copied. */
 type AgentDiagnosticEvent = Exclude<keyof ChannelRegistry['agent'], AgentSpanEvent>;
 /**
- * All 8 point events on `ChannelRegistry['agent']`, in a stable order — handy for wiring
+ * All 9 point events on `ChannelRegistry['agent']`, in a stable order — handy for wiring
  * subscribers (mirrors nestjs-media's `MEDIA_DIAGNOSTIC_EVENTS`). Span-only events (see
  * {@link AgentSpanEvent}) are excluded. A drift between this list and the registry is a compile
  * error in both directions: an extra/misspelled entry fails this array's own
@@ -1496,4 +1745,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 AiToolCtx, type AppendMessageInput, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceUsageInput, 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 UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, agentDiagnosticKey, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, 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, 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 };

package/dist/index.js

@@ -52,6 +52,22 @@ async function seedModelPrices(store, prices) {
 }
 __name(seedModelPrices, "seedModelPrices");
 
+// src/spi/governance-queries.ts
+var THREAD_DETAIL_CONTENT_CHARS = 2e3;
+function truncateDetailContent(content) {
+  if (content.length <= THREAD_DETAIL_CONTENT_CHARS) {
+    return {
+      content,
+      truncated: false
+    };
+  }
+  return {
+    content: content.slice(0, THREAD_DETAIL_CONTENT_CHARS),
+    truncated: true
+  };
+}
+__name(truncateDetailContent, "truncateDetailContent");
+
 // src/governance/compute.ts
 function estimateCost(usage, price) {
   if (price === void 0) {
@@ -157,6 +173,24 @@ function bucketByThread(rows, prices, threads, options) {
   return result.slice(0, options.limit);
 }
 __name(bucketByThread, "bucketByThread");
+function rollupThreadUsage(rows, prices) {
+  const rollup = {
+    requests: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    costUsd: 0
+  };
+  for (const row of rows) {
+    rollup.requests += 1;
+    rollup.inputTokens += row.inputTokens;
+    rollup.outputTokens += row.outputTokens;
+    rollup.totalTokens += row.inputTokens + row.outputTokens;
+    rollup.costUsd += rowCost(row, prices);
+  }
+  return rollup;
+}
+__name(rollupThreadUsage, "rollupThreadUsage");
 function bucketUsageTrend(rows, prices) {
   const byDay = /* @__PURE__ */ new Map();
   for (const row of rows) {
@@ -363,6 +397,10 @@ function publishAgentRetrieved(payload) {
   emit("agent", "retrieved", payload);
 }
 __name(publishAgentRetrieved, "publishAgentRetrieved");
+function publishAgentToolRetry(payload) {
+  emit("agent", "tool.retry", payload);
+}
+__name(publishAgentToolRetry, "publishAgentToolRetry");
 var AGENT_SPAN_EVENTS = [
   "llm.turn",
   "tool.execution",
@@ -377,13 +415,96 @@ var AGENT_DIAGNOSTIC_EVENTS = [
   "run.finished",
   "run.failed",
   "delegated",
-  "retrieved"
+  "retrieved",
+  "tool.retry"
 ];
 function agentDiagnosticKey(event) {
   return `agent:${event}`;
 }
 __name(agentDiagnosticKey, "agentDiagnosticKey");
 
+// src/tool-retry.ts
+function hasTransientShape(error) {
+  if (typeof error !== "object" || error === null) {
+    return false;
+  }
+  const code = "code" in error ? error.code : void 0;
+  const errno = "errno" in error ? error.errno : void 0;
+  const sqlState = "sqlState" in error ? error.sqlState : void 0;
+  if (code === 1213 || code === 1205 || errno === 1213 || errno === 1205) {
+    return true;
+  }
+  if (code === "ER_LOCK_DEADLOCK" || code === "ER_LOCK_WAIT_TIMEOUT") {
+    return true;
+  }
+  if (code === "40001" || code === "40P01" || sqlState === "40001" || sqlState === "40P01") {
+    return true;
+  }
+  if (code === "SQLITE_BUSY") {
+    return true;
+  }
+  const message = "message" in error ? error.message : void 0;
+  return typeof message === "string" && /deadlock|lock wait timeout|serialization failure/i.test(message);
+}
+__name(hasTransientShape, "hasTransientShape");
+function isTransientToolError(error) {
+  if (hasTransientShape(error)) {
+    return true;
+  }
+  if (typeof error === "object" && error !== null && "cause" in error) {
+    const cause = error.cause;
+    if (cause !== void 0 && cause !== error && hasTransientShape(cause)) {
+      return true;
+    }
+  }
+  return false;
+}
+__name(isTransientToolError, "isTransientToolError");
+var DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS = 2;
+var DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS = 150;
+function resolveToolTransientRetryNumbers(setting) {
+  if (setting === false) {
+    return false;
+  }
+  return {
+    attempts: setting?.attempts ?? DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS,
+    backoffMs: setting?.backoffMs ?? DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS
+  };
+}
+__name(resolveToolTransientRetryNumbers, "resolveToolTransientRetryNumbers");
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+__name(delay, "delay");
+async function invokeWithTransientRetry(fn, setting, options) {
+  if (setting === false) {
+    return fn();
+  }
+  const attempts = setting.attempts ?? DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS;
+  const backoffMs = setting.backoffMs ?? DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS;
+  const classify = setting.classify ?? isTransientToolError;
+  let attempt = 1;
+  for (; ; ) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (options?.isControlFlowError?.(error) === true) {
+        throw error;
+      }
+      const attemptsRemain = attempt < attempts;
+      if (!attemptsRemain || !classify(error)) {
+        throw error;
+      }
+      options?.onRetry?.(attempt, error);
+      await delay(backoffMs * attempt);
+      attempt += 1;
+    }
+  }
+}
+__name(invokeWithTransientRetry, "invokeWithTransientRetry");
+
 // src/agent-loop.ts
 function resolveCostUsd(usage, reportedCostUsd, price) {
   if (reportedCostUsd !== void 0) {
@@ -942,7 +1063,10 @@ ${buildContextBlock(passages)}`;
             ctx: stepCtx,
             ...deps.toolTimeoutMs !== void 0 ? {
               timeoutMs: deps.toolTimeoutMs
-            } : {}
+            } : {},
+            // Numeric-only: the handler applies withToolTimeout AND its own local `classify` — see
+            // ToolStepEnvelope.transientRetry.
+            transientRetry: resolveToolTransientRetryNumbers(deps.toolTransientRetry)
           };
           output = await hooks.dispatchTool(call, envelope);
         } else {
@@ -950,7 +1074,19 @@ ${buildContextBlock(passages)}`;
             toolCallId: call.id,
             toolName: call.name,
             toolType
-          }, () => deps.registry.invoke(call.name, call.input, ctx, deps.rolesPolicy)));
+          }, () => invokeWithTransientRetry(() => deps.registry.invoke(call.name, call.input, ctx, deps.rolesPolicy), deps.toolTransientRetry ?? {}, {
+            ...hooks.isControlFlowError !== void 0 ? {
+              isControlFlowError: hooks.isControlFlowError
+            } : {},
+            onRetry: /* @__PURE__ */ __name((attempt, retryError) => {
+              publishAgentToolRetry({
+                toolName: call.name,
+                toolCallId: call.id,
+                attempt,
+                message: retryError instanceof Error ? retryError.message : String(retryError)
+              });
+            }, "onRetry")
+          })));
           output = deps.toolTimeoutMs !== void 0 ? await withToolTimeout(invocation, deps.toolTimeoutMs, call.name) : await invocation;
         }
         const executionMs = Date.now() - startedAt2;
@@ -1072,8 +1208,11 @@ export {
   AGENT_TOOL_REGISTRY,
   AgentRegistry,
   AgentStreamError,
+  DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS,
+  DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS,
   DefaultRolesPolicy,
   QuotaExceededError,
+  THREAD_DETAIL_CONTENT_CHARS,
   ToolForbiddenError,
   ToolInputInvalidError,
   ToolNotFoundError,
@@ -1088,6 +1227,8 @@ export {
   estimateCost,
   filterToolsByAllowList,
   filterToolsByRole,
+  invokeWithTransientRetry,
+  isTransientToolError,
   publishAgentDelegated,
   publishAgentMessage,
   publishAgentQuotaExceeded,
@@ -1096,10 +1237,14 @@ export {
   publishAgentRunFinished,
   publishAgentRunStarted,
   publishAgentToolCall,
+  publishAgentToolRetry,
+  resolveToolTransientRetryNumbers,
+  rollupThreadUsage,
   runAgentLoop,
   seedModelPrices,
   traceLlmTurn,
   traceToolExecution,
+  truncateDetailContent,
   withToolTimeout
 };
 //# sourceMappingURL=index.js.map