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

package/dist/actions/restore.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @module actions/restore
+ * @description Action for restoring stashed form sessions
+ *
+ * ## Why an Action (Not Evaluator)
+ *
+ * The restore operation is unique among form intents because:
+ *
+ * 1. **Timing Matters**: The restored form context must be available
+ *    to the agent BEFORE it generates a response. Evaluators run
+ *    AFTER response generation.
+ *
+ * 2. **Preemption**: When user says "resume my form", the FORM_RESTORE
+ *    action should preempt REPLY, generate its own response with the
+ *    restored context, and let the agent continue naturally.
+ *
+ * 3. **Immediate Context**: After restore, the provider runs and gives
+ *    the agent the restored form context for its response.
+ *
+ * ## Flow Comparison
+ *
+ * ### Other Intents (via Evaluator):
+ * ```
+ * Message → Provider (no context) → REPLY → Evaluator (updates state)
+ *                                              ↓
+ *                                    Next message has updated context
+ * ```
+ *
+ * ### Restore Intent (via Action):
+ * ```
+ * Message → FORM_RESTORE.validate() → true
+ *                    ↓
+ *         FORM_RESTORE.handler() → Restore session → Generate response
+ *                                        ↓
+ *                               Next message has restored context immediately
+ * ```
+ *
+ * ## Handling Multiple Stashed Forms
+ *
+ * If user has multiple stashed forms, this action restores the most recent.
+ * Future enhancement: Let user choose which form to restore.
+ *
+ * ## Conflicts with Active Forms
+ *
+ * If user has an active form in the current room and tries to restore,
+ * the action asks them to either continue or stash the current one.
+ */
+import { type Action } from "@elizaos/core";
+/**
+ * Form Restore Action
+ *
+ * Fast-path action for restoring stashed forms.
+ * Preempts REPLY to provide immediate restoration with summary.
+ *
+ * WHY action:
+ * - Needs to run BEFORE provider
+ * - Must generate immediate response
+ * - Context needed for next message
+ */
+export declare const formRestoreAction: Action;
+export default formRestoreAction;
+//# sourceMappingURL=restore.d.ts.map

package/dist/actions/restore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore.d.ts","sourceRoot":"","sources":["../../src/actions/restore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,EACL,KAAK,MAAM,EASZ,MAAM,eAAe,CAAC;AAIvB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAkM/B,CAAC;AAEF,eAAe,iBAAiB,CAAC"}

package/dist/builder.d.ts

@@ -0,0 +1,320 @@
+/**
+ * @module builder
+ * @description Fluent builder API for defining forms and controls
+ *
+ * ## Why a Builder API
+ *
+ * Form definitions can be verbose with many optional fields. The builder
+ * API provides:
+ *
+ * 1. **Type Safety**: Method chaining with TypeScript gives autocomplete
+ * 2. **Readability**: Intent is clear from method names
+ * 3. **Defaults**: Builder applies sensible defaults
+ * 4. **Validation**: Build-time checks for common mistakes
+ *
+ * ## Usage Examples
+ *
+ * ### Simple Form
+ *
+ * ```typescript
+ * const form = Form.create('contact')
+ *   .name('Contact Form')
+ *   .control(C.email('email').required())
+ *   .control(C.text('message').required())
+ *   .build();
+ * ```
+ *
+ * ### Complex Form
+ *
+ * ```typescript
+ * const registrationForm = Form.create('registration')
+ *   .name('User Registration')
+ *   .description('Create your account')
+ *   .control(
+ *     C.email('email')
+ *       .required()
+ *       .ask('What email should we use for your account?')
+ *       .example('user@example.com')
+ *   )
+ *   .control(
+ *     C.text('username')
+ *       .required()
+ *       .minLength(3)
+ *       .maxLength(20)
+ *       .pattern('^[a-z0-9_]+$')
+ *       .ask('Choose a username (letters, numbers, underscore)')
+ *   )
+ *   .control(
+ *     C.number('age')
+ *       .min(13)
+ *       .ask('How old are you?')
+ *   )
+ *   .onSubmit('handle_registration')
+ *   .ttl({ minDays: 7, maxDays: 30 })
+ *   .build();
+ * ```
+ *
+ * ### Custom Type
+ *
+ * ```typescript
+ * // Register custom type first
+ * FormService.registerType('solana_address', {
+ *   validate: (v) => ({
+ *     valid: /^[1-9A-HJ-NP-Za-km-z]{32,44}$/.test(String(v)),
+ *     error: 'Invalid Solana address'
+ *   }),
+ *   extractionPrompt: 'a Solana wallet address (Base58 encoded)'
+ * });
+ *
+ * // Use in form
+ * const form = Form.create('wallet')
+ *   .control(
+ *     C.field('walletAddress')
+ *       .type('solana_address')
+ *       .required()
+ *       .label('Wallet Address')
+ *       .ask('What is your Solana wallet address?')
+ *   )
+ *   .build();
+ * ```
+ *
+ * ## Shorthand Exports
+ *
+ * For convenience:
+ * - `Form` is an alias for `FormBuilder`
+ * - `C` is an alias for `ControlBuilder`
+ *
+ * This enables the concise syntax shown in examples.
+ */
+import type { JsonValue } from "@elizaos/core";
+import type { FormControl, FormControlOption, FormControlDependency, FormDefinition, FormDefinitionHooks } from "./types";
+/**
+ * Fluent builder for FormControl.
+ *
+ * Create controls with readable, chainable syntax:
+ *
+ * ```typescript
+ * ControlBuilder.email('email').required().ask('What is your email?')
+ * ```
+ *
+ * All methods return `this` for chaining except `build()` which returns
+ * the final FormControl.
+ */
+export declare class ControlBuilder {
+    /** Partial control being built */
+    private control;
+    /**
+     * Create a new ControlBuilder.
+     *
+     * @param key - The unique key for this control
+     */
+    constructor(key: string);
+    /** Create a generic field builder */
+    static field(key: string): ControlBuilder;
+    /** Create a text field */
+    static text(key: string): ControlBuilder;
+    /** Create an email field */
+    static email(key: string): ControlBuilder;
+    /** Create a number field */
+    static number(key: string): ControlBuilder;
+    /** Create a boolean (yes/no) field */
+    static boolean(key: string): ControlBuilder;
+    /** Create a select field with options */
+    static select(key: string, options: FormControlOption[]): ControlBuilder;
+    /** Create a date field */
+    static date(key: string): ControlBuilder;
+    /** Create a file upload field */
+    static file(key: string): ControlBuilder;
+    /** Set the field type */
+    type(type: string): this;
+    /** Mark field as required */
+    required(): this;
+    /** Mark field as optional (default) */
+    optional(): this;
+    /** Mark field as hidden (extract silently, never ask) */
+    hidden(): this;
+    /** Mark field as sensitive (don't echo value back) */
+    sensitive(): this;
+    /** Mark field as readonly (can't change after set) */
+    readonly(): this;
+    /** Mark field as accepting multiple values */
+    multiple(): this;
+    /** Set regex pattern for validation */
+    pattern(regex: string): this;
+    /** Set minimum value (for numbers) or minimum length (via minLength) */
+    min(n: number): this;
+    /** Set maximum value (for numbers) or maximum length (via maxLength) */
+    max(n: number): this;
+    /** Set minimum string length */
+    minLength(n: number): this;
+    /** Set maximum string length */
+    maxLength(n: number): this;
+    /** Set allowed values (enum) */
+    enum(values: string[]): this;
+    /** Set select options */
+    options(opts: FormControlOption[]): this;
+    /** Set human-readable label */
+    label(label: string): this;
+    /** Set custom prompt for asking this field */
+    ask(prompt: string): this;
+    /** Set description for LLM context */
+    description(desc: string): this;
+    /** Add extraction hints (keywords to look for) */
+    hint(...hints: string[]): this;
+    /** Set example value for "give me an example" */
+    example(value: string): this;
+    /** Set confidence threshold for auto-acceptance */
+    confirmThreshold(n: number): this;
+    /** Set accepted MIME types for file upload */
+    accept(mimeTypes: string[]): this;
+    /** Set maximum file size in bytes */
+    maxSize(bytes: number): this;
+    /** Set maximum number of files */
+    maxFiles(n: number): this;
+    /** Set roles that can see/fill this field */
+    roles(...roles: string[]): this;
+    /** Set default value */
+    default(value: JsonValue): this;
+    /** Set dependency on another field */
+    dependsOn(field: string, condition?: FormControlDependency["condition"], value?: JsonValue): this;
+    /** Set database column name (defaults to key) */
+    dbbind(columnName: string): this;
+    /** Set section name for grouping */
+    section(name: string): this;
+    /** Set display order within section */
+    order(n: number): this;
+    /** Set placeholder text */
+    placeholder(text: string): this;
+    /** Set help text */
+    helpText(text: string): this;
+    /** Set custom widget type */
+    widget(type: string): this;
+    /** Add localized text for a locale */
+    i18n(locale: string, translations: {
+        label?: string;
+        description?: string;
+        askPrompt?: string;
+        helpText?: string;
+    }): this;
+    /** Add custom metadata */
+    meta(key: string, value: JsonValue): this;
+    /**
+     * Build the final FormControl.
+     *
+     * Applies defaults and validates the control.
+     *
+     * @returns Complete FormControl object
+     */
+    build(): FormControl;
+}
+/**
+ * Fluent builder for FormDefinition.
+ *
+ * Create forms with readable, chainable syntax:
+ *
+ * ```typescript
+ * Form.create('contact')
+ *   .name('Contact Form')
+ *   .control(C.email('email').required())
+ *   .onSubmit('handle_contact')
+ *   .build();
+ * ```
+ */
+export declare class FormBuilder {
+    /** Partial form being built */
+    private form;
+    /**
+     * Create a new FormBuilder.
+     *
+     * @param id - Unique form identifier
+     */
+    constructor(id: string);
+    /** Create a new form builder */
+    static create(id: string): FormBuilder;
+    /** Set form name */
+    name(name: string): this;
+    /** Set form description */
+    description(desc: string): this;
+    /** Set form version */
+    version(v: number): this;
+    /**
+     * Add a control to the form.
+     *
+     * Accepts either a ControlBuilder (calls .build()) or a FormControl.
+     */
+    control(builder: ControlBuilder | FormControl): this;
+    /** Add multiple controls */
+    controls(...builders: (ControlBuilder | FormControl)[]): this;
+    /** Add required text fields */
+    required(...keys: string[]): this;
+    /** Add optional text fields */
+    optional(...keys: string[]): this;
+    /** Set roles that can start this form */
+    roles(...roles: string[]): this;
+    /** Allow multiple submissions per user */
+    allowMultiple(): this;
+    /** Disable undo functionality */
+    noUndo(): this;
+    /** Disable skip functionality */
+    noSkip(): this;
+    /** Disable autofill */
+    noAutofill(): this;
+    /** Set maximum undo steps */
+    maxUndoSteps(n: number): this;
+    /** Configure TTL (time-to-live) settings */
+    ttl(config: {
+        minDays?: number;
+        maxDays?: number;
+        effortMultiplier?: number;
+    }): this;
+    /** Disable nudge messages */
+    noNudge(): this;
+    /** Set inactivity hours before nudge */
+    nudgeAfter(hours: number): this;
+    /** Set custom nudge message */
+    nudgeMessage(message: string): this;
+    /** Set task worker to call on session start */
+    onStart(workerName: string): this;
+    /** Set task worker to call on field change */
+    onFieldChange(workerName: string): this;
+    /** Set task worker to call when form is ready to submit */
+    onReady(workerName: string): this;
+    /** Set task worker to call on submission */
+    onSubmit(workerName: string): this;
+    /** Set task worker to call on cancellation */
+    onCancel(workerName: string): this;
+    /** Set task worker to call on expiration */
+    onExpire(workerName: string): this;
+    /** Set multiple hooks at once */
+    hooks(hooks: FormDefinitionHooks): this;
+    /** Enable debug mode (logs extraction reasoning) */
+    debug(): this;
+    /** Add localized form text */
+    i18n(locale: string, translations: {
+        name?: string;
+        description?: string;
+    }): this;
+    /** Add custom metadata */
+    meta(key: string, value: JsonValue): this;
+    /**
+     * Build the final FormDefinition.
+     *
+     * Applies defaults and validates the form.
+     *
+     * @returns Complete FormDefinition object
+     */
+    build(): FormDefinition;
+}
+/**
+ * Shorthand for FormBuilder.create
+ *
+ * Usage: `Form.create('myForm')...`
+ */
+export declare const Form: typeof FormBuilder;
+/**
+ * Shorthand for ControlBuilder factories
+ *
+ * Usage: `C.email('email').required()`
+ */
+export declare const C: typeof ControlBuilder;
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"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"}

package/dist/builtins.d.ts

@@ -0,0 +1,128 @@
+/**
+ * @module builtins
+ * @description Built-in control types for the Form Plugin
+ *
+ * ## Overview
+ *
+ * This module defines the standard control types that are available out of the box:
+ * - text: Plain text strings
+ * - number: Numeric values (integers or decimals)
+ * - email: Email addresses with format validation
+ * - boolean: Yes/no, true/false values
+ * - select: Choice from predefined options
+ * - date: Date values in various formats
+ * - file: File uploads (handled specially)
+ *
+ * ## Why Built-in Types
+ *
+ * Built-in types provide:
+ * 1. **Consistent validation** across all forms - same rules everywhere
+ * 2. **Sensible defaults** for common field types - less configuration
+ * 3. **LLM extraction hints** optimized for each type - better extraction
+ * 4. **Override protection** to prevent accidental shadowing - safety first
+ *
+ * ## Architecture Decision: ControlType vs TypeHandler
+ *
+ * We use ControlType (not the legacy TypeHandler) because:
+ * - ControlType is the unified interface for all type categories
+ * - ControlType supports composite types (subcontrols)
+ * - ControlType supports external types (activate/confirm)
+ * - TypeHandler is legacy and maintained only for backwards compatibility
+ *
+ * ## Why These Specific Types
+ *
+ * | Type | Why Built-in |
+ * |------|--------------|
+ * | text | Most common field type, catch-all for strings |
+ * | number | Second most common, needs special parsing (commas, $) |
+ * | email | Critical for communication, has clear format rules |
+ * | boolean | Binary choice, many natural language forms (yes/no/true/false) |
+ * | select | Constrained choice, validation against options |
+ * | date | Complex parsing (many formats), needs normalization |
+ * | file | Special handling needed (size, type, storage) |
+ *
+ * ## Extending
+ *
+ * Plugins can register custom types via FormService.registerControlType().
+ * Built-in types can be overridden with { allowOverride: true } option,
+ * but this will log a warning.
+ *
+ * ## Usage
+ *
+ * Built-in types are automatically registered when FormService starts.
+ * You don't need to call registerBuiltinTypes() manually.
+ *
+ * @example
+ * ```typescript
+ * // Check if a type is built-in before overriding
+ * if (isBuiltinType('email')) {
+ *   console.log('Warning: overriding built-in type');
+ *   formService.registerControlType(myEmailType, { allowOverride: true });
+ * }
+ * ```
+ */
+import type { ControlType } from "./types";
+/**
+ * Array of all built-in control types.
+ *
+ * These are registered automatically when FormService starts.
+ * The order doesn't matter; they're looked up by id.
+ *
+ * WHY array + map:
+ * - Array allows easy iteration for registration
+ * - Map provides O(1) lookup for override checks
+ * - Both derived from same source ensures consistency
+ */
+export declare const BUILTIN_TYPES: ControlType[];
+/**
+ * Map of built-in types by id for quick lookup.
+ *
+ * WHY Map (not object):
+ * - Type-safe keys
+ * - O(1) lookup performance
+ * - Clear has/get semantics
+ */
+export declare const BUILTIN_TYPE_MAP: Map<string, ControlType>;
+/**
+ * Register all built-in types with a FormService instance.
+ *
+ * This is called automatically during FormService.start().
+ * You typically don't need to call this directly.
+ *
+ * WHY take a function (not FormService):
+ * - Avoids circular dependency (builtins.ts ↔ service.ts)
+ * - Service passes its registerControlType method
+ * - Clean separation of concerns
+ *
+ * @param registerFn - The FormService.registerControlType method
+ */
+export declare function registerBuiltinTypes(registerFn: (type: ControlType, options?: {
+    allowOverride?: boolean;
+}) => void): void;
+/**
+ * Get a built-in type by id.
+ *
+ * This is a convenience for checking if a type is built-in
+ * before attempting to override it.
+ *
+ * WHY this exists:
+ * - Plugins may want to extend a built-in type
+ * - Checking before override allows informed decisions
+ * - Avoids accidental shadowing
+ *
+ * @param id - The type id to look up
+ * @returns The ControlType if found, undefined otherwise
+ */
+export declare function getBuiltinType(id: string): ControlType | undefined;
+/**
+ * Check if a type id is a built-in type.
+ *
+ * WHY boolean convenience:
+ * - Most callers just need yes/no answer
+ * - Cleaner than checking getBuiltinType() !== undefined
+ *
+ * @param id - The type id to check
+ * @returns true if the type is built-in
+ */
+export declare function isBuiltinType(id: string): boolean;
+//# sourceMappingURL=builtins.d.ts.map

package/dist/builtins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAiC,MAAM,SAAS,CAAC;AA+a1E;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,EAQtC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAErD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,CACV,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,KAClC,IAAI,GACR,IAAI,CAIN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAElE;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAEjD"}

package/dist/defaults.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @module defaults
+ * @description Default value application for forms and controls
+ *
+ * ## Purpose
+ *
+ * Form definitions can be quite minimal:
+ *
+ * ```typescript
+ * { id: 'contact', controls: [{ key: 'email' }] }
+ * ```
+ *
+ * This module fills in sensible defaults:
+ *
+ * ```typescript
+ * {
+ *   id: 'contact',
+ *   name: 'Contact',           // Prettified from id
+ *   version: 1,                // Default version
+ *   status: 'active',          // Default status
+ *   controls: [{
+ *     key: 'email',
+ *     label: 'Email',          // Prettified from key
+ *     type: 'text',            // Default type
+ *     required: false,         // Default required
+ *     confirmThreshold: 0.8,   // Default confidence threshold
+ *   }],
+ *   ux: { ... },               // All UX defaults
+ *   ttl: { ... },              // All TTL defaults
+ *   nudge: { ... },            // All nudge defaults
+ *   debug: false,              // Default debug off
+ * }
+ * ```
+ *
+ * ## When Defaults Apply
+ *
+ * Defaults are applied:
+ *
+ * 1. **At Registration**: When a form is registered via FormService
+ * 2. **At Build**: When using FormBuilder.build()
+ *
+ * This ensures:
+ * - Minimal definitions work correctly
+ * - All optional fields have values
+ * - Code can rely on values being present
+ *
+ * ## Default Values Philosophy
+ *
+ * Default values were chosen to be:
+ *
+ * - **Safe**: Won't cause unexpected behavior
+ * - **User-Friendly**: Enable features users expect
+ * - **Minimal**: Don't add unnecessary restrictions
+ *
+ * For example:
+ * - TTL defaults are generous (14-90 days)
+ * - UX features are enabled by default
+ * - Required defaults to false (explicit opt-in)
+ */
+import type { FormControl, FormDefinition } from "./types";
+/**
+ * Apply defaults to a FormControl.
+ *
+ * Ensures all optional fields have values.
+ *
+ * @param control - Partial control to complete
+ * @returns Complete FormControl with all defaults applied
+ */
+export declare function applyControlDefaults(control: Partial<FormControl>): FormControl;
+/**
+ * Apply defaults to a FormDefinition.
+ *
+ * Ensures all optional fields have values and applies
+ * defaults to all controls.
+ *
+ * @param form - Partial form to complete
+ * @returns Complete FormDefinition with all defaults applied
+ */
+export declare function applyFormDefaults(form: Partial<FormDefinition>): FormDefinition;
+/**
+ * Convert snake_case or kebab-case to Title Case.
+ *
+ * Used to generate human-readable labels from field keys
+ * and form names from form IDs.
+ *
+ * @example
+ * prettify('first_name')    // "First Name"
+ * prettify('email-address') // "Email Address"
+ * prettify('userId')        // "UserId" (camelCase preserved)
+ *
+ * @param key - The key to prettify
+ * @returns Human-readable title case string
+ */
+export declare function prettify(key: string): string;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG3D;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,WAAW,CAmBb;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,CAAC,cAAc,CAAC,GAC5B,cAAc,CAwDhB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ5C"}