@dudousxd/nestjs-agent-core 0.20.0 → 0.22.0

package/dist/index.js

@@ -157,6 +157,95 @@ function withTurnFrames(result, frames) {
 }
 __name(withTurnFrames, "withTurnFrames");
 
+// src/tool-ui.ts
+var TOOL_STEP_UI = "@@nestjs-agent/tool-step-ui";
+function wrapToolStepOutput(output, ui) {
+  if (ui.length === 0) {
+    return output;
+  }
+  const wrapped = {
+    [TOOL_STEP_UI]: 1,
+    output,
+    ui: [
+      ...ui
+    ]
+  };
+  return wrapped;
+}
+__name(wrapToolStepOutput, "wrapToolStepOutput");
+function unwrapToolStepOutput(raw) {
+  if (typeof raw === "object" && raw !== null && raw[TOOL_STEP_UI] === 1) {
+    const wrapped = raw;
+    return {
+      output: wrapped.output,
+      ui: Array.isArray(wrapped.ui) ? wrapped.ui : []
+    };
+  }
+  return {
+    output: raw,
+    ui: []
+  };
+}
+__name(unwrapToolStepOutput, "unwrapToolStepOutput");
+function createUiCollector(toolCallId, write) {
+  const pushed = /* @__PURE__ */ new Map();
+  let next = 0;
+  const emit2 = /* @__PURE__ */ __name(async (component, props, options = {}) => {
+    if (typeof component !== "string" || component.length === 0) {
+      throw new Error("emitUi: component must be a non-empty string");
+    }
+    if (typeof props !== "object" || props === null || Array.isArray(props)) {
+      throw new Error("emitUi: props must be a JSON object");
+    }
+    let id = options.id;
+    if (id === void 0) {
+      id = `${toolCallId}:ui:${next}`;
+      next += 1;
+    }
+    const entry = {
+      id,
+      component,
+      // Snapshot: the frame and the persisted value are what the tool pushed at THIS moment, not
+      // whatever the object it handed over looks like when the step settles.
+      props: JSON.parse(JSON.stringify(props)),
+      ...options.version !== void 0 ? {
+        version: options.version
+      } : {},
+      toolCallId
+    };
+    pushed.set(id, entry);
+    await write?.({
+      kind: "ui",
+      ...entry
+    });
+    return {
+      id
+    };
+  }, "emit");
+  return {
+    emit: emit2,
+    components: /* @__PURE__ */ __name(() => [
+      ...pushed.values()
+    ], "components"),
+    restart: /* @__PURE__ */ __name(() => {
+      next = 0;
+    }, "restart")
+  };
+}
+__name(createUiCollector, "createUiCollector");
+function mergeUi(...lists) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    for (const component of list ?? []) {
+      merged.set(component.id, component);
+    }
+  }
+  return [
+    ...merged.values()
+  ];
+}
+__name(mergeUi, "mergeUi");
+
 // src/spi/pricing-store.ts
 async function seedModelPrices(store, prices) {
   for (const price of prices) {
@@ -831,11 +920,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(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(optionValues, "optionValues");
+__name(readElicitationQuestions, "readElicitationQuestions");
+
+// src/elicitation.ts
 function normalizeElicitationReply(reply) {
   if (typeof reply !== "object" || reply === null) {
     return {
@@ -871,8 +1184,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 {
@@ -893,7 +1205,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:";
@@ -959,7 +1271,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"
@@ -967,7 +1295,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",
@@ -977,6 +1305,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,
@@ -996,7 +1351,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
@@ -1024,9 +1383,7 @@ var ASK_JSON_SCHEMA = {
         additionalProperties: false,
         required: [
           "id",
-          "prompt",
-          "options",
-          "defaults"
+          "prompt"
         ],
         properties: {
           id: {
@@ -1036,6 +1393,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."
@@ -1050,7 +1451,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",
@@ -2859,6 +3260,11 @@ async function claimToolCall(turn, call) {
       ...spec?.detached === true ? {
         detached: true
       } : {},
+      // Same for `terminal`: absent unless declared, so a deployment with no terminal tool writes
+      // the bytes it always has, and a replay reads the branch back instead of re-deciding it.
+      ...spec?.terminal === true ? {
+        terminal: true
+      } : {},
       ...approval !== void 0 ? {
         approval
       } : {}
@@ -2880,6 +3286,9 @@ async function claimToolCall(turn, call) {
     ...persisted?.detached === true ? {
       detached: true
     } : {},
+    ...persisted?.terminal === true ? {
+      terminal: true
+    } : {},
     ...toolType === "action" && persisted?.approval !== void 0 ? {
       approval: persisted.approval
     } : {},
@@ -3046,7 +3455,7 @@ async function invokeClaimedTool(turn, claimed) {
     if (claimed.toolType === "memory") {
       return await rememberIntoTurn(turn, claimed, startedAt);
     }
-    let output;
+    let raw;
     if (hooks.dispatchTool) {
       const stepCtx = {
         actor: input.actor,
@@ -3069,28 +3478,47 @@ async function invokeClaimedTool(turn, claimed) {
         } : {},
         // Numeric-only: the handler applies withToolTimeout AND its own local `classify` — see
         // ToolStepEnvelope.transientRetry.
-        transientRetry: resolveToolTransientRetryNumbers(deps.toolTransientRetry)
+        transientRetry: resolveToolTransientRetryNumbers(deps.toolTransientRetry),
+        // The handler hands back what the tool pushed through `ctx.emitUi` with its output.
+        collectUi: true
       };
-      output = await hooks.dispatchTool(resolvedCall, envelope);
+      raw = await hooks.dispatchTool(resolvedCall, envelope);
     } else {
-      const invocation = hooks.step(`tool:${call.id}`, () => traceToolExecution(hooks.runId, {
-        toolCallId: call.id,
-        toolName: call.name,
-        toolType
-      }, () => invokeWithTransientRetry(() => deps.registry.invoke(call.name, call.input, ctx, deps.rolesPolicy), deps.toolTransientRetry ?? {}, {
-        ...hooks.isControlFlowError !== void 0 ? {
-          isControlFlowError: hooks.isControlFlowError
-        } : {},
-        onRetry: /* @__PURE__ */ __name((attempt, retryError) => {
-          publishAgentToolRetry({
-            toolName: call.name,
-            toolCallId: call.id,
-            attempt,
-            message: retryError instanceof Error ? retryError.message : String(retryError)
-          });
-        }, "onRetry")
-      })));
-      output = deps.toolTimeoutMs !== void 0 ? await withToolTimeout(invocation, deps.toolTimeoutMs, call.name) : await invocation;
+      const invocation = hooks.step(`tool:${call.id}`, async () => {
+        const ui2 = createUiCollector(call.id, (event) => turn.writer.write(encodeStreamEvent(event)));
+        const output2 = await traceToolExecution(hooks.runId, {
+          toolCallId: call.id,
+          toolName: call.name,
+          toolType
+        }, () => invokeWithTransientRetry(() => {
+          ui2.restart();
+          return deps.registry.invoke(call.name, call.input, {
+            ...ctx,
+            emitUi: ui2.emit
+          }, deps.rolesPolicy);
+        }, deps.toolTransientRetry ?? {}, {
+          ...hooks.isControlFlowError !== void 0 ? {
+            isControlFlowError: hooks.isControlFlowError
+          } : {},
+          onRetry: /* @__PURE__ */ __name((attempt, retryError) => {
+            publishAgentToolRetry({
+              toolName: call.name,
+              toolCallId: call.id,
+              attempt,
+              message: retryError instanceof Error ? retryError.message : String(retryError)
+            });
+          }, "onRetry")
+        }));
+        return wrapToolStepOutput(output2, ui2.components());
+      });
+      raw = deps.toolTimeoutMs !== void 0 ? await withToolTimeout(invocation, deps.toolTimeoutMs, call.name) : await invocation;
+    }
+    const { output, ui } = unwrapToolStepOutput(raw);
+    if (ui.length > 0) {
+      turn.toolUi.set(call.id, ui);
+    }
+    if (claimed.terminal === true) {
+      turn.halt.terminal = true;
     }
     return {
       status: "executed",
@@ -3988,6 +4416,10 @@ ${block}`;
       hooks,
       messageId: assistant.id,
       writer,
+      toolUi: /* @__PURE__ */ new Map(),
+      halt: {
+        terminal: false
+      },
       ...skillOffer !== void 0 ? {
         skills: skillOffer
       } : {},
@@ -4020,6 +4452,10 @@ ${block}`;
     assistantMessage.toolResults = settledResults;
     await hooks.step(`stream:tool-outputs:${i}`, async () => {
       await deps.store.setMessageToolResults(assistant.id, settledResults);
+      const toolUi = toolCallsWithKind.flatMap((call) => turnCalls.toolUi.get(call.id) ?? []);
+      if (toolUi.length > 0) {
+        await deps.store.setMessageUi?.(assistant.id, mergeUi(turn.ui, toolUi));
+      }
       for (const result of results) {
         await writer.write(encodeStreamEvent(outputFrame(result)));
       }
@@ -4034,6 +4470,9 @@ ${block}`;
         } : {}
       }));
     });
+    if (turnCalls.halt.terminal) {
+      break;
+    }
   }
   if (history.title === "" || history.title === "New chat") {
     await hooks.step("persist:title", () => deps.store.setTitle(input.threadId, deriveTitle(input.userText)));
@@ -4129,6 +4568,7 @@ export {
   DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS,
   DefaultApprovalPolicy,
   DefaultRolesPolicy,
+  ELICITATION_INPUT_TYPES,
   GLOBAL_SCOPE,
   MAX_ASK_QUESTIONS,
   OutputRejectedError,
@@ -4162,6 +4602,7 @@ export {
   compositeSkillProvider,
   createFrameBuffer,
   createIncrementalGate,
+  createUiCollector,
   dayBoundsUtc,
   decodeStreamEvent,
   defaultCanDecide,
@@ -4184,10 +4625,12 @@ export {
   isReplayIntegrityError,
   isToolEnabled,
   isTransientToolError,
+  isTypedQuestion,
   loadSkill,
   mayDecideApproval,
   memoryForgetVerdict,
   memoryWriteVerdict,
+  mergeUi,
   normalizeDelegation,
   normalizeElicitationReply,
   observeTurnFrames,
@@ -4205,6 +4648,9 @@ export {
   publishAgentSkillsResolved,
   publishAgentToolCall,
   publishAgentToolRetry,
+  questionOptions,
+  readElicitationInput,
+  readElicitationQuestions,
   releaseGatedFrames,
   rememberInputSchema,
   rememberToolDefinition,
@@ -4235,6 +4681,9 @@ export {
   traceLlmTurn,
   traceToolExecution,
   truncateDetailContent,
+  unwrapToolStepOutput,
+  validateElicitationAnswer,
+  validateElicitationValue,
   validateStructured,
   windowHistory,
   withAskTool,
@@ -4242,6 +4691,7 @@ export {
   withSkillTool,
   withToolTimeout,
   withTurnFrames,
+  wrapToolStepOutput,
   writeMemory
 };
 //# sourceMappingURL=index.js.map