@dudousxd/nestjs-agent-core 0.36.0 → 0.38.0

package/dist/index.js

@@ -27,6 +27,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) {
@@ -87,7 +88,7 @@ __name(decodeStreamEvent, "decodeStreamEvent");
 
 // src/turn-frames.ts
 function observeTurnFrames(writer, now = Date.now) {
-  const decoder2 = new TextDecoder();
+  const decoder3 = new TextDecoder();
   let pending = "";
   let reasoning = "";
   let reasoningMs = 0;
@@ -127,7 +128,7 @@ function observeTurnFrames(writer, now = Date.now) {
   }
   __name(observeLine, "observeLine");
   function observe(chunk) {
-    pending += decoder2.decode(chunk, {
+    pending += decoder3.decode(chunk, {
       stream: true
     });
     let newline = pending.indexOf("\n");
@@ -5787,11 +5788,560 @@ var InMemoryAgentStore = class {
     };
   }
 };
+
+// src/confirm-token.ts
+import { createHash as createHash2, createHmac, timingSafeEqual } from "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 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 && timingSafeEqual(expected, given);
+}
+__name(verifyConfirmToken, "verifyConfirmToken");
+function hashConfirmToken(token) {
+  return createHash2("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");
+
+// src/sql-token-stream-sink.ts
+var DEFAULT_TTL_SECONDS = 3600;
+var DEFAULT_POLL_INTERVAL_MS = 250;
+var DEFAULT_IDLE_POLL_INTERVAL_MS = 1e3;
+var IDLE_AFTER_MS = 5e3;
+var DEFAULT_FLUSH_MS = 50;
+var READ_PAGE = 500;
+var PURGE_CHUNK = 200;
+var AUTO_PURGE_EVERY_MS = 6e4;
+var APPEND_ATTEMPTS = 8;
+var decoder2 = new TextDecoder();
+var encoder2 = new TextEncoder();
+var sleep = /* @__PURE__ */ __name((ms) => new Promise((resolve) => setTimeout(resolve, ms)), "sleep");
+function textOf(line) {
+  if (!line.startsWith('{"kind":"text"')) return null;
+  try {
+    const parsed = JSON.parse(line);
+    if (typeof parsed === "object" && parsed !== null && Object.keys(parsed).length === 2 && parsed.kind === "text" && typeof parsed.text === "string") {
+      return parsed.text;
+    }
+  } catch {
+  }
+  return null;
+}
+__name(textOf, "textOf");
+var SqlTokenStreamSink = class {
+  static {
+    __name(this, "SqlTokenStreamSink");
+  }
+  table;
+  pollIntervalMs;
+  idlePollIntervalMs;
+  flushMs;
+  ttlSeconds;
+  autoPurge;
+  writes = /* @__PURE__ */ new Map();
+  lastAutoPurge = 0;
+  constructor(table, options = {}) {
+    this.table = table;
+    this.pollIntervalMs = Math.max(1, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+    this.idlePollIntervalMs = Math.max(this.pollIntervalMs, options.idlePollIntervalMs ?? DEFAULT_IDLE_POLL_INTERVAL_MS);
+    this.flushMs = Math.max(0, options.flushMs ?? DEFAULT_FLUSH_MS);
+    this.ttlSeconds = options.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+    this.autoPurge = options.autoPurge ?? true;
+  }
+  runWrites(runId) {
+    let state = this.writes.get(runId);
+    if (state === void 0) {
+      state = {
+        text: null,
+        timer: void 0,
+        tail: Promise.resolve(),
+        pending: 0,
+        failure: void 0
+      };
+      this.writes.set(runId, state);
+    }
+    return state;
+  }
+  /** Forget a run's write state once nothing is gathered, queued or left to report. */
+  release(runId, state) {
+    if (state.pending === 0 && state.text === null && state.failure === void 0 && this.writes.get(runId) === state) {
+      this.writes.delete(runId);
+    }
+  }
+  /** Queue `work` behind every write already queued for the run, so rows land in call order. */
+  enqueue(runId, state, work) {
+    state.pending += 1;
+    const next = state.tail.then(work);
+    state.tail = next.then(() => void 0, () => void 0).then(() => {
+      state.pending -= 1;
+      this.release(runId, state);
+    });
+    return next;
+  }
+  /** Queue the gathered text (if any) as one `text` row. */
+  flushText(runId, state) {
+    if (state.timer !== void 0) {
+      clearTimeout(state.timer);
+      state.timer = void 0;
+    }
+    if (state.text === null) return Promise.resolve();
+    const line = decoder2.decode(encodeStreamEvent({
+      kind: "text",
+      text: state.text
+    }));
+    state.text = null;
+    return this.enqueue(runId, state, () => this.append(runId, line, null));
+  }
+  /** Raise, once, a gathered write that failed with nobody awaiting it. */
+  raiseFailure(state) {
+    const failure = state.failure;
+    if (failure !== void 0) {
+      state.failure = void 0;
+      throw failure.error;
+    }
+  }
+  /** Append one row — a frame, or the terminal row (`frame: null`, with `error` on a failure). */
+  async append(runId, frame, error) {
+    for (let attempt = 1; ; attempt += 1) {
+      try {
+        await this.table.append(runId, {
+          frame,
+          error,
+          createdAt: Date.now()
+        });
+        return;
+      } catch (caught) {
+        if (attempt >= APPEND_ATTEMPTS || !this.table.isUniqueViolation(caught)) throw caught;
+      }
+    }
+  }
+  /** Write out what is gathered, then a terminal row; raise a failure nobody saw. */
+  async terminate(runId, error) {
+    const state = this.runWrites(runId);
+    const flushed = this.flushText(runId, state);
+    const ended = this.enqueue(runId, state, () => this.append(runId, null, error));
+    await Promise.all([
+      flushed,
+      ended
+    ]);
+    this.raiseFailure(state);
+    this.release(runId, state);
+    this.purgeInBackground();
+  }
+  /**
+  * The run's writer. Writers opened for the same run in one process share what they are gathering,
+  * so a delegated run's text (forwarded through a child writer) and its parent's next frame keep
+  * the order they were written in.
+  */
+  open(runId) {
+    return {
+      write: /* @__PURE__ */ __name(async (chunk) => {
+        const state = this.runWrites(runId);
+        this.raiseFailure(state);
+        const line = decoder2.decode(chunk);
+        const text = this.flushMs > 0 ? textOf(line.trimEnd()) : null;
+        if (text !== null) {
+          state.text = (state.text ?? "") + text;
+          if (state.timer === void 0) {
+            state.timer = setTimeout(() => {
+              state.timer = void 0;
+              this.flushText(runId, state).catch((error) => {
+                state.failure = {
+                  error
+                };
+              });
+            }, this.flushMs);
+          }
+          return;
+        }
+        const flushed = this.flushText(runId, state);
+        const appended = this.enqueue(runId, state, () => this.append(runId, line, null));
+        await Promise.all([
+          flushed,
+          appended
+        ]);
+      }, "write"),
+      flush: /* @__PURE__ */ __name(async () => {
+        const state = this.runWrites(runId);
+        const flushed = this.flushText(runId, state);
+        await Promise.all([
+          flushed,
+          state.tail
+        ]);
+        this.raiseFailure(state);
+        this.release(runId, state);
+      }, "flush"),
+      end: /* @__PURE__ */ __name(() => this.terminate(runId, null), "end"),
+      fail: /* @__PURE__ */ __name((error) => this.terminate(runId, JSON.stringify({
+        code: error.code,
+        message: error.message
+      })), "fail")
+    };
+  }
+  async *subscribe(runId) {
+    let cursor = 0;
+    let quietSince = Date.now();
+    while (true) {
+      const rows = await this.table.read(runId, cursor, READ_PAGE);
+      for (const row of rows) {
+        cursor = row.seq;
+        if (row.frame === null) {
+          if (row.error !== null) {
+            throw new AgentStreamError(JSON.parse(row.error));
+          }
+          return;
+        }
+        yield encoder2.encode(row.frame);
+      }
+      if (rows.length > 0) {
+        quietSince = Date.now();
+        if (rows.length >= READ_PAGE) continue;
+      }
+      await sleep(Date.now() - quietSince >= IDLE_AFTER_MS ? this.idlePollIntervalMs : this.pollIntervalMs);
+    }
+  }
+  /** Does the table hold anything for the run — a frame, or its end? */
+  has(runId) {
+    return this.table.has(runId);
+  }
+  async close(runId) {
+    const state = this.writes.get(runId);
+    if (state !== void 0) {
+      if (state.timer !== void 0) clearTimeout(state.timer);
+      state.timer = void 0;
+      state.text = null;
+      state.failure = void 0;
+      await state.tail;
+      this.writes.delete(runId);
+    }
+    await this.table.remove([
+      runId
+    ]);
+  }
+  /**
+  * Delete every run whose last write is older than `ttlSeconds` at `now` (epoch-ms) — ended runs
+  * past their replay window and runs that crashed without ending alike. Returns how many runs went.
+  * Safe from any replica, and from several at once. A no-op under `ttlSeconds: 0`.
+  */
+  async purgeExpired(now = Date.now()) {
+    if (this.ttlSeconds <= 0) return 0;
+    const lapsed = await this.table.lapsedRuns(now - this.ttlSeconds * 1e3);
+    for (let index = 0; index < lapsed.length; index += PURGE_CHUNK) {
+      await this.table.remove(lapsed.slice(index, index + PURGE_CHUNK));
+    }
+    return lapsed.length;
+  }
+  /** {@link purgeExpired}, unawaited and at most once a minute. Its failure is not the run's. */
+  purgeInBackground() {
+    if (!this.autoPurge || this.ttlSeconds <= 0) return;
+    const now = Date.now();
+    if (now - this.lastAutoPurge < AUTO_PURGE_EVERY_MS) return;
+    this.lastAutoPurge = now;
+    this.purgeExpired(now).catch(() => {
+    });
+  }
+};
 export {
   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,
@@ -5821,7 +6371,10 @@ export {
   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,
@@ -5837,6 +6390,7 @@ export {
   ELICITATION_INPUT_TYPES,
   GLOBAL_SCOPE,
   InMemoryAgentStore,
+  InMemoryConfirmTokenStore,
   MAX_ASK_QUESTIONS,
   OutputRejectedError,
   ProcessorFailedError,
@@ -5850,8 +6404,10 @@ export {
   RUN_NOT_ACTIVE_MESSAGE,
   RUN_NO_LONGER_RUNNING,
   RunCancelledError,
+  SCHEMA_EXTENSION,
   SKILL_TOOL_DESCRIPTION,
   SKILL_TOOL_NAME,
+  SqlTokenStreamSink,
   StructuredOutputError,
   THREAD_DETAIL_CONTENT_CHARS,
   ToolDisabledError,
@@ -5872,8 +6428,10 @@ export {
   buildMemoryBlock,
   buildSkillsBlock,
   canActorUseTool,
+  canonicalJson,
   closeEmptyRoles,
   compositeSkillProvider,
+  confirmTokenExpiry,
   createFrameBuffer,
   createIncrementalGate,
   createNoopEmitUi,
@@ -5883,6 +6441,7 @@ export {
   decodeStreamEvent,
   defaultCanDecide,
   defaultScopeResolver,
+  defineConfirmedTool,
   detachedDelivered,
   detachedStarted,
   detachedUnsettled,
@@ -5899,6 +6458,7 @@ export {
   findCatalogModel,
   gateFollowUps,
   gateTail,
+  hashConfirmToken,
   invokeWithTransientRetry,
   isChatQueueStore,
   isControlFlowSignal,
@@ -5951,12 +6511,14 @@ export {
   runAgentLoop,
   runInputProcessors,
   runOutputProcessors,
+  schemaExtensionOf,
   seedModelPrices,
   settleAll,
   settleDanglingToolCalls,
   settleDeadRun,
   settleElicitation,
   settleUnsettledDelegation,
+  signConfirmToken,
   skillInputSchema,
   skillToolDefinition,
   skillWriteVerdict,
@@ -5975,8 +6537,10 @@ export {
   validateElicitationAnswer,
   validateElicitationValue,
   validateStructured,
+  verifyConfirmToken,
   windowHistory,
   withAskTool,
+  withConfirmFields,
   withMemoryTool,
   withSelectedModel,
   withSkillTool,