@dudousxd/nestjs-agent-core 0.18.0 → 0.20.0

package/dist/index.js

@@ -215,6 +215,63 @@ function truncateDetailContent(content) {
 }
 __name(truncateDetailContent, "truncateDetailContent");
 
+// src/spi/approval-policy.ts
+var REQUESTER_APPROVER = "requester";
+var DefaultApprovalPolicy = class {
+  static {
+    __name(this, "DefaultApprovalPolicy");
+  }
+  requirementFor(tool) {
+    return {
+      required: tool.kind === "action",
+      approver: REQUESTER_APPROVER
+    };
+  }
+};
+function defaultCanDecide(actor, decision) {
+  if (decision.approver === REQUESTER_APPROVER) {
+    return actor.id === decision.requesterRef;
+  }
+  return actor.roles?.includes(decision.approver) === true;
+}
+__name(defaultCanDecide, "defaultCanDecide");
+async function mayDecideApproval(policy, actor, decision) {
+  if (policy?.canDecide !== void 0) {
+    return policy.canDecide(actor, decision);
+  }
+  return defaultCanDecide(actor, decision);
+}
+__name(mayDecideApproval, "mayDecideApproval");
+function toolCallApprovalFromRow(row) {
+  if (row.approver === null || row.approver === void 0) {
+    return null;
+  }
+  const status = row.status === "pending_approval" ? "pending" : row.status === "rejected" ? "rejected" : row.status === "expired" ? "expired" : "approved";
+  const expiresAt = row.expiresAt instanceof Date ? row.expiresAt.toISOString() : typeof row.expiresAt === "string" ? row.expiresAt : void 0;
+  const decided = status === "approved" || status === "rejected";
+  return {
+    toolCallId: row.toolCallId,
+    approver: row.approver,
+    status,
+    ...expiresAt !== void 0 ? {
+      expiresAt
+    } : {},
+    ...row.remember === true ? {
+      remember: true
+    } : {},
+    ...decided && typeof row.executedByRef === "string" ? {
+      decidedBy: row.executedByRef
+    } : {},
+    ...decided && typeof row.decidedVia === "string" ? {
+      decidedVia: row.decidedVia
+    } : {},
+    ...status === "rejected" && typeof row.error === "string" ? {
+      reason: row.error
+    } : {}
+  };
+}
+__name(toolCallApprovalFromRow, "toolCallApprovalFromRow");
+
 // src/governance/compute.ts
 function estimateCost(usage, price) {
   if (price === void 0) {
@@ -1877,6 +1934,19 @@ var ToolRegistry = class {
   * tool the allow-list has already excluded is a call whose answer nothing reads.
   */
   async definitionsFor(actor, policy, allowedTools) {
+    return (await this.visibleSpecs(actor, policy, allowedTools)).map((spec) => ({
+      name: spec.name,
+      kind: spec.kind,
+      description: spec.description,
+      inputSchema: spec.inputSchema
+    }));
+  }
+  /**
+  * The specs {@link definitionsFor} offers the model, whole — the same four gates (allow-list,
+  * enabled, role, `canUse`) in the same order. For a surface that lists what an actor can reach
+  * (`GET <base>/tools`), which must never disagree with what the model is actually shown.
+  */
+  async visibleSpecs(actor, policy, allowedTools) {
     const pinnedNames = new Set(filterToolsByAllowList(this.allSpecs(), allowedTools).map((spec) => spec.name));
     const pinned = [
       ...this.entries.values()
@@ -1885,12 +1955,7 @@ var ToolRegistry = class {
     const allowedByRole = new Set((await filterToolsByRole(live.map((entry) => entry.spec), actor, policy)).map((spec) => spec.name));
     const roleScoped = live.filter((entry) => allowedByRole.has(entry.spec.name));
     const actorScoped = await filterToolsByCanUse(roleScoped, actor);
-    return actorScoped.map(({ spec }) => ({
-      name: spec.name,
-      kind: spec.kind,
-      description: spec.description,
-      inputSchema: spec.inputSchema
-    }));
+    return actorScoped.map(({ spec }) => spec);
   }
   /**
   * Run a tool. Re-checks that the tool is enabled and that the role allows it (defense-in-depth —
@@ -2757,15 +2822,33 @@ async function claimToolCall(turn, call) {
     const spec = deps.registry.spec(call.name);
     const kind = call.kind ?? declaredKind(deps, call.name);
     const awaitsHuman = kind === "action" || kind === "ask";
+    const approval = kind === "action" ? await claimApproval(turn, call, spec) : void 0;
+    const parks = kind === "ask" || approval?.mode === "ask";
     await deps.store.recordToolCall({
       toolCallId: call.id,
       messageId,
       toolName: call.name,
       toolType: awaitsHuman ? "action" : "read",
       input: call.input,
-      status: awaitsHuman ? "pending_approval" : "auto_executed",
-      runId: hooks.runId
+      status: parks ? "pending_approval" : "auto_executed",
+      runId: hooks.runId,
+      ...approval !== void 0 && approval.mode !== "auto" ? {
+        approver: approval.approver
+      } : {},
+      ...approval?.mode === "ask" && approval.expiresAt !== void 0 ? {
+        expiresAt: approval.expiresAt
+      } : {}
     });
+    if (approval?.mode === "ask") {
+      await turn.writer.write(encodeStreamEvent({
+        kind: "approval-requested",
+        id: call.id,
+        approver: approval.approver,
+        ...approval.expiresAt !== void 0 ? {
+          expiresAt: approval.expiresAt
+        } : {}
+      }));
+    }
     return {
       kind,
       ...spec?.targetAgent !== void 0 ? {
@@ -2775,6 +2858,9 @@ async function claimToolCall(turn, call) {
       // deployment with no detached edge writes the same bytes here it always has.
       ...spec?.detached === true ? {
         detached: true
+      } : {},
+      ...approval !== void 0 ? {
+        approval
       } : {}
     };
   });
@@ -2794,10 +2880,52 @@ async function claimToolCall(turn, call) {
     ...persisted?.detached === true ? {
       detached: true
     } : {},
+    ...toolType === "action" && persisted?.approval !== void 0 ? {
+      approval: persisted.approval
+    } : {},
     ctx: toolContext(deps, input, hooks)
   };
 }
 __name(claimToolCall, "claimToolCall");
+async function claimApproval(turn, call, spec) {
+  const { deps, input, hooks } = turn;
+  const policy = deps.approvalPolicy ?? new DefaultApprovalPolicy();
+  const requirement = await policy.requirementFor({
+    name: call.name,
+    kind: "action",
+    ...spec !== void 0 ? {
+      spec
+    } : {}
+  }, input.actor, {
+    threadId: input.threadId,
+    runId: hooks.runId,
+    ...input.agentName !== void 0 ? {
+      agentName: input.agentName
+    } : {}
+  });
+  if (!requirement.required) {
+    return {
+      mode: "auto"
+    };
+  }
+  const remembered = await deps.store.rememberedApprovals?.(input.threadId) ?? [];
+  if (remembered.includes(call.name)) {
+    return {
+      mode: "remembered",
+      approver: requirement.approver
+    };
+  }
+  const ttlMs = requirement.ttlMs !== void 0 && Number.isFinite(requirement.ttlMs) && requirement.ttlMs > 0 ? Math.floor(requirement.ttlMs) : void 0;
+  return {
+    mode: "ask",
+    approver: requirement.approver,
+    ...ttlMs !== void 0 ? {
+      ttlMs,
+      expiresAt: new Date(Date.now() + ttlMs).toISOString()
+    } : {}
+  };
+}
+__name(claimApproval, "claimApproval");
 async function loadSkillIntoTurn(turn, claimed, startedAt) {
   const { deps, input, hooks } = turn;
   const { call } = claimed;
@@ -2981,17 +3109,50 @@ async function invokeClaimedTool(turn, claimed) {
   }
 }
 __name(invokeClaimedTool, "invokeClaimedTool");
-async function recordToolOutcome(turn, claimed, outcome, deciderRef) {
+async function recordToolOutcome(turn, claimed, outcome, deciderRef, meta) {
   const { deps, hooks } = turn;
   const { call } = claimed;
   const toolType = claimed.toolType === "action" ? "action" : "read";
-  if (outcome.status === "failed") {
-    await hooks.step(`persist:toolfail:${call.id}`, () => deps.store.updateToolCall({
-      toolCallId: call.id,
-      status: "failed",
-      error: outcome.error,
-      executionMs: outcome.executionMs
+  const decided = meta === void 0 ? {} : {
+    executedByRef: meta.decidedBy,
+    ...meta.decidedVia !== void 0 ? {
+      decidedVia: meta.decidedVia
+    } : {},
+    ...meta.remember === true ? {
+      remember: true
+    } : {}
+  };
+  const settle = /* @__PURE__ */ __name(async () => {
+    if (meta === void 0 || !meta.streamed) {
+      return;
+    }
+    await turn.writer.write(encodeStreamEvent({
+      kind: "approval-settled",
+      id: call.id,
+      status: "approved",
+      ...meta.approver !== void 0 ? {
+        approver: meta.approver
+      } : {},
+      decidedBy: meta.decidedBy,
+      ...meta.decidedVia !== void 0 ? {
+        decidedVia: meta.decidedVia
+      } : {},
+      ...meta.remember === true ? {
+        remember: true
+      } : {}
     }));
+  }, "settle");
+  if (outcome.status === "failed") {
+    await hooks.step(`persist:toolfail:${call.id}`, async () => {
+      await deps.store.updateToolCall({
+        toolCallId: call.id,
+        status: "failed",
+        error: outcome.error,
+        executionMs: outcome.executionMs,
+        ...decided
+      });
+      await settle();
+    });
     publishAgentToolCall({
       runId: hooks.runId,
       toolName: call.name,
@@ -3006,15 +3167,19 @@ async function recordToolOutcome(turn, claimed, outcome, deciderRef) {
       error: outcome.error
     };
   }
-  await hooks.step(`persist:toolexec:${call.id}`, () => deps.store.updateToolCall({
-    toolCallId: call.id,
-    status: "executed",
-    output: outcome.output,
-    executionMs: outcome.executionMs,
-    ...toolType === "action" ? {
-      executedByRef: deciderRef
-    } : {}
-  }));
+  await hooks.step(`persist:toolexec:${call.id}`, async () => {
+    await deps.store.updateToolCall({
+      toolCallId: call.id,
+      status: "executed",
+      output: outcome.output,
+      executionMs: outcome.executionMs,
+      ...toolType === "action" ? {
+        executedByRef: deciderRef
+      } : {},
+      ...decided
+    });
+    await settle();
+  });
   publishAgentToolCall({
     runId: hooks.runId,
     toolName: call.name,
@@ -3152,18 +3317,53 @@ async function runClaimedToolCall(turn, claimed) {
     return elicitToolCall(turn, claimed);
   }
   let deciderRef = input.actor.id;
-  if (toolType === "action") {
-    const decision = await hooks.awaitApproval(call, ctx);
+  let meta;
+  if (toolType === "action" && claimed.approval?.mode === "remembered") {
+    meta = {
+      approver: claimed.approval.approver,
+      decidedBy: input.actor.id,
+      decidedVia: "remembered",
+      remember: true,
+      streamed: true
+    };
+  } else if (toolType === "action" && claimed.approval?.mode !== "auto") {
+    const ttlMs = claimed.approval?.mode === "ask" ? claimed.approval.ttlMs : void 0;
+    const decision = ttlMs !== void 0 ? await hooks.awaitApproval(call, ctx, {
+      timeoutMs: ttlMs
+    }) : await hooks.awaitApproval(call, ctx);
     deciderRef = decision.executedByRef ?? input.actor.id;
+    const streamsSettlement = claimed.approval !== void 0;
+    if (decision.expired === true) {
+      return expireToolCall(turn, claimed);
+    }
     if (!decision.approved) {
-      await hooks.step(`persist:toolreject:${call.id}`, () => deps.store.updateToolCall({
-        toolCallId: call.id,
-        status: "rejected",
-        executedByRef: deciderRef,
-        ...decision.reason !== void 0 ? {
-          error: decision.reason
-        } : {}
-      }));
+      await hooks.step(`persist:toolreject:${call.id}`, async () => {
+        await deps.store.updateToolCall({
+          toolCallId: call.id,
+          status: "rejected",
+          executedByRef: deciderRef,
+          ...decision.reason !== void 0 ? {
+            error: decision.reason
+          } : {},
+          ...decision.decidedVia !== void 0 ? {
+            decidedVia: decision.decidedVia
+          } : {}
+        });
+        if (streamsSettlement) {
+          await turn.writer.write(encodeStreamEvent({
+            kind: "approval-settled",
+            id: call.id,
+            status: "rejected",
+            decidedBy: deciderRef,
+            ...decision.decidedVia !== void 0 ? {
+              decidedVia: decision.decidedVia
+            } : {},
+            ...decision.reason !== void 0 ? {
+              reason: decision.reason
+            } : {}
+          }));
+        }
+      });
       publishAgentToolCall({
         runId: hooks.runId,
         toolName: call.name,
@@ -3186,10 +3386,60 @@ async function runClaimedToolCall(turn, claimed) {
         error: refusalNarrative(decision.reason)
       };
     }
+    meta = {
+      decidedBy: deciderRef,
+      ...decision.decidedVia !== void 0 ? {
+        decidedVia: decision.decidedVia
+      } : {},
+      ...decision.remember === true ? {
+        remember: true
+      } : {},
+      streamed: streamsSettlement
+    };
   }
-  return recordToolOutcome(turn, claimed, await invokeClaimedTool(turn, claimed), deciderRef);
+  return recordToolOutcome(turn, claimed, await invokeClaimedTool(turn, claimed), deciderRef, meta);
 }
 __name(runClaimedToolCall, "runClaimedToolCall");
+async function expireToolCall(turn, claimed) {
+  const { deps, hooks } = turn;
+  const { call } = claimed;
+  await hooks.step(`persist:toolreject:${call.id}`, async () => {
+    await deps.store.updateToolCall({
+      toolCallId: call.id,
+      status: "expired",
+      error: APPROVAL_EXPIRED_REASON
+    });
+    await turn.writer.write(encodeStreamEvent({
+      kind: "approval-settled",
+      id: call.id,
+      status: "expired"
+    }));
+  });
+  publishAgentToolCall({
+    runId: hooks.runId,
+    toolName: call.name,
+    toolType: "action",
+    status: "rejected"
+  });
+  return {
+    id: call.id,
+    name: call.name,
+    output: {
+      rejected: true,
+      expired: true,
+      reason: APPROVAL_EXPIRED_REASON
+    },
+    denied: true,
+    expired: true,
+    error: expiryNarrative()
+  };
+}
+__name(expireToolCall, "expireToolCall");
+var APPROVAL_EXPIRED_REASON = "approval expired";
+function expiryNarrative() {
+  return "This action needed approval, and the approval request expired before anyone decided. Nothing ran and nothing changed. Do not run it again on your own; tell the person it was not approved in time and ask whether they still want it.";
+}
+__name(expiryNarrative, "expiryNarrative");
 function outputFrame(result) {
   if (result.denied === true) {
     const reason = refusalReason(result);
@@ -3862,6 +4112,7 @@ export {
   AGENT_SPAN_EVENTS,
   AGENT_STORE,
   AGENT_TOOL_REGISTRY,
+  APPROVAL_EXPIRED_REASON,
   ASK_TOOL_DESCRIPTION,
   ASK_TOOL_NAME,
   AgentRegistry,
@@ -3876,6 +4127,7 @@ export {
   DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION,
   DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS,
   DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS,
+  DefaultApprovalPolicy,
   DefaultRolesPolicy,
   GLOBAL_SCOPE,
   MAX_ASK_QUESTIONS,
@@ -3884,6 +4136,7 @@ export {
   QuotaExceededError,
   REMEMBER_TOOL_DESCRIPTION,
   REMEMBER_TOOL_NAME,
+  REQUESTER_APPROVER,
   RunCancelledError,
   SKILL_TOOL_DESCRIPTION,
   SKILL_TOOL_NAME,
@@ -3911,6 +4164,7 @@ export {
   createIncrementalGate,
   dayBoundsUtc,
   decodeStreamEvent,
+  defaultCanDecide,
   defaultScopeResolver,
   detachedDelivered,
   detachedStarted,
@@ -3931,6 +4185,7 @@ export {
   isToolEnabled,
   isTransientToolError,
   loadSkill,
+  mayDecideApproval,
   memoryForgetVerdict,
   memoryWriteVerdict,
   normalizeDelegation,
@@ -3976,6 +4231,7 @@ export {
   staticSkillProvider,
   summarizeWithModel,
   tenantScope,
+  toolCallApprovalFromRow,
   traceLlmTurn,
   traceToolExecution,
   truncateDetailContent,