@dudousxd/nestjs-agent-core 0.3.2 → 0.4.0

package/dist/index.d.cts

@@ -48,6 +48,13 @@ interface ToolCallRequest {
     id: string;
     name: string;
     input: unknown;
+    /**
+     * The tool's declared kind (`ToolSpec.kind`), stamped by the loop from the tool registry so
+     * thread-read consumers know a call's kind without hardcoding a tool-name allowlist. Undefined
+     * only for a call the loop couldn't resolve against the registry (defensively treated as `read`
+     * wherever a definite value is required).
+     */
+    kind?: ToolKind;
 }
 /** Result of running a tool. */
 interface ToolResult {
@@ -82,6 +89,13 @@ interface MessageUsage {
      * non-reasoning models or providers that don't report it.
      */
     reasoningTokens?: number;
+    /**
+     * This turn's USD cost: the provider's own reported figure when it has one, else an estimate from
+     * the bound `AgentPricingStore` (cached once per run — see `AgentLoopDeps.pricingStore`), else
+     * `null` when no pricing store is bound or the model has no price row. Never `0` for an unpriced
+     * model — a real $0 turn and "we don't know" must stay distinguishable.
+     */
+    costUsd?: number | null;
 }
 type UsagePurpose = 'chat' | 'follow_ups';
 interface QuotaState {
@@ -107,12 +121,30 @@ interface Decision {
     reason?: string;
 }
 type MessageRole = 'user' | 'assistant' | 'system';
+/**
+ * A file a user attached to a message so a vision-capable model sees it natively (an image, a PDF).
+ * The lib stays provider-agnostic: it passes {@link MessageAttachment.url} straight through as the
+ * model's image/file part data — making that URL reachable by the provider (presigned S3, a proxy)
+ * is the consumer's job. The lib never fetches bytes or talks to a store.
+ */
+interface MessageAttachment {
+    /** Stable id of the stored media object in the consumer's media store. Provenance + replay key. */
+    mediaId: string;
+    /** A URL the model provider can fetch the bytes from at turn time. */
+    url: string;
+    /** MIME type — routes the part: `image/*` → image part, otherwise → file part. */
+    contentType: string;
+    /** Original filename, for display and the file part's filename. */
+    name: string;
+}
 /** A neutral chat message exchanged with the model. */
 interface ModelMessage {
     role: MessageRole;
     content: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
+    /** User-message attachments (image/PDF), rendered as native model content parts by the adapter. */
+    attachments?: MessageAttachment[];
 }
 interface PageContext {
     kind?: string;
@@ -148,6 +180,8 @@ interface AgentRunInput {
     actor: Actor;
     /** The latest user message text. */
     userText: string;
+    /** Files attached to the latest user message (image/PDF). Persisted with it and sent to the model. */
+    attachments?: MessageAttachment[];
     pageContext?: PageContext;
     /** YYYY-MM-DD stamped by the runner so quota/day stays deterministic under durable replay. */
     day?: string;
@@ -209,6 +243,18 @@ interface ThreadSummary {
     createdAt: string;
     updatedAt: string;
     lastMessagePreview?: string;
+    /**
+     * The agent a `chat()` call on this thread uses when the caller doesn't name one explicitly.
+     * Optional — undefined for a store that doesn't implement `AgentStore.updateThread` (the only
+     * way to set it). The REST/service read-model normalizes this to `null` when absent.
+     */
+    defaultAgent?: string | null;
+    /**
+     * The runId of a currently-running turn on this thread, or `null` if none is running. Optional —
+     * undefined for a store that doesn't implement `AgentStore.activeRunForThread`. The REST/service
+     * read-model normalizes this to `null` when absent, so a client can always do `?? null`.
+     */
+    activeRunId?: string | null;
 }
 interface StoredMessage {
     id: string;
@@ -218,6 +264,8 @@ interface StoredMessage {
     agentName?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
+    /** Files the user attached to this message (image/PDF). Persisted with the message, replayed as-is. */
+    attachments?: MessageAttachment[];
     followUps?: string[];
     usage?: MessageUsage;
     createdAt: string;
@@ -266,6 +314,17 @@ declare const AGENT_EMBEDDING_PROVIDER: unique symbol;
 declare const AGENT_DEPS_FACTORY: unique symbol;
 /** App-wide, ordered `@SystemPromptContributor()` functions the loop appends after the agent base. */
 declare const AGENT_PROMPT_CONTRIBUTORS: unique symbol;
+/**
+ * Resolves opaque store `actorRef`s to human display labels for governance/dashboard read surfaces.
+ * Optional — see {@link import('./spi/actor-directory.js').ActorDirectory}.
+ */
+declare const AGENT_ACTOR_DIRECTORY: unique symbol;
+/**
+ * Persists an uploaded attachment somewhere the model can fetch it from and returns a
+ * `MessageAttachment`. Optional — see
+ * {@link import('./spi/attachment-staging.js').AttachmentStagingStore}.
+ */
+declare const AGENT_ATTACHMENT_STAGING: unique symbol;
 
 /**
  * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
@@ -371,6 +430,67 @@ interface ModelProvider {
     runTurn(args: ModelTurnArgs): Promise<ModelTurnResult>;
 }
 
+/**
+ * The structured live-stream vocabulary carried over the {@link SinkWriter} byte channel.
+ *
+ * The model turn (via the AI-SDK adapter) and the agent loop write these events as NDJSON — one
+ * `JSON.stringify(event)\n` per {@link SinkWriter.write}. The HTTP layer forwards each line as an
+ * SSE `data:` frame, and the client transport maps them back to the AI SDK UI-message chunk
+ * protocol so the browser renders text, reasoning, and tool cards (input + output) LIVE — the same
+ * rich rendering a raw `streamText().toUIMessageStream()` would give, but reconstructed on the
+ * client so the sink stays a format-agnostic byte buffer (durable buffering/replay is untouched).
+ *
+ * Keeping this vocabulary neutral (not AI-SDK `UIMessageChunk`) means core never depends on `ai`:
+ * the adapter owns model-parts → event, the transport owns event → UI-chunk.
+ */
+
+type AgentStreamEvent = {
+    kind: 'step-start';
+}
+/**
+ * Closes the step opened by the matching `step-start`. Carries the model call's token usage and
+ * `costUsd` (an estimate from the bound pricing store, or `null` when unpriced/unbound — never a
+ * fabricated `0`) so a live client can render running cost without waiting for a thread re-fetch.
+ */
+ | {
+    kind: 'step-finish';
+    usage?: MessageUsage;
+    costUsd?: number | null;
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'reasoning';
+    text: string;
+}
+/** `toolKind` collapses `ToolKind`'s `'agent'` into `'read'` — delegation tools auto-execute like a read tool. */
+ | {
+    kind: 'tool-input-start';
+    id: string;
+    name: string;
+    toolKind: 'read' | 'action';
+} | {
+    kind: 'tool-input-delta';
+    id: string;
+    delta: string;
+} | {
+    kind: 'tool-input-available';
+    id: string;
+    name: string;
+    input: unknown;
+    toolKind: 'read' | 'action';
+} | {
+    kind: 'tool-output';
+    id: string;
+    output: unknown;
+} | {
+    kind: 'tool-output-error';
+    id: string;
+    error: string;
+};
+/** Encode one event as an NDJSON line (`{...}\n`) for {@link SinkWriter.write}. */
+declare function encodeStreamEvent(event: AgentStreamEvent): Uint8Array;
+
 interface CreateThreadInput {
     actor: Actor;
     transient?: boolean;
@@ -384,6 +504,8 @@ interface AppendMessageInput {
     agentName?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
+    /** Files the user attached to this message (image/PDF). Persisted verbatim. */
+    attachments?: MessageAttachment[];
     followUps?: string[];
     usage?: MessageUsage;
 }
@@ -403,6 +525,12 @@ interface UpdateToolCallInput {
     executionMs?: number;
     executedByRef?: string;
 }
+/** Patch applied by {@link AgentStore.updateThread}. An omitted key leaves that field untouched. */
+interface UpdateThreadInput {
+    title?: string;
+    /** `null` clears the thread's default agent (falls back to the module default). */
+    defaultAgent?: string | null;
+}
 interface RecordUsageInput {
     threadId: string;
     actorRef: string;
@@ -428,6 +556,20 @@ interface AgentStore {
      */
     promoteThread(threadId: string): Promise<void>;
     setActiveStream(threadId: string, runId: string | null): Promise<void>;
+    /**
+     * OPTIONAL: rename a thread and/or set its default agent in one write. Absent on a store that
+     * predates this — `setTitle` still covers title-only edits, so nothing else in the lib requires
+     * this method; the REST `PATCH /threads/:id` endpoint responds 501 for a `defaultAgent` change
+     * against a store that lacks it.
+     */
+    updateThread?(threadId: string, patch: UpdateThreadInput): Promise<void>;
+    /**
+     * OPTIONAL: the runId of a currently-running turn on this thread, or `null` if none is running.
+     * Lets a client that reconnects (page refresh) discover a run to reattach to via the existing
+     * `GET /chat/:runId/stream`, instead of only being told about a run right after starting it.
+     * Absent on a store that predates this — thread read/list payloads report `activeRunId: null`.
+     */
+    activeRunForThread?(threadId: string): Promise<string | null>;
     /**
      * 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
@@ -695,6 +837,45 @@ interface AgentGovernanceQueries {
     recentThreads(limit: number): Promise<ThreadActivityRow[]>;
 }
 
+/**
+ * Optional read-side lookup from opaque store `actorRef`s to human display labels.
+ *
+ * The store keeps `actorRef` opaque by design (no FK into the host's user table — hosts own their
+ * own identity schema). That's fine for enforcement and accounting, but a governance/dashboard read
+ * surface showing a raw ref ("u_8f21...") instead of a name is a bad experience. Binding an
+ * `ActorDirectory` lets those surfaces resolve refs to labels; leaving it unbound just means they
+ * render the raw ref. Consumers inject via `AGENT_ACTOR_DIRECTORY`.
+ */
+interface ActorDirectory {
+    /** Resolve opaque actor refs to display labels. Missing refs may be omitted. */
+    resolveDisplay(refs: readonly string[]): Promise<Record<string, string>>;
+}
+
+/** Input to {@link AttachmentStagingStore.stage} — the raw bytes plus who uploaded them. */
+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; consumers inject via `AGENT_ATTACHMENT_STAGING`. Unbound, the optional `POST /agent/attachments`
+ * upload controller is never mounted.
+ */
+interface AttachmentStagingStore {
+    /**
+     * Persist an uploaded file somewhere the model can later fetch (presigned URL etc.) 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>;
+}
+
 /**
  * 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
@@ -864,6 +1045,12 @@ interface AgentLoopDeps {
     retriever?: Retriever;
     /** How many passages inject-mode retrieval requests. Undefined → 5. */
     retrievalTopK?: number;
+    /**
+     * Prices each step's token usage into `costUsd` (on the `step-finish` stream frame and the
+     * persisted assistant message's `usage`). The current price list is fetched ONCE per run (not per
+     * message/step) and reused for every step's estimate. Undefined → `costUsd` is always `null`.
+     */
+    pricingStore?: AgentPricingStore;
 }
 interface AgentLoopHooks {
     runId: string;
@@ -971,4 +1158,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 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 };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_ATTACHMENT_STAGING, 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 ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type SinkWriter, type StageAttachmentInput, 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 UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };

package/dist/index.d.ts

@@ -48,6 +48,13 @@ interface ToolCallRequest {
     id: string;
     name: string;
     input: unknown;
+    /**
+     * The tool's declared kind (`ToolSpec.kind`), stamped by the loop from the tool registry so
+     * thread-read consumers know a call's kind without hardcoding a tool-name allowlist. Undefined
+     * only for a call the loop couldn't resolve against the registry (defensively treated as `read`
+     * wherever a definite value is required).
+     */
+    kind?: ToolKind;
 }
 /** Result of running a tool. */
 interface ToolResult {
@@ -82,6 +89,13 @@ interface MessageUsage {
      * non-reasoning models or providers that don't report it.
      */
     reasoningTokens?: number;
+    /**
+     * This turn's USD cost: the provider's own reported figure when it has one, else an estimate from
+     * the bound `AgentPricingStore` (cached once per run — see `AgentLoopDeps.pricingStore`), else
+     * `null` when no pricing store is bound or the model has no price row. Never `0` for an unpriced
+     * model — a real $0 turn and "we don't know" must stay distinguishable.
+     */
+    costUsd?: number | null;
 }
 type UsagePurpose = 'chat' | 'follow_ups';
 interface QuotaState {
@@ -107,12 +121,30 @@ interface Decision {
     reason?: string;
 }
 type MessageRole = 'user' | 'assistant' | 'system';
+/**
+ * A file a user attached to a message so a vision-capable model sees it natively (an image, a PDF).
+ * The lib stays provider-agnostic: it passes {@link MessageAttachment.url} straight through as the
+ * model's image/file part data — making that URL reachable by the provider (presigned S3, a proxy)
+ * is the consumer's job. The lib never fetches bytes or talks to a store.
+ */
+interface MessageAttachment {
+    /** Stable id of the stored media object in the consumer's media store. Provenance + replay key. */
+    mediaId: string;
+    /** A URL the model provider can fetch the bytes from at turn time. */
+    url: string;
+    /** MIME type — routes the part: `image/*` → image part, otherwise → file part. */
+    contentType: string;
+    /** Original filename, for display and the file part's filename. */
+    name: string;
+}
 /** A neutral chat message exchanged with the model. */
 interface ModelMessage {
     role: MessageRole;
     content: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
+    /** User-message attachments (image/PDF), rendered as native model content parts by the adapter. */
+    attachments?: MessageAttachment[];
 }
 interface PageContext {
     kind?: string;
@@ -148,6 +180,8 @@ interface AgentRunInput {
     actor: Actor;
     /** The latest user message text. */
     userText: string;
+    /** Files attached to the latest user message (image/PDF). Persisted with it and sent to the model. */
+    attachments?: MessageAttachment[];
     pageContext?: PageContext;
     /** YYYY-MM-DD stamped by the runner so quota/day stays deterministic under durable replay. */
     day?: string;
@@ -209,6 +243,18 @@ interface ThreadSummary {
     createdAt: string;
     updatedAt: string;
     lastMessagePreview?: string;
+    /**
+     * The agent a `chat()` call on this thread uses when the caller doesn't name one explicitly.
+     * Optional — undefined for a store that doesn't implement `AgentStore.updateThread` (the only
+     * way to set it). The REST/service read-model normalizes this to `null` when absent.
+     */
+    defaultAgent?: string | null;
+    /**
+     * The runId of a currently-running turn on this thread, or `null` if none is running. Optional —
+     * undefined for a store that doesn't implement `AgentStore.activeRunForThread`. The REST/service
+     * read-model normalizes this to `null` when absent, so a client can always do `?? null`.
+     */
+    activeRunId?: string | null;
 }
 interface StoredMessage {
     id: string;
@@ -218,6 +264,8 @@ interface StoredMessage {
     agentName?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
+    /** Files the user attached to this message (image/PDF). Persisted with the message, replayed as-is. */
+    attachments?: MessageAttachment[];
     followUps?: string[];
     usage?: MessageUsage;
     createdAt: string;
@@ -266,6 +314,17 @@ declare const AGENT_EMBEDDING_PROVIDER: unique symbol;
 declare const AGENT_DEPS_FACTORY: unique symbol;
 /** App-wide, ordered `@SystemPromptContributor()` functions the loop appends after the agent base. */
 declare const AGENT_PROMPT_CONTRIBUTORS: unique symbol;
+/**
+ * Resolves opaque store `actorRef`s to human display labels for governance/dashboard read surfaces.
+ * Optional — see {@link import('./spi/actor-directory.js').ActorDirectory}.
+ */
+declare const AGENT_ACTOR_DIRECTORY: unique symbol;
+/**
+ * Persists an uploaded attachment somewhere the model can fetch it from and returns a
+ * `MessageAttachment`. Optional — see
+ * {@link import('./spi/attachment-staging.js').AttachmentStagingStore}.
+ */
+declare const AGENT_ATTACHMENT_STAGING: unique symbol;
 
 /**
  * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
@@ -371,6 +430,67 @@ interface ModelProvider {
     runTurn(args: ModelTurnArgs): Promise<ModelTurnResult>;
 }
 
+/**
+ * The structured live-stream vocabulary carried over the {@link SinkWriter} byte channel.
+ *
+ * The model turn (via the AI-SDK adapter) and the agent loop write these events as NDJSON — one
+ * `JSON.stringify(event)\n` per {@link SinkWriter.write}. The HTTP layer forwards each line as an
+ * SSE `data:` frame, and the client transport maps them back to the AI SDK UI-message chunk
+ * protocol so the browser renders text, reasoning, and tool cards (input + output) LIVE — the same
+ * rich rendering a raw `streamText().toUIMessageStream()` would give, but reconstructed on the
+ * client so the sink stays a format-agnostic byte buffer (durable buffering/replay is untouched).
+ *
+ * Keeping this vocabulary neutral (not AI-SDK `UIMessageChunk`) means core never depends on `ai`:
+ * the adapter owns model-parts → event, the transport owns event → UI-chunk.
+ */
+
+type AgentStreamEvent = {
+    kind: 'step-start';
+}
+/**
+ * Closes the step opened by the matching `step-start`. Carries the model call's token usage and
+ * `costUsd` (an estimate from the bound pricing store, or `null` when unpriced/unbound — never a
+ * fabricated `0`) so a live client can render running cost without waiting for a thread re-fetch.
+ */
+ | {
+    kind: 'step-finish';
+    usage?: MessageUsage;
+    costUsd?: number | null;
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'reasoning';
+    text: string;
+}
+/** `toolKind` collapses `ToolKind`'s `'agent'` into `'read'` — delegation tools auto-execute like a read tool. */
+ | {
+    kind: 'tool-input-start';
+    id: string;
+    name: string;
+    toolKind: 'read' | 'action';
+} | {
+    kind: 'tool-input-delta';
+    id: string;
+    delta: string;
+} | {
+    kind: 'tool-input-available';
+    id: string;
+    name: string;
+    input: unknown;
+    toolKind: 'read' | 'action';
+} | {
+    kind: 'tool-output';
+    id: string;
+    output: unknown;
+} | {
+    kind: 'tool-output-error';
+    id: string;
+    error: string;
+};
+/** Encode one event as an NDJSON line (`{...}\n`) for {@link SinkWriter.write}. */
+declare function encodeStreamEvent(event: AgentStreamEvent): Uint8Array;
+
 interface CreateThreadInput {
     actor: Actor;
     transient?: boolean;
@@ -384,6 +504,8 @@ interface AppendMessageInput {
     agentName?: string;
     toolCalls?: ToolCallRequest[];
     toolResults?: ToolResult[];
+    /** Files the user attached to this message (image/PDF). Persisted verbatim. */
+    attachments?: MessageAttachment[];
     followUps?: string[];
     usage?: MessageUsage;
 }
@@ -403,6 +525,12 @@ interface UpdateToolCallInput {
     executionMs?: number;
     executedByRef?: string;
 }
+/** Patch applied by {@link AgentStore.updateThread}. An omitted key leaves that field untouched. */
+interface UpdateThreadInput {
+    title?: string;
+    /** `null` clears the thread's default agent (falls back to the module default). */
+    defaultAgent?: string | null;
+}
 interface RecordUsageInput {
     threadId: string;
     actorRef: string;
@@ -428,6 +556,20 @@ interface AgentStore {
      */
     promoteThread(threadId: string): Promise<void>;
     setActiveStream(threadId: string, runId: string | null): Promise<void>;
+    /**
+     * OPTIONAL: rename a thread and/or set its default agent in one write. Absent on a store that
+     * predates this — `setTitle` still covers title-only edits, so nothing else in the lib requires
+     * this method; the REST `PATCH /threads/:id` endpoint responds 501 for a `defaultAgent` change
+     * against a store that lacks it.
+     */
+    updateThread?(threadId: string, patch: UpdateThreadInput): Promise<void>;
+    /**
+     * OPTIONAL: the runId of a currently-running turn on this thread, or `null` if none is running.
+     * Lets a client that reconnects (page refresh) discover a run to reattach to via the existing
+     * `GET /chat/:runId/stream`, instead of only being told about a run right after starting it.
+     * Absent on a store that predates this — thread read/list payloads report `activeRunId: null`.
+     */
+    activeRunForThread?(threadId: string): Promise<string | null>;
     /**
      * 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
@@ -695,6 +837,45 @@ interface AgentGovernanceQueries {
     recentThreads(limit: number): Promise<ThreadActivityRow[]>;
 }
 
+/**
+ * Optional read-side lookup from opaque store `actorRef`s to human display labels.
+ *
+ * The store keeps `actorRef` opaque by design (no FK into the host's user table — hosts own their
+ * own identity schema). That's fine for enforcement and accounting, but a governance/dashboard read
+ * surface showing a raw ref ("u_8f21...") instead of a name is a bad experience. Binding an
+ * `ActorDirectory` lets those surfaces resolve refs to labels; leaving it unbound just means they
+ * render the raw ref. Consumers inject via `AGENT_ACTOR_DIRECTORY`.
+ */
+interface ActorDirectory {
+    /** Resolve opaque actor refs to display labels. Missing refs may be omitted. */
+    resolveDisplay(refs: readonly string[]): Promise<Record<string, string>>;
+}
+
+/** Input to {@link AttachmentStagingStore.stage} — the raw bytes plus who uploaded them. */
+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; consumers inject via `AGENT_ATTACHMENT_STAGING`. Unbound, the optional `POST /agent/attachments`
+ * upload controller is never mounted.
+ */
+interface AttachmentStagingStore {
+    /**
+     * Persist an uploaded file somewhere the model can later fetch (presigned URL etc.) 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>;
+}
+
 /**
  * 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
@@ -864,6 +1045,12 @@ interface AgentLoopDeps {
     retriever?: Retriever;
     /** How many passages inject-mode retrieval requests. Undefined → 5. */
     retrievalTopK?: number;
+    /**
+     * Prices each step's token usage into `costUsd` (on the `step-finish` stream frame and the
+     * persisted assistant message's `usage`). The current price list is fetched ONCE per run (not per
+     * message/step) and reused for every step's estimate. Undefined → `costUsd` is always `null`.
+     */
+    pricingStore?: AgentPricingStore;
 }
 interface AgentLoopHooks {
     runId: string;
@@ -971,4 +1158,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 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 };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_ATTACHMENT_STAGING, 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 ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type SinkWriter, type StageAttachmentInput, 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 UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices };