@adonis-agora/agent 0.1.0

package/dist/src/spi/attachment-staging.d.ts

@@ -0,0 +1,27 @@
+import type { Actor, MessageAttachment } from '../types.js';
+/** Input to {@link AttachmentStagingStore.stage} — the raw bytes plus who uploaded them. */
+export interface StageAttachmentInput {
+    data: Buffer;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    actor: Actor;
+}
+/**
+ * Optional upload-side seam for message attachments (an image/PDF a user attaches to a chat message
+ * before the model ever sees it). The lib never fetches bytes itself — {@link MessageAttachment.url}
+ * must already be reachable by the model provider — so something has to turn an uploaded file into
+ * that URL first. A store adapter (or a thin wrapper over the host's own media pipeline) implements
+ * this and is wired via `defineConfig({ attachmentStaging })` — pass an instance, a lazy
+ * `attachmentStores.*()` factory, or omit it. When omitted the optional `POST /agent/attachments`
+ * upload route is never mounted, so a client sends already-staged {@link MessageAttachment}s directly.
+ */
+export interface AttachmentStagingStore {
+    /**
+     * Persist an uploaded file somewhere the model can later fetch (a presigned URL, a proxy, or a
+     * `data:` URI) and return the {@link MessageAttachment} to send with the next chat message. The lib
+     * never fetches bytes; the returned url must be reachable by the model provider.
+     */
+    stage(input: StageAttachmentInput): Promise<MessageAttachment>;
+}
+//# sourceMappingURL=attachment-staging.d.ts.map

package/dist/src/spi/attachment-staging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-staging.d.ts","sourceRoot":"","sources":["../../../src/spi/attachment-staging.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE5D,4FAA4F;AAC5F,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChE"}

package/dist/src/spi/attachment-staging.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=attachment-staging.js.map

package/dist/src/spi/attachment-staging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-staging.js","sourceRoot":"","sources":["../../../src/spi/attachment-staging.ts"],"names":[],"mappings":""}

package/dist/src/spi/embedding-provider.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Turns text into embedding vectors — the retrieval-side sibling of {@link import('./model-provider.js').ModelProvider}.
+ * Batched (`texts` → one vector each, in the same order) so ingestion can embed many chunks per call.
+ * An adapter implements it (`aiSdkEmbedding` over the Vercel AI SDK `embedMany`, deferred this round);
+ * `@adonis-agora/agent/testing` ships a deterministic {@link import('../testing/fake-embedding-provider.js').FakeEmbeddingProvider}
+ * for offline tests. Mirrors the reference `EmbeddingProvider` contract exactly.
+ */
+export interface EmbeddingProvider {
+    /** Embed each input string; returns one vector per input, in the same order. */
+    embed(texts: string[]): Promise<number[][]>;
+}
+//# sourceMappingURL=embedding-provider.d.ts.map

package/dist/src/spi/embedding-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-provider.d.ts","sourceRoot":"","sources":["../../../src/spi/embedding-provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;CAC7C"}

package/dist/src/spi/embedding-provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=embedding-provider.js.map

package/dist/src/spi/embedding-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-provider.js","sourceRoot":"","sources":["../../../src/spi/embedding-provider.ts"],"names":[],"mappings":""}

package/dist/src/spi/governance-queries.d.ts

@@ -0,0 +1,215 @@
+/**
+ * A read-model over the persisted agent data (usage ⋈ pricing, tool calls, threads) for the
+ * governance surfaces — the standalone `-dashboard` SPA and the `-telescope` "Agent" tab both
+ * consume this ONE interface, so cost/usage aggregation lives in a single place.
+ *
+ * Separate from {@link AgentStore} on purpose: that SPI owns the write/thread path, this owns the
+ * read/analytics path. A store adapter implements both. Consumers inject via
+ * `AGENT_GOVERNANCE_QUERIES`.
+ *
+ * Live activity (in-flight runs, streaming tool calls, delegations, forbidden attempts) is NOT here
+ * — that comes off the `aviary:agent:*` diagnostics channel. This interface is the durable, restart-
+ * surviving history.
+ */
+/** Inclusive UTC day range, each `YYYY-MM-DD`. */
+export interface GovernanceRange {
+    fromDay: string;
+    toDay: string;
+}
+/** Spend + token totals for one model over a range. */
+export interface ModelSpendRow {
+    modelId: string;
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+}
+/** Spend + token totals for one acting ref (user/tenant) over a range. */
+export interface ActorSpendRow {
+    actorRef: string;
+    requests: number;
+    totalTokens: number;
+    costUsd: number;
+}
+/** One point on the daily usage/cost trend. */
+export interface UsageTrendPoint {
+    day: string;
+    totalTokens: number;
+    costUsd: number;
+}
+/** A recent tool-call for the activity feed. */
+export interface ToolCallActivityRow {
+    toolCallId: string;
+    toolName: string;
+    toolType: string;
+    status: string;
+    threadId: string;
+    createdAt: string;
+}
+/** A recent thread with rolled-up activity. */
+export interface ThreadActivityRow {
+    threadId: string;
+    title: string;
+    actorRef: string;
+    messageCount: number;
+    totalTokens: number;
+    lastActivityAt: string;
+}
+/** A run's lifecycle status as the read-model surfaces it. */
+export type RunStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+/** Filters + cursor for {@link AgentGovernanceQueries.listRuns}. All optional; absent = no constraint. */
+export interface ListRunsFilter {
+    /** Exact `actor_ref`. */
+    actor?: string;
+    /** Exact `agent_name`. */
+    agent?: string;
+    status?: RunStatus;
+    /** Inclusive UTC-day lower bound on `started_at`, `YYYY-MM-DD`. */
+    from?: string;
+    /** Inclusive UTC-day upper bound on `started_at`, `YYYY-MM-DD`. */
+    to?: string;
+    /** Opaque cursor from a prior page's {@link ListRunsResult.nextCursor}; omit for the first page. */
+    cursor?: string;
+    /** Page size; defaults to 50, clamped to 200 by the adapter. */
+    limit?: number;
+}
+/** A run row for the governance list + detail. Newest-first in {@link ListRunsResult}. */
+export interface RunSummaryRow {
+    runId: string;
+    threadId: string;
+    actorRef: string;
+    tenantRef: string | null;
+    agentName: string | null;
+    status: string;
+    /** ISO timestamp. */
+    startedAt: string;
+    /** ISO timestamp, `null` while still running. */
+    finishedAt: string | null;
+    /** `finishedAt - startedAt` in ms, `null` while still running. */
+    durationMs: number | null;
+    stepCount: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number | null;
+    error: string | null;
+    durable: boolean;
+}
+/** One page of {@link AgentGovernanceQueries.listRuns}, newest-first, with an opaque forward cursor. */
+export interface ListRunsResult {
+    runs: RunSummaryRow[];
+    /** Pass back as {@link ListRunsFilter.cursor} for the next page; `null` when the last page was returned. */
+    nextCursor: string | null;
+}
+/** A message belonging to a run, for {@link RunDetail}. */
+export interface RunMessageRow {
+    id: string;
+    role: string;
+    content: string;
+    createdAt: string;
+}
+/** A tool call belonging to a run, for {@link RunDetail} (and the approvals subset). */
+export interface RunToolCallRow {
+    toolCallId: string;
+    toolName: string;
+    toolType: string;
+    status: string;
+    input: unknown;
+    output: unknown;
+    error: string | null;
+    executionMs: number | null;
+    createdAt: string;
+}
+/** A usage ledger row belonging to a run, for {@link RunDetail}. */
+export interface RunUsageRow {
+    modelId: string;
+    purpose: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number | null;
+    createdAt: string;
+}
+/** The full trace of one run: the run row plus its messages, tool calls, pending approvals and usage. */
+export interface RunDetail {
+    run: RunSummaryRow;
+    messages: RunMessageRow[];
+    toolCalls: RunToolCallRow[];
+    /** The subset of `toolCalls` still `pending_approval`. */
+    approvals: RunToolCallRow[];
+    usage: RunUsageRow[];
+}
+/** Filters for {@link AgentGovernanceQueries.pendingApprovals}. */
+export interface PendingApprovalsFilter {
+    /** Restrict to a single acting ref (the owning run's `actor_ref`). */
+    actor?: string;
+    /** Cap the inbox; defaults to 50, clamped to 200 by the adapter. */
+    limit?: number;
+}
+/** One tool call awaiting a HITL decision, for the cross-thread approvals inbox (oldest first). */
+export interface PendingApprovalRow {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    threadId: string;
+    /** The run this call belongs to, for a trace deep-link; `null` for a call recorded before run tracking. */
+    runId: string | null;
+    /** Who asked — the owning run's (or thread's) actor. */
+    actorRef: string;
+    /** ISO timestamp the call was recorded (requested). */
+    requestedAt: string;
+}
+/** Inclusive UTC-day range for the run/tool aggregates; each bound `YYYY-MM-DD`, both optional. */
+export interface ToolStatsRange {
+    /** Lower bound on the row's `created_at`/`started_at`; omit for no lower bound. */
+    from?: string;
+    /** Upper bound; omit for no upper bound. */
+    to?: string;
+}
+/** Per-tool call/failure/rejection/latency rollup over a range, highest call count first. */
+export interface PerToolStatRow {
+    toolName: string;
+    toolType: string;
+    calls: number;
+    failed: number;
+    rejected: number;
+    /** Mean `executionMs` across calls that recorded one; `null` when none did. */
+    avgDurationMs: number | null;
+}
+/** Aggregated run reliability over a range — success / failure / cancel rates. */
+export interface RunReliability {
+    runs: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    running: number;
+    /** completed / runs, 0 when runs = 0. */
+    successRate: number;
+    /** failed / runs, 0 when runs = 0. */
+    failureRate: number;
+    /** cancelled / runs, 0 when runs = 0. */
+    cancelRate: number;
+    /** Mean duration of settled (completed/failed/cancelled) runs in ms; `null` when none settled. */
+    avgDurationMs: number | null;
+}
+/**
+ * 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
+ * (its tokens still count).
+ */
+export interface AgentGovernanceQueries {
+    spendByModel(range: GovernanceRange): Promise<ModelSpendRow[]>;
+    spendByActor(range: GovernanceRange): Promise<ActorSpendRow[]>;
+    usageTrend(range: GovernanceRange): Promise<UsageTrendPoint[]>;
+    recentToolCalls(limit: number): Promise<ToolCallActivityRow[]>;
+    recentThreads(limit: number): Promise<ThreadActivityRow[]>;
+    /** Filterable, cursor-paginated run list, newest-first. */
+    listRuns(filter?: ListRunsFilter): Promise<ListRunsResult>;
+    /** The full trace of one run (run + messages + tool calls + approvals + usage), or `null` if unknown. */
+    runDetail(runId: string): Promise<RunDetail | null>;
+    /** Tool calls sitting `pending_approval`, oldest first (an inbox drains from the back). */
+    pendingApprovals(filter?: PendingApprovalsFilter): Promise<PendingApprovalRow[]>;
+    /** Per-tool call/failure/rejection/latency rollup over the range, highest call count first. */
+    perToolStats(range?: ToolStatsRange): Promise<PerToolStatRow[]>;
+    /** Success/failure/cancel rates + mean settled duration over the range. */
+    runReliability(range?: ToolStatsRange): Promise<RunReliability>;
+}
+//# sourceMappingURL=governance-queries.d.ts.map

package/dist/src/spi/governance-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governance-queries.d.ts","sourceRoot":"","sources":["../../../src/spi/governance-queries.ts"],"names":[],"mappings":"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"}

package/dist/src/spi/governance-queries.js

@@ -0,0 +1,15 @@
+/**
+ * A read-model over the persisted agent data (usage ⋈ pricing, tool calls, threads) for the
+ * governance surfaces — the standalone `-dashboard` SPA and the `-telescope` "Agent" tab both
+ * consume this ONE interface, so cost/usage aggregation lives in a single place.
+ *
+ * Separate from {@link AgentStore} on purpose: that SPI owns the write/thread path, this owns the
+ * read/analytics path. A store adapter implements both. Consumers inject via
+ * `AGENT_GOVERNANCE_QUERIES`.
+ *
+ * Live activity (in-flight runs, streaming tool calls, delegations, forbidden attempts) is NOT here
+ * — that comes off the `aviary:agent:*` diagnostics channel. This interface is the durable, restart-
+ * surviving history.
+ */
+export {};
+//# sourceMappingURL=governance-queries.js.map

package/dist/src/spi/governance-queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"governance-queries.js","sourceRoot":"","sources":["../../../src/spi/governance-queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/src/spi/model-provider.d.ts

@@ -0,0 +1,41 @@
+import type { MessageUsage, ModelMessage, ToolCallRequest, ToolDefinition } from '../types.js';
+import type { SinkWriter } from './token-stream-sink.js';
+export interface ModelTurnArgs {
+    system: string;
+    messages: ModelMessage[];
+    tools: ToolDefinition[];
+    /** The model writes streamed text deltas here as it generates them. */
+    sink: SinkWriter;
+    abortSignal?: AbortSignal;
+}
+/** The outcome of ONE assistant turn. The loop — not the model — drives tool execution. */
+export interface ModelTurnResult {
+    text: string;
+    toolCalls: ToolCallRequest[];
+    usage: MessageUsage;
+    /**
+     * The model actually used this turn (e.g. `anthropic.claude-...`), recorded with usage for
+     * cost accounting. When set it wins over the module's configured `modelId`, so the accounting
+     * label can't silently drift from the runtime. Omit if the provider can't report one.
+     */
+    modelId?: string;
+    /**
+     * The ACTUAL USD cost of this turn, when the provider knows it — a gateway (Vercel AI Gateway
+     * `providerMetadata.gateway.cost`, OpenRouter `total_cost`) reports real spend; a direct provider
+     * (Anthropic/OpenAI/Bedrock) reports only tokens and leaves this undefined. When set, the
+     * governance read-model uses it verbatim; otherwise it estimates from tokens × the pricing table.
+     */
+    costUsd?: number;
+}
+/**
+ * Thin wrapper over the actual LLM. The concrete impl (e.g. Vercel AI SDK `streamText`
+ * over Bedrock/Anthropic) lives in the host app or an adapter; core stays provider-free.
+ *
+ * Contract: `runTurn` performs exactly one model turn, streaming deltas to `args.sink`,
+ * and returns the assembled text + requested tool calls + usage. It MUST NOT execute
+ * tools — the agent loop runs each as a (durable) step for replay-safety.
+ */
+export interface ModelProvider {
+    runTurn(args: ModelTurnArgs): Promise<ModelTurnResult>;
+}
+//# sourceMappingURL=model-provider.d.ts.map

package/dist/src/spi/model-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-provider.d.ts","sourceRoot":"","sources":["../../../src/spi/model-provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC/F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,uEAAuE;IACvE,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,KAAK,EAAE,YAAY,CAAC;IACpB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CACxD"}

package/dist/src/spi/pricing-store.d.ts

@@ -0,0 +1,45 @@
+import type { MessageUsage } from '../types.js';
+/**
+ * The WRITE side of the model pricing table the loop's cost fold prices token usage against. Cost is
+ * `null` (not `0`) for an unpriced model, so an app seeds its models' per-1M rates once (and
+ * re-`upsert`s when a provider changes prices). An adapter implements this — `LucidPricingStore`
+ * (production, over the `agent_model_pricing` table) and `InMemoryPricingStore` (testing) ship. Wire
+ * it in `config/agent.ts` via `pricingStore: pricingStores.lucid()`; use {@link seedModelPrices} for a
+ * one-shot batch. Mirrors the reference `AgentPricingStore` contract exactly.
+ */
+/** A per-1M-token price for one model. Cache rates fall back to the input rate when omitted. */
+export interface ModelPriceInput {
+    modelId: string;
+    inputPricePer1m: number;
+    outputPricePer1m: number;
+    /** Per-1M price for cache-write (prompt-cache) input tokens. Omit → priced at the input rate. */
+    cacheWritePricePer1m?: number;
+    /** Per-1M price for cache-read (prompt-cache) input tokens. Omit → priced at the input rate. */
+    cacheReadPricePer1m?: number;
+}
+/** A current price row as read back, with the ISO timestamp it took effect. */
+export interface CurrentModelPrice extends ModelPriceInput {
+    effectiveFrom: string;
+}
+export interface AgentPricingStore {
+    /**
+     * Set the current price for a model. Atomic supersede: the model's prior `is_current` row (if any)
+     * is retired and this one is inserted as current, effective now — so the cost fold always joins to
+     * exactly one live price per model, with no window where two rows race for `is_current`.
+     */
+    upsertModelPrice(input: ModelPriceInput): Promise<void>;
+    /** The current price row per model (`is_current`), fetched ONCE per run for the loop's cost fold. */
+    listCurrentPrices(): Promise<CurrentModelPrice[]>;
+}
+/** Seed (or refresh) a batch of model prices — one `upsertModelPrice` per row, in order. */
+export declare function seedModelPrices(store: AgentPricingStore, prices: ModelPriceInput[]): Promise<void>;
+/**
+ * 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. Reasoning tokens are a subset of output and are billed at the
+ * output rate, so they don't change the estimate. Cache token counts are subsets of `inputTokens`,
+ * so the uncached remainder is the difference. Pure — the SQL and in-memory adapters share it, so
+ * every surface reports identical numbers.
+ */
+export declare function estimateCost(usage: MessageUsage, price: CurrentModelPrice): number;
+//# sourceMappingURL=pricing-store.d.ts.map

package/dist/src/spi/pricing-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing-store.d.ts","sourceRoot":"","sources":["../../../src/spi/pricing-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;GAOG;AAEH,gGAAgG;AAChG,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iGAAiG;IACjG,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gGAAgG;IAChG,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,qGAAqG;IACrG,iBAAiB,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;CACnD;AAED,4FAA4F;AAC5F,wBAAsB,eAAe,CACnC,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,eAAe,EAAE,GACxB,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAUlF"}

package/dist/src/spi/pricing-store.js

@@ -0,0 +1,24 @@
+/** Seed (or refresh) a batch of model prices — one `upsertModelPrice` per row, in order. */
+export async function seedModelPrices(store, prices) {
+    for (const price of prices) {
+        await store.upsertModelPrice(price);
+    }
+}
+/**
+ * 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. Reasoning tokens are a subset of output and are billed at the
+ * output rate, so they don't change the estimate. Cache token counts are subsets of `inputTokens`,
+ * so the uncached remainder is the difference. Pure — the SQL and in-memory adapters share it, so
+ * every surface reports identical numbers.
+ */
+export function estimateCost(usage, price) {
+    const cacheWriteTokens = usage.cacheWriteTokens ?? 0;
+    const cacheReadTokens = usage.cacheReadTokens ?? 0;
+    const uncachedInputTokens = usage.inputTokens - cacheWriteTokens - cacheReadTokens;
+    return ((uncachedInputTokens / 1_000_000) * price.inputPricePer1m +
+        (cacheWriteTokens / 1_000_000) * (price.cacheWritePricePer1m ?? price.inputPricePer1m) +
+        (cacheReadTokens / 1_000_000) * (price.cacheReadPricePer1m ?? price.inputPricePer1m) +
+        (usage.outputTokens / 1_000_000) * price.outputPricePer1m);
+}
+//# sourceMappingURL=pricing-store.js.map

package/dist/src/spi/pricing-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing-store.js","sourceRoot":"","sources":["../../../src/spi/pricing-store.ts"],"names":[],"mappings":"AAsCA,4FAA4F;AAC5F,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAwB,EACxB,MAAyB;IAEzB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,KAAmB,EAAE,KAAwB;IACxE,MAAM,gBAAgB,GAAG,KAAK,CAAC,gBAAgB,IAAI,CAAC,CAAC;IACrD,MAAM,eAAe,GAAG,KAAK,CAAC,eAAe,IAAI,CAAC,CAAC;IACnD,MAAM,mBAAmB,GAAG,KAAK,CAAC,WAAW,GAAG,gBAAgB,GAAG,eAAe,CAAC;IACnF,OAAO,CACL,CAAC,mBAAmB,GAAG,SAAS,CAAC,GAAG,KAAK,CAAC,eAAe;QACzD,CAAC,gBAAgB,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,oBAAoB,IAAI,KAAK,CAAC,eAAe,CAAC;QACtF,CAAC,eAAe,GAAG,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,mBAAmB,IAAI,KAAK,CAAC,eAAe,CAAC;QACpF,CAAC,KAAK,CAAC,YAAY,GAAG,SAAS,CAAC,GAAG,KAAK,CAAC,gBAAgB,CAC1D,CAAC;AACJ,CAAC"}

package/dist/src/spi/quota-store.d.ts

@@ -0,0 +1,7 @@
+import type { QuotaState } from '../types.js';
+/** Per-actor/day token budget. Default impl is in-memory; Redis impl ships in transport-redis. */
+export interface QuotaStore {
+    check(actorRef: string, day: string): Promise<QuotaState>;
+    bump(actorRef: string, day: string, tokens: number): Promise<void>;
+}
+//# sourceMappingURL=quota-store.d.ts.map

package/dist/src/spi/quota-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quota-store.d.ts","sourceRoot":"","sources":["../../../src/spi/quota-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,kGAAkG;AAClG,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1D,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE"}

package/dist/src/spi/reranker.d.ts

@@ -0,0 +1,17 @@
+import type { Passage } from './retriever.js';
+export interface RerankOptions {
+    /** Keep only the top N after reranking. Undefined → keep all, reordered. */
+    topK?: number;
+}
+/**
+ * Re-scores retrieved passages against the query with a stronger (usually cross-encoder) model than
+ * the first-stage retriever — the standard precision boost for RAG. It's a black box like
+ * {@link import('./retriever.js').Retriever}: bring a Cohere/Voyage rerank endpoint or a local
+ * cross-encoder. Provider implementations are deferred this round (SPI only); the testing kit ships a
+ * trivial identity reranker. Mirrors the reference `Reranker` contract exactly.
+ */
+export interface Reranker {
+    /** Re-order `passages` by relevance to `query`, rewriting their `score`; may drop to `topK`. */
+    rerank(query: string, passages: Passage[], options?: RerankOptions): Promise<Passage[]>;
+}
+//# sourceMappingURL=reranker.d.ts.map

package/dist/src/spi/reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../../../src/spi/reranker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,gGAAgG;IAChG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACzF"}

package/dist/src/spi/reranker.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=reranker.js.map

package/dist/src/spi/reranker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.js","sourceRoot":"","sources":["../../../src/spi/reranker.ts"],"names":[],"mappings":""}

package/dist/src/spi/retriever.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Retrieval seam for RAG. A `Retriever` is a black box — the agent loop asks it for the passages most
+ * relevant to a query and never sees how (vector search, keyword, hybrid, a remote service). This
+ * package ships an {@link import('../rag/embedding-retriever.js').EmbeddingRetriever} (embed + vector
+ * store) built via the `retrievers` factory namespace, but any impl satisfying this SPI works. Wired
+ * on the config's `retriever` it drives always-on ("inject") retrieval: the loop retrieves once for
+ * the user message and folds the passages into the system prompt. Mirrors the reference `Retriever`
+ * contract exactly.
+ */
+/** One retrieved passage. `source` is a human/citation-facing origin; `score` is impl-defined relevance. */
+export interface Passage {
+    id: string;
+    text: string;
+    score: number;
+    /** Where the passage came from (document title, URL, row id) — surfaced as a citation. */
+    source?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface RetrieveOptions {
+    /** Max passages to return. The impl may cap it; the loop defaults to 5 when unset. */
+    topK?: number;
+    /** Impl-specific metadata filter (e.g. `{ tenantRef }`). Opaque to the runtime. */
+    filter?: Record<string, unknown>;
+}
+export interface Retriever {
+    retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+}
+//# sourceMappingURL=retriever.d.ts.map

package/dist/src/spi/retriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retriever.d.ts","sourceRoot":"","sources":["../../../src/spi/retriever.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,4GAA4G;AAC5G,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACxE"}

package/dist/src/spi/retriever.js

@@ -0,0 +1,11 @@
+/**
+ * Retrieval seam for RAG. A `Retriever` is a black box — the agent loop asks it for the passages most
+ * relevant to a query and never sees how (vector search, keyword, hybrid, a remote service). This
+ * package ships an {@link import('../rag/embedding-retriever.js').EmbeddingRetriever} (embed + vector
+ * store) built via the `retrievers` factory namespace, but any impl satisfying this SPI works. Wired
+ * on the config's `retriever` it drives always-on ("inject") retrieval: the loop retrieves once for
+ * the user message and folds the passages into the system prompt. Mirrors the reference `Retriever`
+ * contract exactly.
+ */
+export {};
+//# sourceMappingURL=retriever.js.map

package/dist/src/spi/retriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retriever.js","sourceRoot":"","sources":["../../../src/spi/retriever.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/src/spi/roles-policy.d.ts

@@ -0,0 +1,11 @@
+import type { Actor, ToolSpec } from '../types.js';
+/**
+ * Decides whether an actor may invoke a tool. The default impl checks the actor's role
+ * against `spec.roles` (defaulting to an ADMIN-only set). Apps can plug `nestjs-authz`
+ * or any custom gate here.
+ */
+export interface RolesPolicy {
+    /** May return a promise — an authz Gate (`gate.forUser(actor).allows(...)`) is async. */
+    can(actor: Actor, tool: ToolSpec): boolean | Promise<boolean>;
+}
+//# sourceMappingURL=roles-policy.d.ts.map

package/dist/src/spi/roles-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roles-policy.d.ts","sourceRoot":"","sources":["../../../src/spi/roles-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/D"}

package/dist/src/spi/tool.d.ts

@@ -0,0 +1,21 @@
+import type { Actor, PageContext, Persona } from '../types.js';
+/**
+ * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
+ * on {@link AiToolCtx.actor} — read `ctx.actor.id` / `ctx.actor.tenantRef` (single source of truth;
+ * no denormalized copies).
+ */
+export interface AiToolCtx {
+    actor: Actor;
+    threadId: string;
+    runId: string;
+    requestId: string;
+    persona?: Persona;
+    pageContext?: PageContext;
+    /** Optional host handle (e.g. an ORM EntityManager) the app threads through options. */
+    host?: unknown;
+}
+/** A tool implementation. `I` is the parsed (Zod-validated) input. */
+export interface ToolHandler<I = unknown> {
+    execute(input: I, ctx: AiToolCtx): Promise<unknown>;
+}
+//# sourceMappingURL=tool.d.ts.map

package/dist/src/spi/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../src/spi/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,wFAAwF;IACxF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,OAAO,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACrD"}