@dudousxd/nestjs-agent-core 0.19.0 → 0.20.0

package/README.md

@@ -35,7 +35,8 @@ import type { ModelProvider, AgentStore, ToolSpec, RolesPolicy } from '@dudousxd
 - `RunCancelledError` / `AgentLoopHooks.cancelled()` — real cancellation. The loop asks `hooks.cancelled()` at the points where stopping is safe and cheap (between steps, before the next model call, before a turn's tools are dispatched), ALWAYS from inside a checkpoint, so the answer is journaled and a cancel arriving between two replays can never change a branch a replayed position already took; the positions themselves sit behind `hooks.patched('agent:cancellation')`, so a run already in flight keeps its recorded shape. A tool already executing is never interrupted — there is no un-executing a side effect, and abandoning a dispatched step leaves a journal holding a dispatch whose result never lands. Observing a cancel throws `RunCancelledError`, which unwinds through the path a suspend already uses; the RUNNER settles it, recording the run `cancelled` (`AgentStore.recordRunEnd`'s third terminal, never `failed`) and ending the stream on a `{ kind: 'cancelled' }` frame rather than failing it, so a user pressing Stop is not in anybody's error rate.
 - `isControlFlowSignal(error)` / `isReplayIntegrityError(error)` — recognize a durable suspend and a checkpoint refusal without importing the durable packages (a `Symbol.for` marker and a class name, respectively). Rethrow both untouched from any `catch` in a workflow body.
 - `settleAll(tasks)` / `SettledTask<T>` — the implementation behind the optional `AgentLoopHooks.parallel`, which is how a turn's `read` tool calls run concurrently. It invokes every task synchronously, in list order, before awaiting any of them (so a runner that takes checkpoint positions on the call keeps them in call order), and resolves only once all of them have settled (so a runner that unwinds a turn by throwing never abandons a sibling mid-dispatch). A runner that assigns positions anywhere else simply omits the hook and the loop stays sequential.
-- `AgentStreamEvent` / `encodeStreamEvent` / `decodeStreamEvent` — the live-stream vocabulary (text, reasoning, tool calls with optional `parentId` nesting, `elicitation`, `approval-requested` with `approver`/`expiresAt`, server-pushed `ui` components, `title`, `cancelled`). It is also the contract a runner that is not this loop writes to get the React client for free: see [docs/stream-protocol.md](../../docs/stream-protocol.md). `AgentUiComponent` and `AgentApprovalRequest` are the payload types.
+- `AgentStreamEvent` / `encodeStreamEvent` / `decodeStreamEvent` — the live-stream vocabulary (text, reasoning, tool calls with optional `parentId` nesting, `elicitation`, `approval-requested` with `approver`/`expiresAt`, server-pushed `ui` components, `title`, `cancelled`). It is also the contract a runner that is not this loop writes to get the React client for free: see [docs/stream-protocol.md](../../docs/stream-protocol.md). `AgentUiComponent`, `AgentApprovalRequest` and `AgentApprovalSettlement` (the `approval-settled` frame) are the payload types.
+- `ApprovalPolicy` / `DefaultApprovalPolicy` / `mayDecideApproval` — **who approves an `action` call, and for how long.** `requirementFor(tool, actor, thread)` answers `{ required, approver, ttlMs? }`: `required: false` runs the call straight away, `approver` is `'requester'` (the thread's own actor — the default) or a role, `ttlMs` bounds the wait. The answer is taken INSIDE the call's `persist:toolcall` checkpoint (together with the thread's remembered approvals, `AgentStore.rememberedApprovals`), so a replay reads the branch back instead of re-asking a policy that changed while the run was parked. The loop streams `approval-requested` with the approver and `expiresAt`, hands the ttl to `AgentLoopHooks.awaitApproval(call, ctx, { timeoutMs })`, and settles a lapsed wait (`Decision.expired`) as `ToolCallStatus 'expired'` — denied to the model with "the approval expired", streamed as `tool-output-denied` + `approval-settled { status: 'expired' }`. `Decision.remember` approves later calls of the same tool in the same thread; `Decision.decidedVia` records the surface. `StoredMessage.approvals` carries the persisted record on a reloaded thread. A run claimed before this existed keeps waiting on the requester with no timeout.
 - `observeTurnFrames` / `withTurnFrames` — what a model turn streamed that its result does not carry: the model's thinking (`reasoning` text, and `reasoningMs` summed over each burst of consecutive reasoning frames) and pushed `ui` components (first-seen order, last props per id). The loop and the dispatched `llm` step wrap the provider's sink with it inside the model checkpoint, so every provider that streams the vocabulary gets reasoning persisted (`StoredMessage.reasoning` / `reasoningMs` / `ui`) and a replay reads the journaled numbers back. A provider may set `ModelTurnResult.reasoning` / `reasoningMs` / `ui` itself; its values win. The step's `reasoningMs` also rides the `step-finish` frame.
 - `ToolPresentation` / `ToolResultView` / `ToolCatalogEntry` — how a person-facing surface talks about a tool without naming it (`ToolSpec.presentation`, set by `@AiTool({ presentation })`; never shown to the model). `ToolRegistry.visibleSpecs(actor, policy, allowList)` returns the whole specs behind the same gates `definitionsFor` applies, which is what `GET /agent/tools` serves.
 - `runAgentLoop(deps, input, hooks)` — the loop; the NestJS package drives it from both runners

package/dist/guardrails/index.d.cts

@@ -1,4 +1,4 @@
-import { A as Actor, I as InputProcessor, O as OutputProcessor, T as ToolHandler } from '../tool-Q2rmGeaG.cjs';
+import { A as Actor, I as InputProcessor, O as OutputProcessor, T as ToolHandler } from '../tool-B2Dq9ZwF.cjs';
 import '@standard-schema/spec';
 
 /**

package/dist/guardrails/index.d.ts

@@ -1,4 +1,4 @@
-import { A as Actor, I as InputProcessor, O as OutputProcessor, T as ToolHandler } from '../tool-Q2rmGeaG.js';
+import { A as Actor, I as InputProcessor, O as OutputProcessor, T as ToolHandler } from '../tool-B2Dq9ZwF.js';
 import '@standard-schema/spec';
 
 /**

package/dist/index.cjs

@@ -46,6 +46,7 @@ __export(src_exports, {
   AGENT_SPAN_EVENTS: () => AGENT_SPAN_EVENTS,
   AGENT_STORE: () => AGENT_STORE,
   AGENT_TOOL_REGISTRY: () => AGENT_TOOL_REGISTRY,
+  APPROVAL_EXPIRED_REASON: () => APPROVAL_EXPIRED_REASON,
   ASK_TOOL_DESCRIPTION: () => ASK_TOOL_DESCRIPTION,
   ASK_TOOL_NAME: () => ASK_TOOL_NAME,
   AgentRegistry: () => AgentRegistry,
@@ -60,6 +61,7 @@ __export(src_exports, {
   DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION: () => DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION,
   DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS: () => DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS,
   DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS: () => DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS,
+  DefaultApprovalPolicy: () => DefaultApprovalPolicy,
   DefaultRolesPolicy: () => DefaultRolesPolicy,
   GLOBAL_SCOPE: () => GLOBAL_SCOPE,
   MAX_ASK_QUESTIONS: () => MAX_ASK_QUESTIONS,
@@ -68,6 +70,7 @@ __export(src_exports, {
   QuotaExceededError: () => QuotaExceededError,
   REMEMBER_TOOL_DESCRIPTION: () => REMEMBER_TOOL_DESCRIPTION,
   REMEMBER_TOOL_NAME: () => REMEMBER_TOOL_NAME,
+  REQUESTER_APPROVER: () => REQUESTER_APPROVER,
   RunCancelledError: () => RunCancelledError,
   SKILL_TOOL_DESCRIPTION: () => SKILL_TOOL_DESCRIPTION,
   SKILL_TOOL_NAME: () => SKILL_TOOL_NAME,
@@ -95,6 +98,7 @@ __export(src_exports, {
   createIncrementalGate: () => createIncrementalGate,
   dayBoundsUtc: () => dayBoundsUtc,
   decodeStreamEvent: () => decodeStreamEvent,
+  defaultCanDecide: () => defaultCanDecide,
   defaultScopeResolver: () => defaultScopeResolver,
   detachedDelivered: () => detachedDelivered,
   detachedStarted: () => detachedStarted,
@@ -115,6 +119,7 @@ __export(src_exports, {
   isToolEnabled: () => isToolEnabled,
   isTransientToolError: () => isTransientToolError,
   loadSkill: () => loadSkill,
+  mayDecideApproval: () => mayDecideApproval,
   memoryForgetVerdict: () => memoryForgetVerdict,
   memoryWriteVerdict: () => memoryWriteVerdict,
   normalizeDelegation: () => normalizeDelegation,
@@ -160,6 +165,7 @@ __export(src_exports, {
   staticSkillProvider: () => staticSkillProvider,
   summarizeWithModel: () => summarizeWithModel,
   tenantScope: () => tenantScope,
+  toolCallApprovalFromRow: () => toolCallApprovalFromRow,
   traceLlmTurn: () => traceLlmTurn,
   traceToolExecution: () => traceToolExecution,
   truncateDetailContent: () => truncateDetailContent,
@@ -388,6 +394,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) {
@@ -2938,15 +3001,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 ? {
@@ -2956,6 +3037,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
       } : {}
     };
   });
@@ -2975,10 +3059,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;
@@ -3162,17 +3288,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,
@@ -3187,15 +3346,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,
@@ -3333,18 +3496,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,
@@ -3367,10 +3565,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);
@@ -4044,6 +4292,7 @@ __name(runAgentLoop, "runAgentLoop");
   AGENT_SPAN_EVENTS,
   AGENT_STORE,
   AGENT_TOOL_REGISTRY,
+  APPROVAL_EXPIRED_REASON,
   ASK_TOOL_DESCRIPTION,
   ASK_TOOL_NAME,
   AgentRegistry,
@@ -4058,6 +4307,7 @@ __name(runAgentLoop, "runAgentLoop");
   DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION,
   DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS,
   DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS,
+  DefaultApprovalPolicy,
   DefaultRolesPolicy,
   GLOBAL_SCOPE,
   MAX_ASK_QUESTIONS,
@@ -4066,6 +4316,7 @@ __name(runAgentLoop, "runAgentLoop");
   QuotaExceededError,
   REMEMBER_TOOL_DESCRIPTION,
   REMEMBER_TOOL_NAME,
+  REQUESTER_APPROVER,
   RunCancelledError,
   SKILL_TOOL_DESCRIPTION,
   SKILL_TOOL_NAME,
@@ -4093,6 +4344,7 @@ __name(runAgentLoop, "runAgentLoop");
   createIncrementalGate,
   dayBoundsUtc,
   decodeStreamEvent,
+  defaultCanDecide,
   defaultScopeResolver,
   detachedDelivered,
   detachedStarted,
@@ -4113,6 +4365,7 @@ __name(runAgentLoop, "runAgentLoop");
   isToolEnabled,
   isTransientToolError,
   loadSkill,
+  mayDecideApproval,
   memoryForgetVerdict,
   memoryWriteVerdict,
   normalizeDelegation,
@@ -4158,6 +4411,7 @@ __name(runAgentLoop, "runAgentLoop");
   staticSkillProvider,
   summarizeWithModel,
   tenantScope,
+  toolCallApprovalFromRow,
   traceLlmTurn,
   traceToolExecution,
   truncateDetailContent,