@elizaos/plugin-form 2.0.3-beta.5 → 2.0.3-beta.7

package/dist/evaluators/extractor.js

@@ -0,0 +1,251 @@
+import { EvaluatorPriority, logger } from "@elizaos/core";
+import {
+  buildFormExtractorPromptSection,
+  buildFormExtractorSchema,
+  coerceExtractionsAgainstControls,
+  parseFormExtractorOutput
+} from "../extraction.js";
+import { buildTemplateValues } from "../template.js";
+async function emitEvent(runtime, eventType, payload) {
+  if (typeof runtime.emitEvent !== "function") return;
+  const eventPayload = { runtime, ...payload };
+  await runtime.emitEvent(eventType, eventPayload);
+}
+async function checkAndActivateExternalField(runtime, formService, session, form, entityId, field) {
+  const freshSession = await formService.getActiveSession(
+    entityId,
+    session.roomId
+  );
+  if (!freshSession) return;
+  const control = form.controls.find((c) => c.key === field);
+  if (!control || !formService.isExternalType(control.type)) return;
+  if (!formService.areSubFieldsFilled(freshSession, field)) return;
+  const subValues = formService.getSubFieldValues(freshSession, field);
+  await emitEvent(runtime, "FORM_SUBCONTROLS_FILLED", {
+    sessionId: session.id,
+    field,
+    subValues
+  });
+  const activation = await formService.activateExternalField(
+    session.id,
+    entityId,
+    field
+  );
+  const activationPayload = JSON.parse(JSON.stringify(activation));
+  await emitEvent(runtime, "FORM_EXTERNAL_ACTIVATED", {
+    sessionId: session.id,
+    field,
+    activation: activationPayload
+  });
+  logger.info(
+    `[FormEvaluator] Activated external field ${field}: ${activation.instructions}`
+  );
+}
+const formIntentProcessor = {
+  name: "formIntent",
+  priority: 100,
+  async process({ output, prepared, runtime: _runtime, message: _message }) {
+    const { formService, session, form, entityId } = prepared;
+    switch (output.formIntent) {
+      case "submit":
+        await formService.submit(session.id, entityId);
+        return { success: true, values: { formIntent: "submit" } };
+      case "stash":
+        await formService.stash(session.id, entityId);
+        return { success: true, values: { formIntent: "stash" } };
+      case "cancel":
+        await formService.cancel(session.id, entityId);
+        return { success: true, values: { formIntent: "cancel" } };
+      case "undo": {
+        if (!form.ux?.allowUndo) return void 0;
+        const result = await formService.undoLastChange(session.id, entityId);
+        return result ? {
+          success: true,
+          values: { formIntent: "undo", undid: result.field }
+        } : void 0;
+      }
+      case "skip": {
+        if (!form.ux?.allowSkip || !session.lastAskedField) return void 0;
+        const skipped = await formService.skipField(
+          session.id,
+          entityId,
+          session.lastAskedField
+        );
+        return skipped ? {
+          success: true,
+          values: { formIntent: "skip", skipped: session.lastAskedField }
+        } : void 0;
+      }
+      case "autofill":
+        await formService.applyAutofill(session);
+        return { success: true, values: { formIntent: "autofill" } };
+      case "explain":
+      case "example":
+      case "progress":
+        return { success: true, values: { formIntent: output.formIntent } };
+      case "restore":
+        return void 0;
+      default:
+        return void 0;
+    }
+  }
+};
+const formExtractionsProcessor = {
+  name: "formExtractions",
+  priority: 200,
+  async process({ output, prepared, runtime, message }) {
+    const { formService, session, form, entityId } = prepared;
+    if (output.formIntent !== "fill_form" && output.formIntent !== "other") {
+      const refreshed2 = await formService.getActiveSession(
+        entityId,
+        session.roomId
+      );
+      if (refreshed2) {
+        refreshed2.lastMessageId = message.id;
+        await formService.saveSession(refreshed2);
+      }
+      return void 0;
+    }
+    const updatedParents = /* @__PURE__ */ new Set();
+    const coerced = coerceExtractionsAgainstControls(
+      output.formExtractions,
+      form.controls,
+      prepared.templateValues
+    );
+    for (const extraction of coerced) {
+      if (extraction.field.includes(".")) {
+        const [parentKey, subKey] = extraction.field.split(".");
+        await formService.updateSubField(
+          session.id,
+          entityId,
+          parentKey,
+          subKey,
+          extraction.value,
+          extraction.confidence,
+          message.id
+        );
+        await emitEvent(runtime, "FORM_SUBFIELD_UPDATED", {
+          sessionId: session.id,
+          parentField: parentKey,
+          subField: subKey,
+          value: extraction.value,
+          confidence: extraction.confidence
+        });
+        updatedParents.add(parentKey);
+      } else {
+        await formService.updateField(
+          session.id,
+          entityId,
+          extraction.field,
+          extraction.value,
+          extraction.confidence,
+          extraction.isCorrection ? "correction" : "extraction",
+          message.id
+        );
+        await emitEvent(runtime, "FORM_FIELD_EXTRACTED", {
+          sessionId: session.id,
+          field: extraction.field,
+          value: extraction.value,
+          confidence: extraction.confidence
+        });
+      }
+    }
+    for (const parentKey of updatedParents) {
+      await checkAndActivateExternalField(
+        runtime,
+        formService,
+        session,
+        form,
+        entityId,
+        parentKey
+      );
+    }
+    const refreshed = await formService.getActiveSession(
+      entityId,
+      session.roomId
+    );
+    if (refreshed) {
+      refreshed.lastMessageId = message.id;
+      await formService.saveSession(refreshed);
+    }
+    return {
+      success: true,
+      values: {
+        extractionCount: output.formExtractions.length
+      }
+    };
+  }
+};
+const formEvaluator = {
+  name: "form_extractor",
+  description: "Extracts form values + lifecycle/UX intent from user message.",
+  similes: ["FORM_EXTRACTION", "FORM_HANDLER", "form_evaluator"],
+  // Run before reflection/memory so downstream evaluators see updated form state.
+  priority: EvaluatorPriority.FORM,
+  providers: ["RECENT_MESSAGES"],
+  schema: buildFormExtractorSchema(),
+  async shouldRun({ runtime, message }) {
+    const formService = runtime.getService("FORM");
+    if (!formService) return false;
+    const entityId = message.entityId;
+    const roomId = message.roomId;
+    if (!entityId || !roomId) return false;
+    const text = message.content?.text;
+    if (!text?.trim()) return false;
+    const session = await formService.getActiveSession(entityId, roomId);
+    if (session) return true;
+    const stashed = await formService.getStashedSessions(entityId);
+    return stashed.length > 0;
+  },
+  async prepare({ runtime, message }) {
+    const formService = runtime.getService("FORM");
+    if (!formService) {
+      throw new Error("FormService not found in prepare()");
+    }
+    const entityId = message.entityId;
+    const roomId = message.roomId;
+    const session = await formService.getActiveSession(entityId, roomId);
+    if (!session) {
+      throw new Error(
+        "Form evaluator prepared without an active session; FORM action=restore owns the stashed-only path"
+      );
+    }
+    const form = formService.getForm(session.formId);
+    if (!form) {
+      throw new Error(
+        `Form definition not found for session formId=${session.formId}`
+      );
+    }
+    return {
+      formService,
+      session,
+      form,
+      templateValues: buildTemplateValues(session),
+      entityId
+    };
+  },
+  prompt({ message, prepared }) {
+    const text = message.content?.text ?? "";
+    return buildFormExtractorPromptSection({
+      text,
+      form: prepared.form,
+      controls: prepared.form.controls,
+      templateValues: prepared.templateValues
+    });
+  },
+  parse(raw) {
+    const parsed = parseFormExtractorOutput(raw);
+    if (!parsed) return null;
+    return {
+      formIntent: parsed.intent,
+      formExtractions: parsed.extractions
+    };
+  },
+  processors: [formIntentProcessor, formExtractionsProcessor]
+};
+var extractor_default = formEvaluator;
+export {
+  extractor_default as default,
+  formEvaluator
+};
+//# sourceMappingURL=extractor.js.map

package/dist/evaluators/extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/evaluators/extractor.ts"],"sourcesContent":["/**\n * @module evaluators/extractor\n * @description Form post-turn evaluator that runs in the\n * EvaluatorService pass. Detects form intents (submit, stash, cancel, undo,\n * skip, autofill, info) and extracts field values from the user message,\n * then mutates session state accordingly.\n *\n * The 'restore' intent is handled by FORM action=restore (a planner Action)\n * so the restored form is in scope before the agent's response is generated.\n */\n\nimport type {\n  Evaluator,\n  EvaluatorProcessor,\n  EventPayload,\n  IAgentRuntime,\n  JsonValue,\n  UUID,\n} from \"@elizaos/core\";\nimport { EvaluatorPriority, logger } from \"@elizaos/core\";\nimport {\n  buildFormExtractorPromptSection,\n  buildFormExtractorSchema,\n  coerceExtractionsAgainstControls,\n  parseFormExtractorOutput,\n} from \"../extraction.js\";\nimport type { FormService } from \"../service.js\";\nimport { buildTemplateValues, type TemplateValues } from \"../template.js\";\nimport type {\n  ExtractionResult,\n  FormDefinition,\n  FormIntent,\n  FormSession,\n} from \"../types.js\";\n\ninterface FormExtractorOutput {\n  formIntent: FormIntent;\n  formExtractions: ExtractionResult[];\n}\n\ninterface FormExtractorPrepared {\n  formService: FormService;\n  session: FormSession;\n  form: FormDefinition;\n  templateValues: TemplateValues;\n  entityId: UUID;\n}\n\nasync function emitEvent(\n  runtime: IAgentRuntime,\n  eventType: string,\n  payload: Record<string, JsonValue>,\n): Promise<void> {\n  if (typeof runtime.emitEvent !== \"function\") return;\n  const eventPayload: EventPayload = { runtime, ...payload };\n  await runtime.emitEvent(eventType, eventPayload);\n}\n\nasync function checkAndActivateExternalField(\n  runtime: IAgentRuntime,\n  formService: FormService,\n  session: FormSession,\n  form: FormDefinition,\n  entityId: UUID,\n  field: string,\n): Promise<void> {\n  const freshSession = await formService.getActiveSession(\n    entityId,\n    session.roomId,\n  );\n  if (!freshSession) return;\n\n  const control = form.controls.find((c) => c.key === field);\n  if (!control || !formService.isExternalType(control.type)) return;\n  if (!formService.areSubFieldsFilled(freshSession, field)) return;\n\n  const subValues = formService.getSubFieldValues(freshSession, field);\n  await emitEvent(runtime, \"FORM_SUBCONTROLS_FILLED\", {\n    sessionId: session.id,\n    field,\n    subValues,\n  });\n\n  const activation = await formService.activateExternalField(\n    session.id,\n    entityId,\n    field,\n  );\n  const activationPayload = JSON.parse(JSON.stringify(activation)) as JsonValue;\n\n  await emitEvent(runtime, \"FORM_EXTERNAL_ACTIVATED\", {\n    sessionId: session.id,\n    field,\n    activation: activationPayload,\n  });\n\n  logger.info(\n    `[FormEvaluator] Activated external field ${field}: ${activation.instructions}`,\n  );\n}\n\nconst formIntentProcessor: EvaluatorProcessor<\n  FormExtractorOutput,\n  FormExtractorPrepared\n> = {\n  name: \"formIntent\",\n  priority: 100,\n  async process({ output, prepared, runtime: _runtime, message: _message }) {\n    const { formService, session, form, entityId } = prepared;\n\n    switch (output.formIntent) {\n      case \"submit\":\n        await formService.submit(session.id, entityId);\n        return { success: true, values: { formIntent: \"submit\" } };\n\n      case \"stash\":\n        await formService.stash(session.id, entityId);\n        return { success: true, values: { formIntent: \"stash\" } };\n\n      case \"cancel\":\n        await formService.cancel(session.id, entityId);\n        return { success: true, values: { formIntent: \"cancel\" } };\n\n      case \"undo\": {\n        if (!form.ux?.allowUndo) return undefined;\n        const result = await formService.undoLastChange(session.id, entityId);\n        return result\n          ? {\n              success: true,\n              values: { formIntent: \"undo\", undid: result.field },\n            }\n          : undefined;\n      }\n\n      case \"skip\": {\n        if (!form.ux?.allowSkip || !session.lastAskedField) return undefined;\n        const skipped = await formService.skipField(\n          session.id,\n          entityId,\n          session.lastAskedField,\n        );\n        return skipped\n          ? {\n              success: true,\n              values: { formIntent: \"skip\", skipped: session.lastAskedField },\n            }\n          : undefined;\n      }\n\n      case \"autofill\":\n        await formService.applyAutofill(session);\n        return { success: true, values: { formIntent: \"autofill\" } };\n\n      case \"explain\":\n      case \"example\":\n      case \"progress\":\n        return { success: true, values: { formIntent: output.formIntent } };\n\n      case \"restore\":\n        // FORM action=restore owns this path; nothing to do here.\n        return undefined;\n\n      default:\n        return undefined;\n    }\n  },\n};\n\nconst formExtractionsProcessor: EvaluatorProcessor<\n  FormExtractorOutput,\n  FormExtractorPrepared\n> = {\n  name: \"formExtractions\",\n  priority: 200,\n  async process({ output, prepared, runtime, message }) {\n    const { formService, session, form, entityId } = prepared;\n\n    // Lifecycle / UX intents shouldn't double-process extractions; only\n    // fill_form and `other` may carry inline data.\n    if (output.formIntent !== \"fill_form\" && output.formIntent !== \"other\") {\n      // Still update last-message tracking before bailing so deduplication works.\n      const refreshed = await formService.getActiveSession(\n        entityId,\n        session.roomId,\n      );\n      if (refreshed) {\n        refreshed.lastMessageId = message.id;\n        await formService.saveSession(refreshed);\n      }\n      return undefined;\n    }\n\n    const updatedParents = new Set<string>();\n    const coerced = coerceExtractionsAgainstControls(\n      output.formExtractions,\n      form.controls,\n      prepared.templateValues,\n    );\n\n    for (const extraction of coerced) {\n      if (extraction.field.includes(\".\")) {\n        const [parentKey, subKey] = extraction.field.split(\".\");\n        await formService.updateSubField(\n          session.id,\n          entityId,\n          parentKey,\n          subKey,\n          extraction.value,\n          extraction.confidence,\n          message.id,\n        );\n        await emitEvent(runtime, \"FORM_SUBFIELD_UPDATED\", {\n          sessionId: session.id,\n          parentField: parentKey,\n          subField: subKey,\n          value: extraction.value,\n          confidence: extraction.confidence,\n        });\n        updatedParents.add(parentKey);\n      } else {\n        await formService.updateField(\n          session.id,\n          entityId,\n          extraction.field,\n          extraction.value,\n          extraction.confidence,\n          extraction.isCorrection ? \"correction\" : \"extraction\",\n          message.id,\n        );\n        await emitEvent(runtime, \"FORM_FIELD_EXTRACTED\", {\n          sessionId: session.id,\n          field: extraction.field,\n          value: extraction.value,\n          confidence: extraction.confidence,\n        });\n      }\n    }\n\n    for (const parentKey of updatedParents) {\n      await checkAndActivateExternalField(\n        runtime,\n        formService,\n        session,\n        form,\n        entityId,\n        parentKey,\n      );\n    }\n\n    const refreshed = await formService.getActiveSession(\n      entityId,\n      session.roomId,\n    );\n    if (refreshed) {\n      refreshed.lastMessageId = message.id;\n      await formService.saveSession(refreshed);\n    }\n\n    return {\n      success: true,\n      values: {\n        extractionCount: output.formExtractions.length,\n      },\n    };\n  },\n};\n\nexport const formEvaluator: Evaluator<\n  FormExtractorOutput,\n  FormExtractorPrepared\n> = {\n  name: \"form_extractor\",\n  description: \"Extracts form values + lifecycle/UX intent from user message.\",\n  similes: [\"FORM_EXTRACTION\", \"FORM_HANDLER\", \"form_evaluator\"],\n  // Run before reflection/memory so downstream evaluators see updated form state.\n  priority: EvaluatorPriority.FORM,\n  providers: [\"RECENT_MESSAGES\"],\n  schema: buildFormExtractorSchema(),\n\n  async shouldRun({ runtime, message }) {\n    const formService = runtime.getService(\"FORM\") as FormService | null;\n    if (!formService) return false;\n\n    const entityId = message.entityId as UUID | undefined;\n    const roomId = message.roomId as UUID | undefined;\n    if (!entityId || !roomId) return false;\n\n    const text = message.content?.text;\n    if (!text?.trim()) return false;\n\n    const session = await formService.getActiveSession(entityId, roomId);\n    if (session) return true;\n\n    const stashed = await formService.getStashedSessions(entityId);\n    return stashed.length > 0;\n  },\n\n  async prepare({ runtime, message }) {\n    const formService = runtime.getService(\"FORM\") as FormService | null;\n    if (!formService) {\n      throw new Error(\"FormService not found in prepare()\");\n    }\n    const entityId = message.entityId as UUID;\n    const roomId = message.roomId as UUID;\n\n    const session = await formService.getActiveSession(entityId, roomId);\n    if (!session) {\n      // shouldRun gates this — only stashed-only state reaches here, in which\n      // case the evaluator section will produce an `other` intent and no\n      // extractions will be applied because there's no active session.\n      throw new Error(\n        \"Form evaluator prepared without an active session; FORM action=restore owns the stashed-only path\",\n      );\n    }\n\n    const form = formService.getForm(session.formId);\n    if (!form) {\n      throw new Error(\n        `Form definition not found for session formId=${session.formId}`,\n      );\n    }\n\n    return {\n      formService,\n      session,\n      form,\n      templateValues: buildTemplateValues(session),\n      entityId,\n    };\n  },\n\n  prompt({ message, prepared }) {\n    const text = message.content?.text ?? \"\";\n    return buildFormExtractorPromptSection({\n      text,\n      form: prepared.form,\n      controls: prepared.form.controls,\n      templateValues: prepared.templateValues,\n    });\n  },\n\n  parse(raw) {\n    const parsed = parseFormExtractorOutput(raw);\n    if (!parsed) return null;\n    return {\n      formIntent: parsed.intent,\n      formExtractions: parsed.extractions,\n    };\n  },\n\n  processors: [formIntentProcessor, formExtractionsProcessor],\n};\n\nexport default formEvaluator;\n"],"mappings":"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","names":["refreshed"]}

package/dist/extraction.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @module extraction
+ * @description LLM-based field extraction from natural language.
+ *
+ * Exposes prompt/schema/parse helpers consumed by the form Evaluator and
+ * runs the LLM call directly only for the targeted single-field and
+ * correction-detection helpers.
+ */
+import type { IAgentRuntime, JSONSchema, JsonValue } from "@elizaos/core";
+import type { TemplateValues } from "./template";
+import type { ExtractionResult, FormControl, FormDefinition, IntentResult } from "./types";
+/**
+ * Build the JSON Schema fragment for the form-extractor evaluator section.
+ *
+ * Returned shape:
+ *   { formIntent: <enum>, formExtractions: [{ field, value, confidence, isCorrection }] }
+ */
+export declare function buildFormExtractorSchema(): JSONSchema;
+/**
+ * Build the prompt section for the form-extractor evaluator.
+ *
+ * The evaluator prompt inlines this string and asks the model to
+ * populate `{ formIntent, formExtractions }` for the active form.
+ */
+export declare function buildFormExtractorPromptSection(params: {
+    text: string;
+    form: FormDefinition;
+    controls: FormControl[];
+    templateValues?: TemplateValues;
+}): string;
+/**
+ * Parse the raw `{ formIntent, formExtractions }` object produced by the
+ * evaluator pass into a typed `IntentResult`. Type coercion and
+ * validation against control rules happen later (in the processor) where
+ * the form definition is in scope.
+ */
+export declare function parseFormExtractorOutput(raw: unknown): IntentResult | null;
+/**
+ * Apply type coercion + validation to a parsed extractions list against the
+ * resolved form controls. Lowers confidence to 0.3 when a value fails the
+ * control's validator (so downstream confirmation flow kicks in).
+ */
+export declare function coerceExtractionsAgainstControls(extractions: ExtractionResult[], controls: FormControl[], templateValues?: TemplateValues): ExtractionResult[];
+/**
+ * Extract a specific field value from a user message with a focused prompt.
+ *
+ * Used when the agent has just asked for a specific field and expects a
+ * direct answer. Independent of the evaluator pass.
+ */
+export declare function extractSingleField(runtime: IAgentRuntime, text: string, control: FormControl, debug?: boolean, templateValues?: TemplateValues): Promise<ExtractionResult | null>;
+/**
+ * Detect whether the user is correcting a previously filled value.
+ */
+export declare function detectCorrection(runtime: IAgentRuntime, text: string, currentValues: Record<string, JsonValue>, controls: FormControl[], templateValues?: TemplateValues): Promise<ExtractionResult[]>;
+//# sourceMappingURL=extraction.d.ts.map

package/dist/extraction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extraction.d.ts","sourceRoot":"","sources":["../src/extraction.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,cAAc,EAEd,YAAY,EACb,MAAM,SAAS,CAAC;AAoGjB;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,UAAU,CA2BrD;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,EAAE;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC,GAAG,MAAM,CAsDT;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,GAAG,IAAI,CA8C1E;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,CAC9C,WAAW,EAAE,gBAAgB,EAAE,EAC/B,QAAQ,EAAE,WAAW,EAAE,EACvB,cAAc,CAAC,EAAE,cAAc,GAC9B,gBAAgB,EAAE,CA2CpB;AAMD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,WAAW,EACpB,KAAK,CAAC,EAAE,OAAO,EACf,cAAc,CAAC,EAAE,cAAc,GAC9B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAsElC;AAMD;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,EACxC,QAAQ,EAAE,WAAW,EAAE,EACvB,cAAc,CAAC,EAAE,cAAc,GAC9B,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAiG7B"}

package/dist/extraction.js

@@ -0,0 +1,347 @@
+import { ModelType } from "@elizaos/core";
+import { resolveControlTemplates } from "./template.js";
+import { getTypeHandler, parseValue, validateField } from "./validation.js";
+const FORM_INTENTS = [
+  "fill_form",
+  "submit",
+  "stash",
+  "restore",
+  "cancel",
+  "undo",
+  "skip",
+  "explain",
+  "example",
+  "progress",
+  "autofill",
+  "other"
+];
+const UNSAFE_OBJECT_KEYS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+const INTENT_MEANINGS = {
+  fill_form: "user is providing field values",
+  submit: "user wants to submit or finish the form",
+  stash: "user wants to save or pause the form for later",
+  restore: "user wants to resume a saved form",
+  cancel: "user wants to cancel or abandon the form",
+  undo: "user wants to undo the last change",
+  skip: "user wants to skip the current field",
+  explain: "user wants an explanation",
+  example: "user wants an example value",
+  progress: "user wants a progress update",
+  autofill: "user wants to use saved values",
+  other: "none of the above"
+};
+function parseJsonObjectResponse(response) {
+  try {
+    const trimmed = response.trim();
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+    const candidate = (fenced?.[1] ?? trimmed).trim();
+    const firstBrace = candidate.indexOf("{");
+    const lastBrace = candidate.lastIndexOf("}");
+    if (firstBrace < 0 || lastBrace <= firstBrace) return null;
+    const parsed = JSON.parse(candidate.slice(firstBrace, lastBrace + 1));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function parseBoolean(value) {
+  return String(value ?? "").trim().toLowerCase() === "true";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isValidIntent(str) {
+  return FORM_INTENTS.includes(str);
+}
+function isSafeExtractionField(field) {
+  return field.split(".").every((part) => part.length > 0 && !UNSAFE_OBJECT_KEYS.has(part));
+}
+function buildFormExtractorSchema() {
+  return {
+    type: "object",
+    properties: {
+      formIntent: {
+        type: "string",
+        enum: [...FORM_INTENTS]
+      },
+      formExtractions: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            field: { type: "string" },
+            value: {},
+            confidence: { type: "number" },
+            isCorrection: { type: "boolean" },
+            reasoning: { type: "string" }
+          },
+          required: ["field", "confidence"],
+          additionalProperties: false
+        }
+      }
+    },
+    required: ["formIntent", "formExtractions"],
+    additionalProperties: false
+  };
+}
+function buildFormExtractorPromptSection(params) {
+  const { text, form, controls, templateValues } = params;
+  const resolvedControls = templateValues ? controls.map(
+    (control) => resolveControlTemplates(control, templateValues)
+  ) : controls;
+  const visibleControls = resolvedControls.filter((c) => !c.hidden);
+  const fieldsDescription = visibleControls.map((c) => {
+    const handler = getTypeHandler(c.type);
+    const typeHint = handler?.extractionPrompt || c.type;
+    return {
+      key: c.key,
+      label: c.label,
+      type: typeHint,
+      description: c.description || typeHint,
+      hints: c.extractHints ?? [],
+      options: c.options?.map((o) => o.value) ?? []
+    };
+  });
+  return `Extract active form intent + field values.
+
+Context JSON:
+${JSON.stringify(
+    {
+      form: {
+        name: form.name,
+        description: form.description
+      },
+      fields: fieldsDescription,
+      user_message: text,
+      intent_options: FORM_INTENTS,
+      intent_meanings: INTENT_MEANINGS
+    },
+    null,
+    2
+  )}
+
+Return:
+{
+  "formIntent": "one of intent_options",
+  "formExtractions": [
+    { "field": "<key>", "value": <extracted>, "confidence": 0.0-1.0, "isCorrection": false, "reasoning": "brief" }
+  ]
+}
+
+Rules:
+- Choose exactly one intent.
+- fill_form: extract every mentioned field value.
+- No fields -> formExtractions=[].
+- confidence 0.0-1.0.`;
+}
+function parseFormExtractorOutput(raw) {
+  if (!isRecord(raw)) return null;
+  const intentStr = typeof raw.formIntent === "string" ? raw.formIntent.toLowerCase() : "other";
+  const intent = isValidIntent(intentStr) ? intentStr : "other";
+  const rawExtractions = Array.isArray(raw.formExtractions) ? raw.formExtractions : [];
+  const extractions = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of rawExtractions) {
+    if (!isRecord(entry)) continue;
+    const fieldKey = typeof entry.field === "string" ? entry.field : "";
+    if (!fieldKey) continue;
+    if (!isSafeExtractionField(fieldKey)) continue;
+    const dedupeKey = `${fieldKey}\0${String(entry.value ?? "")}`;
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    const value = entry.value ?? null;
+    let confidence = typeof entry.confidence === "number" ? entry.confidence : parseFloat(String(entry.confidence ?? ""));
+    if (!Number.isFinite(confidence)) confidence = 0.5;
+    confidence = Math.max(0, Math.min(1, confidence));
+    const reasoning = typeof entry.reasoning === "string" ? entry.reasoning : void 0;
+    extractions.push({
+      field: fieldKey,
+      value,
+      confidence,
+      reasoning,
+      isCorrection: parseBoolean(entry.isCorrection)
+    });
+  }
+  return { intent, extractions };
+}
+function coerceExtractionsAgainstControls(extractions, controls, templateValues) {
+  const resolvedControls = templateValues ? controls.map(
+    (control) => resolveControlTemplates(control, templateValues)
+  ) : controls;
+  const controlsByKey = new Map(
+    resolvedControls.map((control) => [control.key, control])
+  );
+  return extractions.flatMap((extraction) => {
+    if (extraction.field.includes(".")) {
+      const [parentKey, subKey, ...extraParts] = extraction.field.split(".");
+      if (extraParts.length > 0 || !parentKey || !subKey) return [];
+      if (!controlsByKey.has(parentKey)) return [];
+      return [extraction];
+    }
+    const control = controlsByKey.get(extraction.field);
+    if (!control) return [];
+    let value = extraction.value;
+    if (typeof value === "string") {
+      value = parseValue(value, control);
+    }
+    const validation = validateField(value, control);
+    if (!validation.valid) {
+      const reasoning = `${extraction.reasoning ?? ""} (Validation failed: ${validation.error})`.trim();
+      return [
+        {
+          ...extraction,
+          value,
+          confidence: Math.min(extraction.confidence, 0.3),
+          reasoning
+        }
+      ];
+    }
+    return [{ ...extraction, value }];
+  });
+}
+async function extractSingleField(runtime, text, control, debug, templateValues) {
+  const resolvedControl = templateValues ? resolveControlTemplates(control, templateValues) : control;
+  const handler = getTypeHandler(resolvedControl.type);
+  const typeHint = handler?.extractionPrompt || resolvedControl.type;
+  const prompt = `Extract a single form field value from the user message.
+
+Context JSON:
+${JSON.stringify(
+    {
+      field: {
+        key: resolvedControl.key,
+        label: resolvedControl.label,
+        type: typeHint,
+        description: resolvedControl.description,
+        hints: resolvedControl.extractHints ?? [],
+        options: resolvedControl.options?.map((o) => o.value) ?? [],
+        example: resolvedControl.example
+      },
+      user_message: text
+    },
+    null,
+    2
+  )}
+
+Return only a valid JSON object with this schema:
+{
+  "found": true,
+  "value": "extracted value or null if not found",
+  "confidence": 0.95,
+  "reasoning": "brief explanation"
+}`;
+  const runModel = runtime.useModel.bind(runtime);
+  const response = await runModel(ModelType.TEXT_SMALL, {
+    prompt,
+    temperature: 0.1
+  });
+  const parsed = parseJsonObjectResponse(response);
+  const found = parsed?.found === true || parsed?.found === "true";
+  if (!found || !parsed) return null;
+  let value = parsed.value;
+  if (typeof value === "string") {
+    value = parseValue(value, resolvedControl);
+  }
+  const confidence = typeof parsed.confidence === "number" ? parsed.confidence : parseFloat(String(parsed.confidence ?? ""));
+  const result = {
+    field: resolvedControl.key,
+    value: value ?? null,
+    confidence: Number.isFinite(confidence) ? confidence : 0.5,
+    reasoning: parsed.reasoning ? String(parsed.reasoning) : void 0
+  };
+  if (debug) {
+    runtime.logger.debug(
+      "[FormExtraction] Single field extraction:",
+      JSON.stringify(result)
+    );
+  }
+  return result;
+}
+async function detectCorrection(runtime, text, currentValues, controls, templateValues) {
+  const resolvedControls = templateValues ? controls.map(
+    (control) => resolveControlTemplates(control, templateValues)
+  ) : controls;
+  const currentValueEntries = resolvedControls.filter(
+    (c) => currentValues[c.key] !== void 0
+  );
+  if (currentValueEntries.length === 0) return [];
+  const currentValueRows = currentValueEntries.map((c) => ({
+    key: c.key,
+    label: c.label,
+    value: currentValues[c.key]
+  }));
+  const prompt = `Detect whether the user is correcting a previous form value.
+
+Context JSON:
+${JSON.stringify(
+    {
+      current_values: currentValueRows,
+      user_message: text
+    },
+    null,
+    2
+  )}
+
+Return only a valid JSON object with this schema:
+{
+  "has_correction": true,
+  "corrections": [
+    {
+      "field": "email",
+      "old_value": "old@example.com",
+      "new_value": "new@example.com",
+      "confidence": 0.9
+    }
+  ]
+}
+
+Rules:
+- Decide whether the user is correcting a previous value.
+- When correcting, extract the replacement value.
+- Use an empty corrections array when no corrections were found.`;
+  const runModel = runtime.useModel.bind(runtime);
+  const response = await runModel(ModelType.TEXT_SMALL, {
+    prompt,
+    temperature: 0.1
+  });
+  const parsed = parseJsonObjectResponse(response);
+  const hasCorrection = parsed?.has_correction === true || parsed?.has_correction === "true";
+  if (!parsed || !hasCorrection || !parsed.corrections) return [];
+  const corrections = [];
+  const correctionList = Array.isArray(parsed.corrections) ? parsed.corrections : [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const correction of correctionList) {
+    const fieldName = correction.field ? String(correction.field) : "";
+    const control = resolvedControls.find(
+      (c) => c.label.toLowerCase() === fieldName.toLowerCase() || c.key.toLowerCase() === fieldName.toLowerCase()
+    );
+    if (!control) continue;
+    const dedupeKey = `${control.key}\0${String(correction.new_value ?? "")}`;
+    if (seen.has(dedupeKey)) continue;
+    seen.add(dedupeKey);
+    let value = correction.new_value;
+    if (typeof value === "string") {
+      value = parseValue(value, control);
+    }
+    const confidence = typeof correction.confidence === "number" ? correction.confidence : parseFloat(String(correction.confidence ?? ""));
+    corrections.push({
+      field: control.key,
+      value: value ?? null,
+      confidence: Number.isFinite(confidence) ? confidence : 0.8,
+      isCorrection: true
+    });
+  }
+  return corrections;
+}
+export {
+  buildFormExtractorPromptSection,
+  buildFormExtractorSchema,
+  coerceExtractionsAgainstControls,
+  detectCorrection,
+  extractSingleField,
+  parseFormExtractorOutput
+};
+//# sourceMappingURL=extraction.js.map