@dudousxd/nestjs-agent-core 0.3.0 → 0.3.2

package/dist/index.d.cts

@@ -181,6 +181,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 +192,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;
@@ -592,11 +604,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>;
 }
 
 /**
@@ -631,6 +644,17 @@ interface ActorSpendRow {
     requests: number;
     totalTokens: number;
     costUsd: number;
+    /** Distinct threads the actor used in the range. */
+    threadCount: number;
+}
+/** Spend + token totals for one thread over a range. */
+interface ThreadSpendRow {
+    threadId: string;
+    title: string;
+    actorRef: string;
+    requests: number;
+    totalTokens: number;
+    costUsd: number;
 }
 /** One point on the daily usage/cost trend. */
 interface UsageTrendPoint {
@@ -664,11 +688,81 @@ interface ThreadActivityRow {
 interface AgentGovernanceQueries {
     spendByModel(range: GovernanceRange): Promise<ModelSpendRow[]>;
     spendByActor(range: GovernanceRange): Promise<ActorSpendRow[]>;
+    /** Top threads by spend within the range, highest cost first, capped at `limit`. */
+    spendByThread(range: GovernanceRange, limit: number): Promise<ThreadSpendRow[]>;
     usageTrend(range: GovernanceRange): Promise<UsageTrendPoint[]>;
     recentToolCalls(limit: number): Promise<ToolCallActivityRow[]>;
     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. */
@@ -877,4 +971,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 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 AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, 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, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };

package/dist/index.d.ts

@@ -181,6 +181,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 +192,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;
@@ -592,11 +604,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>;
 }
 
 /**
@@ -631,6 +644,17 @@ interface ActorSpendRow {
     requests: number;
     totalTokens: number;
     costUsd: number;
+    /** Distinct threads the actor used in the range. */
+    threadCount: number;
+}
+/** Spend + token totals for one thread over a range. */
+interface ThreadSpendRow {
+    threadId: string;
+    title: string;
+    actorRef: string;
+    requests: number;
+    totalTokens: number;
+    costUsd: number;
 }
 /** One point on the daily usage/cost trend. */
 interface UsageTrendPoint {
@@ -664,11 +688,81 @@ interface ThreadActivityRow {
 interface AgentGovernanceQueries {
     spendByModel(range: GovernanceRange): Promise<ModelSpendRow[]>;
     spendByActor(range: GovernanceRange): Promise<ActorSpendRow[]>;
+    /** Top threads by spend within the range, highest cost first, capped at `limit`. */
+    spendByThread(range: GovernanceRange, limit: number): Promise<ThreadSpendRow[]>;
     usageTrend(range: GovernanceRange): Promise<UsageTrendPoint[]>;
     recentToolCalls(limit: number): Promise<ToolCallActivityRow[]>;
     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. */
@@ -877,4 +971,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 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 AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, 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, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };

package/dist/index.js

@@ -41,6 +41,142 @@ async function seedModelPrices(store, prices) {
 }
 __name(seedModelPrices, "seedModelPrices");
 
+// src/governance/compute.ts
+function estimateCost(usage, price) {
+  if (price === void 0) {
+    return 0;
+  }
+  const cacheWriteTokens = usage.cacheWriteTokens ?? 0;
+  const cacheReadTokens = usage.cacheReadTokens ?? 0;
+  const uncachedInputTokens = usage.inputTokens - cacheWriteTokens - cacheReadTokens;
+  return uncachedInputTokens / 1e6 * price.inputPricePer1m + cacheWriteTokens / 1e6 * (price.cacheWritePricePer1m ?? price.inputPricePer1m) + cacheReadTokens / 1e6 * (price.cacheReadPricePer1m ?? price.inputPricePer1m) + usage.outputTokens / 1e6 * price.outputPricePer1m;
+}
+__name(estimateCost, "estimateCost");
+function rowCost(row, prices) {
+  return row.costUsd ?? estimateCost(row, prices.get(row.modelId));
+}
+__name(rowCost, "rowCost");
+function bucketByModel(rows, prices) {
+  const byModel = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const bucket = byModel.get(row.modelId) ?? {
+      requests: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      costUsd: 0
+    };
+    bucket.requests += 1;
+    bucket.inputTokens += row.inputTokens;
+    bucket.outputTokens += row.outputTokens;
+    bucket.costUsd += rowCost(row, prices);
+    byModel.set(row.modelId, bucket);
+  }
+  const result = [];
+  for (const [modelId, bucket] of byModel) {
+    result.push({
+      modelId,
+      requests: bucket.requests,
+      inputTokens: bucket.inputTokens,
+      outputTokens: bucket.outputTokens,
+      costUsd: bucket.costUsd
+    });
+  }
+  result.sort((left, right) => right.costUsd - left.costUsd || left.modelId.localeCompare(right.modelId));
+  return result;
+}
+__name(bucketByModel, "bucketByModel");
+function bucketByActor(rows, prices) {
+  const byActor = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const bucket = byActor.get(row.actorRef) ?? {
+      requests: 0,
+      totalTokens: 0,
+      costUsd: 0,
+      threadIds: /* @__PURE__ */ new Set()
+    };
+    bucket.requests += 1;
+    bucket.totalTokens += row.inputTokens + row.outputTokens;
+    bucket.costUsd += rowCost(row, prices);
+    bucket.threadIds.add(row.threadId);
+    byActor.set(row.actorRef, bucket);
+  }
+  const result = [];
+  for (const [actorRef, bucket] of byActor) {
+    result.push({
+      actorRef,
+      requests: bucket.requests,
+      totalTokens: bucket.totalTokens,
+      costUsd: bucket.costUsd,
+      threadCount: bucket.threadIds.size
+    });
+  }
+  result.sort((left, right) => right.costUsd - left.costUsd || left.actorRef.localeCompare(right.actorRef));
+  return result;
+}
+__name(bucketByActor, "bucketByActor");
+function bucketByThread(rows, prices, threads, options) {
+  const byThread = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const bucket = byThread.get(row.threadId) ?? {
+      requests: 0,
+      totalTokens: 0,
+      costUsd: 0
+    };
+    bucket.requests += 1;
+    bucket.totalTokens += row.inputTokens + row.outputTokens;
+    bucket.costUsd += rowCost(row, prices);
+    byThread.set(row.threadId, bucket);
+  }
+  const result = [];
+  for (const [threadId, bucket] of byThread) {
+    const thread = threads.get(threadId);
+    if (thread === void 0 && !options.includeUnknownThreads) {
+      continue;
+    }
+    result.push({
+      threadId,
+      title: thread?.title ?? "",
+      actorRef: thread?.actorRef ?? "",
+      requests: bucket.requests,
+      totalTokens: bucket.totalTokens,
+      costUsd: bucket.costUsd
+    });
+  }
+  result.sort((left, right) => right.costUsd - left.costUsd || left.threadId.localeCompare(right.threadId));
+  return result.slice(0, options.limit);
+}
+__name(bucketByThread, "bucketByThread");
+function bucketUsageTrend(rows, prices) {
+  const byDay = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const bucket = byDay.get(row.day) ?? {
+      totalTokens: 0,
+      costUsd: 0
+    };
+    bucket.totalTokens += row.inputTokens + row.outputTokens;
+    bucket.costUsd += rowCost(row, prices);
+    byDay.set(row.day, bucket);
+  }
+  const result = [];
+  for (const [day, bucket] of byDay) {
+    result.push({
+      day,
+      totalTokens: bucket.totalTokens,
+      costUsd: bucket.costUsd
+    });
+  }
+  result.sort((left, right) => left.day.localeCompare(right.day));
+  return result;
+}
+__name(bucketUsageTrend, "bucketUsageTrend");
+function dayBoundsUtc(range) {
+  return {
+    start: /* @__PURE__ */ new Date(`${range.fromDay}T00:00:00.000Z`),
+    end: /* @__PURE__ */ new Date(`${range.toDay}T23:59:59.999Z`)
+  };
+}
+__name(dayBoundsUtc, "dayBoundsUtc");
+
 // src/tool-filters.ts
 async function filterToolsByRole(tools, actor, policy) {
   const checked = await Promise.all(tools.map(async (tool) => ({
@@ -721,6 +857,12 @@ export {
   ToolInputInvalidError,
   ToolNotFoundError,
   ToolRegistry,
+  bucketByActor,
+  bucketByModel,
+  bucketByThread,
+  bucketUsageTrend,
+  dayBoundsUtc,
+  estimateCost,
   filterToolsByAllowList,
   filterToolsByRole,
   publishAgentDelegated,