@dudousxd/nestjs-agent 1.27.1 → 1.28.0

package/dist/index-CBO7egb7.d.ts

@@ -0,0 +1,619 @@
+import { A2uiStreamOptions } from '@dudousxd/nestjs-agent-core/a2ui';
+import { AgentAttachmentConfig, AttachmentStagingStore, AgentStore, Actor, ListActionProposals, ActionProposalView, ActionProposalMutationView, TextActionProposalVocabulary, AgentRunner, ModelCatalog, QuotaProvider, ActionApprovalMode, MessageAttachment, QuotaReport, ModelCatalogView, AgentHostContext, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver } from '@dudousxd/nestjs-agent-core';
+import { Request, Response } from 'express';
+import { UiCapabilities } from '@dudousxd/nestjs-agent-core/genui';
+import { b as AgentModuleOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter } from './chat-queue.service-B-fVOJGf.js';
+
+/** Default per-file size cap (20 MiB). */
+declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
+/** Default allowlist: what multimodal model providers commonly accept as native image/file parts. */
+declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
+/** How many attachments one message may name. */
+declare const MAX_ATTACHMENTS_PER_MESSAGE = 10;
+/** The attachment rules in force — `AgentAttachmentConfig`, as `GET <base>/config` serves it. */
+type AttachmentLimits = AgentAttachmentConfig;
+/**
+ * One source for attachment limits: the staging store's own `describe()` when it declares them
+ * (`AgentMediaAttachmentsModule` does), else `AgentModule`'s `attachments` option, else the defaults.
+ */
+declare function attachmentLimits(options: Pick<AgentModuleOptions, 'attachments'> | undefined, staging: AttachmentStagingStore | undefined): AttachmentLimits;
+
+declare class ActionProposalService {
+    private readonly store;
+    private readonly options;
+    constructor(store: AgentStore, options: Pick<AgentModuleOptions, 'approvalPolicy' | 'actionProposalText'>);
+    /** The words a text decision is made of, and what the agent answers — English unless configured. */
+    private readonly vocabulary;
+    private readonly replies;
+    private hasCapability;
+    private capability;
+    private scope;
+    private mayDecide;
+    /**
+     * One page of a thread's proposals this actor may see. A store without the proposal capability
+     * can only run blocking approvals, so a thread there has no proposals: an empty, final page rather
+     * than `501` — a client that lists by default (React's `useAgentChat`) needs no flag. Deciding one
+     * still answers `501`.
+     */
+    listPage(threadId: string, actor: Actor, query?: Pick<ListActionProposals, 'after'>): Promise<{
+        items: ActionProposalView[];
+        next?: NonNullable<ListActionProposals['after']>;
+    }>;
+    list(threadId: string, actor: Actor): Promise<ActionProposalView[]>;
+    decide(threadId: string, proposalId: string, actor: Actor, command: {
+        decision: 'approved' | 'rejected';
+        remember?: boolean;
+        reason?: string;
+        via?: string;
+    }): Promise<ActionProposalMutationView>;
+    handleTextDecision(threadId: string, actor: Actor, text: string): Promise<{
+        status: "unmatched";
+    } | {
+        threadId: string;
+        proposalDecision: ActionProposalMutationView;
+        text: string;
+    } | {
+        threadId: string;
+        proposalDecision: {
+            status: "ambiguous";
+            proposalIds: string[];
+        };
+        text: string;
+    }>;
+    private textReceipt;
+    /** The configured words a text decision is made of (`actionProposalText.vocabulary`). */
+    textVocabulary(): TextActionProposalVocabulary;
+    /** The configured reply to a decision the store answered with `result`. */
+    reply(result: Pick<ActionProposalMutationView, 'status' | 'proposal'>, decision: 'approved' | 'rejected'): string;
+}
+
+/**
+ * What a send does when its thread already has a turn running:
+ *  - `'auto'` (default) — run now when the thread is idle, else wait in the thread's queue.
+ *  - `'queue'` — always wait in the queue, behind whatever is already waiting (it still starts at
+ *    once when nothing is running and nothing is ahead of it).
+ *  - `'interrupt'` — cancel the running turn and run this one next, ahead of the queue.
+ */
+type ChatSendMode = 'auto' | 'queue' | 'interrupt';
+/** A send that is waiting in its thread's queue instead of running. */
+interface QueuedSend {
+    threadId: string;
+    queued: true;
+    /** The queued message's id — also the run id it will start under. */
+    messageId: string;
+    /** 0-based place in the queue at the time it was queued (`0` → next). */
+    position: number;
+    queue: ChatQueueState;
+    /** The turn it started under, when it started straight away (an idle thread). */
+    runId?: string;
+    /** The run an interrupt cancelled to make room for it. */
+    interrupting?: string;
+}
+/** What {@link AgentService.send} did: started a turn, or queued the message. */
+type ChatSendResult = {
+    runId: string;
+    threadId: string;
+    queued?: undefined;
+} | QueuedSend | {
+    threadId: string;
+    proposalDecision: unknown;
+    text: string;
+    queued?: undefined;
+};
+/** The code of the `400` a send with nothing to answer gets (also AG-UI's, for the same case). */
+declare const NO_USER_MESSAGE_CODE = "no_user_message";
+interface ChatParams {
+    uiCapabilities?: UiCapabilities;
+    actor: Actor;
+    message: string;
+    /** The host's own facts about this send — see `AgentRunInput.hostContext`. */
+    hostContext?: AgentHostContext;
+    /**
+     * The HOST already decided this actor may write this thread — a chat-app thread several people
+     * share, where anyone in it may continue the conversation. Skips the thread-ownership check of a
+     * send; never set it from a request's own claim.
+     */
+    authorized?: boolean;
+    threadId?: string;
+    agentName?: string;
+    /**
+     * Run this turn under one of the agent's personas (`@Agent({ personas })`), and pin it on the
+     * thread so later sends that name none keep it. Refused (400 `persona_not_found`) unless the agent
+     * declares it. Omitted → the thread's pinned persona, else the agent's `defaultPersona`, else none.
+     */
+    personaId?: string;
+    /**
+     * Files attached to this message (image/PDF) for a vision-capable model, named by the `mediaId`
+     * the upload returned. Only the id is read: the url, content type and name are resolved from the
+     * bound {@link AttachmentStagingStore}, so nothing a caller says decides what the model fetches.
+     */
+    attachments?: AttachmentRef[];
+    pageContext?: PageContext;
+    /** Re-run the last exchange instead of adding a new message. Requires an existing `threadId`. */
+    regenerate?: boolean;
+    /**
+     * Run this turn on a catalog model instead of the thread's pinned one (or the provider default).
+     * Refused (400) unless the bound `ModelCatalog` lists it as available to this actor and agent.
+     */
+    model?: string;
+    /**
+     * When creating a thread (no `threadId`), start it transient — a scratch conversation hidden from
+     * the thread list until the caller promotes it. Ignored when `threadId` is set.
+     */
+    transient?: boolean;
+    /** What to do when the thread already has a turn running — see {@link ChatSendMode}. */
+    mode?: ChatSendMode;
+    /**
+     * When creating a thread (no `threadId`), ask the store to create it under this id — the id an
+     * AG-UI consumer named the conversation with. A store may ignore it (`CreateThreadInput.id`); the
+     * thread's real id is always the one on the result.
+     */
+    newThreadId?: string;
+}
+/**
+ * A store that can answer a thread's default agent on its own, without materializing the thread.
+ *
+ * Probed STRUCTURALLY rather than declared on `AgentStore`: the projection is an optimization a
+ * store either offers or doesn't, and a store that predates it still answers correctly through
+ * `getThread`. Every adapter in this repo implements it.
+ */
+interface ThreadDefaultAgentReader {
+    defaultAgentForThread(threadId: string): Promise<string | null>;
+}
+/** Like {@link ThreadDefaultAgentReader}, for the thread's pinned model. */
+interface ThreadModelReader {
+    modelForThread(threadId: string): Promise<string | null>;
+}
+/** The orchestration facade the controllers call. */
+declare class AgentService {
+    private readonly runner;
+    private readonly store;
+    private readonly deps;
+    private readonly staging?;
+    private readonly models?;
+    private readonly quotaProvider?;
+    private readonly options?;
+    private readonly queue?;
+    private readonly proposals?;
+    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota" | "actionApprovalMode" | "attachments"> | undefined, queue?: ChatQueueService | undefined, proposals?: ActionProposalService | undefined);
+    /**
+     * Decide one independent proposal through the scoped proposal service — what the native
+     * `action-proposals/:id/approve|reject` routes call — and the reply to show for it. `404` when
+     * proposals are not on, `403`/`404` when this actor may not decide it.
+     */
+    decideActionProposal(actor: Actor, threadId: string, proposalId: string, command: {
+        decision: 'approved' | 'rejected';
+        remember?: boolean;
+        reason?: string;
+        via: string;
+    }): Promise<{
+        proposalDecision: ActionProposalMutationView;
+        text: string;
+    }>;
+    handleTextDecision(threadId: string, actor: Actor, text: string): Promise<{
+        status: "unmatched";
+    } | {
+        threadId: string;
+        proposalDecision: ActionProposalMutationView;
+        text: string;
+    } | {
+        threadId: string;
+        proposalDecision: {
+            status: "ambiguous";
+            proposalIds: string[];
+        };
+        text: string;
+    }>;
+    /** How `action` tools wait for their approval here — `AgentModule.forRoot({ actionApprovalMode })`. */
+    actionApprovalMode(): ActionApprovalMode;
+    /**
+     * The words a text decision is made of (`actionProposalText.vocabulary`, English by default) — what
+     * a surface without buttons tells the person to reply.
+     */
+    actionProposalVocabulary(): TextActionProposalVocabulary;
+    /** The configured reply (`actionProposalText.replies`) to a decision the store answered with `result`. */
+    actionProposalReply(result: Pick<ActionProposalMutationView, 'status' | 'proposal'>, decision: 'approved' | 'rejected'): string;
+    /**
+     * The proposals of a thread this actor may see — the thread's own actor, or one the policy lets
+     * decide them; what `GET <base>/threads/:threadId/action-proposals` serves (its first page).
+     * Without independent approvals (the default blocking mode) there are none, so the read answers an
+     * empty list rather than refusing; deciding one still refuses.
+     */
+    listActionProposals(actor: Actor, threadId: string): Promise<ActionProposalView[]>;
+    /**
+     * The attachment rules in force — what `GET <base>/config` serves and `POST <base>/attachments`
+     * enforces. `enabled: false` when no `AGENT_ATTACHMENT_STAGING` provider is bound.
+     */
+    attachmentLimits(): AttachmentLimits;
+    /**
+     * Stage a file for a later turn, held to the same limits as `POST <base>/attachments` — for a
+     * surface that receives files itself (a messaging webhook). Refuses with `501` when attachments are
+     * off, `415` for a type outside the allowlist and `413` past the size cap; send the returned
+     * `mediaId` as `attachments: [{ mediaId }]`.
+     */
+    stageAttachment(actor: Actor, file: {
+        data: Buffer;
+        contentType: string;
+        filename: string;
+    }): Promise<MessageAttachment>;
+    /** The queue service when the bound store can hold a queue, else `undefined`. */
+    private queueing;
+    /** The queue service, or a 501 naming what is missing. */
+    private requireQueue;
+    /**
+     * The actor's budget across windows (`GET <base>/quota`) — the bound {@link QuotaProvider}'s
+     * report. Without one (a service built outside the module), a day window from the ledger.
+     */
+    quotaReport(actor: Actor): Promise<QuotaReport>;
+    /**
+     * Refuse a turn the actor's budget no longer covers — only when the host configured one
+     * (`quota`): the default report is informational.
+     */
+    private assertWithinQuota;
+    /**
+     * The models `actor` may pick for `agent` (`GET <base>/models`). An empty catalog when none is
+     * bound, so a picker simply has nothing to offer.
+     */
+    listModels(actor: Actor, agent?: string): Promise<ModelCatalogView>;
+    /**
+     * `model` if the catalog offers it to this actor and agent right now, else a 400 naming why. The
+     * one gate every model choice passes — a send's own, and a thread's pinned one at the moment it is
+     * pinned and again at every turn that runs on it (availability can change in between).
+     */
+    private assertModelAllowed;
+    /**
+     * The model a turn runs on: the send's own (that turn only — it is never stored on the thread),
+     * else the thread's pinned one, else none. An agent the catalog locks to one model runs on it
+     * whatever was sent or pinned, and a send naming another model is refused.
+     */
+    private resolveModel;
+    private threadModel;
+    /**
+     * Start a turn — for in-process callers that need a run id back. A send that would have to wait
+     * (its thread already has a turn running) is refused with `409` instead; {@link send} is the form
+     * that queues it.
+     */
+    chat(params: ChatParams): Promise<{
+        runId: string;
+        threadId: string;
+    }>;
+    /**
+     * Send a message: start a turn, or — when its thread already has one running — queue the message
+     * to run after it (see {@link ChatSendMode}). What `POST <base>/chat` calls.
+     */
+    send(claimed: ChatParams, sendOptions?: {
+        textDecisions?: boolean;
+    }): Promise<ChatSendResult>;
+    /**
+     * Start a turn the thread is already claimed for, under the claimed id. A runner that minted an
+     * id of its own anyway gets the thread re-pointed at it; one that fails to start frees the thread.
+     */
+    private startClaimed;
+    /** Put a send in its thread's queue, then drain it if the thread turned out to be free. */
+    private enqueue;
+    /** `GET <base>/threads/:id/queue` — the thread's waiting messages and whether it drains. */
+    getQueue(actor: Actor, threadId: string): Promise<ChatQueueState>;
+    /**
+     * `PATCH <base>/queue/:messageId` — change a waiting message's text and/or attachments, and/or move
+     * it to `position` in the queue. Answers the thread's queue.
+     */
+    updateQueuedMessage(actor: Actor, messageId: string, patch: {
+        message?: string;
+        attachments?: AttachmentRef[] | null;
+        position?: number;
+    }): Promise<ChatQueueState>;
+    /** `DELETE <base>/queue/:messageId` — drop a waiting message. Answers the thread's queue. */
+    removeQueuedMessage(actor: Actor, messageId: string): Promise<ChatQueueState>;
+    /**
+     * `POST <base>/queue/:messageId/interrupt` — run a message that is already waiting NOW: it moves
+     * to the head of its queue marked as an interrupt, any pause is lifted, and the running turn is
+     * cancelled (its settle starts this message — the same path a `mode: 'interrupt'` send takes).
+     * With nothing running, the message starts at once.
+     *
+     * One request, and the message never leaves the queue: a client that removed it and sent it again
+     * would lose it if the second call failed, and would run it twice if another tab's drain started
+     * it in between. Answers the queue, plus `interrupting` (the run that was cancelled) or `runId`
+     * (the run this message started).
+     */
+    interruptQueuedMessage(actor: Actor, messageId: string): Promise<ChatQueueState & {
+        runId?: string;
+        interrupting?: string;
+    }>;
+    /** `DELETE <base>/threads/:id/queue` — drop every waiting message (and any pause). */
+    clearQueue(actor: Actor, threadId: string): Promise<ChatQueueState>;
+    /**
+     * `POST <base>/threads/:id/queue/resume` — lift a pause and start the head when nothing is
+     * running. Answers the queue, and the run the head started under, if it did.
+     */
+    resumeQueue(actor: Actor, threadId: string): Promise<ChatQueueState & {
+        runId?: string;
+    }>;
+    /** The thread a queued message waits on, once the caller is shown to own it. */
+    private assertOwnsQueuedMessage;
+    /**
+     * Rebuild this turn's attachments from the staging store, keyed by the ids the caller claimed.
+     * The model provider fetches {@link MessageAttachment.url} verbatim, so that url is only ever
+     * allowed to come from the host's own store — a caller that could name it could point the server
+     * at anything it can reach (cloud metadata, internal services) and read the response back out of
+     * the model's answer.
+     *
+     * No store bound means no way to tell an id the actor owns from one they don't, so a turn simply
+     * cannot carry attachments: 501 rather than trusting the request.
+     */
+    private resolveAttachments;
+    /**
+     * The run's live token stream, WITHOUT an ownership check — for in-process callers that are
+     * already authorized (the MCP bridge, a host's own job code), the same split as
+     * {@link signalToolCall} vs {@link approve}. Anything reachable from a request must go through
+     * {@link subscribeAs} instead: a runId is the only thing standing between a caller and another
+     * actor's answer, tool arguments and tool results.
+     */
+    subscribe(runId: string): AsyncIterable<Uint8Array>;
+    /**
+     * {@link subscribe}, gated the way {@link cancel} is: only the actor whose thread is currently
+     * streaming this run may read it. A run that has already finished is reported missing rather than
+     * replayed — the runner clears the thread's active stream as the run ends, and that field is what
+     * ownership is derived from.
+     */
+    subscribeAs(actor: Actor, runId: string): Promise<AsyncIterable<Uint8Array>>;
+    /**
+     * Approve a parked action call as `actor`. Who may is the call's recorded approver's business
+     * (see {@link assertMayDecide}); `remember` approves later calls of the same tool in the same
+     * thread, and `via` names the surface the decision came through (`'web'`, `'slack'`, …) — both
+     * persisted with the call.
+     */
+    approve(actor: Actor, toolCallId: string, opts?: {
+        remember?: boolean;
+        via?: string;
+    }): Promise<void>;
+    reject(actor: Actor, toolCallId: string, reason?: string, opts?: {
+        via?: string;
+    }): Promise<void>;
+    /**
+     * Answer a parked question set. An omitted question takes the request's own pre-picked default —
+     * resolved by the LOOP against the request it already holds, so "the user just submitted" and
+     * "the user picked exactly the defaults" persist as the same answers, and no client has to
+     * re-send what it was shown.
+     */
+    answer(actor: Actor, toolCallId: string, answers?: Record<string, string[]>, opts?: {
+        via?: string;
+    }): Promise<void>;
+    /**
+     * Decline to answer and let the agent proceed on its own assumptions. NOT the same as confirming
+     * them: the run records this as a rejection, so a reader auditing what the agent was told can
+     * tell a choice the user made from one they refused to make.
+     */
+    skip(actor: Actor, toolCallId: string, opts?: {
+        via?: string;
+    }): Promise<void>;
+    /**
+     * The decision core behind approve/reject, WITHOUT an ownership check: resolves the run
+     * currently awaiting `toolCallId` and signals it. `approve`/`reject` above call this after their
+     * own `assertOwnsToolCall` gate; the console `AgentApprovalPort` adapter (bound by `AgentModule`)
+     * calls it directly — a console caller is already authorized by the dashboard's own guards, and
+     * re-deriving thread ownership here would reject a legitimate operator decision (an operator is
+     * not the thread's own actor).
+     */
+    signalToolCall(toolCallId: string, reply: HumanReply): Promise<void>;
+    /**
+     * Refuse a decision addressed at a run that is over (`409 run_not_active`). The runtime would take
+     * the signal and buffer it for a run that never comes back — the person's "yes" is accepted, the
+     * card says so, and nothing runs. Settles the calls the dead run left awaiting a decision on the
+     * way out, so the card stops asking. A runner that cannot say whether a run is alive is taken at
+     * its word that it is, and so is one that fails to answer.
+     */
+    private assertRunWaiting;
+    /** Who owns the thread, or `null` when there is no such (live) thread. */
+    threadOwner(threadId: string): Promise<string | null>;
+    /**
+     * May `actor` continue the run whose stream is `runId` — the AG-UI resume? Only the actor whose
+     * thread is streaming it (`403` otherwise), and only while it still is: a run that is over is
+     * waiting on no one (`409 run_not_active`), whatever an old interrupt id says.
+     */
+    assertResumable(actor: Actor, runId: string): Promise<void>;
+    /**
+     * Everything {@link approve} / {@link reject} check before they signal — who may decide, and
+     * that the request has not lapsed — without signalling. For a caller that settles several
+     * decisions at once and must refuse all of them if one is refused (an AG-UI resume).
+     */
+    checkDecision(actor: Actor, toolCallId: string): Promise<void>;
+    /** Everything {@link answer} checks before it signals, without signalling — see {@link checkDecision}. */
+    checkAnswer(actor: Actor, toolCallId: string, answers: Record<string, string[]>): Promise<void>;
+    cancel(actor: Actor, runId: string): Promise<void>;
+    listThreads(actorRef: string): Promise<ThreadSummary[]>;
+    getThread(actor: Actor, threadId: string): Promise<ThreadDetail | null>;
+    deleteThread(actor: Actor, threadId: string): Promise<void>;
+    forkThread(actor: Actor, threadId: string, fromMessageId: string): Promise<ThreadSummary>;
+    /** Kept for source compatibility — a thin wrapper over the more general `updateThread`. */
+    renameThread(actor: Actor, threadId: string, title: string): Promise<void>;
+    /**
+     * Rename a thread and/or set its default agent. Title-only patches work against ANY store (via
+     * the required `setTitle`); a `defaultAgent` change requires the bound store to implement the
+     * optional `updateThread` — 501 with a clear message when it doesn't, rather than silently
+     * dropping the field.
+     */
+    updateThread(actor: Actor, threadId: string, patch: UpdateThreadInput): Promise<void>;
+    /**
+     * The persona this send runs under — see {@link AgentDepsFactory.resolvePersona}. The thread's
+     * pinned persona is read only when the send names none AND the agent has personas to pick from.
+     */
+    private resolvePersona;
+    /** Pin `persona` on the thread when it is not already — a no-op on a store that cannot. */
+    private pinThreadPersona;
+    private validateTitle;
+    /**
+     * Agent-selection precedence for a `chat()` call with no explicit `agentName`: the thread's own
+     * `defaultAgent` (if the thread exists and one is set) wins over the module's configured default.
+     * Skips the store entirely when the caller already named an agent or there's no thread yet.
+     *
+     * What this needs is one nullable scalar, so it asks for one. `getThread` returns the entire
+     * transcript — every message, every persisted tool output — and this discards all of it; on a
+     * long thread with large tool results that is hundreds of kilobytes read per turn, outside the
+     * workflow, for a string. A store predating {@link ThreadDefaultAgentReader} still answers, via
+     * the full read.
+     */
+    private resolveAgentName;
+    private threadDefaultAgent;
+    private toSummaryView;
+    private toDetailView;
+    /**
+     * Re-mint each replayed attachment's url from the staging store, by `mediaId`: the url persisted
+     * with the message was minted for THAT turn (a presigned url with an expiry), so an old turn would
+     * otherwise show a dead link. The store's own access check applies — an attachment it will not
+     * resolve for this actor keeps the url it was stored with.
+     */
+    private freshAttachmentUrls;
+    promoteThread(actor: Actor, threadId: string): Promise<void>;
+    /**
+     * Drop a message and everything after it — the "edit and resend" / "delete from here" primitive.
+     * The client then sends a fresh turn on the truncated thread. Ownership-gated like the other
+     * thread-scoped mutations.
+     */
+    truncateThreadFrom(actor: Actor, threadId: string, messageId: string): Promise<void>;
+    /**
+     * Rate a message in one of `actor`'s threads: `'up'`/`'down'` with an optional comment, or `null`
+     * to clear the rating. Answers `404` for an unknown message, `403` for another actor's, and `501`
+     * on a store without `threadOfMessage` + `setMessageFeedback`.
+     */
+    setMessageFeedback(actor: Actor, messageId: string, input: {
+        value: MessageFeedbackValue | null;
+        comment?: string;
+    }): Promise<MessageFeedback | null>;
+    /**
+     * Every file this actor has staged, newest first — across threads, including uploads that were
+     * never sent, which nothing else on this surface can see.
+     *
+     * Metadata only. A url is minted per turn by `resolve` so it can be short-lived, and handing one
+     * back per entry would undo that for the price of rendering a list.
+     */
+    listAttachments(actor: Actor, options?: {
+        limit?: number;
+    }): Promise<StagedAttachment[]>;
+    /**
+     * This actor's staged media that no live message references and that is old enough not to be an
+     * upload in flight — the candidate set for a sweep. Returns them; never deletes them. The bytes
+     * are the host's, and so is the decision.
+     *
+     * `olderThan` is required and has no default. How long a composer may sit open with a file
+     * attached is the host's knowledge, and a library-chosen grace period would eventually delete a
+     * file someone was about to send. The staging store is asked to apply it, and the result is
+     * filtered again here: a store that ignores the hint would otherwise turn this into exactly that
+     * bug, silently.
+     *
+     * Both halves must be answerable or this refuses. An unanswerable reference query means "cannot
+     * tell", and treating it as "nothing is referenced" would hand back every attachment the actor
+     * ever sent, marked safe to delete.
+     */
+    collectableAttachments(actor: Actor, options: {
+        olderThan: Date;
+        limit?: number;
+    }): Promise<StagedAttachment[]>;
+    /**
+     * The bound staging store's `list`, or a refusal. Absence is never answered with an empty list:
+     * "this host keeps no inventory" and "this actor has no files" are opposite facts that would
+     * otherwise render identically — as a clean file list, and as a sweep that collects nothing.
+     */
+    private attachmentInventory;
+    /**
+     * Authorization seam for thread-scoped endpoints: the caller must own the thread. A missing
+     * thread is a 404; someone else's thread is a 403 — one actor never touches another's thread.
+     */
+    private assertOwnsThread;
+    /**
+     * Authorization seam for HITL approve/reject: the caller must own the tool call's thread. Split
+     * out from run resolution (see {@link resolveRunForToolCall}) so the console `AgentApprovalPort`
+     * adapter can resolve+signal a decision WITHOUT this check — it is authorized upstream instead.
+     */
+    private assertOwnsToolCall;
+    /**
+     * Check a reply against the questions it answers before it is signalled: every submitted value a
+     * question's own rules accept (a typed input's type, bounds and pattern; a pick from the offered
+     * options), and every `required` question answered — by the reply, or by the defaults an omitted
+     * question falls back to. A reply the loop would have to drop parts of is refused here instead, so
+     * the person who typed it hears why. Needs the store to hand back the call's recorded questions;
+     * without that seam the loop's own filtering is the only check.
+     */
+    private assertAnswersFit;
+    /**
+     * Authorization seam for approve/reject. The call's recorded approver decides who may settle it:
+     * the requester (the default, and every call recorded before approvers existed) is the thread's
+     * own actor — the ownership check this always was; any other approver goes through the policy's
+     * `canDecide`, which by default asks whether the actor holds that role.
+     */
+    private assertMayDecide;
+    /**
+     * Refuse a decision on a request that has already lapsed — recorded `expired`, or past its
+     * `expiresAt` with the run's own timer about to fire. Signalling it anyway would race the timeout:
+     * a durable runtime buffers a signal nobody is waiting on, and a late approval must not be what a
+     * later replay of the run reads back.
+     */
+    private assertNotExpired;
+    /**
+     * Resolve the run awaiting `toolCallId`. Derived server-side from the tool call alone — the client
+     * never knows or supplies a runId, and that run is the sub-agent's own child run when the pending
+     * call belongs to a delegated agent. The store answers from the CALL'S OWN `runId` where it has
+     * one; see `AgentStore.runForToolCall` for why that matters once a thread can hold more than one
+     * live run.
+     */
+    private resolveRunForToolCall;
+    /** Authorization seam for `cancel`: the caller must own the thread currently streaming this run. */
+    private assertOwnsActiveStream;
+}
+
+interface A2uiAdapterOptions extends A2uiStreamOptions {
+    /** Where the route mounts, under the agent's path. Default `'a2ui'` → `POST <path>/a2ui`. */
+    path?: string;
+    /** As `agUiAdapter`'s: how long a run waiting on a person may stay silent before the stream ends. */
+    quietMs?: number;
+    /** Largest action accepted, as JSON, in bytes. Default 8192. */
+    maxActionBytes?: number;
+}
+/**
+ * Serves the agent as an A2UI agent. Not mounted directly — {@link a2uiAdapter} mounts a subclass at
+ * the configured path — but exported so a host can extend it under a route of its own.
+ */
+declare class A2uiRunHandler {
+    protected readonly agent: AgentService;
+    protected readonly actorResolver: ActorResolver;
+    protected readonly projection: A2uiStreamOptions;
+    protected readonly quietMs: number | undefined;
+    protected readonly maxActionBytes: number | undefined;
+    constructor(agent: AgentService, actorResolver: ActorResolver, projection: A2uiStreamOptions, quietMs: number | undefined, maxActionBytes: number | undefined);
+    handle(req: Request, res: Response, raw: unknown): Promise<void>;
+    /** Open the JSON Lines response. */
+    protected writeHead(res: Response, extra: Record<string, string>): void;
+    /** Write one run as A2UI JSON Lines, until it ends or stops to ask. */
+    protected stream(res: Response, runId: string, options: {
+        threadId?: string;
+        skip?: number;
+        answered?: string[];
+    }): Promise<void>;
+}
+/**
+ * Serve the agent as an A2UI (https://a2ui.org, v0.9) agent: `POST <path>/a2ui` answers with the
+ * run as a JSON Lines stream of A2UI server-to-client messages — `createSurface`,
+ * `updateComponents`, `updateDataModel`, `deleteSurface` — that any A2UI renderer draws.
+ *
+ * ```ts
+ * import { a2uiAdapter } from '@dudousxd/nestjs-agent/a2ui'
+ *
+ * AgentModule.forRoot({ model, adapters: [a2uiAdapter()] })
+ * ```
+ *
+ * The body is `{ threadId?, message?, action?, uiCapabilities?, agent? }`:
+ *  - `message` — the user's text;
+ *  - `action` — an A2UI client message (`{ version: 'v0.9', action: { name, surfaceId,
+ *    sourceComponentId, timestamp, context } }`, or v0.8's `{ userAction }`): it becomes the turn
+ *    (`uiActionText`). `agora.approve` / `agora.reject` with `context.interruptId` decide the
+ *    approval a previous stream ended on, and stream the rest of that run (an independent
+ *    proposal is decided through the proposal service and answered with its reply);
+ *  - `threadId` — continue that thread (its owner is checked), or start one under that id.
+ *
+ * Response headers name the library's ids: `X-Agent-Thread-Id`, `X-Agent-Run-Id`. Authenticated by
+ * the module's `actorResolver`, guarded by its `guards` and owner-scoped exactly as `chat` is.
+ * Components nothing maps are drawn as their text, from the `AgentGenuiModule` catalog when there
+ * is one (or `catalog` here).
+ */
+declare function a2uiAdapter(options?: A2uiAdapterOptions): AgentProtocolAdapter;
+
+export { AgentService as A, type ChatParams as C, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES as D, MAX_ATTACHMENTS_PER_MESSAGE as M, NO_USER_MESSAGE_CODE as N, type QueuedSend as Q, type ThreadDefaultAgentReader as T, ActionProposalService as a, type A2uiAdapterOptions as b, A2uiRunHandler as c, type AttachmentLimits as d, type ChatSendMode as e, type ChatSendResult as f, DEFAULT_MAX_ATTACHMENT_BYTES as g, type ThreadModelReader as h, a2uiAdapter as i, attachmentLimits as j };