@dudousxd/nestjs-agent-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,848 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+/** Who is driving the turn. Roles + tenant come from the host app (nestjs-context/authz). */
+interface Actor {
+    id: string;
+    /** The caller's roles. Tool authorization is a set intersection against a tool's `roles`. */
+    roles?: string[];
+    tenantRef?: string;
+}
+type ToolKind = 'read' | 'action' | 'agent';
+/**
+ * Declared shape of a tool.
+ *  - `read`   auto-executes.
+ *  - `action` never auto-executes — requires HITL approval.
+ *  - `agent`  delegates to another named agent (durable: a child workflow; inline: a nested loop),
+ *             handled at the loop level — NOT via a handler. Carries `targetAgent`.
+ */
+interface ToolSpec {
+    name: string;
+    kind: ToolKind;
+    description: string;
+    /**
+     * Input schema as a [Standard Schema](https://standardschema.dev) — validation-agnostic, so
+     * Zod, Valibot, or ArkType all work. The loop validates input via `~standard.validate` before
+     * running the handler, and providers convert it to the model's tool-parameter JSON schema.
+     */
+    inputSchema: StandardSchemaV1;
+    /** For `kind: 'agent'` — the name of the agent to delegate to. */
+    targetAgent?: string;
+    /** Roles allowed to invoke. Undefined → defaults applied by RolesPolicy (e.g. ADMIN-only). */
+    roles?: string[];
+    /**
+     * An authorization ability name (e.g. 'cache.purge'). Consumed by an ability-aware RolesPolicy
+     * such as the `@dudousxd/nestjs-agent-authz` Gate adapter. Apps that don't use authz ignore it
+     * and rely on `roles` instead — both live on the same SPI, so neither is required.
+     */
+    ability?: string;
+}
+/** What the model is told a tool looks like (no handler, no host types). */
+interface ToolDefinition {
+    name: string;
+    kind: ToolKind;
+    description: string;
+    inputSchema: StandardSchemaV1;
+}
+/** A tool call the model asked for during a turn. */
+interface ToolCallRequest {
+    id: string;
+    name: string;
+    input: unknown;
+}
+/** Result of running a tool. */
+interface ToolResult {
+    id: string;
+    name: string;
+    output: unknown;
+    error?: string;
+}
+interface MessageUsage {
+    /**
+     * Total input (prompt) tokens for the turn — the whole input side, cached and uncached alike.
+     * `cacheWriteTokens` + `cacheReadTokens` are subsets of this count, not additions to it, so
+     * token totals and quota never change when a breakdown is present.
+     */
+    inputTokens: number;
+    /** Total output (completion) tokens for the turn; `reasoningTokens` is a subset of this. */
+    outputTokens: number;
+    /**
+     * How many of `inputTokens` were written to the prompt cache this turn (billed at a premium,
+     * ~1.25× base input). Undefined when the provider doesn't report caching. Refines the cost
+     * estimate only — priced by the pricing row's cache-write rate (falling back to the input rate).
+     */
+    cacheWriteTokens?: number;
+    /**
+     * How many of `inputTokens` were served from the prompt cache this turn (billed at a discount,
+     * ~0.1× base input). Undefined when the provider doesn't report caching.
+     */
+    cacheReadTokens?: number;
+    /**
+     * How many of `outputTokens` the model spent on reasoning/thinking. Observability only — reasoning
+     * tokens are billed at the output rate, so they don't change the cost estimate. Undefined for
+     * non-reasoning models or providers that don't report it.
+     */
+    reasoningTokens?: number;
+}
+type UsagePurpose = 'chat' | 'follow_ups';
+interface QuotaState {
+    usedTokens: number;
+    limitTokens: number;
+    withinLimit: boolean;
+}
+/** A human decision on a pending action tool call. */
+interface Decision {
+    approved: boolean;
+    reason?: string;
+}
+type MessageRole = 'user' | 'assistant' | 'system';
+/** A neutral chat message exchanged with the model. */
+interface ModelMessage {
+    role: MessageRole;
+    content: string;
+    toolCalls?: ToolCallRequest[];
+    toolResults?: ToolResult[];
+}
+interface PageContext {
+    kind?: string;
+    [key: string]: unknown;
+}
+/**
+ * Inputs a {@link PromptBuilder} may use to compose the effective system prompt for a turn.
+ * `basePrompt` is the agent's own (already-resolved) base prompt, so a persona builder can wrap
+ * or extend it rather than replace it.
+ */
+interface PromptContext {
+    actor: Actor;
+    persona?: Persona;
+    pageContext?: PageContext;
+    basePrompt: string;
+}
+/**
+ * A dynamic system prompt. Return a string (optionally async) built from the turn's context —
+ * e.g. injecting the actor, the current page, or a data-shape description. The loop resolves it
+ * once per turn from stable inputs (actor/persona/pageContext), so it stays replay-safe.
+ */
+type PromptBuilder = (ctx: PromptContext) => string | Promise<string>;
+interface Persona {
+    id: string;
+    label: string;
+    /** A flat prompt, or a {@link PromptBuilder} composed per request from {@link PromptContext}. */
+    systemPrompt: string | PromptBuilder;
+    /** If set, only these tool names are offered (after role filtering). */
+    allowedTools?: string[];
+}
+/** Everything needed to run one agent turn. */
+interface AgentRunInput {
+    threadId: string;
+    actor: Actor;
+    /** The latest user message text. */
+    userText: string;
+    persona?: Persona;
+    pageContext?: PageContext;
+    /** YYYY-MM-DD stamped by the runner so quota/day stays deterministic under durable replay. */
+    day?: string;
+    /** Which named agent runs this turn. Omitted → the default/single agent. */
+    agentName?: string;
+    /**
+     * How many agent→agent delegations deep this run already is (0 for a top-level turn). The runner
+     * increments it for each child run; the loop refuses to delegate past {@link MAX_DELEGATION_DEPTH}.
+     */
+    delegationDepth?: number;
+    /**
+     * When set, this run streams into ANOTHER run's sink instead of its own. A sub-agent run carries
+     * its top-level ancestor's runId here so its tokens (and its pending action-tool frames) land in
+     * the live stream the human is already watching — the only way a human can see, and therefore
+     * approve, a sub-agent's HITL action. Propagated unchanged down the delegation chain.
+     */
+    sinkRunId?: string;
+    /**
+     * Re-run the last exchange instead of adding a new message: the loop truncates everything after
+     * the thread's last user message and re-answers it (no `userText` is appended). Used by a
+     * "regenerate" button. `userText` is ignored when set.
+     */
+    regenerate?: boolean;
+}
+/**
+ * A named agent: its prompt, the tools it may use, and its personas. Multiple definitions are
+ * registered via `AgentModule.forFeature([...])`; an orchestrator delegates to others through
+ * `ctx.runAgent(name, task)`. Model/store/sink/governance are shared from the module unless
+ * overridden here.
+ */
+interface AgentDefinition {
+    name: 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). */
+    tools?: string[];
+    /** Names of other agents this agent may delegate to (auto-registered as `agent`-kind tools). */
+    delegatesTo?: string[];
+    personas?: Persona[];
+    defaultPersona?: string;
+    modelId?: string;
+    maxSteps?: number;
+}
+interface ThreadSummary {
+    id: string;
+    title: string;
+    persona: string;
+    transient: boolean;
+    createdAt: string;
+    updatedAt: string;
+    lastMessagePreview?: string;
+}
+interface StoredMessage {
+    id: string;
+    role: MessageRole;
+    content: string;
+    toolCalls?: ToolCallRequest[];
+    toolResults?: ToolResult[];
+    followUps?: string[];
+    usage?: MessageUsage;
+    createdAt: string;
+}
+interface ThreadDetail extends ThreadSummary {
+    messages: StoredMessage[];
+    activeStreamId?: string;
+}
+type ToolCallStatus = 'auto_executed' | 'pending_approval' | 'executed' | 'rejected' | 'failed';
+
+/**
+ * Public, cross-lib-discoverable DI tokens.
+ *
+ * These use `Symbol.for(...)` (the global symbol registry) on purpose: pnpm peer
+ * multiplexing + dual ESM/CJS can load `core` more than once, and a plain `Symbol()`
+ * would mint a distinct token per copy and break DI across package boundaries. A
+ * registered symbol collapses every copy onto the same token, and lets a sibling lib
+ * resolve our injectables by name without importing our internals.
+ *
+ * Naming convention (ecosystem-wide): `@dudousxd/nestjs-<lib>:<name>`.
+ */
+declare const AGENT_OPTIONS: unique symbol;
+declare const AGENT_STORE: unique symbol;
+declare const AGENT_RUNNER: unique symbol;
+/**
+ * The durable runner, provided ONLY by `AgentDurableModule`. When `durable: true`, the module
+ * binds `AGENT_RUNNER` to this via an optional injection, so a missing `AgentDurableModule`
+ * fails with a clear error instead of a cryptic unresolved-dependency one.
+ */
+declare const AGENT_DURABLE_RUNNER: unique symbol;
+declare const AGENT_SINK: unique symbol;
+declare const AGENT_MODEL: unique symbol;
+declare const AGENT_ROLES_POLICY: unique symbol;
+declare const AGENT_QUOTA_STORE: unique symbol;
+declare const AGENT_TOOL_REGISTRY: unique symbol;
+declare const AGENT_REGISTRY: unique symbol;
+declare const AGENT_ACTOR_RESOLVER: unique symbol;
+/** The governance read-model (usage/spend/threads), consumed by the dashboard + telescope surfaces. */
+declare const AGENT_GOVERNANCE_QUERIES: unique symbol;
+/** The pricing WRITE side (`AgentPricingStore`) — seeds/updates the per-model rates cost is priced against. */
+declare const AGENT_PRICING_STORE: unique symbol;
+/** The RAG retrieval seam (`Retriever`) — vector/keyword search behind the agentic tool or inject mode. */
+declare const AGENT_RETRIEVER: unique symbol;
+/** The embedding provider (`EmbeddingProvider`) — text→vector for retrieval + ingestion. */
+declare const AGENT_EMBEDDING_PROVIDER: unique symbol;
+declare const AGENT_DEPS_FACTORY: unique symbol;
+
+/**
+ * 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).
+ */
+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. */
+interface ToolHandler<I = unknown> {
+    execute(input: I, ctx: AiToolCtx): Promise<unknown>;
+}
+
+/**
+ * The "data plane": live token transport, decoupled from the durable control plane.
+ *
+ * The model turn writes deltas to a `SinkWriter` keyed by runId; the HTTP layer
+ * `subscribe`s by runId and pipes the chunks to the browser as SSE. A late subscriber
+ * (reconnect/resume) replays buffered chunks first, then follows live — which is what
+ * makes streaming survive a dropped connection or a pod restart.
+ */
+interface SinkWriter {
+    write(chunk: Uint8Array): void | Promise<void>;
+    /** Mark the run's stream finished (no more chunks). */
+    end(): void | Promise<void>;
+    /**
+     * Terminate the run's stream with an error instead of a normal end. Subscribers replay any
+     * buffered chunks first, then throw an {@link AgentStreamError} carrying this `code`/`message`
+     * — so the transport can surface a typed failure frame instead of leaking it as assistant text.
+     */
+    fail(error: StreamError): void | Promise<void>;
+}
+/** A machine-readable stream failure. `code` is a stable slug; `message` is human-facing. */
+interface StreamError {
+    code: string;
+    message: string;
+}
+/**
+ * Thrown out of {@link TokenStreamSink.subscribe} when a run ended via {@link SinkWriter.fail}.
+ * Carries the structured {@link StreamError} so the HTTP layer can emit an `event: error` frame.
+ */
+declare class AgentStreamError extends Error {
+    readonly code: string;
+    constructor(error: StreamError);
+}
+interface TokenStreamSink {
+    /** Open (or reopen) the writer for a run. */
+    open(runId: string): SinkWriter | Promise<SinkWriter>;
+    /**
+     * Replay buffered chunks for the run, then yield live ones until `end()`. Throws
+     * {@link AgentStreamError} if the run was terminated with {@link SinkWriter.fail}.
+     */
+    subscribe(runId: string): AsyncIterable<Uint8Array>;
+    /** Drop any buffer/resources for the run. */
+    close(runId: string): void | Promise<void>;
+}
+
+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. */
+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.
+ */
+interface ModelProvider {
+    runTurn(args: ModelTurnArgs): Promise<ModelTurnResult>;
+}
+
+interface CreateThreadInput {
+    actor: Actor;
+    persona: string;
+    transient?: boolean;
+    title?: string;
+}
+interface AppendMessageInput {
+    threadId: string;
+    role: StoredMessage['role'];
+    content: string;
+    persona?: string;
+    toolCalls?: ToolCallRequest[];
+    toolResults?: ToolResult[];
+    followUps?: string[];
+    usage?: MessageUsage;
+}
+interface RecordToolCallInput {
+    toolCallId: string;
+    messageId: string;
+    toolName: string;
+    toolType: 'read' | 'action';
+    input: unknown;
+    status: ToolCallStatus;
+}
+interface UpdateToolCallInput {
+    toolCallId: string;
+    status: ToolCallStatus;
+    output?: unknown;
+    error?: string;
+    executionMs?: number;
+    executedByRef?: string;
+}
+interface RecordUsageInput {
+    threadId: string;
+    actorRef: string;
+    messageId?: string;
+    modelId: string;
+    purpose: UsagePurpose;
+    usage: MessageUsage;
+    /** Provider-reported actual USD cost for this turn, when known (gateways report it). */
+    costUsd?: number;
+}
+/** ORM-agnostic persistence. Refs are string ids; adapters may add real relations. */
+interface AgentStore {
+    createThread(input: CreateThreadInput): Promise<ThreadSummary>;
+    getThread(threadId: string): Promise<ThreadDetail | null>;
+    listThreads(actorRef: string, limit?: number): Promise<ThreadSummary[]>;
+    softDeleteThread(threadId: string): Promise<void>;
+    forkThread(threadId: string, fromMessageId: string): Promise<ThreadSummary>;
+    setTitle(threadId: string, title: string): Promise<void>;
+    setActiveStream(threadId: string, runId: string | null): Promise<void>;
+    /**
+     * The `actorRef` that owns a thread, or `null` if no such thread exists. The authorization seam
+     * for thread-scoped endpoints (detail / delete / fork): the service compares this against the
+     * resolved caller before acting, so one actor can never read or mutate another's thread.
+     */
+    ownerOfThread(threadId: string): Promise<string | null>;
+    /**
+     * The `actorRef` that owns the thread a tool call belongs to, or `null` if the call is unknown.
+     * The authorization seam for HITL approve / reject: the caller must own the run they approve.
+     */
+    ownerOfToolCall(toolCallId: string): Promise<string | null>;
+    /**
+     * The runId currently streaming the thread a tool call belongs to (its thread's `activeStreamId`),
+     * or `null` if the call or its active run is unknown. HITL approve / reject route the decision to
+     * THIS run, derived server-side from the tool call alone — so a decision reaches the exact run
+     * awaiting it, including a sub-agent's own child run, which the client never sees and could not
+     * name. No client-supplied runId is trusted (or needed).
+     */
+    runForToolCall(toolCallId: string): Promise<string | null>;
+    /**
+     * The `actorRef` that owns the thread currently streaming `runId` (its `activeStreamId`), or
+     * `null` if no thread is streaming it. The authorization seam for `cancel`: the caller must own
+     * the run they abort. Resolvable during the live window (a run cancel only matters while active).
+     */
+    ownerOfActiveStream(runId: string): Promise<string | null>;
+    appendMessage(input: AppendMessageInput): Promise<StoredMessage>;
+    truncateFrom(threadId: string, messageId: string): Promise<void>;
+    recordToolCall(input: RecordToolCallInput): Promise<void>;
+    updateToolCall(input: UpdateToolCallInput): Promise<void>;
+    recordUsage(input: RecordUsageInput): Promise<void>;
+    quotaToday(actorRef: string, day: string): Promise<{
+        usedTokens: number;
+    }>;
+}
+
+/**
+ * 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.
+ */
+interface RolesPolicy {
+    /** May return a promise — an authz Gate (`gate.forUser(actor).allows(...)`) is async. */
+    can(actor: Actor, tool: ToolSpec): boolean | Promise<boolean>;
+}
+
+/**
+ * Per-actor/day token budget. `check` reports the day's usage against the limit before a turn;
+ * `bump` accounts a turn's tokens after it. Two impls ship: `InMemoryQuotaStore` (testing/offline)
+ * and the production `LedgerQuotaStore` (nestjs) which reads the persisted usage ledger — set
+ * `AgentModule.forRoot({ quotaLimitTokens })` to bind it, or supply your own for a bespoke budget.
+ */
+interface QuotaStore {
+    check(actorRef: string, day: string): Promise<QuotaState>;
+    /** Account a turn's tokens. A no-op for ledger-backed stores, which read `recordUsage` directly. */
+    bump(actorRef: string, day: string, tokens: number): Promise<void>;
+}
+
+/**
+ * The WRITE side of the pricing table the {@link import('./governance-queries.js').AgentGovernanceQueries}
+ * read-model prices usage against. Cost is $0 for an unpriced model, so an app seeds its models'
+ * per-1M rates once (and re-`upsert`s when a provider changes prices). A store adapter implements
+ * this; consumers inject via `AGENT_PRICING_STORE`. Use `seedModelPrices` for a one-shot batch.
+ */
+/** A per-1M-token price for one model. Cache rates fall back to the input rate when omitted. */
+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 timestamp it took effect. */
+interface CurrentModelPrice extends ModelPriceInput {
+    effectiveFrom: string;
+}
+interface AgentPricingStore {
+    /**
+     * Set the current price for a model. Atomic supersede: the model's prior `isCurrent` row (if any)
+     * is retired and this one is inserted as current, effective now — so the read-model always joins
+     * to exactly one live price per model, with no window where two rows race for `isCurrent`.
+     */
+    upsertModelPrice(input: ModelPriceInput): Promise<void>;
+    /** The current price row per model (`isCurrent`), for a pricing admin view. */
+    listCurrentPrices(): Promise<CurrentModelPrice[]>;
+}
+/** Seed (or refresh) a batch of model prices — one `upsertModelPrice` per row, in order. */
+declare function seedModelPrices(store: AgentPricingStore, prices: ModelPriceInput[]): Promise<void>;
+
+/**
+ * Retrieval seam for RAG. A `Retriever` is a black box — the agent runtime asks it for the passages
+ * most relevant to a query and never sees how (vector search, keyword, hybrid, a remote service).
+ * The `@dudousxd/nestjs-agent-rag` package ships an `EmbeddingRetriever` (embed + vector store) and
+ * store adapters, but any impl satisfying this SPI works. Wire it as a tool for agentic retrieval
+ * (`createRetrievalTool`), or for always-on injection via `AgentModule.forRoot({ retrieval })`.
+ */
+/** One retrieved passage. `source` is a human/citation-facing origin; `score` is impl-defined relevance. */
+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>;
+}
+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>;
+}
+interface Retriever {
+    retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+}
+
+/**
+ * Turns text into embedding vectors — the sibling of {@link import('./model-provider.js').ModelProvider}
+ * for the retrieval side. Batched (`texts` → one vector each, same order) so ingestion can embed many
+ * chunks per call. `@dudousxd/nestjs-agent-ai-sdk` implements it over the Vercel AI SDK `embedMany`;
+ * `@dudousxd/nestjs-agent-testing` ships a deterministic fake for offline tests.
+ */
+interface EmbeddingProvider {
+    /** Embed each input string; returns one vector per input, in the same order. */
+    embed(texts: string[]): Promise<number[][]>;
+}
+
+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. Compose it over any retriever with `RerankingRetriever` (over-fetch → rerank → topK).
+ */
+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[]>;
+}
+
+/**
+ * Runs an agent turn. Two impls exist:
+ *  - InlineAgentRunner (default): the loop runs in-process — no extra dependencies. This is what
+ *    `AGENT_RUNNER` binds to unless `durable: true` is set.
+ *  - DurableAgentRunner (opt-in via `durable: true`): the turn is a `@dudousxd/nestjs-durable`
+ *    `@Workflow`, so each model/tool call is a checkpointed step and HITL is `ctx.waitForSignal`.
+ *
+ * `start` ENQUEUES and returns immediately with the runId — the live tokens flow on the
+ * TokenStreamSink, not through this call.
+ */
+interface AgentRunner {
+    start(input: AgentRunInput): Promise<{
+        runId: string;
+    }>;
+    /** Deliver a HITL decision for a pending action tool call. */
+    signal(runId: string, toolCallId: string, decision: Decision): Promise<void>;
+    cancel(runId: string): Promise<void>;
+}
+
+/**
+ * Resolves the acting {@link Actor} for an inbound request. This is the identity seam:
+ * the agent NEVER fabricates a caller. Configure one via `AgentModule.forRoot({ actorResolver })`
+ * that reads your authenticated principal (session, JWT, `@dudousxd/nestjs-context`, ...).
+ *
+ * When no resolver is configured, the module installs one that throws on every request —
+ * 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`.
+ */
+interface ActorResolver {
+    resolve(req: unknown): Actor | Promise<Actor>;
+}
+
+/**
+ * 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`. */
+interface GovernanceRange {
+    fromDay: string;
+    toDay: string;
+}
+/** Spend + token totals for one model over a range. */
+interface ModelSpendRow {
+    modelId: string;
+    requests: number;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+}
+/** Spend + token totals for one acting ref (user/tenant) over a range. */
+interface ActorSpendRow {
+    actorRef: string;
+    requests: number;
+    totalTokens: number;
+    costUsd: number;
+}
+/** One point on the daily usage/cost trend. */
+interface UsageTrendPoint {
+    day: string;
+    totalTokens: number;
+    costUsd: number;
+}
+/** A recent tool-call for the activity feed. */
+interface ToolCallActivityRow {
+    toolCallId: string;
+    toolName: string;
+    toolType: string;
+    status: string;
+    threadId: string;
+    createdAt: string;
+}
+/** A recent thread with rolled-up activity. */
+interface ThreadActivityRow {
+    threadId: string;
+    title: string;
+    actorRef: string;
+    messageCount: number;
+    totalTokens: number;
+    lastActivityAt: string;
+}
+/**
+ * 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).
+ */
+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[]>;
+}
+
+/** 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 persona pins an allow-list, keep only those tool names. */
+declare function personaFilterTools(tools: ToolSpec[], allowedTools: string[] | undefined): ToolSpec[];
+
+/** Holds the named agent definitions registered via `AgentModule.forFeature([...])`. */
+declare class AgentRegistry {
+    private readonly definitions;
+    register(definition: AgentDefinition): void;
+    get(name: string): AgentDefinition | undefined;
+    has(name: string): boolean;
+    list(): AgentDefinition[];
+}
+
+/** Thrown when an actor invokes a tool their role is not allowed. */
+declare class ToolForbiddenError extends Error {
+    readonly toolName: string;
+    constructor(toolName: string);
+}
+/** Thrown when a tool is invoked that was never registered. */
+declare class ToolNotFoundError extends Error {
+    readonly toolName: string;
+    constructor(toolName: string);
+}
+/** Thrown when a tool's input fails its Standard Schema validation. */
+declare class ToolInputInvalidError extends Error {
+    readonly toolName: string;
+    readonly issues: readonly StandardSchemaV1.Issue[];
+    constructor(toolName: string, issues: readonly StandardSchemaV1.Issue[]);
+}
+/**
+ * Holds every registered tool and gates invocation.
+ *
+ * Note: `definitionsFor` returns NEUTRAL definitions (no `execute`). The agent loop runs
+ * each tool itself as a (durable) step — so even read tools are not auto-executed by the
+ * model. `action` tools additionally require HITL approval before the loop runs them.
+ */
+declare class ToolRegistry {
+    private readonly entries;
+    register(spec: ToolSpec, handler: ToolHandler): void;
+    has(name: string): boolean;
+    spec(name: string): ToolSpec | undefined;
+    allSpecs(): ToolSpec[];
+    /** The tools to offer the model for this actor+persona, after the two filter layers. */
+    definitionsFor(actor: Actor, policy: RolesPolicy, allowedTools?: string[]): Promise<ToolDefinition[]>;
+    /** Run a tool. Re-checks the role (defense-in-depth) and re-parses the input via Zod. */
+    invoke(name: string, input: unknown, ctx: AiToolCtx, policy: RolesPolicy): Promise<unknown>;
+}
+/** Default gate: one of the actor's roles must be in spec.roles (defaulting to ADMIN-only). */
+declare class DefaultRolesPolicy implements RolesPolicy {
+    private readonly defaultRoles;
+    constructor(defaultRoles?: string[]);
+    can(actor: Actor, tool: ToolSpec): boolean;
+}
+
+interface AgentLoopDeps {
+    model: ModelProvider;
+    store: AgentStore;
+    registry: ToolRegistry;
+    rolesPolicy: RolesPolicy;
+    quota?: QuotaStore;
+    /**
+     * Fallback accounting label when the provider's turn result doesn't report a `modelId`.
+     * Optional — a provider that reports its own model makes this unnecessary.
+     */
+    modelId?: string;
+    /** Pre-computed (YYYY-MM-DD) so the loop body stays deterministic under durable replay. */
+    day: string;
+    /** The agent's base prompt. A flat string, or a {@link PromptBuilder} resolved per turn. */
+    systemPrompt: string | PromptBuilder;
+    maxSteps?: number;
+    /** Optional host handle threaded to tool ctx (e.g. an ORM EntityManager). */
+    host?: unknown;
+    /** Agent-level tool allow-list (intersected with the persona's). Undefined → all tools. */
+    toolAllowList?: string[];
+    /**
+     * Per-tool execution timeout in ms. A tool that runs longer is aborted and recorded as failed
+     * (the model gets the timeout as its result and can adapt) rather than hanging the turn.
+     * Undefined → no timeout.
+     */
+    toolTimeoutMs?: number;
+    /**
+     * When set, after the final turn the loop makes one extra model call to propose up to this many
+     * short follow-up questions, stored on the assistant message's `followUps`. Costs an extra call
+     * (recorded as `follow_ups` usage). Undefined/0 → disabled.
+     */
+    followUpsCount?: number;
+    /**
+     * Enables always-on ("inject") RAG: before the turn, retrieve passages for the user message and
+     * augment the system prompt with them. Its presence IS inject mode — agentic (tool) retrieval sets
+     * no retriever here (it rides a normal `read` tool). Undefined → no injection.
+     */
+    retriever?: Retriever;
+    /** How many passages inject-mode retrieval requests. Undefined → 5. */
+    retrievalTopK?: number;
+}
+interface AgentLoopHooks {
+    runId: string;
+    /** A writer for this run's live token stream (data plane). */
+    openSink(): SinkWriter | Promise<SinkWriter>;
+    /** HITL gate for an action tool. Inline resolves a pending promise; durable awaits a signal. */
+    awaitApproval(call: ToolCallRequest, ctx: AiToolCtx): Promise<Decision>;
+    /**
+     * Run another named agent and return its answer. Provided only when the host wired multi-agent
+     * support (durable → child workflow, inline → nested loop). Exposed to tools as `ctx.runAgent`.
+     */
+    runAgent?(agentName: string, task: string): Promise<{
+        text: string;
+    }>;
+    /**
+     * Checkpoint wrapper. Inline = call fn directly; durable = ctx.step(name, fn).
+     * EVERY side-effect and control-flow read goes through this so durable replay returns
+     * cached results (stable ids, no double-write, no re-streaming).
+     */
+    step<T>(name: string, fn: () => Promise<T>): Promise<T>;
+}
+declare class QuotaExceededError extends Error {
+    constructor();
+}
+/**
+ * The provider-agnostic agent turn, reused by both the inline and durable runners.
+ * It drives the model→tools→model iteration; the runner supplies the `step`/`awaitApproval`
+ * hooks that make the same loop body either in-process or a replay-safe durable workflow.
+ */
+declare function runAgentLoop(deps: AgentLoopDeps, input: AgentRunInput, hooks: AgentLoopHooks): Promise<{
+    text: string;
+}>;
+
+/** Payloads carried on each `aviary:agent:*` channel. */
+interface AgentRunStarted {
+    runId: string;
+    threadId: string;
+    actorId: string;
+    persona?: string;
+}
+interface AgentMessageEvent {
+    runId: string;
+    threadId: string;
+    role: 'user' | 'assistant';
+    textLength: number;
+}
+interface AgentToolCallEvent {
+    runId: string;
+    toolName: string;
+    toolType: 'read' | 'action';
+    status: string;
+    durationMs?: number;
+}
+interface AgentQuotaExceeded {
+    actorId: string;
+    usedTokens: number;
+    limitTokens: number;
+}
+interface AgentRunFinished {
+    runId: string;
+    threadId: string;
+    steps: number;
+    inputTokens: number;
+    outputTokens: number;
+}
+interface AgentRunFailed {
+    runId: string;
+    /** Stable failure slug, e.g. `quota_exceeded` or `run_failed`. */
+    code: string;
+    message: string;
+}
+interface AgentDelegated {
+    runId: string;
+    fromAgent?: string;
+    toAgent: string;
+}
+interface AgentRetrieved {
+    runId: string;
+    query: string;
+    /** How many passages the retriever returned. */
+    count: number;
+}
+/** Declaration-merge so `emit('agent', ...)` and telescope infer the agent payloads. */
+declare module '@dudousxd/nestjs-diagnostics' {
+    interface ChannelRegistry {
+        agent: {
+            'run.started': AgentRunStarted;
+            message: AgentMessageEvent;
+            'tool-call': AgentToolCallEvent;
+            'quota.exceeded': AgentQuotaExceeded;
+            'run.finished': AgentRunFinished;
+            'run.failed': AgentRunFailed;
+            delegated: AgentDelegated;
+            retrieved: AgentRetrieved;
+        };
+    }
+}
+declare function publishAgentRunStarted(payload: AgentRunStarted): void;
+declare function publishAgentMessage(payload: AgentMessageEvent): void;
+declare function publishAgentToolCall(payload: AgentToolCallEvent): void;
+declare function publishAgentQuotaExceeded(payload: AgentQuotaExceeded): void;
+declare function publishAgentRunFinished(payload: AgentRunFinished): void;
+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_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 Persona, type PromptBuilder, type PromptContext, QuotaExceededError, type QuotaState, type QuotaStore, 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, filterToolsByRole, personaFilterTools, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };