@dudousxd/nestjs-agent 0.11.1 → 0.12.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { DynamicModule, OnModuleInit, Type, OnApplicationBootstrap } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory } from './agent-deps.factory-D7GdhqdK.js';
-export { d as AGENT_TOOL_BRAND, e as AgentAttachmentsOptions, f as AgentDeps, a as AgentSurface, F as FunctionalTool, g as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-D7GdhqdK.js';
-import { AgentRunner, AgentStore, QuotaStore, Actor, MessageAttachment, PageContext, Decision, ThreadSummary, ThreadDetail, UpdateThreadInput, QuotaView, AgentApprovalPort, ActorResolver, AttachmentStagingStore, ToolRegistry, AgentRegistry, PromptContributor, AgentRunInput, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-EROMcBNh.js';
+export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, i as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-EROMcBNh.js';
+import { AgentRunner, AgentStore, QuotaStore, AttachmentStagingStore, Actor, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, StagedAttachment, QuotaView, AgentApprovalPort, ActorResolver, MessageAttachment, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -17,8 +17,12 @@ interface ChatParams {
     message: string;
     threadId?: string;
     agentName?: string;
-    /** Files attached to this message (image/PDF) for a vision-capable model. */
-    attachments?: MessageAttachment[];
+    /**
+     * 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;
@@ -28,20 +32,69 @@ interface ChatParams {
      */
     transient?: boolean;
 }
+/**
+ * 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>;
+}
 /** The orchestration facade the controllers call. */
 declare class AgentService {
     private readonly runner;
     private readonly store;
     private readonly deps;
     private readonly quota;
-    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, quota: QuotaStore | undefined);
+    private readonly staging?;
+    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, quota: QuotaStore | undefined, staging?: AttachmentStagingStore | undefined);
     chat(params: ChatParams): Promise<{
         runId: string;
         threadId: string;
     }>;
+    /**
+     * 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(actor: Actor, toolCallId: string): Promise<void>;
     reject(actor: Actor, toolCallId: string, reason?: 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[]>): 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): 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
@@ -50,7 +103,7 @@ declare class AgentService {
      * re-deriving thread ownership here would reject a legitimate operator decision (an operator is
      * not the thread's own actor).
      */
-    signalToolCall(toolCallId: string, decision: Decision): Promise<void>;
+    signalToolCall(toolCallId: string, reply: HumanReply): Promise<void>;
     cancel(actor: Actor, runId: string): Promise<void>;
     listThreads(actorRef: string): Promise<ThreadSummary[]>;
     getThread(actor: Actor, threadId: string): Promise<ThreadDetail | null>;
@@ -69,9 +122,16 @@ declare class AgentService {
     /**
      * 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 thread lookup entirely when the caller already named an agent or there's no thread yet.
+     * 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;
     promoteThread(actor: Actor, threadId: string): Promise<void>;
@@ -81,6 +141,41 @@ declare class AgentService {
      * thread-scoped mutations.
      */
     truncateThreadFrom(actor: Actor, threadId: string, messageId: string): Promise<void>;
+    /**
+     * 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;
     /**
      * The day's usage for the badge: tokens + summed USD cost from the store, and the configured
      * limit from the quota store (null → unlimited). `withinLimit` comes from the quota store so it
@@ -99,9 +194,11 @@ declare class AgentService {
      */
     private assertOwnsToolCall;
     /**
-     * Resolve the run currently awaiting `toolCallId` (its thread's active stream). That run is the
-     * sub-agent's own child run when the pending call belongs to a delegated agent — the client never
-     * knows or supplies a runId; it is derived here from the tool call alone.
+     * 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. */
@@ -135,6 +232,12 @@ declare class AgentApprovalPortAdapter implements AgentApprovalPort {
 
 /** Default per-file size cap when `AgentModuleOptions.attachments.maxBytes` is omitted (20 MiB). */
 declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
+/**
+ * How many entries `GET /agent/attachments` returns. Fixed rather than caller-supplied: this route
+ * exists so a composer can show the files someone has uploaded, and a host that needs real paging
+ * over a large inventory has `AgentService.listAttachments` and its own store's `list` to page with.
+ */
+declare const ATTACHMENT_PAGE_SIZE = 50;
 /**
  * Default allowlist: what multimodal model providers commonly accept as native image/file parts.
  */
@@ -143,14 +246,22 @@ declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
  * Optional `POST /agent/attachments` upload surface — mounted only when `AgentModuleOptions
  * .attachments.upload` (or the async config's `attachmentsUpload`) is `true` (see `agent.module.ts`).
  * Multipart single file field `'file'`, buffered in memory (no disk write — `FileInterceptor`'s
- * default storage), validated against the configured size cap + content-type allowlist, then handed
- * to the bound {@link AttachmentStagingStore} to persist and turn into a model-fetchable URL.
+ * default storage) up to {@link HARD_MAX_ATTACHMENT_BYTES}, then validated against the configured
+ * size cap + content-type allowlist and handed to the bound {@link AttachmentStagingStore} to
+ * persist and turn into a model-fetchable URL. Both size gates answer `413`: the ceiling aborts the
+ * upload mid-stream, the configured cap rejects what was read.
+ *
+ * `GET /agent/attachments` rides the same flag and returns the caller's own staged files as
+ * metadata. Collection is NOT a route: a sweep needs a host-chosen age threshold and ends in the
+ * host deleting bytes, so it stays an in-process call (`AgentService.collectableAttachments`)
+ * rather than something reachable with a session cookie.
  */
 declare class AttachmentsController implements OnModuleInit {
     private readonly options;
     private readonly actorResolver;
+    private readonly agents;
     private readonly staging;
-    constructor(options: AgentModuleOptions, actorResolver: ActorResolver, staging: AttachmentStagingStore | undefined);
+    constructor(options: AgentModuleOptions, actorResolver: ActorResolver, agents: AgentService, staging: AttachmentStagingStore | undefined);
     /**
      * `attachments.upload: true` is what mounts this controller at all (see `agent.module.ts`), so by
      * the time an instance exists the host clearly intends uploads to work. Fail boot loudly rather
@@ -158,6 +269,16 @@ declare class AttachmentsController implements OnModuleInit {
      * `AGENT_ATTACHMENT_STAGING`.
      */
     onModuleInit(): void;
+    /**
+     * The caller's own staged files, newest first — the one question `GET /agent/threads/:id` cannot
+     * answer, since an upload that was never sent belongs to no thread.
+     *
+     * Scoped by the RESOLVED actor and nothing else. There is deliberately no `threadId` filter: a
+     * thread's attachments already ride on its messages in the thread payload, and re-serving them
+     * from here would add a second ownership path to get wrong for information the client already
+     * holds. Metadata only — see {@link StagedAttachment}.
+     */
+    list(req: Request): Promise<StagedAttachment[]>;
     upload(req: Request, file: Express.Multer.File | undefined): Promise<MessageAttachment>;
 }
 
@@ -244,10 +365,77 @@ interface AgentOptions {
     model?: string;
     /** Max model→tool iterations for this agent's turn. Default 8. */
     maxSteps?: number;
+    /**
+     * How deep delegation may nest below this agent before further hops are refused. Default 5.
+     *
+     * Not a budget for how MANY agents a turn delegates to — that is the model's, one tool call each,
+     * and nothing caps it. This bounds the chain a `delegatesTo` cycle would otherwise run forever.
+     */
+    maxDelegationDepth?: number;
+    /**
+     * How many times one agent may appear on a single delegation chain below this one. Default 1.
+     *
+     * This is the exact form of what {@link maxDelegationDepth} approximates: the loop compares a
+     * delegation target against the chain that reached it, so a repeat is a cycle by inspection.
+     * It counts APPEARANCES, so 2 admits exactly one deliberate return to an earlier agent.
+     */
+    maxAgentAppearances?: number;
     /** Allow-list of global tool names this agent may use. Omit → every tool its role allows. */
     tools?: string[];
-    /** Other `@Agent` classes this agent may hand off to (auto-exposed as handoff tools). */
-    handoff?: Type[];
+    /**
+     * Other `@Agent` classes this agent may hand off to (auto-exposed as handoff tools). A bare class
+     * is the delegation that has always existed: this agent's turn waits for the answer.
+     *
+     * `{ agent, detached: true }` is the other shape — the delegate is STARTED and this agent's turn
+     * ends without its answer, which arrives in the conversation later as its own message. Declared
+     * per edge, by the author, and never by the model: the same worker is worth waiting for in one
+     * orchestrator and worth backgrounding in another, and only the person wiring the edge knows
+     * which side of that the user is sitting on.
+     */
+    handoff?: (Type | {
+        agent: Type;
+        detached?: boolean;
+    })[];
+    /**
+     * How much of the thread this agent's turns carry, overriding `AgentModule.forRoot({ history })`.
+     * `{ maxMessages }` and/or `{ maxTokens }` keep the newest that fit; `{ summarize: true }` folds
+     * the rest into a leading summary, at one extra model call per run. Omit → the module-wide
+     * ceiling, or none.
+     */
+    history?: AgentHistoryWindow;
+    /**
+     * Constrain this agent's final answer to a schema (any [Standard Schema](https://standardschema.dev)
+     * — Zod, Valibot, ArkType). The turn calls its tools exactly as it would without one; the schema is
+     * satisfied by one extra formatting call afterwards, so it works on providers that refuse a
+     * response format and a tool set in the same request. The validated value comes back as `object`
+     * on the run's result and is recorded on the assistant message as a `structured_output` tool call.
+     *
+     * Declared HERE rather than per request: a schema is a live object, and `AgentRunInput` crosses a
+     * JSON boundary on its way into a durable workflow.
+     */
+    outputSchema?: StandardSchemaV1;
+    /**
+     * Extra model calls allowed to fix an answer that failed {@link outputSchema}, each shown the
+     * previous attempt's validation issues. Omit → 1; `0` → fail on the first invalid reply with a
+     * `StructuredOutputError`.
+     */
+    outputRepairAttempts?: number;
+    /**
+     * Questions this agent puts to the user BEFORE it starts working — the scope it needs, collected
+     * up front rather than guessed. Authored here, so the turn spends no model call producing them
+     * and a client knows the total ("Question 1 of 3") the moment the form appears. Every question
+     * should pre-pick a default: the claim the surface makes is that confirming is enough.
+     *
+     * `when: 'thread-start'` (the default) asks once per thread; `'every-turn'` asks before each turn.
+     * Omit → no intake.
+     */
+    intake?: AgentIntake;
+    /**
+     * Let the model ask its OWN clarifying question set, via the built-in `ask` tool, when it judges
+     * the scope is missing. Overrides `AgentModule.forRoot({ ask })` for this agent. Omit → the
+     * module-wide setting.
+     */
+    ask?: boolean;
 }
 declare const AGENT_METADATA: unique symbol;
 /** Marks a provider class as an agent. See {@link AgentOptions}. */
@@ -259,6 +447,49 @@ declare function Agent(options: AgentOptions): ClassDecorator;
  */
 declare function readAgentMetadata(target: Type | Function): AgentOptions | undefined;
 
+/**
+ * Declares a provider class as a skill: an authored procedure any agent may pull in when a task
+ * calls for it. Discovered at boot and offered to every turn whose scopes include its `scope`.
+ *
+ * NOT AN AGENT. An `@Agent` is who is answering — its model, its tools, its history ceiling. A skill
+ * is how one task is done, and carries none of those: what it contributes is text, at a scope, under
+ * a name the model can ask for. An instruction that should apply to EVERY turn of an agent is that
+ * agent's `systemPrompt` (or a `@SystemPromptContributor()`), not a skill — a skill is for the ones
+ * that should apply only when the work calls for them, which is what stops them costing a prompt.
+ *
+ * The class is an ordinary provider, so it gets constructor DI — the reason a skill is a class and
+ * not a config entry. The body is either the flat `body` string here or a `body(ctx)` method on the
+ * class (which may read the turn's {@link SkillContext} and inject services); implement
+ * {@link SkillBody} to have the compiler hold you to its shape.
+ */
+interface SkillOptions {
+    /** Unique within its scope. What the model passes to the `skill` tool, and the `/` handle a UI offers. */
+    name: string;
+    /**
+     * One line: what task this covers. Read by the MODEL to decide whether to load it, and by a person
+     * choosing from an autocomplete — so write what it is FOR, not what it contains.
+     */
+    description: string;
+    /**
+     * The scope token this skill is published at. Omit → `'global'`, the deployment-wide default. Any
+     * string a host's `ScopeResolver` can return works: `'tenant:base-7'`, `'sector:logistics'`.
+     */
+    scope?: string;
+    /** A flat body. For one built per actor or per page, add a `body()` method instead. */
+    body?: string;
+}
+/** The shape a `@Skill` class's body method takes. Implement it to be held to it at compile time. */
+interface SkillBody {
+    body(ctx: SkillContext): string | Promise<string>;
+}
+declare const SKILL_METADATA: unique symbol;
+/** Marks a provider class as a skill. See {@link SkillOptions}. */
+declare function Skill(options: SkillOptions): ClassDecorator;
+/** Reads {@link SkillOptions} off a class, or `undefined` if it is not a `@Skill`. */
+declare function readSkillMetadata(target: Type | Function): SkillOptions | undefined;
+/** The scope a `@Skill` publishes at — its own, or the deployment-wide default. */
+declare function skillScope(options: SkillOptions): string;
+
 /**
  * Marks the method on an `@Agent` class that builds the agent's base system prompt. The method
  * receives the turn's `PromptContext` and returns a string (optionally async); because it lives on a
@@ -310,8 +541,12 @@ declare class AgentDiscoveryService implements OnModuleInit {
     onModuleInit(): void;
     /** Build the internal {@link AgentDefinition} from an `@Agent` instance and its options. */
     private definitionFrom;
-    /** Resolve each handoff `@Agent` class to its registered name (skipping non-agent classes). */
-    private handoffNames;
+    /**
+     * Resolve each handoff entry to an {@link AgentDelegation} — its target's registered name, plus
+     * whether that edge detaches (skipping non-agent classes). A bare name is kept for a plain edge
+     * rather than an always-object form, so a definition an older host built by hand still reads.
+     */
+    private handoffEdges;
     /** Push every `@SystemPromptContributor()` method on `instance` (bound) into the contributor list. */
     private collectContributors;
     /** The single method on `instance` carrying `metadataKey`, bound to the instance, or undefined. */
@@ -320,6 +555,114 @@ declare class AgentDiscoveryService implements OnModuleInit {
     private boundMethod;
 }
 
+/**
+ * One `@Skill`-decorated provider, reduced to what a `SkillProvider` needs: its catalog line, and a
+ * bound function that produces its body for a turn.
+ */
+interface DeclaredSkill {
+    name: string;
+    description: string;
+    scope: string;
+    body(ctx: SkillContext): string | Promise<string>;
+}
+/**
+ * Collects every `@Skill`-decorated provider into the shared list the module's skill provider reads
+ * — the discovery counterpart to authoring skills as rows in the host's own table. Both sources feed
+ * one catalog; see `AgentModuleOptions.skills`.
+ *
+ * A class with neither a flat `body` nor a `body()` method is skipped with a warning rather than
+ * offered: a skill the model can see and load, that then returns nothing, reads to it as an
+ * instruction to do nothing in particular — which is worse than the skill not existing.
+ */
+declare class SkillDiscoveryService implements OnModuleInit {
+    private readonly discovery;
+    private readonly declared;
+    private readonly logger;
+    constructor(discovery: DiscoveryService, declared: DeclaredSkill[]);
+    onModuleInit(): void;
+    /** The instance's `body()` method (bound), else the flat string, else nothing to offer. */
+    private bodyOf;
+}
+
+/**
+ * Lists the skills available to THIS caller right now, scope-resolved — so a composer can offer them
+ * after a `/` instead of hardcoding a list, and a settings screen can show which scope each came
+ * from.
+ *
+ * THE SAME LIST THE MODEL IS OFFERED, built by the same call (`offerSkills`) against the same
+ * provider and the same resolver. A second implementation of "which skills apply" would drift the
+ * first time either was edited, and the drift would read to a user as a skill they can invoke that
+ * the agent then says it has never heard of.
+ *
+ * Ownership posture mirrors `GET /agent/agents`: a plain array, no envelope, and nothing the caller
+ * can pass to widen it — the actor comes from the resolver, never from a parameter.
+ */
+declare class SkillsController {
+    private readonly actorResolver;
+    private readonly skills;
+    constructor(actorResolver: ActorResolver, skills: SkillsConfig | undefined);
+    list(req: Request, 
+    /**
+     * The thread this list is for. Only ever handed to the host's own resolver and provider, which
+     * may scope a skill to a conversation; nothing here reads the thread, so an unknown id widens
+     * nothing. Omitted → the empty string, the same value a turn on a brand-new thread carries.
+     */
+    threadId?: string): Promise<SkillCatalogEntry[]>;
+}
+
+/**
+ * What the assistant believes about THIS caller — and how they take one of those beliefs back.
+ *
+ * WHY THIS EXISTS WHERE `GET /agent/skills` HAS NO WRITE SIBLING. A skill is authored by a person
+ * who already knows it exists; a memory is written by the agent, about someone who does not. So the
+ * read-back is not a convenience on top of the feature, it IS half of the feature: a belief nobody
+ * can inspect is one nobody can correct, and a belief nobody can delete is one the deployment keeps
+ * whether or not it is true. That is also why `MemoryProvider.forget` is required rather than
+ * optional — see `memory.ts`.
+ */
+declare class MemoriesController {
+    private readonly actorResolver;
+    private readonly memory;
+    constructor(actorResolver: ActorResolver, memory: MemoryConfig | undefined);
+    /**
+     * Every memory this actor can reach, most specific first, each carrying its origin and whatever
+     * wider value it outranks.
+     *
+     * DELIBERATELY IGNORES `maxMemories`. That ceiling is a budget on what one TURN carries; applying
+     * it here would mean a person could not see — and so could not delete — a belief the assistant is
+     * one write away from acting on again. Showing someone more than the model sees is harmless;
+     * showing them less is the failure this endpoint exists to prevent.
+     */
+    list(req: Request, 
+    /** Only ever handed to the host's own resolver and provider; nothing here reads the thread. */
+    threadId?: string): Promise<MemoryDigestEntry[]>;
+    /**
+     * Forget one. Authorized against the actor's OWN resolved list, the same way a `skill` load is
+     * authorized against the turn's catalog: an id this actor cannot see is answered as missing rather
+     * than refused, so the endpoint cannot be used to find out which memories exist about other people.
+     */
+    forget(req: Request, id: string): Promise<{
+        forgotten: boolean;
+    }>;
+    private unbounded;
+}
+
+/**
+ * The `@Skill`-decorated classes as a `SkillProvider`. Reads `declared` on every call rather than
+ * capturing its contents: DI builds the provider before `SkillDiscoveryService` has filled the list.
+ */
+declare function declaredSkillProvider(declared: readonly DeclaredSkill[]): SkillProvider;
+/**
+ * The turn's skills seam, or `undefined` where the host configured none — which is also what keeps
+ * a deployment that declares no skills from spending the `skills:catalog` checkpoint.
+ *
+ * DISCOVERED `@Skill` CLASSES ALONE DO NOT TURN SKILLS ON. Adding a decorated class would otherwise
+ * insert a checkpoint into every turn, and a run already in flight when that deployment rolled would
+ * replay against a sequence one position short. `skills: {}` is the opt-in; a class discovered
+ * without it is reported at boot rather than silently inert.
+ */
+declare function resolveSkillsConfig(options: AgentSkillsOptions | undefined, declared: readonly DeclaredSkill[]): SkillsConfig | undefined;
+
 /**
  * Runs the agent turn in-process. HITL approval resolves a pending promise keyed by
  * `runId:toolCallId`. Sub-agent delegation runs a nested loop that streams into the top-level run's
@@ -332,13 +675,57 @@ declare class InlineAgentRunner implements AgentRunner {
     private readonly store;
     private readonly logger;
     private readonly pending;
+    /**
+     * Runs someone has asked to stop. In-process, like `pending`, and for the same reason: this runner
+     * is single-replica by construction, so the request is readable by the only loop that could be
+     * running it. A cancelled id is dropped once the run settles, so the set tracks live runs only.
+     */
+    private readonly cancelled;
     constructor(factory: AgentDepsFactory, store: AgentStore);
     start(input: AgentRunInput): Promise<{
         runId: string;
     }>;
-    signal(runId: string, toolCallId: string, decision: Decision): Promise<void>;
+    signal(runId: string, toolCallId: string, reply: HumanReply): Promise<void>;
+    /**
+     * Ask a run to stop, and settle whatever it was parked on.
+     *
+     * The loop observes the request at its next safe point (between steps, before the turn's tools) and
+     * unwinds from there — so a tool already executing is left to finish, and its result is recorded
+     * exactly as it would have been. What this cannot wait for is a turn parked on a human: that wait
+     * is a promise nobody is going to resolve, so it is REJECTED here with the same
+     * {@link RunCancelledError} the loop would have thrown, and the run unwinds through the identical
+     * path.
+     *
+     * Settlement — the run row, the thread's active stream, the stream's terminal — belongs to the
+     * `RunCancelledError` catch in `start`, so a cancel and an ordinary failure settle in one place
+     * each and can never both write.
+     */
     cancel(runId: string): Promise<void>;
+    /**
+     * The single place a cancelled run's state is settled: recorded as its own terminal (never
+     * `failed` — a user pressing Stop must not land in someone's error rate), the thread released, and
+     * the stream ENDED after a `cancelled` frame rather than failed, so a client that retries failed
+     * streams does not retry this one.
+     */
+    private settleCancelled;
+    /**
+     * Park a run on a human, keyed by run + tool call. One map for approvals and for question-set
+     * answers alike: both wait on the same key, and `signal` cannot tell (or need to tell) which
+     * shape it is delivering — the loop asked for one and only ever gets what the caller sent. A
+     * cancel settles the wait too, by rejecting it.
+     */
+    private park;
     private topLevelHooks;
+    /**
+     * Delegate WITHOUT waiting: a nested loop nobody awaits, on its own thread and its own sink, which
+     * posts its answer back into the delegating thread when it lands (`deliverTo`, settled by the
+     * loop). The calling turn gets the run id straight back and finishes.
+     *
+     * No `sinkRunId`, unlike {@link runNested}: forwarding into the stream the human is watching would
+     * write into a turn that has already ended. Its own approvals resolve through the shared pending
+     * map keyed by its own runId — which is what the pending-approvals surface routes to.
+     */
+    private startDetached;
     /**
      * Delegate to another agent as a nested in-process run. The sub-agent streams into `sinkRunId`
      * (the top-level run the human is watching) so its output and any pending action tool are visible,
@@ -377,21 +764,23 @@ declare class LedgerQuotaStore implements QuotaStore {
     private readonly limitTokens;
     constructor(store: AgentStore, limitTokens: number);
     check(actorRef: string, day: string): Promise<QuotaState>;
-    bump(): Promise<void>;
+    bump(_actorRef: string, _day: string, _tokens: number): Promise<void>;
 }
 
 /**
  * A development / gateway {@link ActorResolver} that trusts request headers:
  * `x-actor-id` (required), `x-actor-role` (comma-separated → `roles`), `x-tenant-ref`.
  *
- * **Security:** it throws when `x-actor-id` is absent — it never fabricates an identity
- * and never grants a default role (an actor with no `x-actor-role` gets `roles: []`, i.e.
- * no tools). Trusting client headers is only safe behind a gateway that strips and re-sets
- * them from an authenticated principal. Real deployments should provide their own resolver
- * that reads a verified session/JWT instead of installing this one.
+ * **Security:** it rejects with `UnauthorizedException` when `x-actor-id` is absent — it never
+ * fabricates an identity, and never grants a default role (an actor with no `x-actor-role` gets
+ * `roles: []`, i.e. no tools). Trusting client headers is only safe behind a gateway that strips
+ * and re-sets them from an authenticated principal. Real deployments should provide their own resolver
+ * that reads a verified session/JWT instead of installing this one. A custom resolver should
+ * reject the same way: a plain `Error` surfaces to the caller as a 500 with a logged stack, which
+ * both misreports an unauthenticated request and turns anonymous probes into error noise.
  */
 declare class HeaderActorResolver implements ActorResolver {
     resolve(req: unknown): Actor;
 }
 
-export { AGENT_METADATA, AI_TOOL_METADATA, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, SystemPrompt, SystemPromptContributor, readAgentMetadata, readAiToolMetadata };
+export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, MemoriesController, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, declaredSkillProvider, readAgentMetadata, readAiToolMetadata, readSkillMetadata, resolveSkillsConfig, skillScope };