@dudousxd/nestjs-agent-core 0.10.0 → 0.11.0

package/dist/index.d.cts

@@ -1044,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;
 }
@@ -1095,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
@@ -1113,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[]>;
     /**
@@ -1132,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>;
 }
 
 /**
@@ -1248,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. */
@@ -1597,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 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, 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.d.ts

@@ -1044,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;
 }
@@ -1095,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
@@ -1113,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[]>;
     /**
@@ -1132,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>;
 }
 
 /**
@@ -1248,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. */
@@ -1597,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 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, 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) {
@@ -1178,6 +1212,7 @@ export {
   DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS,
   DefaultRolesPolicy,
   QuotaExceededError,
+  THREAD_DETAIL_CONTENT_CHARS,
   ToolForbiddenError,
   ToolInputInvalidError,
   ToolNotFoundError,
@@ -1204,10 +1239,12 @@ export {
   publishAgentToolCall,
   publishAgentToolRetry,
   resolveToolTransientRetryNumbers,
+  rollupThreadUsage,
   runAgentLoop,
   seedModelPrices,
   traceLlmTurn,
   traceToolExecution,
+  truncateDetailContent,
   withToolTimeout
 };
 //# sourceMappingURL=index.js.map