@dudousxd/nestjs-agent-core 0.19.0 → 0.21.0

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,7 +61,9 @@ __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,
+  ELICITATION_INPUT_TYPES: () => ELICITATION_INPUT_TYPES,
   GLOBAL_SCOPE: () => GLOBAL_SCOPE,
   MAX_ASK_QUESTIONS: () => MAX_ASK_QUESTIONS,
   OutputRejectedError: () => OutputRejectedError,
@@ -68,6 +71,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 +99,7 @@ __export(src_exports, {
   createIncrementalGate: () => createIncrementalGate,
   dayBoundsUtc: () => dayBoundsUtc,
   decodeStreamEvent: () => decodeStreamEvent,
+  defaultCanDecide: () => defaultCanDecide,
   defaultScopeResolver: () => defaultScopeResolver,
   detachedDelivered: () => detachedDelivered,
   detachedStarted: () => detachedStarted,
@@ -114,7 +119,9 @@ __export(src_exports, {
   isReplayIntegrityError: () => isReplayIntegrityError,
   isToolEnabled: () => isToolEnabled,
   isTransientToolError: () => isTransientToolError,
+  isTypedQuestion: () => isTypedQuestion,
   loadSkill: () => loadSkill,
+  mayDecideApproval: () => mayDecideApproval,
   memoryForgetVerdict: () => memoryForgetVerdict,
   memoryWriteVerdict: () => memoryWriteVerdict,
   normalizeDelegation: () => normalizeDelegation,
@@ -134,6 +141,9 @@ __export(src_exports, {
   publishAgentSkillsResolved: () => publishAgentSkillsResolved,
   publishAgentToolCall: () => publishAgentToolCall,
   publishAgentToolRetry: () => publishAgentToolRetry,
+  questionOptions: () => questionOptions,
+  readElicitationInput: () => readElicitationInput,
+  readElicitationQuestions: () => readElicitationQuestions,
   releaseGatedFrames: () => releaseGatedFrames,
   rememberInputSchema: () => rememberInputSchema,
   rememberToolDefinition: () => rememberToolDefinition,
@@ -160,9 +170,12 @@ __export(src_exports, {
   staticSkillProvider: () => staticSkillProvider,
   summarizeWithModel: () => summarizeWithModel,
   tenantScope: () => tenantScope,
+  toolCallApprovalFromRow: () => toolCallApprovalFromRow,
   traceLlmTurn: () => traceLlmTurn,
   traceToolExecution: () => traceToolExecution,
   truncateDetailContent: () => truncateDetailContent,
+  validateElicitationAnswer: () => validateElicitationAnswer,
+  validateElicitationValue: () => validateElicitationValue,
   validateStructured: () => validateStructured,
   windowHistory: () => windowHistory,
   withAskTool: () => withAskTool,
@@ -388,6 +401,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) {
@@ -947,11 +1017,235 @@ ${detail}`;
 }
 __name(repairInstruction, "repairInstruction");
 
-// src/elicitation.ts
-function optionValues(question) {
-  return new Set(question.options.map((option) => option.value));
+// src/elicitation-input.ts
+var ELICITATION_INPUT_TYPES = [
+  "text",
+  "textarea",
+  "number",
+  "boolean",
+  "date",
+  "email",
+  "url",
+  "select"
+];
+function questionOptions(question) {
+  return question.options ?? [];
+}
+__name(questionOptions, "questionOptions");
+function isTypedQuestion(question) {
+  return question.input !== void 0 && question.input.type !== "select";
+}
+__name(isTypedQuestion, "isTypedQuestion");
+var DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+var EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+var NUMBER_PATTERN = /^-?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i;
+function isDate(value) {
+  const match = DATE_PATTERN.exec(value);
+  if (match === null) {
+    return false;
+  }
+  const [, year, month, day] = match;
+  const date = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day)));
+  return date.getUTCFullYear() === Number(year) && date.getUTCMonth() === Number(month) - 1 && date.getUTCDate() === Number(day);
+}
+__name(isDate, "isDate");
+function isHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+__name(isHttpUrl, "isHttpUrl");
+function fullMatch(pattern, value) {
+  try {
+    return new RegExp(`^(?:${pattern})$`, "u").test(value);
+  } catch {
+    return void 0;
+  }
+}
+__name(fullMatch, "fullMatch");
+function asNumber(bound) {
+  if (typeof bound === "number" && Number.isFinite(bound)) {
+    return bound;
+  }
+  if (typeof bound === "string" && NUMBER_PATTERN.test(bound.trim())) {
+    return Number(bound);
+  }
+  return void 0;
+}
+__name(asNumber, "asNumber");
+function validateElicitationValue(question, value) {
+  const input = question.input;
+  if (input === void 0 || input.type === "select") {
+    if (question.allowFreeText === true) {
+      return null;
+    }
+    return questionOptions(question).some((option) => option.value === value) ? null : "must be one of the offered options";
+  }
+  switch (input.type) {
+    case "number": {
+      if (!NUMBER_PATTERN.test(value.trim()) || !Number.isFinite(Number(value))) {
+        return "must be a number";
+      }
+      const number = Number(value);
+      const min = asNumber(input.min);
+      const max = asNumber(input.max);
+      if (min !== void 0 && number < min) {
+        return `must be at least ${min}`;
+      }
+      if (max !== void 0 && number > max) {
+        return `must be at most ${max}`;
+      }
+      return null;
+    }
+    case "boolean":
+      return value === "true" || value === "false" ? null : 'must be "true" or "false"';
+    case "date": {
+      if (!isDate(value)) {
+        return "must be a date as YYYY-MM-DD";
+      }
+      if (typeof input.min === "string" && isDate(input.min) && value < input.min) {
+        return `must be on or after ${input.min}`;
+      }
+      if (typeof input.max === "string" && isDate(input.max) && value > input.max) {
+        return `must be on or before ${input.max}`;
+      }
+      return null;
+    }
+    case "email":
+      if (!EMAIL_PATTERN.test(value)) {
+        return "must be an email address";
+      }
+      break;
+    case "url":
+      if (!isHttpUrl(value)) {
+        return "must be an http(s) URL";
+      }
+      break;
+    case "text":
+    case "textarea": {
+      const min = asNumber(input.min);
+      const max = asNumber(input.max);
+      if (min !== void 0 && value.length < min) {
+        return `must be at least ${min} characters`;
+      }
+      if (max !== void 0 && value.length > max) {
+        return `must be at most ${max} characters`;
+      }
+      break;
+    }
+  }
+  if (input.pattern !== void 0 && fullMatch(input.pattern, value) === false) {
+    return "does not match the expected format";
+  }
+  return null;
+}
+__name(validateElicitationValue, "validateElicitationValue");
+function validateElicitationAnswer(question, values) {
+  const present = values.filter((value) => value !== "");
+  if (present.length === 0) {
+    return question.input?.required === true ? "requires an answer" : null;
+  }
+  if (question.multiple !== true && present.length > 1) {
+    return "takes a single value";
+  }
+  for (const value of present) {
+    const problem = validateElicitationValue(question, value);
+    if (problem !== null) {
+      return problem;
+    }
+  }
+  return null;
+}
+__name(validateElicitationAnswer, "validateElicitationAnswer");
+function readElicitationInput(raw) {
+  if (typeof raw !== "object" || raw === null) {
+    return void 0;
+  }
+  const candidate = raw;
+  const type = candidate.type;
+  if (typeof type !== "string" || !ELICITATION_INPUT_TYPES.includes(type)) {
+    return void 0;
+  }
+  const bound = /* @__PURE__ */ __name((value) => typeof value === "number" && Number.isFinite(value) || typeof value === "string" ? value : void 0, "bound");
+  const min = bound(candidate.min);
+  const max = bound(candidate.max);
+  return {
+    type,
+    ...typeof candidate.placeholder === "string" ? {
+      placeholder: candidate.placeholder
+    } : {},
+    ...candidate.required === true ? {
+      required: true
+    } : {},
+    ...min !== void 0 ? {
+      min
+    } : {},
+    ...max !== void 0 ? {
+      max
+    } : {},
+    ...typeof candidate.pattern === "string" ? {
+      pattern: candidate.pattern
+    } : {}
+  };
 }
-__name(optionValues, "optionValues");
+__name(readElicitationInput, "readElicitationInput");
+function readElicitationQuestions(input) {
+  if (typeof input !== "object" || input === null) {
+    return [];
+  }
+  const raw = input.questions;
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const questions = [];
+  for (const item of raw) {
+    if (typeof item !== "object" || item === null) {
+      continue;
+    }
+    const candidate = item;
+    if (typeof candidate.id !== "string" || typeof candidate.prompt !== "string") {
+      continue;
+    }
+    const options = Array.isArray(candidate.options) ? candidate.options.flatMap((option) => {
+      if (typeof option !== "object" || option === null) {
+        return [];
+      }
+      const { value, label } = option;
+      return typeof value === "string" && typeof label === "string" ? [
+        {
+          value,
+          label
+        }
+      ] : [];
+    }) : [];
+    const typed = readElicitationInput(candidate.input);
+    const defaults = Array.isArray(candidate.defaults) ? candidate.defaults.filter((value) => typeof value === "string") : [];
+    questions.push({
+      id: candidate.id,
+      prompt: candidate.prompt,
+      options,
+      ...typed !== void 0 ? {
+        input: typed
+      } : {},
+      ...defaults.length > 0 ? {
+        defaults
+      } : {},
+      ...candidate.multiple === true ? {
+        multiple: true
+      } : {},
+      ...candidate.allowFreeText === true ? {
+        allowFreeText: true
+      } : {}
+    });
+  }
+  return questions;
+}
+__name(readElicitationQuestions, "readElicitationQuestions");
+
+// src/elicitation.ts
 function normalizeElicitationReply(reply) {
   if (typeof reply !== "object" || reply === null) {
     return {
@@ -987,8 +1281,7 @@ function resolveElicitation(request, raw) {
       defaulted.push(question.id);
       continue;
     }
-    const allowed = optionValues(question);
-    const valid = question.allowFreeText === true ? submitted : submitted.filter((value) => allowed.has(value));
+    const valid = submitted.filter((value) => value !== "" && validateElicitationValue(question, value) === null);
     answers[question.id] = question.multiple === true ? valid : valid.slice(0, 1);
   }
   return {
@@ -1009,7 +1302,7 @@ __name(settleElicitation, "settleElicitation");
 function renderElicitationAnswers(request, outcome) {
   const lines = request.questions.map((question) => {
     const chosen = outcome.answers[question.id] ?? [];
-    const labels = chosen.map((value) => question.options.find((option) => option.value === value)?.label ?? value);
+    const labels = chosen.map((value) => questionOptions(question).find((option) => option.value === value)?.label ?? value);
     return `${question.prompt} \u2192 ${labels.length > 0 ? labels.join(", ") : "(no answer)"}`;
   });
   const preface = outcome.skipped ? "The user declined to answer and asked you to proceed on these assumptions:" : "The user answered:";
@@ -1075,7 +1368,23 @@ function parseQuestion(raw, path, issues) {
     ], "must be a non-empty string"));
     return void 0;
   }
-  if (!Array.isArray(candidate.options) || candidate.options.length === 0) {
+  let input;
+  if (candidate.input !== void 0) {
+    input = readElicitationInput(candidate.input);
+    if (input === void 0) {
+      issues.push(issue([
+        ...path,
+        "input",
+        "type"
+      ], `must be one of ${ELICITATION_INPUT_TYPES.join(", ")}`));
+      return void 0;
+    }
+  }
+  const described = typeof candidate.description === "string" && candidate.description.length > 0 ? {
+    description: candidate.description
+  } : {};
+  const typed = input !== void 0 && input.type !== "select";
+  if (!typed && (!Array.isArray(candidate.options) || candidate.options.length === 0)) {
     issues.push(issue([
       ...path,
       "options"
@@ -1083,7 +1392,7 @@ function parseQuestion(raw, path, issues) {
     return void 0;
   }
   const options = [];
-  for (const [index, rawOption] of candidate.options.entries()) {
+  for (const [index, rawOption] of (Array.isArray(candidate.options) ? candidate.options : []).entries()) {
     const option = parseOption(rawOption, [
       ...path,
       "options",
@@ -1093,6 +1402,33 @@ function parseQuestion(raw, path, issues) {
       options.push(option);
     }
   }
+  if (typed) {
+    const question = {
+      id: candidate.id,
+      prompt: candidate.prompt,
+      ...described,
+      ...options.length > 0 ? {
+        options
+      } : {},
+      input,
+      ...candidate.multiple === true ? {
+        multiple: true
+      } : {}
+    };
+    const offered2 = Array.isArray(candidate.defaults) ? candidate.defaults.filter((value) => typeof value === "string") : [];
+    const defaults2 = offered2.filter((value) => validateElicitationValue(question, value) === null);
+    if (offered2.length > 0 && defaults2.length === 0) {
+      issues.push(issue([
+        ...path,
+        "defaults"
+      ], `must be valid ${input.type} values`));
+      return void 0;
+    }
+    return defaults2.length > 0 ? {
+      ...question,
+      defaults: defaults2
+    } : question;
+  }
   if (!Array.isArray(candidate.defaults) || candidate.defaults.length === 0) {
     issues.push(issue([
       ...path,
@@ -1112,7 +1448,11 @@ function parseQuestion(raw, path, issues) {
   return {
     id: candidate.id,
     prompt: candidate.prompt,
+    ...described,
     options,
+    ...input !== void 0 ? {
+      input
+    } : {},
     defaults,
     ...candidate.multiple === true ? {
       multiple: true
@@ -1140,9 +1480,7 @@ var ASK_JSON_SCHEMA = {
         additionalProperties: false,
         required: [
           "id",
-          "prompt",
-          "options",
-          "defaults"
+          "prompt"
         ],
         properties: {
           id: {
@@ -1152,6 +1490,50 @@ var ASK_JSON_SCHEMA = {
           prompt: {
             type: "string"
           },
+          description: {
+            type: "string",
+            description: "A line of help under the prompt."
+          },
+          input: {
+            type: "object",
+            additionalProperties: false,
+            required: [
+              "type"
+            ],
+            description: 'Ask for a typed value instead of offering options. Omit for a pick from options. Answers come back as strings: numbers as decimals, booleans as "true"/"false", dates as YYYY-MM-DD.',
+            properties: {
+              type: {
+                type: "string",
+                enum: [
+                  ...ELICITATION_INPUT_TYPES
+                ]
+              },
+              placeholder: {
+                type: "string"
+              },
+              required: {
+                type: "boolean"
+              },
+              min: {
+                type: [
+                  "number",
+                  "string"
+                ],
+                description: "number: minimum; text: minimum length; date: earliest YYYY-MM-DD."
+              },
+              max: {
+                type: [
+                  "number",
+                  "string"
+                ],
+                description: "number: maximum; text: maximum length; date: latest YYYY-MM-DD."
+              },
+              pattern: {
+                type: "string",
+                description: "A regex the whole value must match."
+              }
+            }
+          },
           multiple: {
             type: "boolean",
             description: "Allow more than one option to be chosen."
@@ -1166,7 +1548,7 @@ var ASK_JSON_SCHEMA = {
             items: {
               type: "string"
             },
-            description: "REQUIRED. The option values you would pick yourself, so the user can confirm rather than decide."
+            description: "REQUIRED for a pick from options: the option values you would pick yourself, so the user can confirm rather than decide. For a typed input, the value you would enter, when there is a sensible one."
           },
           options: {
             type: "array",
@@ -2938,15 +3320,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 +3356,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 +3378,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 +3607,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 +3665,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 +3815,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 +3884,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 +4611,7 @@ __name(runAgentLoop, "runAgentLoop");
   AGENT_SPAN_EVENTS,
   AGENT_STORE,
   AGENT_TOOL_REGISTRY,
+  APPROVAL_EXPIRED_REASON,
   ASK_TOOL_DESCRIPTION,
   ASK_TOOL_NAME,
   AgentRegistry,
@@ -4058,7 +4626,9 @@ __name(runAgentLoop, "runAgentLoop");
   DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION,
   DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS,
   DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS,
+  DefaultApprovalPolicy,
   DefaultRolesPolicy,
+  ELICITATION_INPUT_TYPES,
   GLOBAL_SCOPE,
   MAX_ASK_QUESTIONS,
   OutputRejectedError,
@@ -4066,6 +4636,7 @@ __name(runAgentLoop, "runAgentLoop");
   QuotaExceededError,
   REMEMBER_TOOL_DESCRIPTION,
   REMEMBER_TOOL_NAME,
+  REQUESTER_APPROVER,
   RunCancelledError,
   SKILL_TOOL_DESCRIPTION,
   SKILL_TOOL_NAME,
@@ -4093,6 +4664,7 @@ __name(runAgentLoop, "runAgentLoop");
   createIncrementalGate,
   dayBoundsUtc,
   decodeStreamEvent,
+  defaultCanDecide,
   defaultScopeResolver,
   detachedDelivered,
   detachedStarted,
@@ -4112,7 +4684,9 @@ __name(runAgentLoop, "runAgentLoop");
   isReplayIntegrityError,
   isToolEnabled,
   isTransientToolError,
+  isTypedQuestion,
   loadSkill,
+  mayDecideApproval,
   memoryForgetVerdict,
   memoryWriteVerdict,
   normalizeDelegation,
@@ -4132,6 +4706,9 @@ __name(runAgentLoop, "runAgentLoop");
   publishAgentSkillsResolved,
   publishAgentToolCall,
   publishAgentToolRetry,
+  questionOptions,
+  readElicitationInput,
+  readElicitationQuestions,
   releaseGatedFrames,
   rememberInputSchema,
   rememberToolDefinition,
@@ -4158,9 +4735,12 @@ __name(runAgentLoop, "runAgentLoop");
   staticSkillProvider,
   summarizeWithModel,
   tenantScope,
+  toolCallApprovalFromRow,
   traceLlmTurn,
   traceToolExecution,
   truncateDetailContent,
+  validateElicitationAnswer,
+  validateElicitationValue,
   validateStructured,
   windowHistory,
   withAskTool,