@dudousxd/nestjs-agent-core 0.20.0 → 0.21.0

package/README.md

@@ -27,6 +27,7 @@ import type { ModelProvider, AgentStore, ToolSpec, RolesPolicy } from '@dudousxd
 - `InputProcessor` / `OutputProcessor` — the seams on either side of the model call. Input rewrites `{ system, messages }` before every model call; output returns `pass` / `replace` / `reject` on each step's answer. Both run inside a checkpoint (so a processor may call a model), and they own TRANSFORMATION only — `HistoryPolicy` owns which messages are there to transform. Registering an output processor takes the turn's model call off the run's sink; what that costs the reader depends on what the chain declares (`resolveOutputGateMode`). An undeclared processor holds the whole answer — `createFrameBuffer` + `releaseGatedFrames`. A chain where EVERY processor sets `incremental` gates the growing prefix instead and keeps streaming — `createIncrementalGate` + `gateTail`, with the widest `lookbackChars` in the chain (`resolveGateLookback`, default `DEFAULT_INCREMENTAL_LOOKBACK_CHARS`) held back. The whole-answer pass stays authoritative either way, and `gateTail` raises `ProcessorFailedError` when the settled answer is not an extension of the released prefix. The output chain covers every model-written value that reaches a reader, not only the streamed answer: the `outputSchema` formatting pass is gated before its text is validated (`process:output:structured:<step>:<attempt>`), and each follow-up suggestion is gated on its own (`gateFollowUps`, `process:output:followups:<step>`) — where a refused suggestion is DROPPED rather than failing a run whose answer already passed the same chain. Neither is streamed, so an `incremental` declaration does not apply to them. The folded history summary is deliberately NOT gated here: it never reaches a reader, it re-enters the next prompt as a leading `system` message, and `inputProcessors` — the seam that owns prompt text — already see it on every step.
 - `outputSchema` (on `AgentLoopDeps`) / `StructuredOutputError` — constrain the final answer to a Standard Schema via one journaled formatting pass after the turn's last model step, with bounded repair. The pass is a translation, so it is shown the question (as the input chain left it) and the gated answer, and nothing else off the transcript — `outputFromTranscript` opts an agent back into the whole turn. `validateStructured` and `extractJson` are the pieces; `ModelTurnArgs.outputSchema` and `ModelTurnResult.object` are how a provider opts into constraining generation itself.
 - `ElicitationRequest` / `ElicitationReply` / `settleElicitation` — putting a structured question set to the USER and waiting for the answer, from either surface (`AgentLoopDeps.intake`, authored on the agent; `AgentLoopDeps.ask`, the model-callable tool). Both persist as one pending tool-call row and park on the `tool:<runId>:<callId>` signal a HITL approval already uses. `settleElicitation` is pure: it fills every unanswered question from the request's own `defaults` and renders the result by option LABEL, so the same values are reached on every replay without a checkpoint of its own. Because the row is parked as a `pending_approval` action, the reply that comes back may be a `Decision` an operator pressed Approve/Reject on rather than answers — `normalizeElicitationReply` reduces one to the other where the reply is CONSUMED (Approve = confirm every pre-picked default, Reject = skip), so the reduction holds on every path rather than only on a host that implemented no `awaitAnswers`. `askToolDefinition()` is the tool as the model sees it — never registered, so its kind can never be decided by a process-local registry lookup.
+- `ElicitationInput` / `validateElicitationValue` / `validateElicitationAnswer` / `readElicitationQuestions` — **typed questions.** `ElicitationQuestion` gains `description?` and `input?: { type: 'text' | 'textarea' | 'number' | 'boolean' | 'date' | 'email' | 'url' | 'select', placeholder?, required?, min?, max?, pattern? }`; `options` becomes optional when `input` asks for a typed value (a `select` still picks from them), and a typed question may omit `defaults`. Answers stay `string[]` on the wire in one canonical form per type (decimal, `"true"`/`"false"`, `YYYY-MM-DD`, …). The validators are the one rule set the loop (which drops values it cannot settle), the answer route (which refuses them with `400`) and the React model (which reports them before sending) share.
 - `Skill` / `SkillProvider` / `ScopeResolver` / `offerSkills` — authored procedures the model pulls in when a task calls for one, instead of every instruction living in the system prompt. A skill is not an agent: an `@Agent` is WHO answers, a skill is HOW one task is done, and any agent may load one. Scoping is by an opaque TOKEN (`actor:u1`, `tenant:berlin`, `global`, or a host's own `depot:north`), and which tokens apply is a host-supplied `ScopeResolver` returning them most-specific-first — so precedence falls out of the order and a new axis is a resolver change, not a schema change. `defaultScopeResolver` covers the tokens derivable from `Actor` alone (actor / tenant / global); `actorScope`, `tenantScope` and `GLOBAL_SCOPE` mint them. This package owns NO skill table: the host owns the rows behind `SkillProvider` (`list(scopes, ctx)` for the catalog, `load(name, scope, ctx)` for one body), so a consumer can relate its own `Sector` entity against the token values in its own read model without writing migrations into a schema the boot-time heal also edits. `staticSkillProvider` and `compositeSkillProvider` are the built-ins. `resolveSkillCatalog` is the pure precedence pass: most specific wins, and the loser's scope is recorded on `shadows` rather than discarded, so the model can say "your setting differs from the org default" instead of choosing silently. What enters the SYSTEM prompt is the catalog only — one line per skill, bounded by `maxSkills` (`DEFAULT_MAX_SKILLS`) — while a BODY arrives as a `skill` tool result on the transcript, where the `HistoryPolicy` ceiling already governs it. The loop spends ONE checkpoint on all of it (`skills:catalog`) holding the whole offer, and serves each load inside the ordinary `tool:<callId>` checkpoint, so both the scopes that applied and the body that entered the prompt are facts the journal holds rather than answers a replaying process's provider would give afresh. `loadSkill` refuses any name the turn's own catalog does not carry, which makes the journaled catalog the authorization boundary as well as the menu. `skillWriteVerdict` is the write rule: your own scope is yours, a wider one needs an elevated HUMAN author, and nothing but a human may ever write above its own scope — an agent that could write a `tenant:` skill is an agent whose prompt anyone in the tenant can edit by talking to it.
 - `MemoryRecord` / `MemoryProvider` / `offerMemories` / `writeMemory` — what the assistant concluded about a person or an organisation, carried across turns and threads. Scoped by the SAME opaque tokens and the same `ScopeResolver` skills use, so a deployment has one answer to "which scopes does this actor have". A memory is a keyed fact: `{ key, text, scope, origin, updatedAt }`, and the key is what makes a conflict mechanically detectable — two memories sharing a key at different scopes are one question answered twice, and `resolveMemoryDigest` lets the narrower win. Where it does, the entry's `overrides` carries the beaten **text** and its **author**, not merely its scope (a skill's `shadows`): the model is following one procedure either way, but a memory is a VALUE, and an agent that knew only that a wider one existed could tell the user nothing except which it picked. **Not retrieval:** a passage is a document someone authored and can fix at its source, a memory is the agent's own inference about someone who never saw it written — hence `MemoryOrigin` on every record, a block that tells the model these are its own fallible notes, and `forget` being REQUIRED on the provider while `write` is optional. Every provider method and every multi-argument export here takes ONE named object (`ListMemoriesInput`, `StoreMemoryInput`, `ResolveMemoryDigestInput`, …): `key`, `text` and `scope` are all strings, and transposed positional arguments would compile clean and write a fact whose key is its value. `memoryWriteVerdict` carries the same four rules as `skillWriteVerdict`; rule three (nothing but a human may write above its own scope, whatever elevation a host grants) is enforced by SHAPE as well as by check, since `rememberToolDefinition()` takes no scope parameter. `memoryForgetVerdict` is narrower still and takes no `elevated` flag: deleting what the assistant believes about YOU needs nobody's permission. What enters the system prompt is one line per memory bounded by `maxMemories` (`DEFAULT_MAX_MEMORIES`), each capped at `maxFactChars` (`DEFAULT_MAX_FACT_CHARS`) when it is WRITTEN — so the block's ceiling is the product of two numbers an operator set, and there is no body/catalog split because a fact that cannot be stated in a line is a document. **The prompt budget is bounded; the store is not.** Once the applicable set outgrows the block, WHICH memories it carries is a decision, and making it by scope starves the widest scopes first — one person's twentieth note would end every chance their organisation's facts had, leaving only a non-zero `omitted` behind. So a provider MAY implement `search({ scopes, query, limit, ctx })` and the block is filled by relevance to the turn instead; omit it and every turn is served by `list`, selecting narrowest-then-newest as before. Scope remains a hard FILTER that gates before ranking (a record returned outside `scopes` is dropped, so a host's filter bug costs throughput rather than privacy), and `search` must return every record sharing a returned key or precedence inverts. `MemoryRecord.pinned` is the categorical always-on marker — present whatever the turn is about, spending the same budget, never set by the agent (`StoreMemoryInput` has no such field, and the `remember` tool has no such parameter), with `MemoryDigest.pinnedOmitted` naming the one omission that is a misconfiguration rather than a budget. `buildMemoryBlock` frames entries by `origin.author`: what the agent CONCLUDED is hedged ("your own notes … prefer what the user says now"), what a person STATED is not, because telling a model to prefer the user over an organisation's published policy hands any user an override of it by assertion. A `partial` block says so, so the model does not read an absence as evidence. The loop spends ONE checkpoint (`memory:digest`) holding the whole digest — the search included, since a ranking is the most re-derivable decision here — which is both what the block is rendered from and what a later `remember` call is authorized against; the write itself happens inside the ordinary `tool:<callId>` checkpoint, which is what makes it idempotent under replay. The query is the user's own turn text and nothing else: the only thing available before the first model call, already a journaled input to the run, and it fails at a turn with no topic — which is what `pinned` is for.
 - `AgentStore.setMessageToolResults(messageId, results)` — a message's tool CALLS are known when it is appended and their outputs are not, so the loop settles them afterwards with one write of the turn's complete result list (its synthetic `retrieve` / `structured_output` calls included). Both halves live on the message because that is where a thread reader pairs them; a call whose output only ever reaches the `agent_tool_call` table renders as a tool still running. Required, not optional — a store that silently declines it breaks a client with nothing logged.

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-B2Dq9ZwF.cjs';
+import { A as Actor, I as InputProcessor, O as OutputProcessor, T as ToolHandler } from '../tool-CwXibnce.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-B2Dq9ZwF.js';
+import { A as Actor, I as InputProcessor, O as OutputProcessor, T as ToolHandler } from '../tool-CwXibnce.js';
 import '@standard-schema/spec';
 
 /**

package/dist/index.cjs

@@ -63,6 +63,7 @@ __export(src_exports, {
   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,
@@ -118,6 +119,7 @@ __export(src_exports, {
   isReplayIntegrityError: () => isReplayIntegrityError,
   isToolEnabled: () => isToolEnabled,
   isTransientToolError: () => isTransientToolError,
+  isTypedQuestion: () => isTypedQuestion,
   loadSkill: () => loadSkill,
   mayDecideApproval: () => mayDecideApproval,
   memoryForgetVerdict: () => memoryForgetVerdict,
@@ -139,6 +141,9 @@ __export(src_exports, {
   publishAgentSkillsResolved: () => publishAgentSkillsResolved,
   publishAgentToolCall: () => publishAgentToolCall,
   publishAgentToolRetry: () => publishAgentToolRetry,
+  questionOptions: () => questionOptions,
+  readElicitationInput: () => readElicitationInput,
+  readElicitationQuestions: () => readElicitationQuestions,
   releaseGatedFrames: () => releaseGatedFrames,
   rememberInputSchema: () => rememberInputSchema,
   rememberToolDefinition: () => rememberToolDefinition,
@@ -169,6 +174,8 @@ __export(src_exports, {
   traceLlmTurn: () => traceLlmTurn,
   traceToolExecution: () => traceToolExecution,
   truncateDetailContent: () => truncateDetailContent,
+  validateElicitationAnswer: () => validateElicitationAnswer,
+  validateElicitationValue: () => validateElicitationValue,
   validateStructured: () => validateStructured,
   windowHistory: () => windowHistory,
   withAskTool: () => withAskTool,
@@ -1010,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(optionValues, "optionValues");
+__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(readElicitationQuestions, "readElicitationQuestions");
+
+// src/elicitation.ts
 function normalizeElicitationReply(reply) {
   if (typeof reply !== "object" || reply === null) {
     return {
@@ -1050,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 {
@@ -1072,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:";
@@ -1138,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"
@@ -1146,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",
@@ -1156,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,
@@ -1175,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
@@ -1203,9 +1480,7 @@ var ASK_JSON_SCHEMA = {
         additionalProperties: false,
         required: [
           "id",
-          "prompt",
-          "options",
-          "defaults"
+          "prompt"
         ],
         properties: {
           id: {
@@ -1215,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."
@@ -1229,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",
@@ -4309,6 +4628,7 @@ __name(runAgentLoop, "runAgentLoop");
   DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS,
   DefaultApprovalPolicy,
   DefaultRolesPolicy,
+  ELICITATION_INPUT_TYPES,
   GLOBAL_SCOPE,
   MAX_ASK_QUESTIONS,
   OutputRejectedError,
@@ -4364,6 +4684,7 @@ __name(runAgentLoop, "runAgentLoop");
   isReplayIntegrityError,
   isToolEnabled,
   isTransientToolError,
+  isTypedQuestion,
   loadSkill,
   mayDecideApproval,
   memoryForgetVerdict,
@@ -4385,6 +4706,9 @@ __name(runAgentLoop, "runAgentLoop");
   publishAgentSkillsResolved,
   publishAgentToolCall,
   publishAgentToolRetry,
+  questionOptions,
+  readElicitationInput,
+  readElicitationQuestions,
   releaseGatedFrames,
   rememberInputSchema,
   rememberToolDefinition,
@@ -4415,6 +4739,8 @@ __name(runAgentLoop, "runAgentLoop");
   traceLlmTurn,
   traceToolExecution,
   truncateDetailContent,
+  validateElicitationAnswer,
+  validateElicitationValue,
   validateStructured,
   windowHistory,
   withAskTool,