@dudousxd/nestjs-agent-core 0.8.0 → 0.10.0

package/dist/index.d.cts

@@ -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;
 }
 
 /**
@@ -559,6 +636,12 @@ interface RecordToolCallInput {
     toolType: 'read' | 'action';
     input: unknown;
     status: ToolCallStatus;
+    /**
+     * The run (turn) this tool call belongs to — enables a governance surface to deep-link a tool
+     * call out to its trace waterfall. Optional so a caller predating this (or a store's own
+     * synthetic tool calls) can omit it; the store persists it as `null` when absent.
+     */
+    runId?: string;
 }
 interface UpdateToolCallInput {
     toolCallId: string;
@@ -879,6 +962,8 @@ interface ToolCallActivityRow {
     status: string;
     threadId: string;
     createdAt: string;
+    /** The run this call belongs to, for a trace deep-link; `null` for a call recorded before this shipped. */
+    runId: string | null;
 }
 /** A recent thread with rolled-up activity. */
 interface ThreadActivityRow {
@@ -949,6 +1034,8 @@ interface PendingApprovalRow {
     agentName: string | null;
     /** ISO timestamp. */
     requestedAt: string;
+    /** The run this call belongs to, for a trace deep-link; `null` for a call recorded before this shipped. */
+    runId: string | null;
 }
 /** Governance rollup for one tool over a range. */
 interface ToolStatRow {
@@ -1004,6 +1091,7 @@ interface RunWhere {
     agentName?: string;
     status?: string;
     errorCode?: string;
+    threadId?: string;
     fromDay?: string;
     toDay?: string;
 }
@@ -1255,6 +1343,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
@@ -1395,6 +1493,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;
@@ -1435,6 +1545,7 @@ declare module '@dudousxd/nestjs-diagnostics' {
             'run.failed': AgentRunFailed;
             delegated: AgentDelegated;
             retrieved: AgentRetrieved;
+            'tool.retry': AgentToolRetry;
             'llm.turn': AgentLlmTurnSpan;
             'tool.execution': AgentToolExecutionSpan;
             retrieval: AgentRetrievalSpan;
@@ -1450,6 +1561,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.
@@ -1463,7 +1575,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
@@ -1485,4 +1597,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 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 };

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;
 }
 
 /**
@@ -559,6 +636,12 @@ interface RecordToolCallInput {
     toolType: 'read' | 'action';
     input: unknown;
     status: ToolCallStatus;
+    /**
+     * The run (turn) this tool call belongs to — enables a governance surface to deep-link a tool
+     * call out to its trace waterfall. Optional so a caller predating this (or a store's own
+     * synthetic tool calls) can omit it; the store persists it as `null` when absent.
+     */
+    runId?: string;
 }
 interface UpdateToolCallInput {
     toolCallId: string;
@@ -879,6 +962,8 @@ interface ToolCallActivityRow {
     status: string;
     threadId: string;
     createdAt: string;
+    /** The run this call belongs to, for a trace deep-link; `null` for a call recorded before this shipped. */
+    runId: string | null;
 }
 /** A recent thread with rolled-up activity. */
 interface ThreadActivityRow {
@@ -949,6 +1034,8 @@ interface PendingApprovalRow {
     agentName: string | null;
     /** ISO timestamp. */
     requestedAt: string;
+    /** The run this call belongs to, for a trace deep-link; `null` for a call recorded before this shipped. */
+    runId: string | null;
 }
 /** Governance rollup for one tool over a range. */
 interface ToolStatRow {
@@ -1004,6 +1091,7 @@ interface RunWhere {
     agentName?: string;
     status?: string;
     errorCode?: string;
+    threadId?: string;
     fromDay?: string;
     toDay?: string;
 }
@@ -1255,6 +1343,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
@@ -1395,6 +1493,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;
@@ -1435,6 +1545,7 @@ declare module '@dudousxd/nestjs-diagnostics' {
             'run.failed': AgentRunFailed;
             delegated: AgentDelegated;
             retrieved: AgentRetrieved;
+            'tool.retry': AgentToolRetry;
             'llm.turn': AgentLlmTurnSpan;
             'tool.execution': AgentToolExecutionSpan;
             retrieval: AgentRetrievalSpan;
@@ -1450,6 +1561,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.
@@ -1463,7 +1575,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
@@ -1485,4 +1597,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 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 };

package/dist/index.js

@@ -363,6 +363,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 +381,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) {
@@ -785,7 +872,8 @@ ${buildContextBlock(passages)}`;
           input: {
             query: input.userText
           },
-          status: "auto_executed"
+          status: "auto_executed",
+          runId: hooks.runId
         });
         await deps.store.updateToolCall({
           toolCallId,
@@ -834,7 +922,8 @@ ${buildContextBlock(passages)}`;
           toolName: call.name,
           toolType: "read",
           input: call.input,
-          status: "auto_executed"
+          status: "auto_executed",
+          runId: hooks.runId
         }));
         const overDepth = (input.delegationDepth ?? 0) >= MAX_DELEGATION_DEPTH;
         publishAgentDelegated({
@@ -876,7 +965,8 @@ ${buildContextBlock(passages)}`;
           toolName: call.name,
           toolType: "action",
           input: call.input,
-          status: "pending_approval"
+          status: "pending_approval",
+          runId: hooks.runId
         }));
         const decision = await hooks.awaitApproval(call, ctx);
         deciderRef = decision.executedByRef ?? input.actor.id;
@@ -913,7 +1003,8 @@ ${buildContextBlock(passages)}`;
           toolName: call.name,
           toolType: "read",
           input: call.input,
-          status: "auto_executed"
+          status: "auto_executed",
+          runId: hooks.runId
         }));
       }
       const startedAt2 = Date.now();
@@ -938,7 +1029,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 {
@@ -946,7 +1040,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;
@@ -1068,6 +1174,8 @@ export {
   AGENT_TOOL_REGISTRY,
   AgentRegistry,
   AgentStreamError,
+  DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS,
+  DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS,
   DefaultRolesPolicy,
   QuotaExceededError,
   ToolForbiddenError,
@@ -1084,6 +1192,8 @@ export {
   estimateCost,
   filterToolsByAllowList,
   filterToolsByRole,
+  invokeWithTransientRetry,
+  isTransientToolError,
   publishAgentDelegated,
   publishAgentMessage,
   publishAgentQuotaExceeded,
@@ -1092,6 +1202,8 @@ export {
   publishAgentRunFinished,
   publishAgentRunStarted,
   publishAgentToolCall,
+  publishAgentToolRetry,
+  resolveToolTransientRetryNumbers,
   runAgentLoop,
   seedModelPrices,
   traceLlmTurn,