@elizaos/plugin-form 2.0.0-alpha.9 → 2.0.3-beta.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# @elizaos/plugin-form
+
+Conversational forms for Eliza agents. Define structured data-collection workflows; the agent extracts values from natural conversation, tracks completion, and delivers a typed `FormSubmission` when all required fields are filled.
+
+## What it does
+
+- **Defines forms** — a `FormDefinition` describes the fields to collect (`FormControl[]`), lifecycle hooks, TTL settings, and UX rules (undo, skip, autofill).
+- **Tracks sessions** — one `FormSession` per user per room. Sessions survive topic changes and can be stashed and resumed later.
+- **Extracts field values via LLM** — the post-turn evaluator detects user intent and pulls values from conversational messages, handling uncertain extractions with a confirm step.
+- **Supports composite and external control types** — composite types (e.g. address) have subfields that must all fill before the parent is complete; external types (e.g. payment) await asynchronous confirmation from another service before marking the field filled.
+- **Effort-aware retention** — session TTL scales with how long the user has invested (default 14–90 days).
+
+## Capabilities added to an Eliza agent
+
+| Capability | How |
+|---|---|
+| FORM\_CONTEXT provider | Injects current form progress into every agent turn — filled/missing fields, uncertain extractions, pending external fields, and a single action directive |
+| FORM action | `action=restore` rehydrates the most recent stashed form before the agent responds. **Not auto-registered** — import `formAction` from `@elizaos/plugin-form` and add it to your consuming plugin's `actions` array to activate it. |
+| Form evaluator | Post-turn: detects submit / stash / cancel / undo / skip / autofill / fill\_form intents and updates session state |
+| FormService | Singleton service: register forms and custom control types, start/manage sessions, submit, stash, restore |
+
+## Installation
+
+Add the plugin to your agent character config:
+
+```json
+{
+  "plugins": ["@elizaos/plugin-form"],
+  "features": {
+    "form": true
+  }
+}
+```
+
+The plugin auto-enables when `config.features.form` is truthy (`true`, or an object whose `enabled` is not `false`). No environment variables are required.
+
+## Built-in field types
+
+`text`, `number`, `email`, `boolean`, `select`, `date`, `file`
+
+Custom types are registered at runtime via `FormService.registerControlType()`.
+
+## Registering a form (consuming plugin example)
+
+```typescript
+import type { FormDefinition } from '@elizaos/plugin-form';
+
+const onboardingForm: FormDefinition = {
+  id: 'onboard',
+  name: 'Onboarding',
+  controls: [
+    { key: 'name',  label: 'Full Name',  type: 'text',   required: true },
+    { key: 'email', label: 'Email',       type: 'email',  required: true },
+    { key: 'role',  label: 'Role',        type: 'select', required: false,
+      options: [{ value: 'dev', label: 'Developer' }, { value: 'pm', label: 'Product' }] },
+  ],
+  hooks: { onSubmit: 'handle_onboarding_submission' },
+};
+
+// In your plugin's start() or action handler:
+const formService = runtime.getService('FORM');
+formService.registerForm(onboardingForm);
+await formService.startSession('onboard', entityId, roomId);
+```
+
+Register a task worker to handle the submission:
+
+```typescript
+runtime.registerTaskWorker({
+  name: 'handle_onboarding_submission',
+  execute: async (runtime, { submission }) => {
+    // submission.values, submission.mappedValues, submission.entityId, etc.
+  },
+});
+```
+
+## Registering a custom control type
+
+```typescript
+// Simple type
+formService.registerControlType({
+  id: 'phone',
+  validate: (v) => ({ valid: /^\+?[\d\s-]{10,}$/.test(String(v)) }),
+  extractionPrompt: 'a phone number with country code',
+});
+
+// External type (async confirmation required)
+formService.registerControlType({
+  id: 'payment',
+  getSubControls: () => [
+    { key: 'amount',   type: 'number', label: 'Amount',   required: true },
+    { key: 'currency', type: 'select', label: 'Currency', required: true,
+      options: [{ value: 'SOL', label: 'SOL' }, { value: 'USDC', label: 'USDC' }] },
+  ],
+  activate: async (ctx) => {
+    // Return instructions and a reference for matching the external event
+    return { instructions: 'Send funds to ...', reference: 'memo-xyz', address: '...' };
+  },
+});
+```
+
+When all subfields are filled the evaluator automatically calls `activateExternalField()`. Your service calls `formService.confirmExternalField(sessionId, entityId, field, value, externalData)` when confirmation arrives.
+
+## FormDefinition reference (key fields)
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `id` | string | required | Unique form identifier |
+| `name` | string | required | Human-readable name |
+| `controls` | FormControl[] | required | Fields to collect |
+| `status` | `draft\|active\|deprecated` | `active` | Draft forms cannot be started |
+| `allowMultiple` | boolean | `false` | Allow multiple submissions per user |
+| `hooks.onStart/onSubmit/onCancel/onReady/onFieldChange/onExpire` | string | — | Task worker names |
+| `ttl.minDays` / `ttl.maxDays` | number | 14 / 90 | Retention bounds |
+| `ttl.effortMultiplier` | number | 0.5 | Extra days per minute of interaction |
+| `ux.allowUndo` / `allowSkip` / `allowAutofill` | boolean | all `true` | UX feature flags |
+| `nudge.afterInactiveHours` / `maxNudges` | number | 48 / 3 | Stale-session nudge config |
+
+## FormControl reference (key fields)
+
+| Field | Type | Description |
+|---|---|---|
+| `key` | string | Unique within form; used in `values` map |
+| `label` | string | Human-readable name |
+| `type` | string | `text`, `number`, `email`, `boolean`, `select`, `date`, `file`, or custom |
+| `required` | boolean | Form cannot submit without this field |
+| `sensitive` | boolean | Value masked in agent context |
+| `hidden` | boolean | Extract silently, never ask directly |
+| `askPrompt` | string | Custom agent prompt for this field |
+| `extractHints` | string[] | Keywords to improve LLM extraction accuracy |
+| `confirmThreshold` | number | Confidence below this triggers confirmation (default 0.8) |
+| `dependsOn` | FormControlDependency | Conditional display based on another field's value |
+| `dbbind` | string | Column name for `mappedValues` in submission |
+| `options` | FormControlOption[] | For `select` type |

package/auto-enable.ts

@@ -0,0 +1,24 @@
+// Auto-enable check for @elizaos/plugin-form.
+//
+// Plugin manifest entry-point — referenced by package.json's
+// `elizaos.plugin.autoEnableModule`. Keep this module light: env reads only,
+// no service init, no transitive imports of the full plugin runtime. The
+// auto-enable engine loads dozens of these per boot.
+import type { PluginAutoEnableContext } from "@elizaos/core";
+
+function isFeatureEnabled(
+  config: PluginAutoEnableContext["config"],
+  key: string,
+): boolean {
+  const f = (config?.features as Record<string, unknown> | undefined)?.[key];
+  if (f === true) return true;
+  if (f && typeof f === "object" && f !== null) {
+    return (f as Record<string, unknown>).enabled !== false;
+  }
+  return false;
+}
+
+/** Enable when `config.features.form` is truthy / not explicitly disabled. */
+export function shouldEnable(ctx: PluginAutoEnableContext): boolean {
+  return isFeatureEnabled(ctx.config, "form");
+}

package/package.json

@@ -1,60 +1,74 @@
 {
   "name": "@elizaos/plugin-form",
-  "description": "Guardrails for agent-guided user journeys - forms as agent guidance rails for ElizaOS",
-  "version": "2.0.0-alpha.9",
+  "version": "2.0.3-beta.2",
   "type": "module",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "packageType": "plugin",
-  "platform": "node",
-  "license": "MIT",
-  "author": "Odilitime",
-  "keywords": [
-    "plugin",
-    "elizaos",
-    "form",
-    "conversational",
-    "data-collection"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/elizaos/elizaos"
-  },
+  "description": "Eliza plugin-form: conversational forms as guardrails for guided user journeys.",
+  "main": "./dist/index.js",
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "dependencies": {
+    "@elizaos/core": "2.0.3-beta.2",
+    "uuid": "^14.0.0"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {},
+    "description": "Conversational forms for structured data collection."
+  },
+  "elizaos": {
+    "app": {
+      "heroImage": "assets/hero.png"
+    },
+    "plugin": {
+      "autoEnableModule": "./auto-enable.ts",
+      "capabilities": [
+        "forms"
+      ]
     }
   },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun run build:js && bun run build:types",
+    "clean": "rm -rf dist",
+    "test": "vitest run --config vitest.config.ts",
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
+    "build:js": "tsup --config ../tsup.plugin-packages.shared.ts",
+    "build:types": "tsc --noCheck -p tsconfig.build.json"
+  },
   "files": [
     "dist",
-    "README.md",
-    "package.json"
+    "auto-enable.ts"
   ],
-  "peerDependencies": {
-    "@elizaos/core": "2.0.0-alpha.3"
-  },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.11",
     "@types/node": "^25.0.3",
-    "typescript": "^5.9.3"
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.18"
   },
-  "scripts": {
-    "build": "bun run build.ts",
-    "build:ts": "bun run build.ts",
-    "dev": "bun --hot build.ts",
-    "test": "vitest run || echo 'TypeScript tests skipped - no tests found'",
-    "typecheck": "tsc --noEmit",
-    "lint": "bunx @biomejs/biome check --write --unsafe .",
-    "lint:check": "bunx @biomejs/biome check .",
-    "clean": "rm -rf dist .turbo",
-    "format": "bunx @biomejs/biome format --write .",
-    "format:check": "bunx @biomejs/biome format ."
-  },
-  "publishConfig": {
-    "access": "public"
-  }
+  "gitHead": "82fe0f44215954c2417328203f5bd6510985c1fc"
 }

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-export * from "./index";
-export { default } from "./index";