@dudousxd/nestjs-agent-core 0.13.0 → 0.15.0

package/dist/index.d.cts

@@ -2614,9 +2614,9 @@ declare function tenantScope(tenantRef: string): string;
  *
  * A HOST-SUPPLIED FUNCTION rather than an enum this library owns, because the axes a deployment
  * scopes by are the deployment's own. `Actor` gives an id and a tenant; it does not give a sector, a
- * squadron, a base, a shift — and every one of those is a real axis in some consumer. An enum here
+ * region, a warehouse, a shift — and every one of those is a real axis in some consumer. An enum here
  * would make each of them a schema change in a library that has no business knowing they exist,
- * while a token is a string a host mints for itself. Return `['sector:logistics', 'tenant:base-7',
+ * while a token is a string a host mints for itself. Return `['sector:logistics', 'tenant:berlin',
  * 'global']` and precedence follows, with nothing in this package edited.
  *
  * MUST be a pure function of its context. It runs inside the `skills:catalog` checkpoint and its
@@ -2915,7 +2915,7 @@ interface MemoryRecord {
     /**
      * Always-on: this fact is in the block whether or not the turn is about it. The difference between
      * working memory and recall, drawn per record — "they report on the calendar year" must not depend
-     * on the turn mentioning dates, while "they prefer the shorter runway" can wait until it comes up.
+     * on the turn mentioning dates, while "they prefer the kerbside dock" can wait until it comes up.
      *
      * A PROPERTY OF THE ROW, NOT OF A WRITE. This library reads it and never sets it, the same way it
      * never mints an `id`: an agent deciding its own conclusions are always-on is an agent deciding
@@ -2997,7 +2997,7 @@ interface ListMemoriesInput {
  *
  * `scopes` GATES, AND IT GATES FIRST. A search that ranks before it filters is a cross-tenant leak
  * wearing a relevance score: the nearest neighbour to "what is our rollback policy" is another
- * base's rollback policy. Filter in the query, not after it. Records returned outside `scopes` are
+ * tenant's rollback policy. Filter in the query, not after it. Records returned outside `scopes` are
  * dropped rather than trusted, so a mistake here costs throughput rather than privacy — but the
  * drop is a backstop, not the boundary.
  */
@@ -3470,6 +3470,16 @@ declare class ToolRegistry {
     private readonly entries;
     register(spec: ToolSpec, handler: ToolHandler): void;
     has(name: string): boolean;
+    /**
+     * Give a name back, and report whether it was held. For an importer that registered tools on
+     * someone else's behalf — the MCP client is the one in this repo — and has to hand back the ones
+     * its source stopped offering.
+     *
+     * The registry cannot tell whether a caller owns a name, so it does not try: whoever registered a
+     * name is responsible for tracking that it did. Unregistering a name it does not own would
+     * silently take a tool away from whoever does.
+     */
+    unregister(name: string): boolean;
     spec(name: string): ToolSpec | undefined;
     allSpecs(): ToolSpec[];
     /**
@@ -3569,7 +3579,9 @@ interface AgentLoopDeps<TOutput = unknown> {
     /**
      * Enables always-on ("inject") RAG: before the turn, retrieve passages for the user message and
      * augment the system prompt with them. Its presence IS inject mode — agentic (tool) retrieval sets
-     * no retriever here (it rides a normal `read` tool). Undefined → no injection.
+     * no retriever here (it rides a normal `read` tool). Undefined → no injection, and no `retrieve`
+     * position: which answer a RUN got is journaled (see {@link PromptStages}), so wiring one does not
+     * move the checkpoints of a turn already in flight.
      */
     retriever?: Retriever;
     /** How many passages inject-mode retrieval requests. Undefined → 5. */
@@ -3673,7 +3685,9 @@ interface AgentLoopDeps<TOutput = unknown> {
     /**
      * Authored procedures the model may pull in when a task calls for one, resolved per turn against
      * the actor's scopes — see `skills.ts`. Undefined → no catalog block, no `skill` tool, and a
-     * turn's checkpoint sequence is byte-identical to one that never had the option.
+     * turn's checkpoint sequence is byte-identical to one that never had the option — including for a
+     * turn that was already in flight when this was wired, because which answer a RUN got is journaled
+     * (see {@link PromptStages}).
      *
      * HOW IT COMPOSES WITH THE OTHER FOUR THINGS THAT WRITE THE PROMPT. The system block is assembled
      * in one fixed order — the agent's base prompt, then each `promptContributors` section, then
@@ -3692,7 +3706,8 @@ interface AgentLoopDeps<TOutput = unknown> {
      * What the assistant has previously concluded about the actor and their organisation, resolved per
      * turn against the same scope tokens skills use — see `memory.ts`. Undefined → no memory block, no
      * `remember` tool, and a turn's checkpoint sequence is byte-identical to one that never had the
-     * option.
+     * option — including for a turn that was already in flight when this was wired, because which
+     * answer a RUN got is journaled (see {@link PromptStages}).
      *
      * WHERE IT SITS IN THE PROMPT. The system block is assembled most-durable-first: the agent's base
      * prompt (the same for everyone, every turn), then `promptContributors`, then MEMORY (the same for

package/dist/index.d.ts

@@ -2614,9 +2614,9 @@ declare function tenantScope(tenantRef: string): string;
  *
  * A HOST-SUPPLIED FUNCTION rather than an enum this library owns, because the axes a deployment
  * scopes by are the deployment's own. `Actor` gives an id and a tenant; it does not give a sector, a
- * squadron, a base, a shift — and every one of those is a real axis in some consumer. An enum here
+ * region, a warehouse, a shift — and every one of those is a real axis in some consumer. An enum here
  * would make each of them a schema change in a library that has no business knowing they exist,
- * while a token is a string a host mints for itself. Return `['sector:logistics', 'tenant:base-7',
+ * while a token is a string a host mints for itself. Return `['sector:logistics', 'tenant:berlin',
  * 'global']` and precedence follows, with nothing in this package edited.
  *
  * MUST be a pure function of its context. It runs inside the `skills:catalog` checkpoint and its
@@ -2915,7 +2915,7 @@ interface MemoryRecord {
     /**
      * Always-on: this fact is in the block whether or not the turn is about it. The difference between
      * working memory and recall, drawn per record — "they report on the calendar year" must not depend
-     * on the turn mentioning dates, while "they prefer the shorter runway" can wait until it comes up.
+     * on the turn mentioning dates, while "they prefer the kerbside dock" can wait until it comes up.
      *
      * A PROPERTY OF THE ROW, NOT OF A WRITE. This library reads it and never sets it, the same way it
      * never mints an `id`: an agent deciding its own conclusions are always-on is an agent deciding
@@ -2997,7 +2997,7 @@ interface ListMemoriesInput {
  *
  * `scopes` GATES, AND IT GATES FIRST. A search that ranks before it filters is a cross-tenant leak
  * wearing a relevance score: the nearest neighbour to "what is our rollback policy" is another
- * base's rollback policy. Filter in the query, not after it. Records returned outside `scopes` are
+ * tenant's rollback policy. Filter in the query, not after it. Records returned outside `scopes` are
  * dropped rather than trusted, so a mistake here costs throughput rather than privacy — but the
  * drop is a backstop, not the boundary.
  */
@@ -3470,6 +3470,16 @@ declare class ToolRegistry {
     private readonly entries;
     register(spec: ToolSpec, handler: ToolHandler): void;
     has(name: string): boolean;
+    /**
+     * Give a name back, and report whether it was held. For an importer that registered tools on
+     * someone else's behalf — the MCP client is the one in this repo — and has to hand back the ones
+     * its source stopped offering.
+     *
+     * The registry cannot tell whether a caller owns a name, so it does not try: whoever registered a
+     * name is responsible for tracking that it did. Unregistering a name it does not own would
+     * silently take a tool away from whoever does.
+     */
+    unregister(name: string): boolean;
     spec(name: string): ToolSpec | undefined;
     allSpecs(): ToolSpec[];
     /**
@@ -3569,7 +3579,9 @@ interface AgentLoopDeps<TOutput = unknown> {
     /**
      * Enables always-on ("inject") RAG: before the turn, retrieve passages for the user message and
      * augment the system prompt with them. Its presence IS inject mode — agentic (tool) retrieval sets
-     * no retriever here (it rides a normal `read` tool). Undefined → no injection.
+     * no retriever here (it rides a normal `read` tool). Undefined → no injection, and no `retrieve`
+     * position: which answer a RUN got is journaled (see {@link PromptStages}), so wiring one does not
+     * move the checkpoints of a turn already in flight.
      */
     retriever?: Retriever;
     /** How many passages inject-mode retrieval requests. Undefined → 5. */
@@ -3673,7 +3685,9 @@ interface AgentLoopDeps<TOutput = unknown> {
     /**
      * Authored procedures the model may pull in when a task calls for one, resolved per turn against
      * the actor's scopes — see `skills.ts`. Undefined → no catalog block, no `skill` tool, and a
-     * turn's checkpoint sequence is byte-identical to one that never had the option.
+     * turn's checkpoint sequence is byte-identical to one that never had the option — including for a
+     * turn that was already in flight when this was wired, because which answer a RUN got is journaled
+     * (see {@link PromptStages}).
      *
      * HOW IT COMPOSES WITH THE OTHER FOUR THINGS THAT WRITE THE PROMPT. The system block is assembled
      * in one fixed order — the agent's base prompt, then each `promptContributors` section, then
@@ -3692,7 +3706,8 @@ interface AgentLoopDeps<TOutput = unknown> {
      * What the assistant has previously concluded about the actor and their organisation, resolved per
      * turn against the same scope tokens skills use — see `memory.ts`. Undefined → no memory block, no
      * `remember` tool, and a turn's checkpoint sequence is byte-identical to one that never had the
-     * option.
+     * option — including for a turn that was already in flight when this was wired, because which
+     * answer a RUN got is journaled (see {@link PromptStages}).
      *
      * WHERE IT SITS IN THE PROMPT. The system block is assembled most-durable-first: the agent's base
      * prompt (the same for everyone, every turn), then `promptContributors`, then MEMORY (the same for

package/dist/index.js

@@ -1746,6 +1746,18 @@ var ToolRegistry = class {
   has(name) {
     return this.entries.has(name);
   }
+  /**
+  * Give a name back, and report whether it was held. For an importer that registered tools on
+  * someone else's behalf — the MCP client is the one in this repo — and has to hand back the ones
+  * its source stopped offering.
+  *
+  * The registry cannot tell whether a caller owns a name, so it does not try: whoever registered a
+  * name is responsible for tracking that it did. Unregistering a name it does not own would
+  * silently take a tool away from whoever does.
+  */
+  unregister(name) {
+    return this.entries.delete(name);
+  }
   spec(name) {
     return this.entries.get(name)?.spec;
   }
@@ -2059,7 +2071,12 @@ var MAX_DELEGATION_DEPTH = 5;
 var DEFAULT_MAX_AGENT_APPEARANCES = 1;
 function delegationRefusal(args) {
   const { deps, input, targetAgent } = args;
-  const ancestry = input.delegationPath ?? [];
+  const ancestry = [
+    ...input.delegationPath ?? [],
+    ...input.agentName !== void 0 ? [
+      input.agentName
+    ] : []
+  ];
   const appearances = ancestry.filter((name) => name === targetAgent).length;
   const maxAppearances = deps.maxAgentAppearances ?? DEFAULT_MAX_AGENT_APPEARANCES;
   if (appearances >= maxAppearances) {
@@ -2594,6 +2611,27 @@ __name(runIntake, "runIntake");
 var PARALLEL_TOOLS_PATCH = "agent:parallel-tools";
 var CANCELLATION_PATCH = "agent:cancellation";
 var SELECTED_HISTORY_PATCH = "agent:selected-history";
+var PROMPT_STAGES_PATCH = "agent:prompt-stages";
+async function resolvePromptStages(deps, hooks) {
+  const configured = {
+    memory: deps.memory !== void 0,
+    retriever: deps.retriever !== void 0,
+    skills: deps.skills !== void 0
+  };
+  return await (hooks.patched?.(PROMPT_STAGES_PATCH) ?? Promise.resolve(true)) ? hooks.step("run:prompt-stages", () => Promise.resolve(configured)) : configured;
+}
+__name(resolvePromptStages, "resolvePromptStages");
+var UNSERVED_MEMORY = {
+  scopes: [],
+  entries: [],
+  omitted: 0,
+  pinnedOmitted: 0
+};
+var UNSERVED_SKILLS = {
+  scopes: [],
+  entries: [],
+  omitted: 0
+};
 async function haltIfCancelled(hooks, cancellable, name) {
   const observe = hooks.cancelled;
   if (!cancellable || observe === void 0) {
@@ -3121,6 +3159,7 @@ async function runAgentLoop(deps, input, hooks) {
       agentName: input.agentName
     } : {}
   });
+  const stages = await resolvePromptStages(deps, hooks);
   const startedAt = await hooks.step("run:started-at", () => Promise.resolve(Date.now()));
   await hooks.step("persist:run:start", async () => {
     const promptHash = createHash("sha256").update(system).digest("hex");
@@ -3138,9 +3177,9 @@ async function runAgentLoop(deps, input, hooks) {
     });
   });
   let memoryDigest;
-  if (deps.memory !== void 0) {
+  if (stages.memory) {
     const config = deps.memory;
-    memoryDigest = await hooks.step("memory:digest", () => offerMemories({
+    memoryDigest = await hooks.step("memory:digest", () => config === void 0 ? Promise.resolve(UNSERVED_MEMORY) : offerMemories({
       config,
       ctx: skillContext(input),
       query: input.userText
@@ -3167,16 +3206,16 @@ ${block}`;
     });
   }
   let injectedPassages;
-  if (deps.retriever !== void 0) {
+  if (stages.retriever) {
     const retriever = deps.retriever;
     const topK = deps.retrievalTopK ?? 5;
     const passages = await hooks.step("retrieve", () => spanned("retrieval", hooks.runId, {
       runId: hooks.runId,
       queryLength: input.userText.length,
       topK
-    }, () => retriever.retrieve(input.userText, {
+    }, () => retriever?.retrieve(input.userText, {
       topK
-    }), (retrieved) => ({
+    }) ?? Promise.resolve([]), (retrieved) => ({
       count: retrieved.length
     })));
     if (passages.length > 0) {
@@ -3192,9 +3231,9 @@ ${buildContextBlock(passages)}`;
     });
   }
   let skillOffer;
-  if (deps.skills !== void 0) {
+  if (stages.skills) {
     const config = deps.skills;
-    skillOffer = await hooks.step("skills:catalog", () => offerSkills(config, skillContext(input)));
+    skillOffer = await hooks.step("skills:catalog", () => config === void 0 ? Promise.resolve(UNSERVED_SKILLS) : offerSkills(config, skillContext(input)));
     const block = skillOffer.entries.length > 0 ? buildSkillsBlock(skillOffer.entries) : "";
     if (block.length > 0) {
       system = `${system}