@dudousxd/nestjs-agent-core 0.3.1 → 0.3.3

package/dist/index.d.cts

@@ -107,12 +107,30 @@ interface Decision {
     reason?: string;
 }
 type MessageRole = 'user' | 'assistant' | 'system';
+/**
+ * A file a user attached to a message so a vision-capable model sees it natively (an image, a PDF).
+ * The lib stays provider-agnostic: it passes {@link MessageAttachment.url} straight through as the
+ * model's image/file part data — making that URL reachable by the provider (presigned S3, a proxy)
+ * is the consumer's job. The lib never fetches bytes or talks to a store.
+ */
+interface MessageAttachment {
+    /** Stable id of the stored media object in the consumer's media store. Provenance + replay key. */
+    mediaId: string;
+    /** A URL the model provider can fetch the bytes from at turn time. */
+    url: string;
+    /** MIME type — routes the part: `image/*` → image part, otherwise → file part. */
+    contentType: string;
+    /** Original filename, for display and the file part's filename. */
+    name: string;
+}
 /** A neutral chat message exchanged with the model. */
 interface ModelMessage {
     role: MessageRole;
     content: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
+    /** User-message attachments (image/PDF), rendered as native model content parts by the adapter. */
+    attachments?: MessageAttachment[];
 }
 interface PageContext {
     kind?: string;
@@ -148,6 +166,8 @@ interface AgentRunInput {
     actor: Actor;
     /** The latest user message text. */
     userText: string;
+    /** Files attached to the latest user message (image/PDF). Persisted with it and sent to the model. */
+    attachments?: MessageAttachment[];
     pageContext?: PageContext;
     /** YYYY-MM-DD stamped by the runner so quota/day stays deterministic under durable replay. */
     day?: string;
@@ -181,6 +201,8 @@ interface AgentRunInput {
  */
 interface AgentDefinition {
     name: string;
+    /** Human-readable summary from `@Agent({ description })`. Surfaced by the `GET agents` catalog. */
+    description?: string;
     /** Base prompt for this agent. A flat string, or a {@link PromptBuilder} resolved per turn. */
     systemPrompt?: string | PromptBuilder;
     /** Allow-list of tool names this agent may use (subset of all registered tools). */
@@ -190,6 +212,16 @@ interface AgentDefinition {
     modelId?: string;
     maxSteps?: number;
 }
+/**
+ * The read-model the `GET agents` endpoint returns to a client — the safe public subset of an
+ * {@link AgentDefinition} so a host can render a persona picker instead of hardcoding one.
+ */
+interface AgentCatalogEntry {
+    name: string;
+    description: string;
+    /** Whether this is the agent a turn uses when the caller names none. Omitted when not the default. */
+    isDefault?: boolean;
+}
 interface ThreadSummary {
     id: string;
     title: string;
@@ -206,6 +238,8 @@ interface StoredMessage {
     agentName?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
+    /** Files the user attached to this message (image/PDF). Persisted with the message, replayed as-is. */
+    attachments?: MessageAttachment[];
     followUps?: string[];
     usage?: MessageUsage;
     createdAt: string;
@@ -359,6 +393,54 @@ interface ModelProvider {
     runTurn(args: ModelTurnArgs): Promise<ModelTurnResult>;
 }
 
+/**
+ * The structured live-stream vocabulary carried over the {@link SinkWriter} byte channel.
+ *
+ * The model turn (via the AI-SDK adapter) and the agent loop write these events as NDJSON — one
+ * `JSON.stringify(event)\n` per {@link SinkWriter.write}. The HTTP layer forwards each line as an
+ * SSE `data:` frame, and the client transport maps them back to the AI SDK UI-message chunk
+ * protocol so the browser renders text, reasoning, and tool cards (input + output) LIVE — the same
+ * rich rendering a raw `streamText().toUIMessageStream()` would give, but reconstructed on the
+ * client so the sink stays a format-agnostic byte buffer (durable buffering/replay is untouched).
+ *
+ * Keeping this vocabulary neutral (not AI-SDK `UIMessageChunk`) means core never depends on `ai`:
+ * the adapter owns model-parts → event, the transport owns event → UI-chunk.
+ */
+type AgentStreamEvent = {
+    kind: 'step-start';
+} | {
+    kind: 'step-finish';
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'reasoning';
+    text: string;
+} | {
+    kind: 'tool-input-start';
+    id: string;
+    name: string;
+} | {
+    kind: 'tool-input-delta';
+    id: string;
+    delta: string;
+} | {
+    kind: 'tool-input-available';
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    kind: 'tool-output';
+    id: string;
+    output: unknown;
+} | {
+    kind: 'tool-output-error';
+    id: string;
+    error: string;
+};
+/** Encode one event as an NDJSON line (`{...}\n`) for {@link SinkWriter.write}. */
+declare function encodeStreamEvent(event: AgentStreamEvent): Uint8Array;
+
 interface CreateThreadInput {
     actor: Actor;
     transient?: boolean;
@@ -372,6 +454,8 @@ interface AppendMessageInput {
     agentName?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
+    /** Files the user attached to this message (image/PDF). Persisted verbatim. */
+    attachments?: MessageAttachment[];
     followUps?: string[];
     usage?: MessageUsage;
 }
@@ -592,11 +676,12 @@ interface AgentRunner {
  * an identity is never invented from a default. See `HeaderActorResolver` for a header-based
  * resolver suitable for demos and gateways that strip/re-set the headers.
  *
- * `req` is the transport request object, typed `unknown` to keep core framework-agnostic;
- * a NestJS/Express app receives the express `Request`.
+ * `req` is the transport request object. Defaults to `unknown` to keep core framework-agnostic
+ * (a NestJS/Express app receives the express `Request`) — a host may narrow it via
+ * `ActorResolver<Request>` instead of writing its own `unknown`-narrowing type guard.
  */
-interface ActorResolver {
-    resolve(req: unknown): Actor | Promise<Actor>;
+interface ActorResolver<TReq = unknown> {
+    resolve(req: TReq): Actor | Promise<Actor>;
 }
 
 /**
@@ -682,6 +767,74 @@ interface AgentGovernanceQueries {
     recentThreads(limit: number): Promise<ThreadActivityRow[]>;
 }
 
+/**
+ * The pure aggregation core shared by every {@link import('../spi/governance-queries.js').AgentGovernanceQueries}
+ * adapter (MikroORM, Drizzle, in-memory). An adapter's only job is the DB-specific row fetch; the
+ * cost formula, the group→sort bucketing, and the day-bounds math live here so all three surfaces
+ * report identical numbers.
+ */
+/** The current per-1M token prices for one model; cache rates fall back to the input rate. */
+interface ModelPrice {
+    inputPricePer1m: number;
+    outputPricePer1m: number;
+    cacheWritePricePer1m?: number | null;
+    cacheReadPricePer1m?: number | null;
+}
+/** The token split of one turn needed to estimate its cost. */
+interface CostUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheWriteTokens?: number | null | undefined;
+    cacheReadTokens?: number | null | undefined;
+}
+/**
+ * A normalized usage row the bucketers consume. Each adapter maps its raw DB row into this shape
+ * (MikroORM reads `thread.id` + `createdAt`, Drizzle/in-memory read the flat `threadId` + `day`).
+ */
+interface GovernanceUsageInput extends CostUsage {
+    modelId: string;
+    actorRef: string;
+    threadId: string;
+    /** The `YYYY-MM-DD` UTC day the row belongs to (its trend bucket). */
+    day: string;
+    /** Provider-reported spend for the row; wins over the token estimate when present. */
+    costUsd?: number | null | undefined;
+}
+/** Thread metadata joined onto a spend bucket. */
+interface ThreadMeta {
+    title: string;
+    actorRef: string;
+}
+/**
+ * Token-ledger estimate for one turn against a pricing row: the uncached input at the input rate,
+ * cache-write/cache-read tokens at their own rates (falling back to the input rate when unpriced),
+ * plus output at the output rate. An unpriced model (`price === undefined`) contributes 0 — its
+ * tokens still count. Cache token counts are subsets of `inputTokens`, so the uncached remainder is
+ * the difference.
+ */
+declare function estimateCost(usage: CostUsage, price: ModelPrice | undefined): number;
+/** Aggregate usage rows into per-model spend, highest cost first then modelId ascending. */
+declare function bucketByModel(rows: GovernanceUsageInput[], prices: ReadonlyMap<string, ModelPrice>): ModelSpendRow[];
+/** Aggregate usage rows into per-actor spend (with distinct thread counts), highest cost first. */
+declare function bucketByActor(rows: GovernanceUsageInput[], prices: ReadonlyMap<string, ModelPrice>): ActorSpendRow[];
+/**
+ * Aggregate usage rows into per-thread spend, highest cost first then threadId ascending, capped at
+ * `limit`. A thread absent from `threads` is dropped when `includeUnknownThreads` is false (the SQL
+ * adapters fetch only non-deleted threads, so a soft-deleted thread's rows vanish from the ranking);
+ * when true it is kept with blank title/actor (the in-memory adapter's semantics).
+ */
+declare function bucketByThread(rows: GovernanceUsageInput[], prices: ReadonlyMap<string, ModelPrice>, threads: ReadonlyMap<string, ThreadMeta>, options: {
+    limit: number;
+    includeUnknownThreads: boolean;
+}): ThreadSpendRow[];
+/** 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. */
+declare function dayBoundsUtc(range: GovernanceRange): {
+    start: Date;
+    end: Date;
+};
+
 /** First filter layer: drop tools the actor's role may not invoke. `can` may be async (authz). */
 declare function filterToolsByRole(tools: ToolSpec[], actor: Actor, policy: RolesPolicy): Promise<ToolSpec[]>;
 /** Second filter layer: if the agent pins an allow-list, keep only those tool names. */
@@ -890,4 +1043,4 @@ declare function publishAgentRunFailed(payload: AgentRunFailed): void;
 declare function publishAgentDelegated(payload: AgentDelegated): void;
 declare function publishAgentRetrieved(payload: AgentRetrieved): void;
 
-export { AGENT_ACTOR_RESOLVER, AGENT_DEPS_FACTORY, 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_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorResolver, type ActorSpendRow, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type MessageRole, type MessageUsage, type ModelMessage, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type SinkWriter, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadSpendRow, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };
+export { AGENT_ACTOR_RESOLVER, AGENT_DEPS_FACTORY, 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_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorResolver, type ActorSpendRow, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, 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 PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type SinkWriter, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };

package/dist/index.d.ts

@@ -107,12 +107,30 @@ interface Decision {
     reason?: string;
 }
 type MessageRole = 'user' | 'assistant' | 'system';
+/**
+ * A file a user attached to a message so a vision-capable model sees it natively (an image, a PDF).
+ * The lib stays provider-agnostic: it passes {@link MessageAttachment.url} straight through as the
+ * model's image/file part data — making that URL reachable by the provider (presigned S3, a proxy)
+ * is the consumer's job. The lib never fetches bytes or talks to a store.
+ */
+interface MessageAttachment {
+    /** Stable id of the stored media object in the consumer's media store. Provenance + replay key. */
+    mediaId: string;
+    /** A URL the model provider can fetch the bytes from at turn time. */
+    url: string;
+    /** MIME type — routes the part: `image/*` → image part, otherwise → file part. */
+    contentType: string;
+    /** Original filename, for display and the file part's filename. */
+    name: string;
+}
 /** A neutral chat message exchanged with the model. */
 interface ModelMessage {
     role: MessageRole;
     content: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
+    /** User-message attachments (image/PDF), rendered as native model content parts by the adapter. */
+    attachments?: MessageAttachment[];
 }
 interface PageContext {
     kind?: string;
@@ -148,6 +166,8 @@ interface AgentRunInput {
     actor: Actor;
     /** The latest user message text. */
     userText: string;
+    /** Files attached to the latest user message (image/PDF). Persisted with it and sent to the model. */
+    attachments?: MessageAttachment[];
     pageContext?: PageContext;
     /** YYYY-MM-DD stamped by the runner so quota/day stays deterministic under durable replay. */
     day?: string;
@@ -181,6 +201,8 @@ interface AgentRunInput {
  */
 interface AgentDefinition {
     name: string;
+    /** Human-readable summary from `@Agent({ description })`. Surfaced by the `GET agents` catalog. */
+    description?: string;
     /** Base prompt for this agent. A flat string, or a {@link PromptBuilder} resolved per turn. */
     systemPrompt?: string | PromptBuilder;
     /** Allow-list of tool names this agent may use (subset of all registered tools). */
@@ -190,6 +212,16 @@ interface AgentDefinition {
     modelId?: string;
     maxSteps?: number;
 }
+/**
+ * The read-model the `GET agents` endpoint returns to a client — the safe public subset of an
+ * {@link AgentDefinition} so a host can render a persona picker instead of hardcoding one.
+ */
+interface AgentCatalogEntry {
+    name: string;
+    description: string;
+    /** Whether this is the agent a turn uses when the caller names none. Omitted when not the default. */
+    isDefault?: boolean;
+}
 interface ThreadSummary {
     id: string;
     title: string;
@@ -206,6 +238,8 @@ interface StoredMessage {
     agentName?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
+    /** Files the user attached to this message (image/PDF). Persisted with the message, replayed as-is. */
+    attachments?: MessageAttachment[];
     followUps?: string[];
     usage?: MessageUsage;
     createdAt: string;
@@ -359,6 +393,54 @@ interface ModelProvider {
     runTurn(args: ModelTurnArgs): Promise<ModelTurnResult>;
 }
 
+/**
+ * The structured live-stream vocabulary carried over the {@link SinkWriter} byte channel.
+ *
+ * The model turn (via the AI-SDK adapter) and the agent loop write these events as NDJSON — one
+ * `JSON.stringify(event)\n` per {@link SinkWriter.write}. The HTTP layer forwards each line as an
+ * SSE `data:` frame, and the client transport maps them back to the AI SDK UI-message chunk
+ * protocol so the browser renders text, reasoning, and tool cards (input + output) LIVE — the same
+ * rich rendering a raw `streamText().toUIMessageStream()` would give, but reconstructed on the
+ * client so the sink stays a format-agnostic byte buffer (durable buffering/replay is untouched).
+ *
+ * Keeping this vocabulary neutral (not AI-SDK `UIMessageChunk`) means core never depends on `ai`:
+ * the adapter owns model-parts → event, the transport owns event → UI-chunk.
+ */
+type AgentStreamEvent = {
+    kind: 'step-start';
+} | {
+    kind: 'step-finish';
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'reasoning';
+    text: string;
+} | {
+    kind: 'tool-input-start';
+    id: string;
+    name: string;
+} | {
+    kind: 'tool-input-delta';
+    id: string;
+    delta: string;
+} | {
+    kind: 'tool-input-available';
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    kind: 'tool-output';
+    id: string;
+    output: unknown;
+} | {
+    kind: 'tool-output-error';
+    id: string;
+    error: string;
+};
+/** Encode one event as an NDJSON line (`{...}\n`) for {@link SinkWriter.write}. */
+declare function encodeStreamEvent(event: AgentStreamEvent): Uint8Array;
+
 interface CreateThreadInput {
     actor: Actor;
     transient?: boolean;
@@ -372,6 +454,8 @@ interface AppendMessageInput {
     agentName?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
+    /** Files the user attached to this message (image/PDF). Persisted verbatim. */
+    attachments?: MessageAttachment[];
     followUps?: string[];
     usage?: MessageUsage;
 }
@@ -592,11 +676,12 @@ interface AgentRunner {
  * an identity is never invented from a default. See `HeaderActorResolver` for a header-based
  * resolver suitable for demos and gateways that strip/re-set the headers.
  *
- * `req` is the transport request object, typed `unknown` to keep core framework-agnostic;
- * a NestJS/Express app receives the express `Request`.
+ * `req` is the transport request object. Defaults to `unknown` to keep core framework-agnostic
+ * (a NestJS/Express app receives the express `Request`) — a host may narrow it via
+ * `ActorResolver<Request>` instead of writing its own `unknown`-narrowing type guard.
  */
-interface ActorResolver {
-    resolve(req: unknown): Actor | Promise<Actor>;
+interface ActorResolver<TReq = unknown> {
+    resolve(req: TReq): Actor | Promise<Actor>;
 }
 
 /**
@@ -682,6 +767,74 @@ interface AgentGovernanceQueries {
     recentThreads(limit: number): Promise<ThreadActivityRow[]>;
 }
 
+/**
+ * The pure aggregation core shared by every {@link import('../spi/governance-queries.js').AgentGovernanceQueries}
+ * adapter (MikroORM, Drizzle, in-memory). An adapter's only job is the DB-specific row fetch; the
+ * cost formula, the group→sort bucketing, and the day-bounds math live here so all three surfaces
+ * report identical numbers.
+ */
+/** The current per-1M token prices for one model; cache rates fall back to the input rate. */
+interface ModelPrice {
+    inputPricePer1m: number;
+    outputPricePer1m: number;
+    cacheWritePricePer1m?: number | null;
+    cacheReadPricePer1m?: number | null;
+}
+/** The token split of one turn needed to estimate its cost. */
+interface CostUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheWriteTokens?: number | null | undefined;
+    cacheReadTokens?: number | null | undefined;
+}
+/**
+ * A normalized usage row the bucketers consume. Each adapter maps its raw DB row into this shape
+ * (MikroORM reads `thread.id` + `createdAt`, Drizzle/in-memory read the flat `threadId` + `day`).
+ */
+interface GovernanceUsageInput extends CostUsage {
+    modelId: string;
+    actorRef: string;
+    threadId: string;
+    /** The `YYYY-MM-DD` UTC day the row belongs to (its trend bucket). */
+    day: string;
+    /** Provider-reported spend for the row; wins over the token estimate when present. */
+    costUsd?: number | null | undefined;
+}
+/** Thread metadata joined onto a spend bucket. */
+interface ThreadMeta {
+    title: string;
+    actorRef: string;
+}
+/**
+ * Token-ledger estimate for one turn against a pricing row: the uncached input at the input rate,
+ * cache-write/cache-read tokens at their own rates (falling back to the input rate when unpriced),
+ * plus output at the output rate. An unpriced model (`price === undefined`) contributes 0 — its
+ * tokens still count. Cache token counts are subsets of `inputTokens`, so the uncached remainder is
+ * the difference.
+ */
+declare function estimateCost(usage: CostUsage, price: ModelPrice | undefined): number;
+/** Aggregate usage rows into per-model spend, highest cost first then modelId ascending. */
+declare function bucketByModel(rows: GovernanceUsageInput[], prices: ReadonlyMap<string, ModelPrice>): ModelSpendRow[];
+/** Aggregate usage rows into per-actor spend (with distinct thread counts), highest cost first. */
+declare function bucketByActor(rows: GovernanceUsageInput[], prices: ReadonlyMap<string, ModelPrice>): ActorSpendRow[];
+/**
+ * Aggregate usage rows into per-thread spend, highest cost first then threadId ascending, capped at
+ * `limit`. A thread absent from `threads` is dropped when `includeUnknownThreads` is false (the SQL
+ * adapters fetch only non-deleted threads, so a soft-deleted thread's rows vanish from the ranking);
+ * when true it is kept with blank title/actor (the in-memory adapter's semantics).
+ */
+declare function bucketByThread(rows: GovernanceUsageInput[], prices: ReadonlyMap<string, ModelPrice>, threads: ReadonlyMap<string, ThreadMeta>, options: {
+    limit: number;
+    includeUnknownThreads: boolean;
+}): ThreadSpendRow[];
+/** 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. */
+declare function dayBoundsUtc(range: GovernanceRange): {
+    start: Date;
+    end: Date;
+};
+
 /** First filter layer: drop tools the actor's role may not invoke. `can` may be async (authz). */
 declare function filterToolsByRole(tools: ToolSpec[], actor: Actor, policy: RolesPolicy): Promise<ToolSpec[]>;
 /** Second filter layer: if the agent pins an allow-list, keep only those tool names. */
@@ -890,4 +1043,4 @@ declare function publishAgentRunFailed(payload: AgentRunFailed): void;
 declare function publishAgentDelegated(payload: AgentDelegated): void;
 declare function publishAgentRetrieved(payload: AgentRetrieved): void;
 
-export { AGENT_ACTOR_RESOLVER, AGENT_DEPS_FACTORY, 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_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorResolver, type ActorSpendRow, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type MessageRole, type MessageUsage, type ModelMessage, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type SinkWriter, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadSpendRow, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };
+export { AGENT_ACTOR_RESOLVER, AGENT_DEPS_FACTORY, 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_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorResolver, type ActorSpendRow, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, 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 PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type SinkWriter, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };