@dudousxd/nestjs-agent-core 0.36.0 → 0.37.0

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(src_exports, {
   AGENT_ACTOR_RESOLVER: () => AGENT_ACTOR_RESOLVER,
   AGENT_APPROVAL_PORT: () => AGENT_APPROVAL_PORT,
   AGENT_ATTACHMENT_STAGING: () => AGENT_ATTACHMENT_STAGING,
+  AGENT_CONFIRM_TOKEN_STORE: () => AGENT_CONFIRM_TOKEN_STORE,
   AGENT_DEPS_FACTORY: () => AGENT_DEPS_FACTORY,
   AGENT_DIAGNOSTIC_EVENTS: () => AGENT_DIAGNOSTIC_EVENTS,
   AGENT_DURABLE_RUNNER: () => AGENT_DURABLE_RUNNER,
@@ -54,7 +55,10 @@ __export(src_exports, {
   ASK_TOOL_NAME: () => ASK_TOOL_NAME,
   AgentRegistry: () => AgentRegistry,
   AgentStreamError: () => AgentStreamError,
+  CONFIRM_JSON_SCHEMA_PROPERTIES: () => CONFIRM_JSON_SCHEMA_PROPERTIES,
   ClosedRolesPolicy: () => ClosedRolesPolicy,
+  ConfirmTokenError: () => ConfirmTokenError,
+  DEFAULT_CONFIRM_TTL_MS: () => DEFAULT_CONFIRM_TTL_MS,
   DEFAULT_HISTORY_SUMMARY_INSTRUCTION: () => DEFAULT_HISTORY_SUMMARY_INSTRUCTION,
   DEFAULT_INCREMENTAL_LOOKBACK_CHARS: () => DEFAULT_INCREMENTAL_LOOKBACK_CHARS,
   DEFAULT_INTAKE_PREAMBLE: () => DEFAULT_INTAKE_PREAMBLE,
@@ -70,6 +74,7 @@ __export(src_exports, {
   ELICITATION_INPUT_TYPES: () => ELICITATION_INPUT_TYPES,
   GLOBAL_SCOPE: () => GLOBAL_SCOPE,
   InMemoryAgentStore: () => InMemoryAgentStore,
+  InMemoryConfirmTokenStore: () => InMemoryConfirmTokenStore,
   MAX_ASK_QUESTIONS: () => MAX_ASK_QUESTIONS,
   OutputRejectedError: () => OutputRejectedError,
   ProcessorFailedError: () => ProcessorFailedError,
@@ -83,6 +88,7 @@ __export(src_exports, {
   RUN_NOT_ACTIVE_MESSAGE: () => RUN_NOT_ACTIVE_MESSAGE,
   RUN_NO_LONGER_RUNNING: () => RUN_NO_LONGER_RUNNING,
   RunCancelledError: () => RunCancelledError,
+  SCHEMA_EXTENSION: () => SCHEMA_EXTENSION,
   SKILL_TOOL_DESCRIPTION: () => SKILL_TOOL_DESCRIPTION,
   SKILL_TOOL_NAME: () => SKILL_TOOL_NAME,
   StructuredOutputError: () => StructuredOutputError,
@@ -105,8 +111,10 @@ __export(src_exports, {
   buildMemoryBlock: () => buildMemoryBlock,
   buildSkillsBlock: () => buildSkillsBlock,
   canActorUseTool: () => canActorUseTool,
+  canonicalJson: () => canonicalJson,
   closeEmptyRoles: () => closeEmptyRoles,
   compositeSkillProvider: () => compositeSkillProvider,
+  confirmTokenExpiry: () => confirmTokenExpiry,
   createFrameBuffer: () => createFrameBuffer,
   createIncrementalGate: () => createIncrementalGate,
   createNoopEmitUi: () => createNoopEmitUi,
@@ -116,6 +124,7 @@ __export(src_exports, {
   decodeStreamEvent: () => decodeStreamEvent,
   defaultCanDecide: () => defaultCanDecide,
   defaultScopeResolver: () => defaultScopeResolver,
+  defineConfirmedTool: () => defineConfirmedTool,
   detachedDelivered: () => detachedDelivered,
   detachedStarted: () => detachedStarted,
   detachedUnsettled: () => detachedUnsettled,
@@ -132,6 +141,7 @@ __export(src_exports, {
   findCatalogModel: () => findCatalogModel,
   gateFollowUps: () => gateFollowUps,
   gateTail: () => gateTail,
+  hashConfirmToken: () => hashConfirmToken,
   invokeWithTransientRetry: () => invokeWithTransientRetry,
   isChatQueueStore: () => isChatQueueStore,
   isControlFlowSignal: () => isControlFlowSignal,
@@ -184,12 +194,14 @@ __export(src_exports, {
   runAgentLoop: () => runAgentLoop,
   runInputProcessors: () => runInputProcessors,
   runOutputProcessors: () => runOutputProcessors,
+  schemaExtensionOf: () => schemaExtensionOf,
   seedModelPrices: () => seedModelPrices,
   settleAll: () => settleAll,
   settleDanglingToolCalls: () => settleDanglingToolCalls,
   settleDeadRun: () => settleDeadRun,
   settleElicitation: () => settleElicitation,
   settleUnsettledDelegation: () => settleUnsettledDelegation,
+  signConfirmToken: () => signConfirmToken,
   skillInputSchema: () => skillInputSchema,
   skillToolDefinition: () => skillToolDefinition,
   skillWriteVerdict: () => skillWriteVerdict,
@@ -208,8 +220,10 @@ __export(src_exports, {
   validateElicitationAnswer: () => validateElicitationAnswer,
   validateElicitationValue: () => validateElicitationValue,
   validateStructured: () => validateStructured,
+  verifyConfirmToken: () => verifyConfirmToken,
   windowHistory: () => windowHistory,
   withAskTool: () => withAskTool,
+  withConfirmFields: () => withConfirmFields,
   withMemoryTool: () => withMemoryTool,
   withSelectedModel: () => withSelectedModel,
   withSkillTool: () => withSkillTool,
@@ -246,6 +260,7 @@ var AGENT_APPROVAL_PORT = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:app
 var AGENT_SKILLS = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:skills");
 var AGENT_MEMORY = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:memory");
 var AGENT_SKILL_SOURCES = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:skill-sources");
+var AGENT_CONFIRM_TOKEN_STORE = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:confirm-token-store");
 
 // src/spi/model-catalog.ts
 function staticModelCatalog(view) {
@@ -6006,12 +6021,322 @@ var InMemoryAgentStore = class {
     };
   }
 };
+
+// src/confirm-token.ts
+var import_node_crypto2 = require("crypto");
+var DEFAULT_CONFIRM_TTL_MS = 15 * 60 * 1e3;
+function canonicalJson(value) {
+  if (value === void 0) return "null";
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value.toJSON === "function") {
+    return canonicalJson(value.toJSON());
+  }
+  const entries = Object.entries(value).filter(([, entry]) => entry !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+}
+__name(canonicalJson, "canonicalJson");
+function signature(subject, expiresAt, secret) {
+  if (secret === "") {
+    throw new Error("confirm token: the secret is empty");
+  }
+  return (0, import_node_crypto2.createHmac)("sha256", secret).update(canonicalJson([
+    "agent-confirm",
+    subject.tool,
+    subject.actorId,
+    subject.tenantRef ?? "",
+    expiresAt,
+    subject.args
+  ])).digest("base64url");
+}
+__name(signature, "signature");
+function signConfirmToken(subject, options) {
+  return `${options.expiresAt}.${signature(subject, options.expiresAt, options.secret)}`;
+}
+__name(signConfirmToken, "signConfirmToken");
+function confirmTokenExpiry(token) {
+  const separator = token.indexOf(".");
+  if (separator <= 0) return void 0;
+  const expiresAt = Number(token.slice(0, separator));
+  return Number.isSafeInteger(expiresAt) && expiresAt > 0 ? expiresAt : void 0;
+}
+__name(confirmTokenExpiry, "confirmTokenExpiry");
+function verifyConfirmToken(token, subject, options) {
+  if (typeof token !== "string") return false;
+  const expiresAt = confirmTokenExpiry(token);
+  if (expiresAt === void 0 || expiresAt < (options.now ?? Date.now())) return false;
+  const expected = Buffer.from(signature(subject, expiresAt, options.secret));
+  const given = Buffer.from(token.slice(token.indexOf(".") + 1));
+  return expected.length === given.length && (0, import_node_crypto2.timingSafeEqual)(expected, given);
+}
+__name(verifyConfirmToken, "verifyConfirmToken");
+function hashConfirmToken(token) {
+  return (0, import_node_crypto2.createHash)("sha256").update(token).digest("hex");
+}
+__name(hashConfirmToken, "hashConfirmToken");
+var InMemoryConfirmTokenStore = class {
+  static {
+    __name(this, "InMemoryConfirmTokenStore");
+  }
+  claims = /* @__PURE__ */ new Map();
+  async claim(input) {
+    await this.purgeExpired();
+    if (this.claims.has(input.hash)) return false;
+    this.claims.set(input.hash, {
+      ...input
+    });
+    return true;
+  }
+  async release(hash) {
+    this.claims.delete(hash);
+  }
+  async purgeExpired(now = Date.now()) {
+    let purged = 0;
+    for (const [hash, claim] of this.claims) {
+      if (claim.expiresAt < now) {
+        this.claims.delete(hash);
+        purged += 1;
+      }
+    }
+    return purged;
+  }
+  /** How many tokens are currently marked as spent. */
+  get size() {
+    return this.claims.size;
+  }
+};
+
+// src/confirmed-tool.ts
+var DEFAULT_MESSAGES = {
+  confirm: 'Nothing was written. Show this preview to the user and ask them to confirm. To commit, call this tool again with the SAME arguments plus "confirm": true and this "confirmToken" (valid for {minutes} minutes).',
+  invalid: 'Invalid or expired confirmation: nothing was written. Call the tool without "confirm" to get a fresh preview, then confirm with the "confirmToken" it returns, without changing the arguments.',
+  used: "This preview was already confirmed: nothing was written again. To repeat the operation, ask for a new preview."
+};
+var ConfirmTokenError = class extends Error {
+  static {
+    __name(this, "ConfirmTokenError");
+  }
+  reason;
+  constructor(reason, message) {
+    super(message), this.reason = reason;
+    this.name = "ConfirmTokenError";
+  }
+};
+var CONFIRM_JSON_SCHEMA_PROPERTIES = {
+  confirm: {
+    type: "boolean",
+    description: "Omit to get a preview (nothing is written). Send true, with confirmToken, to commit."
+  },
+  confirmToken: {
+    type: "string",
+    description: "The confirmToken the preview returned. Required when confirm is true."
+  }
+};
+var SCHEMA_EXTENSION = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:schema-extension");
+function schemaExtensionOf(schema) {
+  const extension = schema[SCHEMA_EXTENSION];
+  return typeof extension === "object" && extension !== null ? extension : void 0;
+}
+__name(schemaExtensionOf, "schemaExtensionOf");
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+__name(isRecord, "isRecord");
+function splitConfirm(input) {
+  if (!isRecord(input)) return {
+    args: input,
+    fields: {}
+  };
+  const { confirm, confirmToken, ...args } = input;
+  return {
+    args,
+    fields: {
+      ...typeof confirm === "boolean" ? {
+        confirm
+      } : {},
+      ...typeof confirmToken === "string" ? {
+        confirmToken
+      } : {}
+    }
+  };
+}
+__name(splitConfirm, "splitConfirm");
+function jsonSchemaInputOf(schema) {
+  const standard = schema["~standard"];
+  const input = standard.jsonSchema?.input;
+  return typeof input === "function" ? (options) => input.call(standard.jsonSchema, options) : void 0;
+}
+__name(jsonSchemaInputOf, "jsonSchemaInputOf");
+function withConfirmFields(schema) {
+  const inner = schema["~standard"];
+  const innerJsonSchema = jsonSchemaInputOf(schema);
+  const describe = /* @__PURE__ */ __name((options) => {
+    const base = innerJsonSchema?.(options) ?? {
+      additionalProperties: true
+    };
+    return {
+      ...base,
+      type: "object",
+      properties: {
+        ...isRecord(base.properties) ? base.properties : {},
+        ...CONFIRM_JSON_SCHEMA_PROPERTIES
+      }
+    };
+  }, "describe");
+  const wrapped = {
+    [SCHEMA_EXTENSION]: {
+      base: schema,
+      properties: CONFIRM_JSON_SCHEMA_PROPERTIES
+    },
+    "~standard": {
+      version: 1,
+      vendor: "@dudousxd/nestjs-agent",
+      validate: /* @__PURE__ */ __name(async (value) => {
+        if (!isRecord(value)) {
+          return {
+            issues: [
+              {
+                message: "expected an object"
+              }
+            ]
+          };
+        }
+        const issues = [];
+        if (value.confirm != null && typeof value.confirm !== "boolean") {
+          issues.push({
+            message: "expected a boolean",
+            path: [
+              "confirm"
+            ]
+          });
+        }
+        if (value.confirmToken != null && typeof value.confirmToken !== "string") {
+          issues.push({
+            message: "expected a string",
+            path: [
+              "confirmToken"
+            ]
+          });
+        }
+        const { args, fields } = splitConfirm(value);
+        const result = await inner.validate(args);
+        if (result.issues !== void 0) {
+          return {
+            issues: [
+              ...issues,
+              ...result.issues
+            ]
+          };
+        }
+        if (issues.length > 0) {
+          return {
+            issues
+          };
+        }
+        return {
+          value: isRecord(result.value) ? {
+            ...result.value,
+            ...fields
+          } : result.value
+        };
+      }, "validate"),
+      jsonSchema: {
+        input: describe,
+        output: describe
+      }
+    }
+  };
+  return wrapped;
+}
+__name(withConfirmFields, "withConfirmFields");
+function defineConfirmedTool(options, steps) {
+  const { secret, ttlMs = DEFAULT_CONFIRM_TTL_MS, store, messages, input, ...specFields } = options;
+  const text = {
+    ...DEFAULT_MESSAGES,
+    ...messages
+  };
+  const howToConfirm = text.confirm.replaceAll("{minutes}", String(Math.round(ttlMs / 6e4)));
+  const secretNow = /* @__PURE__ */ __name(() => typeof secret === "function" ? secret() : secret, "secretNow");
+  const handler = {
+    async execute(value, ctx) {
+      const { args, fields } = splitConfirm(value);
+      const subject = {
+        tool: options.name,
+        actorId: ctx.actor.id,
+        ...ctx.actor.tenantRef !== void 0 ? {
+          tenantRef: ctx.actor.tenantRef
+        } : {},
+        args
+      };
+      const confirming = fields.confirm === true;
+      const token = fields.confirmToken;
+      if (confirming && !verifyConfirmToken(token, subject, {
+        secret: secretNow()
+      })) {
+        throw new ConfirmTokenError("invalid", text.invalid);
+      }
+      const prepared = await steps.prepare(args, ctx);
+      if (!confirming || token === void 0) {
+        const preview = await steps.preview(prepared, ctx);
+        const expiresAt = Date.now() + ttlMs;
+        return {
+          status: "preview",
+          summary: preview.summary,
+          ...preview.data !== void 0 ? {
+            data: preview.data
+          } : {},
+          confirmToken: signConfirmToken(subject, {
+            secret: secretNow(),
+            expiresAt
+          }),
+          expiresAt: new Date(expiresAt).toISOString(),
+          confirm: howToConfirm
+        };
+      }
+      const hash = hashConfirmToken(token);
+      if (store !== void 0) {
+        const claimed = await store.claim({
+          hash,
+          actorRef: ctx.actor.id,
+          tool: options.name,
+          expiresAt: confirmTokenExpiry(token) ?? Date.now() + ttlMs
+        });
+        if (!claimed) {
+          throw new ConfirmTokenError("used", text.used);
+        }
+      }
+      try {
+        const done = await steps.commit(prepared, ctx);
+        return {
+          status: "done",
+          summary: done.summary,
+          ...done.data !== void 0 ? {
+            data: done.data
+          } : {}
+        };
+      } catch (error) {
+        await store?.release(hash).catch(() => void 0);
+        throw error;
+      }
+    }
+  };
+  return {
+    spec: {
+      ...specFields,
+      kind: "read",
+      inputSchema: withConfirmFields(input)
+    },
+    handler
+  };
+}
+__name(defineConfirmedTool, "defineConfirmedTool");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AGENT_ACTOR_DIRECTORY,
   AGENT_ACTOR_RESOLVER,
   AGENT_APPROVAL_PORT,
   AGENT_ATTACHMENT_STAGING,
+  AGENT_CONFIRM_TOKEN_STORE,
   AGENT_DEPS_FACTORY,
   AGENT_DIAGNOSTIC_EVENTS,
   AGENT_DURABLE_RUNNER,
@@ -6041,7 +6366,10 @@ var InMemoryAgentStore = class {
   ASK_TOOL_NAME,
   AgentRegistry,
   AgentStreamError,
+  CONFIRM_JSON_SCHEMA_PROPERTIES,
   ClosedRolesPolicy,
+  ConfirmTokenError,
+  DEFAULT_CONFIRM_TTL_MS,
   DEFAULT_HISTORY_SUMMARY_INSTRUCTION,
   DEFAULT_INCREMENTAL_LOOKBACK_CHARS,
   DEFAULT_INTAKE_PREAMBLE,
@@ -6057,6 +6385,7 @@ var InMemoryAgentStore = class {
   ELICITATION_INPUT_TYPES,
   GLOBAL_SCOPE,
   InMemoryAgentStore,
+  InMemoryConfirmTokenStore,
   MAX_ASK_QUESTIONS,
   OutputRejectedError,
   ProcessorFailedError,
@@ -6070,6 +6399,7 @@ var InMemoryAgentStore = class {
   RUN_NOT_ACTIVE_MESSAGE,
   RUN_NO_LONGER_RUNNING,
   RunCancelledError,
+  SCHEMA_EXTENSION,
   SKILL_TOOL_DESCRIPTION,
   SKILL_TOOL_NAME,
   StructuredOutputError,
@@ -6092,8 +6422,10 @@ var InMemoryAgentStore = class {
   buildMemoryBlock,
   buildSkillsBlock,
   canActorUseTool,
+  canonicalJson,
   closeEmptyRoles,
   compositeSkillProvider,
+  confirmTokenExpiry,
   createFrameBuffer,
   createIncrementalGate,
   createNoopEmitUi,
@@ -6103,6 +6435,7 @@ var InMemoryAgentStore = class {
   decodeStreamEvent,
   defaultCanDecide,
   defaultScopeResolver,
+  defineConfirmedTool,
   detachedDelivered,
   detachedStarted,
   detachedUnsettled,
@@ -6119,6 +6452,7 @@ var InMemoryAgentStore = class {
   findCatalogModel,
   gateFollowUps,
   gateTail,
+  hashConfirmToken,
   invokeWithTransientRetry,
   isChatQueueStore,
   isControlFlowSignal,
@@ -6171,12 +6505,14 @@ var InMemoryAgentStore = class {
   runAgentLoop,
   runInputProcessors,
   runOutputProcessors,
+  schemaExtensionOf,
   seedModelPrices,
   settleAll,
   settleDanglingToolCalls,
   settleDeadRun,
   settleElicitation,
   settleUnsettledDelegation,
+  signConfirmToken,
   skillInputSchema,
   skillToolDefinition,
   skillWriteVerdict,
@@ -6195,8 +6531,10 @@ var InMemoryAgentStore = class {
   validateElicitationAnswer,
   validateElicitationValue,
   validateStructured,
+  verifyConfirmToken,
   windowHistory,
   withAskTool,
+  withConfirmFields,
   withMemoryTool,
   withSelectedModel,
   withSkillTool,