@elizaos/plugin-form 2.0.0-alpha.3 → 2.0.0-alpha.4

package/dist/index.d.ts

@@ -1,174 +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";
-/**
- * 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";