@elizaos/plugin-form 2.0.0-alpha.1 → 2.0.0-alpha.11

package/dist/chunk-XHECCAUT.js

@@ -0,0 +1,544 @@
+import {
+  getTypeHandler,
+  parseValue,
+  validateField
+} from "./chunk-ARWZY3NX.js";
+import {
+  quickIntentDetect
+} from "./chunk-YTWANJ3R.js";
+import {
+  buildTemplateValues,
+  resolveControlTemplates
+} from "./chunk-WY4WK3HD.js";
+
+// src/evaluators/extractor.ts
+import { logger } from "@elizaos/core";
+
+// src/extraction.ts
+import { ModelType, parseKeyValueXml } from "@elizaos/core";
+async function llmIntentAndExtract(runtime, text, form, controls, templateValues) {
+  const resolvedControls = templateValues ? controls.map((control) => resolveControlTemplates(control, templateValues)) : controls;
+  const fieldsDescription = resolvedControls.filter((c) => !c.hidden).map((c) => {
+    const handler = getTypeHandler(c.type);
+    const typeHint = handler?.extractionPrompt || c.type;
+    const hints = c.extractHints?.join(", ") || "";
+    const options = c.options?.map((o) => o.value).join(", ") || "";
+    return `- ${c.key} (${c.label}): ${c.description || typeHint}${hints ? ` [hints: ${hints}]` : ""}${options ? ` [options: ${options}]` : ""}`;
+  }).join("\n");
+  const prompt = `You are extracting structured data from a user's natural language message.
+
+FORM: ${form.name}
+${form.description ? `DESCRIPTION: ${form.description}` : ""}
+
+FIELDS TO EXTRACT:
+${fieldsDescription}
+
+USER MESSAGE:
+"${text}"
+
+INSTRUCTIONS:
+1. Determine the user's intent:
+   - fill_form: They are providing information for form fields
+   - submit: They want to submit/complete the form ("done", "submit", "finish", "that's all")
+   - stash: They want to save for later ("save for later", "pause", "hold on")
+   - restore: They want to resume a saved form ("resume", "continue", "pick up where")
+   - cancel: They want to cancel ("cancel", "abort", "nevermind", "forget it")
+   - undo: They want to undo last change ("undo", "go back", "wait no")
+   - skip: They want to skip current field ("skip", "pass", "don't know")
+   - explain: They want explanation ("why?", "what's that for?")
+   - example: They want an example ("example?", "like what?")
+   - progress: They want progress update ("how far?", "status")
+   - autofill: They want to use saved values ("same as last time")
+   - other: None of the above
+
+2. For fill_form intent, extract all field values mentioned.
+   - For each extracted value, provide a confidence score (0.0-1.0)
+   - Note if this appears to be a correction to a previous value
+
+Respond using TOON like this:
+intent: fill_form, submit, stash, restore, cancel, undo, skip, explain, example, progress, autofill, or other
+extractions[N]{key,value,confidence,reasoning,is_correction}:
+  field_key,extracted_value,0.9,why this value,false
+
+Example:
+intent: fill_form
+extractions[2]{key,value,confidence,reasoning,is_correction}:
+  name,Jane Doe,0.95,User said their name is Jane,false
+  email,jane@example.com,0.9,Email mentioned in message,false
+
+IMPORTANT: Your response must ONLY contain the TOON document above. No preamble or explanation.`;
+  try {
+    const response = await runtime.useModel(ModelType.TEXT_SMALL, {
+      prompt,
+      temperature: 0.1
+    });
+    const parsed = parseExtractionResponse(response);
+    for (const extraction of parsed.extractions) {
+      const control = resolvedControls.find((c) => c.key === extraction.field);
+      if (control) {
+        if (typeof extraction.value === "string") {
+          extraction.value = parseValue(extraction.value, control);
+        }
+        const validation = validateField(extraction.value, control);
+        if (!validation.valid) {
+          extraction.confidence = Math.min(extraction.confidence, 0.3);
+          extraction.reasoning = `${extraction.reasoning || ""} (Validation failed: ${validation.error})`;
+        }
+      }
+    }
+    if (form.debug) {
+      runtime.logger.debug("[FormExtraction] LLM extraction result:", JSON.stringify(parsed));
+    }
+    return parsed;
+  } catch (error) {
+    runtime.logger.error("[FormExtraction] LLM extraction failed:", String(error));
+    return { intent: "other", extractions: [] };
+  }
+}
+function parseExtractionResponse(response) {
+  const result = {
+    intent: "other",
+    extractions: []
+  };
+  try {
+    const parsed = parseKeyValueXml(response);
+    if (parsed) {
+      const intentStr = parsed.intent?.toLowerCase() ?? "other";
+      result.intent = isValidIntent(intentStr) ? intentStr : "other";
+      if (parsed.extractions) {
+        const fields = Array.isArray(parsed.extractions) ? parsed.extractions : parsed.extractions.field ? Array.isArray(parsed.extractions.field) ? parsed.extractions.field : [parsed.extractions.field] : [];
+        for (const field of fields) {
+          if (field?.key) {
+            const extraction = {
+              field: String(field.key),
+              value: field.value ?? null,
+              confidence: parseFloat(String(field.confidence ?? "")) || 0.5,
+              reasoning: field.reasoning ? String(field.reasoning) : void 0,
+              isCorrection: field.is_correction === "true" || field.is_correction === true
+            };
+            result.extractions.push(extraction);
+          }
+        }
+      }
+    }
+  } catch (_error) {
+    const intentMatch = response.match(/<intent>([^<]+)<\/intent>/);
+    if (intentMatch) {
+      const intentStr = intentMatch[1].toLowerCase().trim();
+      result.intent = isValidIntent(intentStr) ? intentStr : "other";
+    }
+    const fieldMatches = response.matchAll(
+      /<field>\s*<key>([^<]+)<\/key>\s*<value>([^<]*)<\/value>\s*<confidence>([^<]+)<\/confidence>/g
+    );
+    for (const match of fieldMatches) {
+      result.extractions.push({
+        field: match[1].trim(),
+        value: match[2].trim(),
+        confidence: parseFloat(match[3]) || 0.5
+      });
+    }
+  }
+  return result;
+}
+function isValidIntent(str) {
+  const validIntents = [
+    "fill_form",
+    "submit",
+    "stash",
+    "restore",
+    "cancel",
+    "undo",
+    "skip",
+    "explain",
+    "example",
+    "progress",
+    "autofill",
+    "other"
+  ];
+  return validIntents.includes(str);
+}
+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 the ${resolvedControl.label} (${typeHint}) from this message:
+
+"${text}"
+
+${resolvedControl.description ? `Context: ${resolvedControl.description}` : ""}
+${resolvedControl.extractHints?.length ? `Look for: ${resolvedControl.extractHints.join(", ")}` : ""}
+${resolvedControl.options?.length ? `Valid options: ${resolvedControl.options.map((o) => o.value).join(", ")}` : ""}
+${resolvedControl.example ? `Example: ${resolvedControl.example}` : ""}
+
+Respond using TOON like this:
+found: true or false
+value: extracted value or empty if not found
+confidence: 0.0 to 1.0
+reasoning: brief explanation
+
+IMPORTANT: Your response must ONLY contain the TOON document above. No preamble or explanation.`;
+  try {
+    const response = await runtime.useModel(ModelType.TEXT_SMALL, {
+      prompt,
+      temperature: 0.1
+    });
+    const parsed = parseKeyValueXml(response);
+    const found = parsed?.found === true || parsed?.found === "true";
+    if (found) {
+      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;
+    }
+    return null;
+  } catch (error) {
+    runtime.logger.error("[FormExtraction] Single field extraction failed:", String(error));
+    return null;
+  }
+}
+async function detectCorrection(runtime, text, currentValues, controls, templateValues) {
+  const resolvedControls = templateValues ? controls.map((control) => resolveControlTemplates(control, templateValues)) : controls;
+  const currentValuesStr = resolvedControls.filter((c) => currentValues[c.key] !== void 0).map((c) => `- ${c.label}: ${currentValues[c.key]}`).join("\n");
+  if (!currentValuesStr) {
+    return [];
+  }
+  const prompt = `Is the user correcting any of these previously provided values?
+
+Current values:
+${currentValuesStr}
+
+User message:
+"${text}"
+
+If they are correcting a value, extract the new value. Otherwise respond with no corrections.
+
+Respond using TOON like this:
+has_correction: true or false
+corrections[N]{field,old_value,new_value,confidence}:
+  field_label,previous value,corrected value,0.9
+
+If no corrections:
+has_correction: false
+
+IMPORTANT: Your response must ONLY contain the TOON document above. No preamble or explanation.`;
+  try {
+    const response = await runtime.useModel(ModelType.TEXT_SMALL, {
+      prompt,
+      temperature: 0.1
+    });
+    const parsed = parseKeyValueXml(response);
+    const hasCorrection = parsed?.has_correction === true || parsed?.has_correction === "true";
+    if (parsed && hasCorrection && parsed.corrections) {
+      const corrections = [];
+      const correctionList = Array.isArray(parsed.corrections) ? parsed.corrections : parsed.corrections.correction ? Array.isArray(parsed.corrections.correction) ? parsed.corrections.correction : [parsed.corrections.correction] : [];
+      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) {
+          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 ?? ""));
+          const extraction = {
+            field: control.key,
+            value: value ?? null,
+            confidence: Number.isFinite(confidence) ? confidence : 0.8,
+            isCorrection: true
+          };
+          corrections.push(extraction);
+        }
+      }
+      return corrections;
+    }
+    return [];
+  } catch (error) {
+    runtime.logger.error("[FormExtraction] Correction detection failed:", String(error));
+    return [];
+  }
+}
+
+// src/evaluators/extractor.ts
+var formEvaluator = {
+  name: "form_evaluator",
+  description: "Extracts form fields and handles form intents from user messages",
+  similes: ["FORM_EXTRACTION", "FORM_HANDLER"],
+  examples: [],
+  // No examples needed for evaluators
+  /**
+   * Validate: Should this evaluator run?
+   *
+   * Only runs if there's an active form session OR stashed sessions
+   * (to handle restore intent).
+   *
+   * WHY check stashed:
+   * - User might say "resume my form"
+   * - Need to detect restore intent even without active session
+   * - Note: Actual restore is handled by FORM_RESTORE action
+   *
+   * @returns true if evaluator should run
+   */
+  validate: async (runtime, message, _state) => {
+    try {
+      const formService = runtime.getService("FORM");
+      if (!formService) return false;
+      const entityId = message.entityId;
+      const roomId = message.roomId;
+      if (!entityId || !roomId) return false;
+      const session = await formService.getActiveSession(entityId, roomId);
+      const stashed = await formService.getStashedSessions(entityId);
+      return session !== null || stashed.length > 0;
+    } catch (error) {
+      logger.error("[FormEvaluator] Validation error:", String(error));
+      return false;
+    }
+  },
+  /**
+   * Handler: Process the message and update form state.
+   *
+   * This is the main logic loop:
+   * 1. Try fast-path intent detection
+   * 2. Fall back to LLM if no match
+   * 3. Handle the detected intent
+   * 4. Process any field extractions
+   *
+   * @param runtime - Agent runtime for service access
+   * @param message - The user message to process
+   * @param state - Current agent state (optional)
+   */
+  handler: async (runtime, message, _state) => {
+    try {
+      const formService = runtime.getService("FORM");
+      if (!formService) return void 0;
+      const entityId = message.entityId;
+      const roomId = message.roomId;
+      const text = message.content?.text || "";
+      if (!entityId || !roomId) return void 0;
+      if (!text.trim()) return void 0;
+      let session = await formService.getActiveSession(entityId, roomId);
+      let intent = quickIntentDetect(text);
+      let extractions = [];
+      if (intent === "restore" && !session) {
+        logger.debug("[FormEvaluator] Restore intent detected, deferring to action");
+        return void 0;
+      }
+      if (!session) {
+        return void 0;
+      }
+      const form = formService.getForm(session.formId);
+      if (!form) {
+        logger.warn("[FormEvaluator] Form not found for session:", session.formId);
+        return void 0;
+      }
+      const templateValues = buildTemplateValues(session);
+      if (!intent) {
+        const result = await llmIntentAndExtract(
+          runtime,
+          text,
+          form,
+          form.controls,
+          templateValues
+        );
+        intent = result.intent;
+        extractions = result.extractions;
+        if (form.debug) {
+          logger.debug(
+            "[FormEvaluator] LLM extraction result:",
+            JSON.stringify({ intent, extractions })
+          );
+        }
+      }
+      switch (intent) {
+        // --- Lifecycle Intents ---
+        case "submit":
+          await handleSubmit(formService, session, entityId);
+          break;
+        case "stash":
+          await formService.stash(session.id, entityId);
+          break;
+        case "cancel":
+          await formService.cancel(session.id, entityId);
+          break;
+        // --- UX Intents ---
+        case "undo":
+          await handleUndo(formService, session, entityId, form);
+          break;
+        case "skip":
+          await handleSkip(formService, session, entityId, form);
+          break;
+        case "autofill":
+          await formService.applyAutofill(session);
+          break;
+        // --- Info Intents ---
+        // These don't change state - the provider gives context for response
+        case "explain":
+        case "example":
+        case "progress":
+          logger.debug(`[FormEvaluator] Info intent: ${intent}`);
+          break;
+        // --- Special Cases ---
+        case "restore":
+          logger.debug("[FormEvaluator] Restore intent - deferring to action");
+          break;
+        default:
+          await processExtractions(
+            runtime,
+            formService,
+            session,
+            form,
+            entityId,
+            extractions,
+            message.id
+          );
+          break;
+      }
+      session = await formService.getActiveSession(entityId, roomId);
+      if (session) {
+        session.lastMessageId = message.id;
+        await formService.saveSession(session);
+      }
+    } catch (error) {
+      logger.error("[FormEvaluator] Handler error:", String(error));
+      return void 0;
+    }
+    return void 0;
+  }
+};
+async function processExtractions(runtime, formService, session, form, entityId, extractions, messageId) {
+  const updatedParents = /* @__PURE__ */ new Set();
+  for (const extraction of extractions) {
+    if (extraction.field.includes(".")) {
+      const [parentKey, subKey] = extraction.field.split(".");
+      await formService.updateSubField(
+        session.id,
+        entityId,
+        parentKey,
+        subKey,
+        extraction.value,
+        extraction.confidence,
+        messageId
+      );
+      await emitEvent(runtime, "FORM_SUBFIELD_UPDATED", {
+        sessionId: session.id,
+        parentField: parentKey,
+        subField: subKey,
+        value: extraction.value,
+        confidence: extraction.confidence
+      });
+      updatedParents.add(parentKey);
+      if (form.debug) {
+        logger.debug(`[FormEvaluator] Updated subfield ${parentKey}.${subKey}`);
+      }
+    } else {
+      await formService.updateField(
+        session.id,
+        entityId,
+        extraction.field,
+        extraction.value,
+        extraction.confidence,
+        extraction.isCorrection ? "correction" : "extraction",
+        messageId
+      );
+      await emitEvent(runtime, "FORM_FIELD_EXTRACTED", {
+        sessionId: session.id,
+        field: extraction.field,
+        value: extraction.value,
+        confidence: extraction.confidence
+      });
+      if (form.debug) {
+        logger.debug(`[FormEvaluator] Updated field ${extraction.field}`);
+      }
+    }
+  }
+  for (const parentKey of updatedParents) {
+    await checkAndActivateExternalField(runtime, formService, session, form, entityId, parentKey);
+  }
+}
+async function checkAndActivateExternalField(runtime, formService, session, form, entityId, field) {
+  const freshSession = await formService.getActiveSession(entityId, session.roomId);
+  if (!freshSession) return;
+  if (!formService.isExternalType(form.controls.find((c) => c.key === field)?.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
+  });
+  logger.debug(`[FormEvaluator] All subcontrols filled for ${field}, activating...`);
+  try {
+    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}`);
+  } catch (error) {
+    logger.error(`[FormEvaluator] Failed to activate external field ${field}:`, String(error));
+  }
+}
+async function emitEvent(runtime, eventType, payload) {
+  try {
+    if (typeof runtime.emitEvent === "function") {
+      const eventPayload = { runtime, ...payload };
+      await runtime.emitEvent(eventType, eventPayload);
+    }
+  } catch (error) {
+    logger.debug(`[FormEvaluator] Event emission (${eventType}):`, String(error));
+  }
+}
+async function handleSubmit(formService, session, entityId) {
+  try {
+    await formService.submit(session.id, entityId);
+  } catch (error) {
+    logger.debug("[FormEvaluator] Submit failed:", String(error));
+  }
+}
+async function handleUndo(formService, session, entityId, form) {
+  if (!form.ux?.allowUndo) {
+    return;
+  }
+  const result = await formService.undoLastChange(session.id, entityId);
+  if (result) {
+    logger.debug("[FormEvaluator] Undid field:", result.field);
+  }
+}
+async function handleSkip(formService, session, entityId, form) {
+  if (!form.ux?.allowSkip) {
+    return;
+  }
+  if (session.lastAskedField) {
+    const skipped = await formService.skipField(session.id, entityId, session.lastAskedField);
+    if (skipped) {
+      logger.debug("[FormEvaluator] Skipped field:", session.lastAskedField);
+    }
+  }
+}
+var extractor_default = formEvaluator;
+
+export {
+  llmIntentAndExtract,
+  extractSingleField,
+  detectCorrection,
+  formEvaluator,
+  extractor_default
+};

package/dist/chunk-YTWANJ3R.js

@@ -0,0 +1,64 @@
+// src/intent.ts
+function quickIntentDetect(text) {
+  const lower = text.toLowerCase().trim();
+  if (lower.length < 2) {
+    return null;
+  }
+  if (/\b(resume|continue|pick up where|go back to|get back to)\b/.test(lower)) {
+    return "restore";
+  }
+  if (/\b(submit|done|finish|send it|that'?s all|i'?m done|complete|all set)\b/.test(lower)) {
+    return "submit";
+  }
+  if (/\b(save|stash|later|hold on|pause|save for later|come back|save this)\b/.test(lower)) {
+    if (!/\b(save and submit|save and send)\b/.test(lower)) {
+      return "stash";
+    }
+  }
+  if (/\b(cancel|abort|nevermind|never mind|forget it|stop|quit|exit)\b/.test(lower)) {
+    return "cancel";
+  }
+  if (/\b(undo|go back|wait no|change that|oops|that'?s wrong|wrong|not right)\b/.test(lower)) {
+    return "undo";
+  }
+  if (/\b(skip|pass|don'?t know|next one|next|don'?t have|no idea)\b/.test(lower)) {
+    if (!/\bskip to\b/.test(lower)) {
+      return "skip";
+    }
+  }
+  if (/\b(why|what'?s that for|explain|what do you mean|what is|purpose|reason)\b\??$/i.test(lower)) {
+    return "explain";
+  }
+  if (/^why\??$/i.test(lower)) {
+    return "explain";
+  }
+  if (/\b(example|like what|show me|such as|for instance|sample)\b\??$/i.test(lower)) {
+    return "example";
+  }
+  if (/^(example|e\.?g\.?)\??$/i.test(lower)) {
+    return "example";
+  }
+  if (/\b(how far|how many left|progress|status|how much more|where are we)\b/.test(lower)) {
+    return "progress";
+  }
+  if (/\b(same as|last time|use my usual|like before|previous|from before)\b/.test(lower)) {
+    return "autofill";
+  }
+  return null;
+}
+function isLifecycleIntent(intent) {
+  return ["submit", "stash", "restore", "cancel"].includes(intent);
+}
+function isUXIntent(intent) {
+  return ["undo", "skip", "explain", "example", "progress", "autofill"].includes(intent);
+}
+function hasDataToExtract(intent) {
+  return intent === "fill_form" || intent === "other";
+}
+
+export {
+  quickIntentDetect,
+  isLifecycleIntent,
+  isUXIntent,
+  hasDataToExtract
+};

package/dist/context-MHPFYZZ2.js

@@ -0,0 +1,9 @@
+import {
+  context_default,
+  formContextProvider
+} from "./chunk-4B5QLNVA.js";
+import "./chunk-WY4WK3HD.js";
+export {
+  context_default as default,
+  formContextProvider
+};

package/dist/extractor-UWASKXKD.js

@@ -0,0 +1,11 @@
+import {
+  extractor_default,
+  formEvaluator
+} from "./chunk-XHECCAUT.js";
+import "./chunk-ARWZY3NX.js";
+import "./chunk-YTWANJ3R.js";
+import "./chunk-WY4WK3HD.js";
+export {
+  extractor_default as default,
+  formEvaluator
+};