@elizaos/plugin-form 2.0.0-alpha.8 → 2.0.0-beta.1

package/dist/service.d.ts

@@ -0,0 +1,402 @@
+/**
+ * @module service
+ * @description Central service for managing agent-guided user journeys
+ *
+ * ## The Core Role
+ *
+ * The FormService is the **journey controller**. It ensures agents stay on
+ * the path defined by form definitions, guiding users reliably to outcomes.
+ *
+ * Without this service, agents would:
+ * - Forget what information they've collected
+ * - Miss required fields
+ * - Lose progress when users switch topics
+ * - Have no way to resume interrupted journeys
+ *
+ * ## What It Does
+ *
+ * 1. **Defines Journeys**: Register form definitions (the maps)
+ * 2. **Tracks Progress**: Manage sessions (where users are)
+ * 3. **Validates Stops**: Ensure collected data meets requirements
+ * 4. **Enables Pausing**: Stash journeys for later resumption
+ * 5. **Records Completions**: Store submissions (outcomes achieved)
+ * 6. **Guides Agents**: Provide context about what to do next
+ * 7. **Manages Control Types**: Widget registry for simple, composite, external types
+ *
+ * ## Widget Registry (ControlType System)
+ *
+ * The FormService manages a registry of control types:
+ *
+ * - **Simple types** (text, number, email): Just validate/parse/format
+ * - **Composite types** (address, payment setup): Have subcontrols
+ * - **External types** (payment, signature): Require async confirmation
+ *
+ * Built-in types are registered at startup. Plugins can register custom types.
+ *
+ * WHY a registry:
+ * - Decouples type definitions from form definitions
+ * - Plugins can add domain-specific types (blockchain addresses, etc.)
+ * - Override protection prevents accidental shadowing of built-ins
+ *
+ * ## Service Lifecycle
+ *
+ * ```
+ * Plugin Init → FormService.start() → Register Builtins → Register Forms → Ready
+ *
+ * User Message → form evaluator → FormService.updateField() → Session Updated
+ *             → FormService.updateSubField() → Subfield Updated
+ *             → FormService.activateExternalField() → External Process Started
+ *                         → FormService.submit() → Submission Created
+ *                         → FormService.stash() → Session Stashed
+ *
+ * External Event → PaymentService → FormService.confirmExternalField() → Field Filled
+ * ```
+ *
+ * ## State Management
+ *
+ * The service maintains two types of state:
+ *
+ * 1. **In-Memory**: Form definitions, control types (loaded at startup)
+ * 2. **Persistent**: Sessions, submissions, autofill (via storage.ts)
+ *
+ * ## Consuming Plugin Pattern
+ *
+ * Plugins that use forms typically:
+ *
+ * ```typescript
+ * // 1. Register form at plugin init
+ * const formService = runtime.getService('FORM') as FormService;
+ * formService.registerForm(myFormDefinition);
+ *
+ * // 2. Optionally register custom control types
+ * formService.registerControlType({
+ *   id: 'payment',
+ *   getSubControls: () => [...],
+ *   activate: async (ctx) => {...},
+ * });
+ *
+ * // 3. Start session when needed
+ * await formService.startSession('my-form', entityId, roomId);
+ *
+ * // 4. Register hook workers for submission handling
+ * runtime.registerTaskWorker({
+ *   name: 'handle_my_form_submission',
+ *   execute: async (runtime, options) => {
+ *     const { submission } = options;
+ *     // Process the submitted data
+ *   }
+ * });
+ * ```
+ *
+ * ## Error Handling
+ *
+ * Most methods throw on invalid state (e.g., session not found).
+ * Callers should handle errors appropriately.
+ */
+import { type IAgentRuntime, type JsonValue, Service, type UUID } from "@elizaos/core";
+import type { ControlType, ExternalActivation, FieldState, FormContextState, FormControl, FormDefinition, FormSession, FormSubmission } from "./types";
+/**
+ * FormService - Central service for managing conversational forms.
+ *
+ * WHY a service:
+ * - Services are singletons, one per agent
+ * - Persist across conversations
+ * - Accessible from actions, evaluators, providers
+ *
+ * WHY static `start` method:
+ * - elizaOS service lifecycle pattern
+ * - Async initialization support
+ * - Returns Service interface
+ */
+export declare class FormService extends Service {
+    /** Service type identifier for runtime.getService() */
+    static serviceType: string;
+    /** Description shown in agent capabilities */
+    capabilityDescription: string;
+    /**
+     * In-memory storage of form definitions.
+     *
+     * WHY Map:
+     * - O(1) lookup by ID
+     * - Forms are static after registration
+     * - No persistence needed (re-registered on startup)
+     */
+    private forms;
+    /**
+     * Control type registry.
+     *
+     * Built-in types are registered on start.
+     * Plugins can register custom types.
+     */
+    private controlTypes;
+    /**
+     * Start the FormService
+     */
+    static start(runtime: IAgentRuntime): Promise<Service>;
+    /**
+     * Stop the FormService
+     */
+    stop(): Promise<void>;
+    /**
+     * Register a form definition
+     */
+    registerForm(definition: FormDefinition): void;
+    /**
+     * Get a form definition by ID
+     */
+    getForm(formId: string): FormDefinition | undefined;
+    /**
+     * Get all registered forms
+     */
+    listForms(): FormDefinition[];
+    /**
+     * Register a control type.
+     *
+     * Control types define how a field type behaves:
+     * - Simple types: validate/parse/format
+     * - Composite types: have subcontrols
+     * - External types: have activate/deactivate for async processes
+     *
+     * Built-in types (text, number, email, etc.) are registered at startup
+     * and protected from override unless explicitly allowed.
+     *
+     * @param type - The ControlType definition
+     * @param options - Registration options
+     * @param options.allowOverride - Allow overriding built-in types (default: false)
+     *
+     * @example
+     * ```typescript
+     * formService.registerControlType({
+     *   id: 'payment',
+     *   getSubControls: () => [
+     *     { key: 'amount', type: 'number', label: 'Amount', required: true },
+     *     { key: 'currency', type: 'select', label: 'Currency', required: true },
+     *   ],
+     *   activate: async (ctx) => {
+     *     const paymentService = ctx.runtime.getService('PAYMENT');
+     *     return paymentService.createPending(ctx.subValues);
+     *   },
+     * });
+     * ```
+     */
+    registerControlType(type: ControlType, options?: {
+        allowOverride?: boolean;
+    }): void;
+    /**
+     * Get a control type by ID.
+     *
+     * @param typeId - The type ID to look up
+     * @returns The ControlType or undefined if not found
+     */
+    getControlType(typeId: string): ControlType | undefined;
+    /**
+     * List all registered control types.
+     *
+     * @returns Array of all registered ControlTypes
+     */
+    listControlTypes(): ControlType[];
+    /**
+     * Check if a control type has subcontrols.
+     *
+     * @param typeId - The type ID to check
+     * @returns true if the type has getSubControls method
+     */
+    isCompositeType(typeId: string): boolean;
+    /**
+     * Check if a control type is an external type.
+     *
+     * @param typeId - The type ID to check
+     * @returns true if the type has activate method
+     */
+    isExternalType(typeId: string): boolean;
+    /**
+     * Get subcontrols for a composite type.
+     *
+     * @param control - The parent control
+     * @returns Array of subcontrols or empty array if not composite
+     */
+    getSubControls(control: FormControl): FormControl[];
+    /**
+     * Start a new form session
+     */
+    startSession(formId: string, entityId: UUID, roomId: UUID, options?: {
+        context?: Record<string, JsonValue>;
+        initialValues?: Record<string, JsonValue>;
+        locale?: string;
+    }): Promise<FormSession>;
+    /**
+     * Get active session for entity in room
+     */
+    getActiveSession(entityId: UUID, roomId: UUID): Promise<FormSession | null>;
+    /**
+     * Get all active sessions for entity (across all rooms)
+     */
+    getAllActiveSessions(entityId: UUID): Promise<FormSession[]>;
+    /**
+     * Get stashed sessions for entity
+     */
+    getStashedSessions(entityId: UUID): Promise<FormSession[]>;
+    /**
+     * Save a session
+     */
+    saveSession(session: FormSession): Promise<void>;
+    /**
+     * Update a field value
+     */
+    updateField(sessionId: string, entityId: UUID, field: string, value: JsonValue, confidence: number, source: FieldState["source"], messageId?: string): Promise<void>;
+    /**
+     * Undo the last field change
+     */
+    undoLastChange(sessionId: string, entityId: UUID): Promise<{
+        field: string;
+        restoredValue: JsonValue;
+    } | null>;
+    /**
+     * Skip an optional field
+     */
+    skipField(sessionId: string, entityId: UUID, field: string): Promise<boolean>;
+    /**
+     * Confirm an uncertain field value
+     */
+    confirmField(sessionId: string, entityId: UUID, field: string, accepted: boolean): Promise<void>;
+    /**
+     * Update a subfield value for a composite control type.
+     *
+     * Composite types (like payment, address) have subcontrols that must
+     * all be filled before the parent field is complete.
+     *
+     * WHY separate from updateField:
+     * - Subfields are stored in fieldState.subFields, not session.fields
+     * - Parent field status depends on all subfields being filled
+     * - Allows tracking subfield confidence/status independently
+     *
+     * @param sessionId - The session ID
+     * @param entityId - The entity/user ID
+     * @param parentField - The parent control key (e.g., "payment")
+     * @param subField - The subcontrol key (e.g., "amount")
+     * @param value - The extracted value
+     * @param confidence - LLM confidence (0-1)
+     * @param messageId - Optional message ID for audit
+     */
+    updateSubField(sessionId: string, entityId: UUID, parentField: string, subField: string, value: JsonValue, confidence: number, messageId?: string): Promise<void>;
+    /**
+     * Check if all subfields of a composite field are filled.
+     *
+     * @param session - The form session
+     * @param parentField - The parent control key
+     * @returns true if all required subfields are filled
+     */
+    areSubFieldsFilled(session: FormSession, parentField: string): boolean;
+    /**
+     * Get the current subfield values for a composite field.
+     *
+     * @param session - The form session
+     * @param parentField - The parent control key
+     * @returns Record of subfield key to value
+     */
+    getSubFieldValues(session: FormSession, parentField: string): Record<string, JsonValue>;
+    /**
+     * Activate an external field.
+     *
+     * External types (payment, signature) require an async activation process.
+     * This is called when all subcontrols are filled and the external process
+     * should begin (e.g., generate payment address, show signing instructions).
+     *
+     * WHY this method:
+     * - Decouples activation trigger from the widget itself
+     * - Stores activation state in the session
+     * - Provides a clear API for the evaluator to call
+     *
+     * @param sessionId - The session ID
+     * @param entityId - The entity/user ID
+     * @param field - The field key
+     * @returns The activation details (instructions, reference, etc.)
+     */
+    activateExternalField(sessionId: string, entityId: UUID, field: string): Promise<ExternalActivation>;
+    /**
+     * Confirm an external field.
+     *
+     * Called by external services (payment, blockchain, etc.) when the
+     * external process is complete (e.g., payment received, signature verified).
+     *
+     * WHY separate from confirmField:
+     * - External confirmation includes external data (txId, etc.)
+     * - Updates externalState, not just field status
+     * - Emits events for other systems to react
+     *
+     * @param sessionId - The session ID
+     * @param entityId - The entity/user ID
+     * @param field - The field key
+     * @param value - The final value to store (usually the confirmed data)
+     * @param externalData - Additional data from the external source (txId, etc.)
+     */
+    confirmExternalField(sessionId: string, entityId: UUID, field: string, value: JsonValue, externalData?: Record<string, JsonValue>): Promise<void>;
+    /**
+     * Cancel an external field activation.
+     *
+     * Called when the external process fails, times out, or user cancels.
+     *
+     * @param sessionId - The session ID
+     * @param entityId - The entity/user ID
+     * @param field - The field key
+     * @param reason - Reason for cancellation
+     */
+    cancelExternalField(sessionId: string, entityId: UUID, field: string, reason: string): Promise<void>;
+    /**
+     * Submit a form session
+     */
+    submit(sessionId: string, entityId: UUID): Promise<FormSubmission>;
+    /**
+     * Stash a session for later
+     */
+    stash(sessionId: string, entityId: UUID): Promise<void>;
+    /**
+     * Restore a stashed session
+     */
+    restore(sessionId: string, entityId: UUID): Promise<FormSession>;
+    /**
+     * Cancel a session
+     */
+    cancel(sessionId: string, entityId: UUID, force?: boolean): Promise<boolean>;
+    /**
+     * Get submissions for entity, optionally filtered by form ID
+     */
+    getSubmissions(entityId: UUID, formId?: string): Promise<FormSubmission[]>;
+    /**
+     * Get autofill data for a form
+     */
+    getAutofill(entityId: UUID, formId: string): Promise<Record<string, JsonValue> | null>;
+    /**
+     * Apply autofill to a session
+     */
+    applyAutofill(session: FormSession): Promise<string[]>;
+    /**
+     * Get session context for provider
+     */
+    getSessionContext(session: FormSession): FormContextState;
+    /**
+     * Get current values from session
+     */
+    getValues(session: FormSession): Record<string, JsonValue>;
+    /**
+     * Get mapped values (using dbbind)
+     */
+    getMappedValues(session: FormSession): Record<string, JsonValue>;
+    /**
+     * Calculate TTL based on effort
+     */
+    calculateTTL(session: FormSession): number;
+    /**
+     * Check if cancel should require confirmation
+     */
+    shouldConfirmCancel(session: FormSession): boolean;
+    /**
+     * Execute a form hook
+     */
+    private executeHook;
+    /**
+     * Check if all required fields are filled
+     */
+    private checkAllRequiredFilled;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

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