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

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Odilitime
+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

package/dist/index.d.ts

@@ -1,175 +1,2 @@
-/**
- * @module @elizaos/plugin-form
- * @description Guardrails for agent-guided user journeys
- *
- * @author Odilitime
- * @copyright 2025 Odilitime
- * @license MIT
- *
- * ## The Core Insight
- *
- * Forms aren't just about data collection - they're **guardrails for agents**.
- *
- * Without structure, agents wander. They forget context, miss required
- * information, and can't reliably guide users to outcomes. This plugin
- * gives agents the tools to follow conventions and shepherd users through
- * structured journeys - registrations, orders, applications, onboarding flows.
- *
- * **Forms define the path. Agents follow it. Users reach outcomes.**
- *
- * ## Key Features
- *
- * - **Natural Language Extraction**: "I'm John, 25, john@example.com"
- * - **Two-Tier Intent Detection**: Fast English keywords + LLM fallback
- * - **UX Magic**: Undo, skip, explain, example, progress, autofill
- * - **Smart TTL**: Retention scales with user effort
- * - **Fluent Builder API**: Type-safe form definitions
- * - **Extensible Types**: Register custom field types
- *
- * ## Architecture
- *
- * ```
- * ┌─────────────────────────────────────────────────────────────┐
- * │                        Form Plugin                          │
- * ├─────────────────────────────────────────────────────────────┤
- * │                                                             │
- * │   Provider (FORM_CONTEXT)                                   │
- * │   - Runs BEFORE agent responds                              │
- * │   - Injects form state into context                         │
- * │   - Tells agent what to ask next                            │
- * │                                                             │
- * │   Evaluator (form_evaluator)                                │
- * │   - Runs AFTER each user message                            │
- * │   - Detects intent (submit, cancel, undo, etc.)             │
- * │   - Extracts field values from natural language             │
- * │   - Updates session state                                   │
- * │                                                             │
- * │   Action (FORM_RESTORE)                                     │
- * │   - Preempts REPLY for restore intent                       │
- * │   - Immediately restores stashed forms                      │
- * │                                                             │
- * │   Service (FormService)                                     │
- * │   - Manages form definitions                                │
- * │   - Manages sessions, submissions, autofill                 │
- * │   - Executes lifecycle hooks                                │
- * │                                                             │
- * └─────────────────────────────────────────────────────────────┘
- * ```
- *
- * ## Quick Start
- *
- * ### 1. Add plugin to your agent
- *
- * ```typescript
- * import { formPlugin } from '@elizaos/plugin-form';
- *
- * const agent = {
- *   plugins: [formPlugin, ...otherPlugins],
- * };
- * ```
- *
- * ### 2. Define a form
- *
- * ```typescript
- * import { Form, C } from '@elizaos/plugin-form';
- *
- * const registrationForm = Form.create('registration')
- *   .name('User Registration')
- *   .control(C.email('email').required().ask('What email should we use?'))
- *   .control(C.text('name').required().ask("What's your name?"))
- *   .control(C.number('age').min(13))
- *   .onSubmit('handle_registration')
- *   .build();
- * ```
- *
- * ### 3. Register and start
- *
- * ```typescript
- * // In your plugin init:
- * const formService = runtime.getService('FORM') as FormService;
- * formService.registerForm(registrationForm);
- *
- * // When you need to collect data:
- * await formService.startSession('registration', entityId, roomId);
- * ```
- *
- * ### 4. Handle submissions
- *
- * ```typescript
- * runtime.registerTaskWorker({
- *   name: 'handle_registration',
- *   execute: async (runtime, options) => {
- *     const { submission } = options;
- *     const { email, name, age } = submission.values;
- *     // Create user account, etc.
- *   }
- * });
- * ```
- *
- * ## User Experience
- *
- * The form plugin handles these user interactions:
- *
- * | User Says | Intent | Result |
- * |-----------|--------|--------|
- * | "I'm John, 25 years old" | fill_form | Extract name=John, age=25 |
- * | "done" / "submit" | submit | Submit the form |
- * | "save for later" | stash | Save and switch contexts |
- * | "resume my form" | restore | Restore stashed form |
- * | "cancel" / "nevermind" | cancel | Abandon form |
- * | "undo" / "go back" | undo | Revert last change |
- * | "skip" | skip | Skip optional field |
- * | "why?" | explain | Explain current field |
- * | "example?" | example | Show example value |
- * | "how far?" | progress | Show completion status |
- * | "same as last time" | autofill | Use saved values |
- *
- * ## Module Exports
- *
- * - **Types**: FormControl, FormDefinition, FormSession, etc.
- * - **Builder**: Form, C (ControlBuilder)
- * - **Service**: FormService
- * - **Utilities**: validateField, parseValue, formatValue
- * - **Plugin**: formPlugin (default export)
- *
- * @see {@link FormService} for form management API
- * @see {@link FormBuilder} for fluent form definition
- * @see {@link ControlBuilder} for field definition
- */
-import type { Plugin } from "@elizaos/core";
-export * from "./types";
-export { BUILTIN_TYPES, BUILTIN_TYPE_MAP, registerBuiltinTypes, getBuiltinType, isBuiltinType, } from "./builtins";
-export { validateField, formatValue, parseValue, matchesMimeType, } from "./validation";
-export { registerTypeHandler, getTypeHandler, clearTypeHandlers, } from "./validation";
-export { quickIntentDetect, isLifecycleIntent, isUXIntent, hasDataToExtract, } from "./intent";
-export { getActiveSession, getAllActiveSessions, getStashedSessions, saveSession, deleteSession, saveSubmission, getSubmissions, getAutofillData, saveAutofillData, } from "./storage";
-export { llmIntentAndExtract, extractSingleField, detectCorrection, } from "./extraction";
-export { calculateTTL, shouldNudge, isExpiringSoon, isExpired, shouldConfirmCancel, formatTimeRemaining, formatEffort, } from "./ttl";
-export { applyControlDefaults, applyFormDefaults, prettify } from "./defaults";
-export { FormBuilder, ControlBuilder, Form, C } from "./builder";
-export { FormService } from "./service";
-export { formContextProvider } from "./providers/context";
-export { formEvaluator } from "./evaluators/extractor";
-export { formRestoreAction } from "./actions/restore";
-export { formNudgeWorker, processEntityNudges } from "./tasks/nudge";
-/**
- * Form Plugin
- *
- * Infrastructure plugin for collecting structured data through natural conversation.
- *
- * Architecture:
- * - Provider: Injects form state into agent context before response
- * - Evaluator: Extracts fields and handles intents after response
- * - Action: Fast-path restore for stashed forms
- * - Service: Manages form definitions, sessions, and submissions
- *
- * Usage:
- * 1. Register form definitions via FormService.registerForm()
- * 2. Start sessions via FormService.startSession()
- * 3. The evaluator automatically extracts field values from user messages
- * 4. The provider gives the agent context about what to ask next
- * 5. The agent (via REPLY) handles the conversation naturally
- */
-export declare const formPlugin: Plugin;
-export default formPlugin;
-//# sourceMappingURL=index.d.ts.map
+export * from "./index";
+export { default } from "./index";

package/package.json

@@ -1,13 +1,25 @@
 {
   "name": "@elizaos/plugin-form",
-  "version": "2.0.0-alpha.1",
   "description": "Guardrails for agent-guided user journeys - forms as agent guidance rails for ElizaOS",
-  "author": "Odilitime",
-  "license": "MIT",
+  "version": "2.0.0-alpha.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"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elizaos/eliza"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -19,34 +31,29 @@
   },
   "files": [
     "dist",
-    "package.json",
-    "LICENSE"
+    "README.md",
+    "package.json"
   ],
-  "dependencies": {
-    "@elizaos/core": "2.0.0-alpha.1"
+  "peerDependencies": {
+    "@elizaos/core": "2.0.0-alpha.2"
   },
   "devDependencies": {
-    "@types/node": "^22.15.3",
-    "bun-types": "^1.2.21",
-    "prettier": "3.5.3",
-    "typescript": "5.8.2"
+    "@biomejs/biome": "^2.3.11",
+    "@types/node": "^25.0.3",
+    "typescript": "^5.9.3"
   },
   "scripts": {
+    "dev": "bun --hot build.ts",
+    "test": "vitest run || echo 'TypeScript tests skipped - no tests found'",
+    "lint": "bunx @biomejs/biome check --write --unsafe .",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo",
+    "lint:check": "bunx @biomejs/biome check .",
     "build": "bun run build.ts",
-    "dev": "bun run build.ts --watch",
-    "lint": "prettier --write ./src",
-    "clean": "rm -rf dist .turbo node_modules .turbo-tsconfig.json tsconfig.tsbuildinfo",
-    "format": "prettier --write ./src",
-    "format:check": "prettier --check ./src",
-    "test": "bun test",
-    "test:watch": "bun test --watch",
-    "test:coverage": "bun test --coverage"
-  },
-  "peerDependencies": {
-    "whatwg-url": "7.1.0"
+    "build:ts": "bun run build.ts"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "05d4ca11d769db8c7f54a722ee24b2ce2b951543"
+  "gitHead": "bc6cac8d36845d7cbde51a64307c6a57c16378ad"
 }