@dudousxd/nestjs-agent-core 0.44.1 → 0.45.0

package/dist/guardrails/index.d.cts

@@ -1,7 +1,7 @@
-import { I as InputProcessor, O as OutputProcessor } from '../processors-BANqZT3O.cjs';
-import { a as Actor, b as ToolHandler } from '../stream-events-BfxJAckJ.cjs';
+import { I as InputProcessor, O as OutputProcessor } from '../processors-BhOGaMPY.cjs';
+import { a as Actor, b as ToolHandler } from '../stream-events-qB6NOOvn.cjs';
 import '@standard-schema/spec';
-import '../catalog-G8usJpx5.cjs';
+import '../catalog-BUmTnAqU.cjs';
 
 /**
  * Guardrails: detectors that look at text on its way to or from a model — prompts, answers, tool

package/dist/guardrails/index.d.ts

@@ -1,7 +1,7 @@
-import { I as InputProcessor, O as OutputProcessor } from '../processors-C9mor-73.js';
-import { a as Actor, b as ToolHandler } from '../stream-events-DFa2Do42.js';
+import { I as InputProcessor, O as OutputProcessor } from '../processors-DDKKky_6.js';
+import { a as Actor, b as ToolHandler } from '../stream-events-CqCqYjJw.js';
 import '@standard-schema/spec';
-import '../catalog-G8usJpx5.js';
+import '../catalog-BUmTnAqU.js';
 
 /**
  * Guardrails: detectors that look at text on its way to or from a model — prompts, answers, tool

package/dist/index.cjs

@@ -68,6 +68,7 @@ __export(src_exports, {
   DEFAULT_MAX_FACT_CHARS: () => DEFAULT_MAX_FACT_CHARS,
   DEFAULT_MAX_MEMORIES: () => DEFAULT_MAX_MEMORIES,
   DEFAULT_MAX_SKILLS: () => DEFAULT_MAX_SKILLS,
+  DEFAULT_PREVIEW_THROTTLE_MS: () => DEFAULT_PREVIEW_THROTTLE_MS,
   DEFAULT_REFUSAL_REASON: () => DEFAULT_REFUSAL_REASON,
   DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION: () => DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION,
   DEFAULT_TEXT_ACTION_PROPOSAL_REPLIES: () => DEFAULT_TEXT_ACTION_PROPOSAL_REPLIES,
@@ -186,9 +187,12 @@ __export(src_exports, {
   observeTurnFrames: () => observeTurnFrames,
   offerMemories: () => offerMemories,
   offerSkills: () => offerSkills,
+  parsePartialJson: () => parsePartialJson,
   parseTextActionProposalCommand: () => parseTextActionProposalCommand,
   personaCatalogEntry: () => personaCatalogEntry,
   prepareActionProposal: () => prepareActionProposal,
+  previewToolInputs: () => previewToolInputs,
+  previewUiId: () => previewUiId,
   ptBrActionProposalText: () => ptBrActionProposalText,
   publishAgentDelegated: () => publishAgentDelegated,
   publishAgentMemoryResolved: () => publishAgentMemoryResolved,
@@ -209,6 +213,7 @@ __export(src_exports, {
   quotaWarning: () => quotaWarning,
   readElicitationInput: () => readElicitationInput,
   readElicitationQuestions: () => readElicitationQuestions,
+  registryInputPreviews: () => registryInputPreviews,
   releaseGatedFrames: () => releaseGatedFrames,
   releaseThreadRun: () => releaseThreadRun,
   rememberInputSchema: () => rememberInputSchema,
@@ -277,6 +282,7 @@ __export(src_exports, {
   withSkillTool: () => withSkillTool,
   withToolTimeout: () => withToolTimeout,
   withTurnFrames: () => withTurnFrames,
+  withdrawPreviewEvent: () => withdrawPreviewEvent,
   wrapToolPreflightDenied: () => wrapToolPreflightDenied,
   wrapToolStepOutput: () => wrapToolStepOutput,
   writeMemory: () => writeMemory
@@ -398,7 +404,7 @@ function observeTurnFrames(writer, now = Date.now) {
       return;
     }
     closeBurst();
-    if (event.kind === "ui") {
+    if (event.kind === "ui" && event.partial !== true) {
       ui.set(event.id, {
         id: event.id,
         component: event.component,
@@ -468,6 +474,423 @@ function withTurnFrames(result2, frames) {
 }
 __name(withTurnFrames, "withTurnFrames");
 
+// src/partial-json.ts
+var Cut = class Cut2 extends Error {
+  static {
+    __name(this, "Cut");
+  }
+};
+function parsePartialJson(text) {
+  const open = /* @__PURE__ */ new WeakSet();
+  const pending = /* @__PURE__ */ new WeakMap();
+  let at = 0;
+  const skipSpace = /* @__PURE__ */ __name(() => {
+    while (at < text.length) {
+      const char = text.charCodeAt(at);
+      if (char === 32 || char === 9 || char === 10 || char === 13) at += 1;
+      else break;
+    }
+  }, "skipSpace");
+  const fail = /* @__PURE__ */ __name(() => {
+    throw new SyntaxError(`unexpected character at ${at}`);
+  }, "fail");
+  const readString = /* @__PURE__ */ __name(() => {
+    at += 1;
+    let out = "";
+    while (at < text.length) {
+      const char = text[at];
+      if (char === '"') {
+        at += 1;
+        return {
+          value: out,
+          cut: false
+        };
+      }
+      if (char === "\\") {
+        const next = text[at + 1];
+        if (next === void 0) {
+          at = text.length;
+          return {
+            value: out,
+            cut: true
+          };
+        }
+        if (next === "u") {
+          const hex = text.slice(at + 2, at + 6);
+          if (hex.length < 4) {
+            at = text.length;
+            return {
+              value: out,
+              cut: true
+            };
+          }
+          if (!/^[0-9a-fA-F]{4}$/.test(hex)) fail();
+          out += String.fromCharCode(Number.parseInt(hex, 16));
+          at += 6;
+          continue;
+        }
+        const escapes = {
+          '"': '"',
+          "\\": "\\",
+          "/": "/",
+          b: "\b",
+          f: "\f",
+          n: "\n",
+          r: "\r",
+          t: "	"
+        };
+        const escaped = escapes[next];
+        if (escaped === void 0) fail();
+        out += escaped;
+        at += 2;
+        continue;
+      }
+      out += char;
+      at += 1;
+    }
+    return {
+      value: out,
+      cut: true
+    };
+  }, "readString");
+  const readValue = /* @__PURE__ */ __name(() => {
+    skipSpace();
+    if (at >= text.length) throw new Cut();
+    const char = text[at];
+    if (char === "{") return readObject();
+    if (char === "[") return readArray();
+    if (char === '"') return readString();
+    const rest = text.slice(at);
+    const number = /^-?\d*(?:\.\d*)?(?:[eE][+-]?\d*)?/.exec(rest)?.[0] ?? "";
+    if (number.length > 0) {
+      if (at + number.length >= text.length) throw new Cut();
+      if (!/^-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?$/.test(number)) fail();
+      at += number.length;
+      return {
+        value: Number(number),
+        cut: false
+      };
+    }
+    for (const [word, value] of [
+      [
+        "true",
+        true
+      ],
+      [
+        "false",
+        false
+      ],
+      [
+        "null",
+        null
+      ]
+    ]) {
+      if (rest.startsWith(word)) {
+        at += word.length;
+        return {
+          value,
+          cut: false
+        };
+      }
+      if (word.startsWith(rest)) throw new Cut();
+    }
+    return fail();
+  }, "readValue");
+  const readObject = /* @__PURE__ */ __name(() => {
+    const object = {};
+    open.add(object);
+    at += 1;
+    skipSpace();
+    if (text[at] === "}") {
+      at += 1;
+      open.delete(object);
+      return {
+        value: object,
+        cut: false
+      };
+    }
+    for (; ; ) {
+      skipSpace();
+      if (at >= text.length) return {
+        value: object,
+        cut: true
+      };
+      if (text[at] !== '"') fail();
+      const key = readString();
+      if (key.cut) return {
+        value: object,
+        cut: true
+      };
+      skipSpace();
+      if (at >= text.length) {
+        pending.set(object, key.value);
+        return {
+          value: object,
+          cut: true
+        };
+      }
+      if (text[at] !== ":") fail();
+      at += 1;
+      let member;
+      try {
+        member = readValue();
+      } catch (error) {
+        if (!(error instanceof Cut)) throw error;
+        pending.set(object, key.value);
+        return {
+          value: object,
+          cut: true
+        };
+      }
+      object[key.value] = member.value;
+      if (member.cut) {
+        pending.set(object, key.value);
+        return {
+          value: object,
+          cut: true
+        };
+      }
+      skipSpace();
+      if (at >= text.length) return {
+        value: object,
+        cut: true
+      };
+      if (text[at] === ",") {
+        at += 1;
+        continue;
+      }
+      if (text[at] === "}") {
+        at += 1;
+        open.delete(object);
+        return {
+          value: object,
+          cut: false
+        };
+      }
+      fail();
+    }
+  }, "readObject");
+  const readArray = /* @__PURE__ */ __name(() => {
+    const array = [];
+    open.add(array);
+    at += 1;
+    skipSpace();
+    if (text[at] === "]") {
+      at += 1;
+      open.delete(array);
+      return {
+        value: array,
+        cut: false
+      };
+    }
+    for (; ; ) {
+      let item;
+      try {
+        item = readValue();
+      } catch (error) {
+        if (!(error instanceof Cut)) throw error;
+        pending.set(array, array.length);
+        return {
+          value: array,
+          cut: true
+        };
+      }
+      array.push(item.value);
+      if (item.cut) {
+        pending.set(array, array.length - 1);
+        return {
+          value: array,
+          cut: true
+        };
+      }
+      skipSpace();
+      if (at >= text.length) return {
+        value: array,
+        cut: true
+      };
+      if (text[at] === ",") {
+        at += 1;
+        continue;
+      }
+      if (text[at] === "]") {
+        at += 1;
+        open.delete(array);
+        return {
+          value: array,
+          cut: false
+        };
+      }
+      fail();
+    }
+  }, "readArray");
+  let root;
+  try {
+    root = readValue();
+  } catch (error) {
+    if (error instanceof Cut) root = {
+      value: void 0,
+      cut: true
+    };
+    else return void 0;
+  }
+  skipSpace();
+  return {
+    value: root.value,
+    complete: !root.cut && at >= text.length,
+    isOpen: /* @__PURE__ */ __name((container) => open.has(container), "isOpen"),
+    pendingMember: /* @__PURE__ */ __name((container) => pending.get(container), "pendingMember")
+  };
+}
+__name(parsePartialJson, "parsePartialJson");
+
+// src/tool-input-preview.ts
+var DEFAULT_PREVIEW_THROTTLE_MS = 100;
+function previewUiId(toolCallId) {
+  return `${toolCallId}:ui:0`;
+}
+__name(previewUiId, "previewUiId");
+function withdrawPreviewEvent(shown) {
+  return {
+    kind: "ui",
+    id: shown.id,
+    component: shown.component,
+    props: {},
+    toolCallId: shown.toolCallId,
+    partial: true
+  };
+}
+__name(withdrawPreviewEvent, "withdrawPreviewEvent");
+function previewToolInputs(inner, resolve, now = Date.now) {
+  const calls = /* @__PURE__ */ new Map();
+  const shown = /* @__PURE__ */ new Map();
+  const decoder3 = new TextDecoder();
+  let pending = "";
+  async function emit2(id, state, input, done) {
+    let rendered;
+    try {
+      const parsed = done && input !== void 0 ? {
+        value: input,
+        complete: true,
+        isOpen: /* @__PURE__ */ __name(() => false, "isOpen"),
+        pendingMember: /* @__PURE__ */ __name(() => void 0, "pendingMember")
+      } : parsePartialJson(state.text);
+      if (parsed === void 0) return;
+      rendered = state.preview.render({
+        value: parsed.value,
+        done: done || parsed.complete,
+        isOpen: parsed.isOpen,
+        pendingMember: parsed.pendingMember
+      });
+    } catch {
+      rendered = null;
+    }
+    if (rendered === void 0) return;
+    const uiId = previewUiId(id);
+    if (rendered === null) {
+      state.stopped = true;
+      const standing = shown.get(uiId);
+      if (standing !== void 0) {
+        shown.delete(uiId);
+        await inner.write(encodeStreamEvent(withdrawPreviewEvent(standing)));
+      }
+      return;
+    }
+    const props = JSON.stringify(rendered.props);
+    if (props === state.lastProps && rendered.component === state.component) return;
+    state.lastProps = props;
+    state.component = rendered.component;
+    state.lastAt = now();
+    shown.set(uiId, {
+      id: uiId,
+      component: rendered.component,
+      toolCallId: id
+    });
+    await inner.write(encodeStreamEvent({
+      kind: "ui",
+      id: uiId,
+      component: rendered.component,
+      props: JSON.parse(props),
+      ...rendered.version !== void 0 ? {
+        version: rendered.version
+      } : {},
+      toolCallId: id,
+      partial: true
+    }));
+  }
+  __name(emit2, "emit");
+  async function observe(event) {
+    if (event.kind === "tool-input-start") {
+      if (calls.has(event.id)) return;
+      let preview;
+      try {
+        preview = await resolve(event.name, event.id);
+      } catch {
+        preview = void 0;
+      }
+      if (preview !== void 0) {
+        calls.set(event.id, {
+          preview,
+          text: "",
+          lastAt: void 0,
+          lastProps: void 0,
+          component: void 0,
+          stopped: false
+        });
+      }
+      return;
+    }
+    if (event.kind === "tool-input-delta") {
+      const state = calls.get(event.id);
+      if (state === void 0 || state.stopped) return;
+      state.text += event.delta;
+      const throttle = state.preview.throttleMs ?? DEFAULT_PREVIEW_THROTTLE_MS;
+      if (state.lastAt !== void 0 && now() - state.lastAt < throttle) return;
+      await emit2(event.id, state, void 0, false);
+      return;
+    }
+    if (event.kind === "tool-input-available") {
+      const state = calls.get(event.id);
+      if (state === void 0) return;
+      calls.delete(event.id);
+      if (state.stopped) return;
+      await emit2(event.id, state, event.input, true);
+    }
+  }
+  __name(observe, "observe");
+  return {
+    writer: {
+      async write(chunk) {
+        await inner.write(chunk);
+        pending += decoder3.decode(chunk, {
+          stream: true
+        });
+        let newline = pending.indexOf("\n");
+        while (newline !== -1) {
+          const line = pending.slice(0, newline);
+          pending = pending.slice(newline + 1);
+          const event = line.trim().length > 0 ? decodeStreamEvent(line) : null;
+          if (event !== null) await observe(event);
+          newline = pending.indexOf("\n");
+        }
+      },
+      end: /* @__PURE__ */ __name(() => inner.end(), "end"),
+      fail: /* @__PURE__ */ __name((error) => inner.fail(error), "fail")
+    },
+    shown: /* @__PURE__ */ __name(() => [
+      ...shown.values()
+    ], "shown")
+  };
+}
+__name(previewToolInputs, "previewToolInputs");
+function registryInputPreviews(registry, offered, scope) {
+  const names = new Set(offered.map((tool) => tool.name));
+  return async (toolName, toolCallId) => names.has(toolName) ? registry.previewInput(toolName, {
+    ...scope,
+    toolCallId
+  }) : void 0;
+}
+__name(registryInputPreviews, "registryInputPreviews");
+
 // src/tool-ui.ts
 var TOOL_STEP_UI = "@@nestjs-agent/tool-step-ui";
 function wrapToolStepOutput(output, ui, text) {
@@ -3354,6 +3777,7 @@ function defineComponent(definition) {
   }
   if (definition.version !== void 0 && (!Number.isSafeInteger(definition.version) || definition.version <= 0)) throw new RangeError("genui: component version must be a positive safe integer");
   if (definition.fallbackText !== void 0 && typeof definition.fallbackText !== "function") throw new TypeError("genui: fallbackText must be a function");
+  if (definition.streaming !== void 0 && definition.streaming !== "partial" && definition.streaming !== "complete") throw new TypeError("genui: streaming must be 'partial' or 'complete'");
   return definition;
 }
 __name(defineComponent, "defineComponent");
@@ -4712,6 +5136,19 @@ var ToolRegistry = class {
   unregister(name) {
     return this.entries.delete(name);
   }
+  /**
+  * How a streamed call of `name` is previewed while its input arrives (`ToolHandler.previewInput`),
+  * or `undefined`. A preview that fails to build is no preview: it never fails the turn.
+  */
+  async previewInput(name, scope) {
+    const handler = this.entries.get(name)?.handler;
+    if (handler?.previewInput === void 0) return void 0;
+    try {
+      return await handler.previewInput(scope) ?? void 0;
+    } catch {
+      return void 0;
+    }
+  }
   spec(name) {
     return this.entries.get(name)?.spec;
   }
@@ -4770,6 +5207,9 @@ var ToolRegistry = class {
   * Run a tool. Re-checks that the tool is enabled and that the role allows it (defense-in-depth —
   * a call can reach here from a replayed durable step or an approval granted before the flag
   * moved, neither of which went through `definitionsFor` again) and re-parses the input via Zod.
+  * A tool whose `describe()` answers `available: false` for the call's scope (actor, thread, agent,
+  * `uiCapabilities`) is refused with {@link ToolNotFoundError}, as the unknown tool it was to the
+  * model.
   */
   async invoke(name, input, ctx, policy, options = {}) {
     const { entry, value, ctx: withEmit } = await this.validated(name, input, ctx, policy, options);
@@ -4823,6 +5263,10 @@ var ToolRegistry = class {
     if (options.allowedTools !== void 0 && !options.allowedTools.includes(name)) {
       throw new ToolForbiddenError(name);
     }
+    if (entry.handler.describe !== void 0) {
+      const described = await entry.handler.describe(describeScopeOf(ctx));
+      if (described?.available === false) throw new ToolNotFoundError(name);
+    }
     const validation = await entry.spec.inputSchema["~standard"].validate(input);
     if (validation.issues !== void 0) {
       throw new ToolInputInvalidError(name, validation.issues);
@@ -4838,6 +5282,21 @@ var ToolRegistry = class {
     };
   }
 };
+function describeScopeOf(ctx) {
+  return {
+    actor: ctx.actor,
+    ...ctx.threadId ? {
+      threadId: ctx.threadId
+    } : {},
+    ...ctx.agentName !== void 0 ? {
+      agentName: ctx.agentName
+    } : {},
+    ...ctx.uiCapabilities !== void 0 ? {
+      uiCapabilities: ctx.uiCapabilities
+    } : {}
+  };
+}
+__name(describeScopeOf, "describeScopeOf");
 var DefaultRolesPolicy = class {
   static {
     __name(this, "DefaultRolesPolicy");
@@ -5221,6 +5680,21 @@ var RunCancelledError = class extends Error {
     this.name = "RunCancelledError";
   }
 };
+async function abortableModelCall(hooks, call) {
+  const signal = hooks.abortSignal;
+  let result2;
+  try {
+    result2 = await call(signal !== void 0 ? {
+      abortSignal: signal
+    } : {});
+  } catch (error) {
+    if (signal?.aborted === true) throw new RunCancelledError();
+    throw error;
+  }
+  if (signal?.aborted === true) throw new RunCancelledError();
+  return result2;
+}
+__name(abortableModelCall, "abortableModelCall");
 function agentFailureCode(error) {
   if (error instanceof RunCancelledError) {
     return "cancelled";
@@ -5678,13 +6152,14 @@ async function structureAnswer(schema, deps, input, hooks, messages, step) {
         fail: /* @__PURE__ */ __name(() => {
         }, "fail")
       };
-      const turn = await deps.model.runTurn({
+      const turn = await abortableModelCall(hooks, (signal) => deps.model.runTurn({
         system,
         messages,
         tools: [],
         sink: discard,
-        outputSchema: schema
-      });
+        outputSchema: schema,
+        ...signal
+      }));
       return {
         text: turn.text,
         usage: turn.usage,
@@ -5806,6 +6281,9 @@ function toolContext(deps, input, hooks) {
     ...deps.host !== void 0 ? {
       host: deps.host
     } : {},
+    ...hooks.abortSignal !== void 0 ? {
+      abortSignal: hooks.abortSignal
+    } : {},
     // Replaced per tool call by the call's own collector (see the tool step); this one only serves
     // what runs outside a call — the elicitation wait.
     emitUi: createNoopEmitUi(hooks.runId)
@@ -7173,26 +7651,46 @@ ${block}`;
           writer
         }) : void 0;
         const buffer = gateMode === "whole" ? createFrameBuffer() : void 0;
-        const frames = observeTurnFrames(incremental?.writer ?? buffer?.writer ?? writer);
-        const result2 = stampToolKinds(withTurnFrames(await traceLlmTurn(hooks.runId, i, () => deps.model.runTurn({
+        const previews = previewToolInputs(incremental?.writer ?? buffer?.writer ?? writer, registryInputPreviews(deps.registry, tools, {
+          actor: input.actor,
+          threadId: input.threadId,
+          ...input.agentName !== void 0 ? {
+            agentName: input.agentName
+          } : {},
+          ...input.uiCapabilities !== void 0 ? {
+            uiCapabilities: input.uiCapabilities
+          } : {}
+        }));
+        const frames = observeTurnFrames(previews.writer);
+        const result2 = stampToolKinds(withTurnFrames(await traceLlmTurn(hooks.runId, i, () => abortableModelCall(hooks, (signal) => deps.model.runTurn({
           system: prompt.system,
           messages: prompt.messages,
           tools,
-          sink: frames.writer
-        })), frames.summary()), deps);
+          sink: frames.writer,
+          ...signal
+        }))), frames.summary()), deps);
+        const shownPreviews = previews.shown();
+        const previewed = shownPreviews.length > 0 ? {
+          previews: shownPreviews
+        } : {};
         if (incremental !== void 0) {
           await incremental.settled();
           const refusal = incremental.rejection();
           return {
             ...result2,
+            ...previewed,
             releasedText: incremental.released(),
             ...refusal !== void 0 ? {
               gateRejection: refusal
             } : {}
           };
         }
-        return buffer === void 0 ? result2 : {
+        return buffer === void 0 ? {
+          ...result2,
+          ...previewed
+        } : {
           ...result2,
+          ...previewed,
           bufferedFrames: buffer.frames()
         };
       });
@@ -7511,6 +8009,12 @@ ${block}`;
       if (toolUi.length > 0) {
         await deps.store.setMessageUi?.(assistant.id, mergeUi(turn.ui, toolUi));
       }
+      for (const preview of turn.previews ?? []) {
+        const pushed = turnCalls.toolUi.get(preview.toolCallId) ?? [];
+        if (!pushed.some((component) => component.id === preview.id)) {
+          await writer.write(encodeStreamEvent(withdrawPreviewEvent(preview)));
+        }
+      }
       for (const result2 of results) {
         await writer.write(encodeStreamEvent(outputFrame(result2)));
       }
@@ -9796,6 +10300,7 @@ __name(createFunctionalTool, "createFunctionalTool");
   DEFAULT_MAX_FACT_CHARS,
   DEFAULT_MAX_MEMORIES,
   DEFAULT_MAX_SKILLS,
+  DEFAULT_PREVIEW_THROTTLE_MS,
   DEFAULT_REFUSAL_REASON,
   DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION,
   DEFAULT_TEXT_ACTION_PROPOSAL_REPLIES,
@@ -9914,9 +10419,12 @@ __name(createFunctionalTool, "createFunctionalTool");
   observeTurnFrames,
   offerMemories,
   offerSkills,
+  parsePartialJson,
   parseTextActionProposalCommand,
   personaCatalogEntry,
   prepareActionProposal,
+  previewToolInputs,
+  previewUiId,
   ptBrActionProposalText,
   publishAgentDelegated,
   publishAgentMemoryResolved,
@@ -9937,6 +10445,7 @@ __name(createFunctionalTool, "createFunctionalTool");
   quotaWarning,
   readElicitationInput,
   readElicitationQuestions,
+  registryInputPreviews,
   releaseGatedFrames,
   releaseThreadRun,
   rememberInputSchema,
@@ -10005,6 +10514,7 @@ __name(createFunctionalTool, "createFunctionalTool");
   withSkillTool,
   withToolTimeout,
   withTurnFrames,
+  withdrawPreviewEvent,
   wrapToolPreflightDenied,
   wrapToolStepOutput,
   writeMemory