@elizaos/ui 2.0.0-alpha.24 → 2.0.0-alpha.333

package/packages/typescript/src/features/advanced-capabilities/form/providers/context.js

@@ -0,0 +1,166 @@
+/**
+ * @module providers/context
+ * @description Form context provider for agent awareness
+ *
+ * This provider injects form state into the agent's context BEFORE
+ * the agent generates a response.
+ */
+import { logger } from "../../../../types/index.js";
+import { buildTemplateValues, renderTemplate, resolveControlTemplates, } from "../template.js";
+export const formContextProvider = {
+    name: "FORM_CONTEXT",
+    description: "Provides context about active form sessions",
+    get: async (runtime, message, _state) => {
+        try {
+            const formService = runtime.getService("FORM");
+            if (!formService) {
+                return {
+                    data: { hasActiveForm: false },
+                    values: { formContext: "" },
+                    text: "",
+                };
+            }
+            const entityId = message.entityId;
+            const roomId = message.roomId;
+            if (!entityId || !roomId) {
+                return {
+                    data: { hasActiveForm: false },
+                    values: { formContext: "" },
+                    text: "",
+                };
+            }
+            const session = await formService.getActiveSession(entityId, roomId);
+            const stashed = await formService.getStashedSessions(entityId);
+            if (!session && stashed.length === 0) {
+                return {
+                    data: { hasActiveForm: false, stashedCount: 0 },
+                    values: { formContext: "" },
+                    text: "",
+                };
+            }
+            let contextText = "";
+            let contextState;
+            if (session) {
+                contextState = formService.getSessionContext(session);
+                const form = formService.getForm(session.formId);
+                const templateValues = buildTemplateValues(session);
+                const resolve = (v) => renderTemplate(v, templateValues);
+                contextState = {
+                    ...contextState,
+                    filledFields: contextState.filledFields.map((f) => ({
+                        ...f,
+                        label: resolve(f.label) ?? f.label,
+                    })),
+                    missingRequired: contextState.missingRequired.map((f) => ({
+                        ...f,
+                        label: resolve(f.label) ?? f.label,
+                        description: resolve(f.description),
+                        askPrompt: resolve(f.askPrompt),
+                    })),
+                    uncertainFields: contextState.uncertainFields.map((f) => ({
+                        ...f,
+                        label: resolve(f.label) ?? f.label,
+                    })),
+                    nextField: contextState.nextField
+                        ? resolveControlTemplates(contextState.nextField, templateValues)
+                        : null,
+                };
+                const controls = form?.controls ?? [];
+                const filledKeys = new Set(contextState.filledFields.map((f) => f.key));
+                const controlByKey = new Map(controls.map((c) => [c.key, c]));
+                const requiredFilled = contextState.filledFields.filter((f) => controlByKey.get(f.key)?.required);
+                const optionalFilled = contextState.filledFields.filter((f) => !controlByKey.get(f.key)?.required);
+                const optionalMissing = controls.filter((c) => !c.hidden && !c.required && !filledKeys.has(c.key));
+                const fmt = (items) => items.length === 0
+                    ? "none"
+                    : items
+                        .map((i) => i.displayValue ? `${i.key} (${i.displayValue})` : i.key)
+                        .join(", ");
+                contextText = `# Active Form: ${form?.name || session.formId}\n`;
+                contextText += `Progress: ${contextState.progress}%\n\n`;
+                contextText += `Required fields we don't have: ${fmt(contextState.missingRequired)}\n`;
+                contextText += `Required fields we do have: ${fmt(requiredFilled)}\n\n`;
+                contextText += `Optional fields we don't have: ${fmt(optionalMissing)}\n`;
+                contextText += `Optional fields we do have: ${fmt(optionalFilled)}\n\n`;
+                if (contextState.uncertainFields.length > 0) {
+                    contextText += `Needs confirmation:\n`;
+                    for (const f of contextState.uncertainFields) {
+                        contextText += `- ${f.label}: "${f.value}" (${Math.round(f.confidence * 100)}% confident)\n`;
+                    }
+                    contextText += "\n";
+                }
+                if (contextState.pendingExternalFields.length > 0) {
+                    contextText += `Waiting for external action:\n`;
+                    for (const f of contextState.pendingExternalFields) {
+                        const mins = Math.floor((Date.now() - f.activatedAt) / 60000);
+                        contextText += `- ${f.label}: ${f.instructions} (${mins < 1 ? "just now" : `${mins}m ago`})`;
+                        if (f.address)
+                            contextText += ` Address: ${f.address}`;
+                        contextText += "\n";
+                    }
+                    contextText += "\n";
+                }
+                if (contextState.pendingExternalFields.length > 0) {
+                    const p = contextState.pendingExternalFields[0];
+                    contextText += `Instruction: Waiting for external action. Remind user: "${p.instructions}"\n`;
+                }
+                else if (contextState.pendingCancelConfirmation) {
+                    contextText += `Instruction: User is trying to cancel. Confirm they really want to lose progress.\n`;
+                }
+                else if (contextState.uncertainFields.length > 0) {
+                    const u = contextState.uncertainFields[0];
+                    contextText += `Instruction: Ask user to confirm "${u.label}" = "${u.value}".\n`;
+                }
+                else if (contextState.missingRequired.length > 0) {
+                    contextText += `Instruction: Please nudge the user into helping complete required fields. The user can provide one or several answers in a single message; the form accepts them all.\n`;
+                }
+                else if (contextState.status === "ready") {
+                    contextText += `Instruction: All required fields collected. Nudge user to submit.\n`;
+                }
+                else if (optionalMissing.length > 0) {
+                    contextText += `Instruction: Required fields are done. Optionally nudge for remaining optional fields, or nudge to submit.\n`;
+                }
+            }
+            else {
+                contextState = {
+                    hasActiveForm: false,
+                    progress: 0,
+                    filledFields: [],
+                    missingRequired: [],
+                    uncertainFields: [],
+                    nextField: null,
+                    stashedCount: stashed.length,
+                    pendingExternalFields: [],
+                };
+            }
+            if (stashed.length > 0) {
+                contextText += `\nSaved forms: User has ${stashed.length} saved form(s). They can say "resume" to restore one.\n`;
+                for (const s of stashed) {
+                    const f = formService.getForm(s.formId);
+                    const ctx = formService.getSessionContext(s);
+                    contextText += `- ${f?.name || s.formId} (${ctx.progress}% complete)\n`;
+                }
+            }
+            return {
+                data: JSON.parse(JSON.stringify(contextState)),
+                values: {
+                    formContext: contextText,
+                    hasActiveForm: String(contextState.hasActiveForm),
+                    formProgress: String(contextState.progress),
+                    formStatus: contextState.status || "",
+                    stashedCount: String(stashed.length),
+                },
+                text: contextText,
+            };
+        }
+        catch (error) {
+            logger.error("[FormContextProvider] Error:", String(error));
+            return {
+                data: { hasActiveForm: false, error: true },
+                values: { formContext: "Error loading form context." },
+                text: "Error loading form context.",
+            };
+        }
+    },
+};
+export default formContextProvider;

package/packages/typescript/src/features/advanced-capabilities/form/service.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @module service
+ * @description Central service for managing agent-guided user journeys
+ *
+ * The FormService is the journey controller. It ensures agents stay on
+ * the path defined by form definitions, guiding users reliably to outcomes.
+ */
+import { type IAgentRuntime, type JsonValue, type UUID } from "../../../types/index.ts";
+import { Service } from "../../../types/service.ts";
+import type { ControlType, ExternalActivation, FieldState, FormContextState, FormControl, FormDefinition, FormSession, FormSubmission } from "./types.ts";
+export declare class FormService extends Service {
+    static serviceType: string;
+    capabilityDescription: string;
+    private forms;
+    private controlTypes;
+    static start(runtime: IAgentRuntime): Promise<Service>;
+    stop(): Promise<void>;
+    registerForm(definition: FormDefinition): void;
+    getForm(formId: string): FormDefinition | undefined;
+    listForms(): FormDefinition[];
+    registerControlType(type: ControlType, options?: {
+        allowOverride?: boolean;
+    }): void;
+    getControlType(typeId: string): ControlType | undefined;
+    listControlTypes(): ControlType[];
+    isCompositeType(typeId: string): boolean;
+    isExternalType(typeId: string): boolean;
+    getSubControls(control: FormControl): FormControl[];
+    startSession(formId: string, entityId: UUID, roomId: UUID, options?: {
+        context?: Record<string, JsonValue>;
+        initialValues?: Record<string, JsonValue>;
+        locale?: string;
+    }): Promise<FormSession>;
+    getActiveSession(entityId: UUID, roomId: UUID): Promise<FormSession | null>;
+    getAllActiveSessions(entityId: UUID): Promise<FormSession[]>;
+    getStashedSessions(entityId: UUID): Promise<FormSession[]>;
+    saveSession(session: FormSession): Promise<void>;
+    updateField(sessionId: string, entityId: UUID, field: string, value: JsonValue, confidence: number, source: FieldState["source"], messageId?: string): Promise<void>;
+    undoLastChange(sessionId: string, entityId: UUID): Promise<{
+        field: string;
+        restoredValue: JsonValue;
+    } | null>;
+    skipField(sessionId: string, entityId: UUID, field: string): Promise<boolean>;
+    confirmField(sessionId: string, entityId: UUID, field: string, accepted: boolean): Promise<void>;
+    updateSubField(sessionId: string, entityId: UUID, parentField: string, subField: string, value: JsonValue, confidence: number, messageId?: string): Promise<void>;
+    areSubFieldsFilled(session: FormSession, parentField: string): boolean;
+    getSubFieldValues(session: FormSession, parentField: string): Record<string, JsonValue>;
+    activateExternalField(sessionId: string, entityId: UUID, field: string): Promise<ExternalActivation>;
+    confirmExternalField(sessionId: string, entityId: UUID, field: string, value: JsonValue, externalData?: Record<string, JsonValue>): Promise<void>;
+    cancelExternalField(sessionId: string, entityId: UUID, field: string, reason: string): Promise<void>;
+    submit(sessionId: string, entityId: UUID): Promise<FormSubmission>;
+    stash(sessionId: string, entityId: UUID): Promise<void>;
+    restore(sessionId: string, entityId: UUID): Promise<FormSession>;
+    cancel(sessionId: string, entityId: UUID, force?: boolean): Promise<boolean>;
+    getSubmissions(entityId: UUID, formId?: string): Promise<FormSubmission[]>;
+    getAutofill(entityId: UUID, formId: string): Promise<Record<string, JsonValue> | null>;
+    applyAutofill(session: FormSession): Promise<string[]>;
+    getSessionContext(session: FormSession): FormContextState;
+    getValues(session: FormSession): Record<string, JsonValue>;
+    getMappedValues(session: FormSession): Record<string, JsonValue>;
+    calculateTTL(session: FormSession): number;
+    shouldConfirmCancel(session: FormSession): boolean;
+    private executeHook;
+    private checkAllRequiredFilled;
+}
+//# sourceMappingURL=service.d.ts.map

package/packages/typescript/src/features/advanced-capabilities/form/service.d.ts.map

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