@dudousxd/nestjs-agent 0.11.1 → 0.13.0

package/README.md

@@ -41,6 +41,66 @@ The module mounts SSE + REST endpoints under `/agent` (`POST /agent/chat`, tool-
 threads, quota). Add `durable: true` + `AgentDurableModule` for the durable runner;
 `AgentModule.forFeature([…])` for multi-agent orchestration.
 
+### Message attachments
+
+A chat turn attaches a file by **`mediaId` only**:
+
+```jsonc
+POST /agent/chat
+{ "message": "what is in this?", "attachments": [{ "mediaId": "med_8f21…" }] }
+```
+
+Every other field a client sends with it is discarded. The url the model provider fetches is read
+back from the `AttachmentStagingStore` bound to `AGENT_ATTACHMENT_STAGING`, whose `resolve({ mediaId,
+actor })` returns the attachment or `null` when the id is unknown or is not that actor's — so a
+caller can never point the server at a url it chose (link-local metadata, an internal service), and
+never at another actor's file. Resolution happens per turn, so a short-lived presigned url is minted
+fresh rather than replayed from the stored message.
+
+With nothing bound to `AGENT_ATTACHMENT_STAGING` there is no way to tell whose media an id is, so a
+turn carrying attachments is refused with `501`. Text-only turns are unaffected. At most 10
+attachments per turn.
+
+The optional `POST /agent/attachments` upload route (`attachments: { upload: true }`) aborts a body
+larger than `HARD_MAX_ATTACHMENT_BYTES` (32 MiB) while it streams; `attachments.maxBytes` narrows
+that ceiling at request time and cannot raise it.
+
+### Sweeping attachments nobody sent
+
+`stage()` writes bytes before any message exists, so a user who attaches a file and then never sends
+it leaves media with nothing pointing at it. Two optional methods make that findable — `list` on
+your `AttachmentStagingStore` (you stored the bytes, so only you can enumerate them) and
+`referencedMediaIds` on your `AgentStore` (only it can see which media a live message carries).
+
+```ts
+// a job the host runs; nothing here is reachable over HTTP
+const olderThan = new Date(Date.now() - 48 * 60 * 60 * 1000);
+for (const entry of await agents.collectableAttachments(actor, { olderThan })) {
+  await myMediaStore.delete(entry.mediaId); // the library never deletes your bytes
+}
+```
+
+`olderThan` is required and has no default: freshly staged media is an upload in flight, not
+garbage, and only you know how long one of your composers may sit open. It is pushed down to `list`
+and re-applied to the result, so a store that ignores the hint still cannot delete a live upload.
+
+References are re-derived on every call rather than latched, because `truncateFrom` — which is what
+regenerating a turn does — deletes messages and frees their media again. If either method is
+missing the call raises `501` rather than reporting everything as collectable.
+
+`GET /agent/attachments` returns the caller's own staged files as metadata (no urls — those are
+minted per turn by `resolve`), bounded to `ATTACHMENT_PAGE_SIZE`, and rides the same
+`attachments: { upload: true }` flag. It takes no `threadId` filter: a thread's attachments already
+ride on its messages in `GET /agent/threads/:id`.
+
+### Who may read a run
+
+`GET /agent/chat/:runId/stream` and `POST /agent/chat/:runId/cancel` both resolve the acting actor
+and require they own the run currently streaming — `403` for another actor's run, `404` for a run
+nobody is streaming (including one that has already finished). In-process callers that are
+authorized elsewhere use `AgentService.subscribe(runId)`; anything reachable from a request must go
+through `AgentService.subscribeAs(actor, runId)`.
+
 ### Deploying split API/worker pods
 
 By default `AgentModule`/`AgentDurableModule` wire everything: every controller, the `agent.run`

package/dist/{agent-deps.factory-D7GdhqdK.d.cts → agent-deps.factory-y2hvoQ6U.d.cts}

@@ -1,4 +1,5 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, ToolSpec, ToolHandler, ActorResolver, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
@@ -15,6 +16,10 @@ interface AgentDeps {
     /** App-wide `@SystemPromptContributor()` sections appended after the agent's base prompt. */
     promptContributors: PromptContributor[];
     maxSteps: number;
+    /** Nesting ceiling for delegation below this agent. Undefined → the loop's default. */
+    maxDelegationDepth?: number;
+    /** How many times one agent may appear on a chain. Undefined → the loop's default. */
+    maxAgentAppearances?: number;
     /** Agent-level tool allow-list. Undefined → all tools (after role filtering). */
     toolAllowList?: string[];
     /** Per-tool execution timeout in ms (from module options). Undefined → no timeout. */
@@ -32,6 +37,30 @@ interface AgentDeps {
     retrievalTopK?: number;
     /** Bound `AGENT_PRICING_STORE`, when a module (e.g. a store's) provides one. Undefined → no pricing. */
     pricingStore?: AgentPricingStore;
+    /** The agent's history ceiling, resolved from `@Agent({ history })` / module options. Undefined → unbounded. */
+    historyPolicy?: HistoryPolicy;
+    /** Module-wide prompt rewriters, applied before every model call. Empty → none. */
+    inputProcessors: InputProcessor[];
+    /** Module-wide answer gates. NON-EMPTY MEANS THE TURN'S MODEL OUTPUT IS BUFFERED, not streamed. */
+    outputProcessors: OutputProcessor[];
+    /** The agent's `@Agent({ outputSchema })`, resolved from DI — never over the wire. Undefined → free text. */
+    outputSchema?: StandardSchemaV1;
+    /** Extra model calls allowed to repair an answer that failed `outputSchema`. Undefined → 1. */
+    outputRepairAttempts?: number;
+    /** The agent's `@Agent({ intake })` question set, asked before the turn starts. Undefined → none. */
+    intake?: AgentIntake;
+    /** Whether the model may call the built-in `ask` tool this turn. Undefined/false → it never sees it. */
+    ask?: boolean;
+    /**
+     * The resolved skills seam (`forRoot({ skills })` + discovered `@Skill` providers). Undefined →
+     * no catalog, no `skill` tool, and the turn spends no checkpoint on either.
+     */
+    skills?: SkillsConfig;
+    /**
+     * The resolved memory seam (`forRoot({ memory })`). Undefined → no block, no `remember` tool, and
+     * the turn spends no checkpoint on either.
+     */
+    memory?: MemoryConfig;
 }
 declare function utcDay(date?: Date): string;
 
@@ -96,6 +125,61 @@ interface AgentAttachmentsOptions {
      */
     upload?: boolean;
 }
+/**
+ * `AgentModuleOptions.skills` — where a turn's skills come from, and which scopes an actor draws
+ * them from. Its PRESENCE turns skills on: `skills: {}` offers whatever the `@Skill`-decorated
+ * providers declare, resolved against the actor's own, their tenant's and the deployment's scopes.
+ */
+interface AgentSkillsOptions {
+    /**
+     * A provider of your own — skills a host stores and administers itself (per user, per sector, per
+     * base). Merged with the discovered `@Skill` classes, and outranking them for a name published at
+     * the same scope. Omit → the decorated classes are the whole catalog.
+     */
+    provider?: SkillProvider;
+    /**
+     * Which scope tokens an actor draws from, most specific first — the precedence order. Omit → the
+     * actor's own (`actor:<id>`), their tenant's (`tenant:<ref>`, when they have one), and `global`.
+     * Supply one to add an axis this library has no key for: a sector, a squadron, a shift.
+     */
+    scopes?: ScopeResolver;
+    /**
+     * How many skills the catalog block offers before it starts leaving the widest ones out. Omit →
+     * 20. A ceiling on what the SYSTEM PROMPT carries, not on how many a deployment may hold.
+     */
+    maxSkills?: number;
+}
+/**
+ * `AgentModuleOptions.memory` — where what the assistant concluded about a person is stored, and how
+ * much of it a turn may carry. Its PRESENCE turns memory on.
+ *
+ * Unlike `skills`, there is no decorator and no zero-config form: a memory is by definition something
+ * the agent worked out about someone, so a memory a developer wrote in a class would be an
+ * instruction wearing a memory's clothes — which is what `@Skill` and `@SystemPromptContributor()`
+ * are for. The rows are the host's from the start.
+ */
+interface AgentMemoryOptions {
+    /**
+     * Where the rows live. `forget` is required on it; `write` is what decides the `remember` tool;
+     * `search` is what decides whether a turn's block is selected by relevance or read whole. Supply
+     * `search` once the applicable set outgrows `maxMemories` — without it the ceiling selects by
+     * scope, and the widest scopes are the ones it starves.
+     */
+    provider: MemoryProvider;
+    /**
+     * Which scope tokens an actor draws from, most specific first — the precedence order, and the same
+     * seam `skills` uses. Omit → the actor's own, their tenant's, and `global`.
+     */
+    scopes?: ScopeResolver;
+    /**
+     * How many memories the block carries. Omit → 20. A budget on the PROMPT, never on the store: with
+     * a provider that can `search`, this is how many matter right now rather than how many a person
+     * may have. Always-on (`pinned`) memories are taken from it first.
+     */
+    maxMemories?: number;
+    /** How long one memory may be, checked when it is written. Omit → 240. */
+    maxFactChars?: number;
+}
 interface AgentModuleOptions {
     /** The LLM provider (e.g. a Vercel AI SDK wrapper). Required. */
     model: ModelProvider;
@@ -139,11 +223,19 @@ interface AgentModuleOptions {
     durable?: boolean;
     /**
      * Dispatch the turn's model call and tool executions as routed durable steps
-     * (`AgentRunSteps.llm` / `AgentRunSteps.tool`) instead of in-process `ctx.localStep`s.
-     * DEFAULT `true` under `durable: true` — dispatching moves the run off its pod during the two
-     * long steps (the correct production posture), and `AgentRunSteps` is always registered so the
-     * routed groups are never unserved. Set `false` to keep the turn's steps in-process localSteps.
-     * `true` without `durable: true` throws at module build.
+     * (`AgentRunSteps.llm` / `AgentRunSteps.tool`) instead of in-process `ctx.localStep`s. OMITTED
+     * keeps them in-process; `true` without `durable: true` throws at module build.
+     *
+     * WHAT IT BUYS: the run is not pinned to one pod for the two long parts of a turn, so a fleet can
+     * scale the model call and tool execution separately from the workflow itself.
+     *
+     * WHY IT IS NOT A DEFAULT. It relocates the HOST's own code. A tool handler no longer runs inside
+     * the turn's workflow body but inside whichever worker serves the routed group, and the `llm`
+     * step re-runs the host's tool-visibility callbacks there to rebuild its tool list. A handler
+     * that resolves anything per invocation from its caller's execution context — a request-scoped
+     * ORM EntityManager, an AsyncLocalStorage tenant, a CLS transaction — finds nothing in that
+     * worker, and the library has no way to know which handlers do that. Turn this on once the tools
+     * this deployment registers establish whatever context they need themselves.
      *
      * The cross-process-sink requirement is a property of `durable: true` itself, not of this flag:
      * the turn already runs on whichever worker takes `agent.run`, which may not be the pod holding
@@ -191,6 +283,75 @@ interface AgentModuleOptions {
         retriever: Retriever;
         topK?: number;
     };
+    /**
+     * Bounds how much of a thread rides into each turn. Omit and a turn carries EVERY message the
+     * thread holds, so a long-lived thread costs more each time and eventually exceeds the model's
+     * context limit outright. `{ maxMessages }` and/or `{ maxTokens }` keep the newest that fit;
+     * `{ summarize: true }` folds what they left out into a leading summary, at the price of one extra
+     * model call per run (recorded as `history_summary` usage). An agent can override this for itself
+     * with `@Agent({ history })`.
+     */
+    history?: AgentHistoryWindow;
+    /**
+     * A {@link HistoryPolicy} of your own — for a window the built-in can't express (pinning the
+     * thread's opening brief, keeping every message that carries a tool result, a budget that varies
+     * by actor). A convenience-vs-custom pair like `quotaLimitTokens`/`quota`: this outranks a
+     * module-wide `history`, and `@Agent({ history })` outranks both for the agent that declares it.
+     * `select` MUST be pure — see the SPI's determinism contract.
+     */
+    historyPolicy?: HistoryPolicy;
+    /**
+     * Rewrites the prompt before every model call — masking identifiers, stamping a policy preamble,
+     * trimming an oversized tool result. Applies to EVERY agent: a transformation one persona can opt
+     * out of is not a control. Transformation only; `history`/`historyPolicy` still own which messages
+     * are there to transform. A processor needing DI-resolved dependencies is built in
+     * `forRootAsync`'s `useFactory` (which has `inject`), the same way `retrieval.retriever` is.
+     */
+    inputProcessors?: InputProcessor[];
+    /**
+     * Gates every model answer before the stream, the store or the next step sees it — redact,
+     * replace, or refuse the turn outright (which fails it with an `output_rejected` stream error).
+     *
+     * REGISTERING ONE TURNS OFF LIVE TOKEN STREAMING. Reading the whole answer and streaming it as it
+     * is generated cannot both be true, so the turn's model output is buffered and released in one
+     * frame once the chain passes. That is the price of a gate that actually gates; see
+     * `AgentLoopDeps.outputProcessors` for exactly what a subscriber still receives live.
+     */
+    outputProcessors?: OutputProcessor[];
+    /**
+     * Offer every agent the built-in `ask` tool, so the model can put its own clarifying question set
+     * to the user when it judges the scope is missing. The turn parks on the answers exactly as it
+     * parks on a HITL approval, and they arrive through `POST /agent/tool-call/answer`.
+     *
+     * `ask` is not a registered tool and has no handler — the loop settles it against a person — so no
+     * `RolesPolicy` gates it: asking a question performs nothing. An `@Agent({ ask })` overrides this
+     * for one persona. Omit → the model never sees it, and nothing about a turn changes.
+     */
+    ask?: boolean;
+    /**
+     * Authored procedures any agent may pull in when a task calls for one — per-user, per-tenant or
+     * deployment-wide, with the most specific winning. Declared as `@Skill`-decorated providers and/or
+     * served by a `provider` of your own; offered to the model as a one-line-each catalog it loads
+     * from on demand, so an instruction costs a prompt only on the turns that need it.
+     *
+     * Omit → no catalog, no `skill` tool, and a turn's checkpoint sequence is byte-identical to one
+     * that never had the option. See {@link AgentSkillsOptions}.
+     */
+    skills?: AgentSkillsOptions;
+    /**
+     * What the assistant has concluded about the actor and their organisation, carried into every turn
+     * as a bounded block of one-line facts and written by the model through a built-in `remember` tool.
+     *
+     * NOT the same thing as retrieval, and not a second name for it: `retrieval` answers from documents
+     * a person curated and can fix at the source, memory answers from the agent's own inferences about
+     * someone who never saw them written. That is why the rows carry an origin, why the block tells the
+     * model they may be wrong, and why `GET /agent/memories` + `DELETE /agent/memories/:id` are part of
+     * the feature rather than an optional console.
+     *
+     * Omit → no block, no `remember` tool, and a turn's checkpoint sequence is byte-identical to one
+     * that never had the option. See {@link AgentMemoryOptions}.
+     */
+    memory?: AgentMemoryOptions;
     /**
      * The name of the agent a turn uses when the caller doesn't select one. Omit → the single
      * discovered `@Agent` (when there is exactly one), else `'default'` (a bare assistant if no
@@ -230,12 +391,11 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
      */
     durable?: boolean;
     /**
-     * Dispatch the turn's model call and tool executions as routed durable steps. DEFAULT `true`
-     * under `durable: true`; set `false` to keep the turn's steps in-process localSteps. Same
-     * static-wiring reasoning as `durable` above — it lives here (not in the async factory result)
-     * because it decides how `AgentRunWorkflow` builds its hooks at module build time. `true` without
-     * `durable: true` throws at module build. See `AgentModuleOptions.dispatchedSteps` for the full
-     * contract.
+     * Dispatch the turn's model call and tool executions as routed durable steps. Omitted keeps the
+     * turn's steps in-process localSteps. Same static-wiring reasoning as `durable` above — it lives
+     * here (not in the async factory result) because it decides how `AgentRunWorkflow` builds its
+     * hooks at module build time. `true` without `durable: true` throws at module build. See
+     * `AgentModuleOptions.dispatchedSteps` for the full contract.
      */
     dispatchedSteps?: boolean;
     /**
@@ -273,8 +433,18 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     surface?: AgentSurface;
 }
 
-/** The synthesized `agent`-kind tool name an orchestrator uses to hand off to `target`. */
-declare function delegateToolName(target: string): string;
+/**
+ * The synthesized `agent`-kind tool name an orchestrator uses to hand off to `target`.
+ *
+ * A detached edge gets its own verb — `start_research` next to `ask_research` — for two reasons.
+ * One agent can be both awaited AND backgrounded by the same orchestrator, and one name cannot
+ * carry both. And the name is the part of a tool the model reads first: `ask` promises an answer,
+ * `start` does not.
+ */
+declare function delegateToolName(args: {
+    target: string;
+    detached?: boolean;
+}): string;
 /** Builds the per-agent loop deps. The single-agent case is just the one registered `@Agent`. */
 declare class AgentDepsFactory {
     private readonly options;
@@ -287,7 +457,13 @@ declare class AgentDepsFactory {
     private readonly promptContributors;
     private readonly quota;
     private readonly pricingStore;
-    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], quota: QuotaStore | undefined, pricingStore: AgentPricingStore | undefined);
+    private readonly skills;
+    private readonly memory;
+    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], quota: QuotaStore | undefined, pricingStore: AgentPricingStore | undefined, skills: SkillsConfig | undefined, memory: MemoryConfig | undefined);
+    /** The turn's memory seam, shared with the read-back endpoint. Undefined → memory is not configured. */
+    memoryConfig(): MemoryConfig | undefined;
+    /** The turn's skills seam, shared with the listing endpoint. Undefined → skills are not configured. */
+    skillsConfig(): SkillsConfig | undefined;
     /**
      * The agent a turn uses when the caller names none: the explicit `defaultAgent` option, else the
      * sole registered `@Agent` when there is exactly one, else `'default'` (a bare assistant).
@@ -295,8 +471,16 @@ declare class AgentDepsFactory {
     defaultAgentName(): string;
     private effectiveTools;
     forAgent(agentName?: string): AgentDeps;
+    /**
+     * The ceiling on how much of a thread this agent's turns carry, most specific wins: the agent's
+     * own `@Agent({ history })`, else a module-wide custom `historyPolicy`, else the module-wide
+     * `history` window. Undefined → unbounded, the behaviour of a module that configures none.
+     */
+    private historyPolicy;
+    /** Build the built-in window policy from the declarative `{ maxMessages, maxTokens, summarize }`. */
+    private window;
     /** Normalize the `followUps` option (`true` → 3, `{ count }` → count) to a number, or undefined. */
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, AGENT_TOOL_BRAND as d, type AgentAttachmentsOptions as e, type AgentDeps as f, delegateToolName as g, provideAgentTool as p, utcDay as u };
+export { AgentDepsFactory as A, type FunctionalTool as F, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, delegateToolName as i, provideAgentTool as p, utcDay as u };

package/dist/{agent-deps.factory-D7GdhqdK.d.ts → agent-deps.factory-y2hvoQ6U.d.ts}

@@ -1,4 +1,5 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, ToolSpec, ToolHandler, ActorResolver, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
@@ -15,6 +16,10 @@ interface AgentDeps {
     /** App-wide `@SystemPromptContributor()` sections appended after the agent's base prompt. */
     promptContributors: PromptContributor[];
     maxSteps: number;
+    /** Nesting ceiling for delegation below this agent. Undefined → the loop's default. */
+    maxDelegationDepth?: number;
+    /** How many times one agent may appear on a chain. Undefined → the loop's default. */
+    maxAgentAppearances?: number;
     /** Agent-level tool allow-list. Undefined → all tools (after role filtering). */
     toolAllowList?: string[];
     /** Per-tool execution timeout in ms (from module options). Undefined → no timeout. */
@@ -32,6 +37,30 @@ interface AgentDeps {
     retrievalTopK?: number;
     /** Bound `AGENT_PRICING_STORE`, when a module (e.g. a store's) provides one. Undefined → no pricing. */
     pricingStore?: AgentPricingStore;
+    /** The agent's history ceiling, resolved from `@Agent({ history })` / module options. Undefined → unbounded. */
+    historyPolicy?: HistoryPolicy;
+    /** Module-wide prompt rewriters, applied before every model call. Empty → none. */
+    inputProcessors: InputProcessor[];
+    /** Module-wide answer gates. NON-EMPTY MEANS THE TURN'S MODEL OUTPUT IS BUFFERED, not streamed. */
+    outputProcessors: OutputProcessor[];
+    /** The agent's `@Agent({ outputSchema })`, resolved from DI — never over the wire. Undefined → free text. */
+    outputSchema?: StandardSchemaV1;
+    /** Extra model calls allowed to repair an answer that failed `outputSchema`. Undefined → 1. */
+    outputRepairAttempts?: number;
+    /** The agent's `@Agent({ intake })` question set, asked before the turn starts. Undefined → none. */
+    intake?: AgentIntake;
+    /** Whether the model may call the built-in `ask` tool this turn. Undefined/false → it never sees it. */
+    ask?: boolean;
+    /**
+     * The resolved skills seam (`forRoot({ skills })` + discovered `@Skill` providers). Undefined →
+     * no catalog, no `skill` tool, and the turn spends no checkpoint on either.
+     */
+    skills?: SkillsConfig;
+    /**
+     * The resolved memory seam (`forRoot({ memory })`). Undefined → no block, no `remember` tool, and
+     * the turn spends no checkpoint on either.
+     */
+    memory?: MemoryConfig;
 }
 declare function utcDay(date?: Date): string;
 
@@ -96,6 +125,61 @@ interface AgentAttachmentsOptions {
      */
     upload?: boolean;
 }
+/**
+ * `AgentModuleOptions.skills` — where a turn's skills come from, and which scopes an actor draws
+ * them from. Its PRESENCE turns skills on: `skills: {}` offers whatever the `@Skill`-decorated
+ * providers declare, resolved against the actor's own, their tenant's and the deployment's scopes.
+ */
+interface AgentSkillsOptions {
+    /**
+     * A provider of your own — skills a host stores and administers itself (per user, per sector, per
+     * base). Merged with the discovered `@Skill` classes, and outranking them for a name published at
+     * the same scope. Omit → the decorated classes are the whole catalog.
+     */
+    provider?: SkillProvider;
+    /**
+     * Which scope tokens an actor draws from, most specific first — the precedence order. Omit → the
+     * actor's own (`actor:<id>`), their tenant's (`tenant:<ref>`, when they have one), and `global`.
+     * Supply one to add an axis this library has no key for: a sector, a squadron, a shift.
+     */
+    scopes?: ScopeResolver;
+    /**
+     * How many skills the catalog block offers before it starts leaving the widest ones out. Omit →
+     * 20. A ceiling on what the SYSTEM PROMPT carries, not on how many a deployment may hold.
+     */
+    maxSkills?: number;
+}
+/**
+ * `AgentModuleOptions.memory` — where what the assistant concluded about a person is stored, and how
+ * much of it a turn may carry. Its PRESENCE turns memory on.
+ *
+ * Unlike `skills`, there is no decorator and no zero-config form: a memory is by definition something
+ * the agent worked out about someone, so a memory a developer wrote in a class would be an
+ * instruction wearing a memory's clothes — which is what `@Skill` and `@SystemPromptContributor()`
+ * are for. The rows are the host's from the start.
+ */
+interface AgentMemoryOptions {
+    /**
+     * Where the rows live. `forget` is required on it; `write` is what decides the `remember` tool;
+     * `search` is what decides whether a turn's block is selected by relevance or read whole. Supply
+     * `search` once the applicable set outgrows `maxMemories` — without it the ceiling selects by
+     * scope, and the widest scopes are the ones it starves.
+     */
+    provider: MemoryProvider;
+    /**
+     * Which scope tokens an actor draws from, most specific first — the precedence order, and the same
+     * seam `skills` uses. Omit → the actor's own, their tenant's, and `global`.
+     */
+    scopes?: ScopeResolver;
+    /**
+     * How many memories the block carries. Omit → 20. A budget on the PROMPT, never on the store: with
+     * a provider that can `search`, this is how many matter right now rather than how many a person
+     * may have. Always-on (`pinned`) memories are taken from it first.
+     */
+    maxMemories?: number;
+    /** How long one memory may be, checked when it is written. Omit → 240. */
+    maxFactChars?: number;
+}
 interface AgentModuleOptions {
     /** The LLM provider (e.g. a Vercel AI SDK wrapper). Required. */
     model: ModelProvider;
@@ -139,11 +223,19 @@ interface AgentModuleOptions {
     durable?: boolean;
     /**
      * Dispatch the turn's model call and tool executions as routed durable steps
-     * (`AgentRunSteps.llm` / `AgentRunSteps.tool`) instead of in-process `ctx.localStep`s.
-     * DEFAULT `true` under `durable: true` — dispatching moves the run off its pod during the two
-     * long steps (the correct production posture), and `AgentRunSteps` is always registered so the
-     * routed groups are never unserved. Set `false` to keep the turn's steps in-process localSteps.
-     * `true` without `durable: true` throws at module build.
+     * (`AgentRunSteps.llm` / `AgentRunSteps.tool`) instead of in-process `ctx.localStep`s. OMITTED
+     * keeps them in-process; `true` without `durable: true` throws at module build.
+     *
+     * WHAT IT BUYS: the run is not pinned to one pod for the two long parts of a turn, so a fleet can
+     * scale the model call and tool execution separately from the workflow itself.
+     *
+     * WHY IT IS NOT A DEFAULT. It relocates the HOST's own code. A tool handler no longer runs inside
+     * the turn's workflow body but inside whichever worker serves the routed group, and the `llm`
+     * step re-runs the host's tool-visibility callbacks there to rebuild its tool list. A handler
+     * that resolves anything per invocation from its caller's execution context — a request-scoped
+     * ORM EntityManager, an AsyncLocalStorage tenant, a CLS transaction — finds nothing in that
+     * worker, and the library has no way to know which handlers do that. Turn this on once the tools
+     * this deployment registers establish whatever context they need themselves.
      *
      * The cross-process-sink requirement is a property of `durable: true` itself, not of this flag:
      * the turn already runs on whichever worker takes `agent.run`, which may not be the pod holding
@@ -191,6 +283,75 @@ interface AgentModuleOptions {
         retriever: Retriever;
         topK?: number;
     };
+    /**
+     * Bounds how much of a thread rides into each turn. Omit and a turn carries EVERY message the
+     * thread holds, so a long-lived thread costs more each time and eventually exceeds the model's
+     * context limit outright. `{ maxMessages }` and/or `{ maxTokens }` keep the newest that fit;
+     * `{ summarize: true }` folds what they left out into a leading summary, at the price of one extra
+     * model call per run (recorded as `history_summary` usage). An agent can override this for itself
+     * with `@Agent({ history })`.
+     */
+    history?: AgentHistoryWindow;
+    /**
+     * A {@link HistoryPolicy} of your own — for a window the built-in can't express (pinning the
+     * thread's opening brief, keeping every message that carries a tool result, a budget that varies
+     * by actor). A convenience-vs-custom pair like `quotaLimitTokens`/`quota`: this outranks a
+     * module-wide `history`, and `@Agent({ history })` outranks both for the agent that declares it.
+     * `select` MUST be pure — see the SPI's determinism contract.
+     */
+    historyPolicy?: HistoryPolicy;
+    /**
+     * Rewrites the prompt before every model call — masking identifiers, stamping a policy preamble,
+     * trimming an oversized tool result. Applies to EVERY agent: a transformation one persona can opt
+     * out of is not a control. Transformation only; `history`/`historyPolicy` still own which messages
+     * are there to transform. A processor needing DI-resolved dependencies is built in
+     * `forRootAsync`'s `useFactory` (which has `inject`), the same way `retrieval.retriever` is.
+     */
+    inputProcessors?: InputProcessor[];
+    /**
+     * Gates every model answer before the stream, the store or the next step sees it — redact,
+     * replace, or refuse the turn outright (which fails it with an `output_rejected` stream error).
+     *
+     * REGISTERING ONE TURNS OFF LIVE TOKEN STREAMING. Reading the whole answer and streaming it as it
+     * is generated cannot both be true, so the turn's model output is buffered and released in one
+     * frame once the chain passes. That is the price of a gate that actually gates; see
+     * `AgentLoopDeps.outputProcessors` for exactly what a subscriber still receives live.
+     */
+    outputProcessors?: OutputProcessor[];
+    /**
+     * Offer every agent the built-in `ask` tool, so the model can put its own clarifying question set
+     * to the user when it judges the scope is missing. The turn parks on the answers exactly as it
+     * parks on a HITL approval, and they arrive through `POST /agent/tool-call/answer`.
+     *
+     * `ask` is not a registered tool and has no handler — the loop settles it against a person — so no
+     * `RolesPolicy` gates it: asking a question performs nothing. An `@Agent({ ask })` overrides this
+     * for one persona. Omit → the model never sees it, and nothing about a turn changes.
+     */
+    ask?: boolean;
+    /**
+     * Authored procedures any agent may pull in when a task calls for one — per-user, per-tenant or
+     * deployment-wide, with the most specific winning. Declared as `@Skill`-decorated providers and/or
+     * served by a `provider` of your own; offered to the model as a one-line-each catalog it loads
+     * from on demand, so an instruction costs a prompt only on the turns that need it.
+     *
+     * Omit → no catalog, no `skill` tool, and a turn's checkpoint sequence is byte-identical to one
+     * that never had the option. See {@link AgentSkillsOptions}.
+     */
+    skills?: AgentSkillsOptions;
+    /**
+     * What the assistant has concluded about the actor and their organisation, carried into every turn
+     * as a bounded block of one-line facts and written by the model through a built-in `remember` tool.
+     *
+     * NOT the same thing as retrieval, and not a second name for it: `retrieval` answers from documents
+     * a person curated and can fix at the source, memory answers from the agent's own inferences about
+     * someone who never saw them written. That is why the rows carry an origin, why the block tells the
+     * model they may be wrong, and why `GET /agent/memories` + `DELETE /agent/memories/:id` are part of
+     * the feature rather than an optional console.
+     *
+     * Omit → no block, no `remember` tool, and a turn's checkpoint sequence is byte-identical to one
+     * that never had the option. See {@link AgentMemoryOptions}.
+     */
+    memory?: AgentMemoryOptions;
     /**
      * The name of the agent a turn uses when the caller doesn't select one. Omit → the single
      * discovered `@Agent` (when there is exactly one), else `'default'` (a bare assistant if no
@@ -230,12 +391,11 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
      */
     durable?: boolean;
     /**
-     * Dispatch the turn's model call and tool executions as routed durable steps. DEFAULT `true`
-     * under `durable: true`; set `false` to keep the turn's steps in-process localSteps. Same
-     * static-wiring reasoning as `durable` above — it lives here (not in the async factory result)
-     * because it decides how `AgentRunWorkflow` builds its hooks at module build time. `true` without
-     * `durable: true` throws at module build. See `AgentModuleOptions.dispatchedSteps` for the full
-     * contract.
+     * Dispatch the turn's model call and tool executions as routed durable steps. Omitted keeps the
+     * turn's steps in-process localSteps. Same static-wiring reasoning as `durable` above — it lives
+     * here (not in the async factory result) because it decides how `AgentRunWorkflow` builds its
+     * hooks at module build time. `true` without `durable: true` throws at module build. See
+     * `AgentModuleOptions.dispatchedSteps` for the full contract.
      */
     dispatchedSteps?: boolean;
     /**
@@ -273,8 +433,18 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     surface?: AgentSurface;
 }
 
-/** The synthesized `agent`-kind tool name an orchestrator uses to hand off to `target`. */
-declare function delegateToolName(target: string): string;
+/**
+ * The synthesized `agent`-kind tool name an orchestrator uses to hand off to `target`.
+ *
+ * A detached edge gets its own verb — `start_research` next to `ask_research` — for two reasons.
+ * One agent can be both awaited AND backgrounded by the same orchestrator, and one name cannot
+ * carry both. And the name is the part of a tool the model reads first: `ask` promises an answer,
+ * `start` does not.
+ */
+declare function delegateToolName(args: {
+    target: string;
+    detached?: boolean;
+}): string;
 /** Builds the per-agent loop deps. The single-agent case is just the one registered `@Agent`. */
 declare class AgentDepsFactory {
     private readonly options;
@@ -287,7 +457,13 @@ declare class AgentDepsFactory {
     private readonly promptContributors;
     private readonly quota;
     private readonly pricingStore;
-    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], quota: QuotaStore | undefined, pricingStore: AgentPricingStore | undefined);
+    private readonly skills;
+    private readonly memory;
+    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], quota: QuotaStore | undefined, pricingStore: AgentPricingStore | undefined, skills: SkillsConfig | undefined, memory: MemoryConfig | undefined);
+    /** The turn's memory seam, shared with the read-back endpoint. Undefined → memory is not configured. */
+    memoryConfig(): MemoryConfig | undefined;
+    /** The turn's skills seam, shared with the listing endpoint. Undefined → skills are not configured. */
+    skillsConfig(): SkillsConfig | undefined;
     /**
      * The agent a turn uses when the caller names none: the explicit `defaultAgent` option, else the
      * sole registered `@Agent` when there is exactly one, else `'default'` (a bare assistant).
@@ -295,8 +471,16 @@ declare class AgentDepsFactory {
     defaultAgentName(): string;
     private effectiveTools;
     forAgent(agentName?: string): AgentDeps;
+    /**
+     * The ceiling on how much of a thread this agent's turns carry, most specific wins: the agent's
+     * own `@Agent({ history })`, else a module-wide custom `historyPolicy`, else the module-wide
+     * `history` window. Undefined → unbounded, the behaviour of a module that configures none.
+     */
+    private historyPolicy;
+    /** Build the built-in window policy from the declarative `{ maxMessages, maxTokens, summarize }`. */
+    private window;
     /** Normalize the `followUps` option (`true` → 3, `{ count }` → count) to a number, or undefined. */
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, AGENT_TOOL_BRAND as d, type AgentAttachmentsOptions as e, type AgentDeps as f, delegateToolName as g, provideAgentTool as p, utcDay as u };
+export { AgentDepsFactory as A, type FunctionalTool as F, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, delegateToolName as i, provideAgentTool as p, utcDay as u };