Unify form node naming and add schema-based multi-field forms

- Rename hitl-form/hitl-wait nodes to create-form/wait-for-form
- Rename HitlToken to FormToken (file, types, functions)
- Rename HITL_SIGNING_KEY to FORM_SIGNING_KEY
- Rename DO storage prefix and methods from hitl to form
- Add schema input to Create Form node for multi-field forms
- Schema stored in WorkflowAgent DO, fetched by form page
- Form page renders dynamic fields based on schema field types
- Wait for Form node outputs single JSON response
- Add schema to allowed parameter types in types test

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: bchapuis

apps/api/src/context.ts

@@ -67,7 +67,7 @@ export interface Bindings {
   R2_SECRET_ACCESS_KEY?: string;
   R2_BUCKET_NAME?: string;
   SECRET_MASTER_KEY: string;
-  HITL_SIGNING_KEY: string;
+  FORM_SIGNING_KEY: string;
   STRIPE_SECRET_KEY?: string;
   STRIPE_WEBHOOK_SECRET?: string;
   STRIPE_PRICE_ID_PRO?: string;

apps/api/src/durable-objects/workflow-agent.ts

@@ -91,7 +91,7 @@ export class WorkflowAgent extends Agent<Bindings, WorkflowAgentState> {
   private static readonly PERSIST_DEBOUNCE_MS = 500;
   private static readonly STORAGE_KEY_DIRTY = "dirty:persist";
   private static readonly STORAGE_PREFIX_EXEC_BUFFER = "execbuf:";
-  private static readonly STORAGE_PREFIX_HITL = "hitl:";
+  private static readonly STORAGE_PREFIX_FORM = "form:";
 
   initialState: WorkflowAgentState = {};
 
@@ -512,6 +512,9 @@ export class WorkflowAgent extends Agent<Bindings, WorkflowAgentState> {
   private async routeExecutionUpdate(
     execution: WorkflowExecution
   ): Promise<void> {
+    // Extract and store form schemas from node outputs
+    await this.extractFormSchemas(execution);
+
     const conn = this.findConnectionByExecutionId(execution.id);
     if (conn) {
       this.sendExecutionUpdate(conn, execution);
@@ -525,6 +528,34 @@ export class WorkflowAgent extends Agent<Bindings, WorkflowAgentState> {
     );
   }
 
+  /**
+   * Scan node outputs for form schema data (`schema` + `token`) and
+   * store them in DO transactional storage. This is how form nodes
+   * register their field definitions without touching the main DB.
+   */
+  private async extractFormSchemas(
+    execution: WorkflowExecution
+  ): Promise<void> {
+    for (const nodeExec of execution.nodeExecutions) {
+      if (
+        nodeExec.status === "completed" &&
+        nodeExec.outputs &&
+        typeof nodeExec.outputs.schema === "string" &&
+        typeof nodeExec.outputs.token === "string"
+      ) {
+        const key =
+          WorkflowAgent.STORAGE_PREFIX_FORM +
+          nodeExec.outputs.token +
+          ":schema";
+        // Only store if not already present (idempotent)
+        const existing = await this.storage.get(key);
+        if (!existing) {
+          await this.storage.put(key, nodeExec.outputs.schema);
+        }
+      }
+    }
+  }
+
   /**
    * Scan live connections for one subscribed to the given execution.
    * Connection state (`connection.setState`) survives DO hibernation via
@@ -570,29 +601,35 @@ export class WorkflowAgent extends Agent<Bindings, WorkflowAgentState> {
     }
   }
 
-  // ── HITL form state ───────────────────────────────────────────────────
+  // ── Form state ────────────────────────────────────────────────────────
 
   /**
-   * Check if a HITL form has already been submitted.
+   * Check if a form has already been submitted.
    * Returns `{ submitted: boolean }`.
    */
-  async getHitlFormStatus(token: string): Promise<{ submitted: boolean }> {
-    const key = WorkflowAgent.STORAGE_PREFIX_HITL + token;
+  async getFormStatus(
+    token: string
+  ): Promise<{ submitted: boolean; schema?: string }> {
+    const key = WorkflowAgent.STORAGE_PREFIX_FORM + token;
     const record = await this.storage.get<{ submitted: boolean }>(key);
-    return { submitted: record?.submitted ?? false };
+    const schema = await this.storage.get<string>(key + ":schema");
+    return {
+      submitted: record?.submitted ?? false,
+      ...(schema ? { schema } : {}),
+    };
   }
 
   /**
-   * Atomically check-and-submit a HITL form response.
+   * Atomically check-and-submit a form response.
    * Rejects duplicate submissions. On success, sends the event to the
    * EXECUTE workflow instance to resume the paused node.
    */
-  async checkAndSubmitHitlForm(
+  async checkAndSubmitForm(
     token: string,
     executionId: string,
-    response: { text?: string; approved?: boolean; metadata?: Record<string, unknown> }
+    response: Record<string, unknown>
   ): Promise<{ success: boolean; error?: string }> {
-    const key = WorkflowAgent.STORAGE_PREFIX_HITL + token;
+    const key = WorkflowAgent.STORAGE_PREFIX_FORM + token;
     const existing = await this.storage.get<{ submitted: boolean }>(key);
 
     if (existing?.submitted) {
@@ -606,19 +643,15 @@ export class WorkflowAgent extends Agent<Bindings, WorkflowAgentState> {
     try {
       const instance = await this.env.EXECUTE.get(executionId);
       await instance.sendEvent({
-        type: `hitl-response-${token}`,
+        type: `form-response-${token}`,
         payload: {
-          outputs: {
-            response: response.text ?? "",
-            approved: response.approved ?? false,
-            metadata: response.metadata ?? {},
-          },
+          outputs: { response },
           usage: 0,
         },
       });
       return { success: true };
     } catch (error) {
-      console.error("Failed to send HITL event:", error);
+      console.error("Failed to send form event:", error);
       return {
         success: false,
         error: "Failed to resume workflow. The execution may have expired.",

apps/api/src/mocks/node-registry.ts

@@ -6,8 +6,8 @@ import {
 import { NumberInputNode } from "@dafthunk/runtime/nodes/input/number-input-node";
 import { ConditionalForkNode } from "@dafthunk/runtime/nodes/logic/conditional-fork-node";
 import { ConditionalJoinNode } from "@dafthunk/runtime/nodes/logic/conditional-join-node";
-import { HitlFormNode } from "@dafthunk/runtime/nodes/logic/hitl-form-node";
-import { HitlWaitNode } from "@dafthunk/runtime/nodes/logic/hitl-wait-node";
+import { CreateFormNode } from "@dafthunk/runtime/nodes/logic/create-form-node";
+import { WaitForFormNode } from "@dafthunk/runtime/nodes/logic/wait-for-form-node";
 import { AdditionNode } from "@dafthunk/runtime/nodes/math/addition-node";
 import { AvgNode } from "@dafthunk/runtime/nodes/math/avg-node";
 import { DivisionNode } from "@dafthunk/runtime/nodes/math/division-node";
@@ -31,7 +31,7 @@ import type { Bindings } from "../context";
  * - Addition, Subtraction, Multiplication, Division
  * - Number Input
  * - Sum, Max, Min, Avg, Median
- * - Conditional Fork, Conditional Join, HITL Form, HITL Wait
+ * - Conditional Fork, Conditional Join, Create Form, Wait for Form
  * - Multi-Step Addition, Failing Multi-Step (test nodes)
  */
 export class MockNodeRegistry extends BaseNodeRegistry<Bindings> {
@@ -48,8 +48,8 @@ export class MockNodeRegistry extends BaseNodeRegistry<Bindings> {
     this.registerImplementation(MedianNode);
     this.registerImplementation(ConditionalForkNode);
     this.registerImplementation(ConditionalJoinNode);
-    this.registerImplementation(HitlFormNode);
-    this.registerImplementation(HitlWaitNode);
+    this.registerImplementation(CreateFormNode);
+    this.registerImplementation(WaitForFormNode);
     this.registerImplementation(MultiStepAdditionNode);
     this.registerImplementation(FailingMultiStepNode);
   }

apps/api/src/routes/forms.ts

@@ -1,12 +1,12 @@
 /**
- * Public HITL Form Routes
+ * Public Form Routes
  *
  * These routes are unauthenticated — the signed token IS the authorization.
  * They allow external users to view and submit human-in-the-loop forms
  * via a shareable URL.
  */
 
-import { verifyHitlToken } from "@dafthunk/runtime";
+import { verifyFormToken } from "@dafthunk/runtime";
 import { Hono } from "hono";
 
 import type { ApiContext } from "../context";
@@ -17,25 +17,38 @@ const formRoutes = new Hono<ApiContext>();
 /**
  * GET /forms/:signedToken
  *
- * Returns the form configuration (prompt, context, input type) and
+ * Returns the form configuration (title, description, fields) and
  * submission status. No authentication required.
  */
 formRoutes.get("/:signedToken", async (c) => {
   const signedToken = c.req.param("signedToken");
-  const payload = await verifyHitlToken(signedToken, c.env.HITL_SIGNING_KEY);
+  const payload = await verifyFormToken(signedToken, c.env.FORM_SIGNING_KEY);
 
   if (!payload) {
     return c.json({ error: "Invalid or expired form link" }, 400);
   }
 
   try {
     const agent = await getAgentByName(c.env.WORKFLOW_AGENT, payload.wid);
-    const { submitted } = await agent.getHitlFormStatus(payload.tok);
+    const { submitted, schema } = await agent.getFormStatus(payload.tok);
+
+    if (!schema) {
+      return c.json(
+        { error: "Form schema not yet available. Please try again shortly." },
+        404
+      );
+    }
+
+    const parsed = JSON.parse(schema) as {
+      title: string;
+      description?: string;
+      fields: Array<{ name: string; type: string; required?: boolean }>;
+    };
 
     return c.json({
-      prompt: payload.p,
-      context: payload.c,
-      inputType: payload.t,
+      title: parsed.title,
+      description: parsed.description,
+      fields: parsed.fields,
       submitted,
     });
   } catch (error) {
@@ -52,28 +65,20 @@ formRoutes.get("/:signedToken", async (c) => {
  */
 formRoutes.post("/:signedToken", async (c) => {
   const signedToken = c.req.param("signedToken");
-  const payload = await verifyHitlToken(signedToken, c.env.HITL_SIGNING_KEY);
+  const payload = await verifyFormToken(signedToken, c.env.FORM_SIGNING_KEY);
 
   if (!payload) {
     return c.json({ error: "Invalid or expired form link" }, 400);
   }
 
-  const body = await c.req.json<{
-    text?: string;
-    approved?: boolean;
-    metadata?: Record<string, unknown>;
-  }>();
+  const body = await c.req.json<Record<string, unknown>>();
 
   try {
     const agent = await getAgentByName(c.env.WORKFLOW_AGENT, payload.wid);
-    const result = await agent.checkAndSubmitHitlForm(
+    const result = await agent.checkAndSubmitForm(
       payload.tok,
       payload.eid,
-      {
-        text: body.text,
-        approved: body.approved,
-        metadata: body.metadata,
-      }
+      body
     );
 
     if (!result.success) {

apps/api/src/routes/types.test.ts

@@ -203,6 +203,7 @@ describe("Types Route Tests", () => {
             "json",
             "document",
             "audio",
+            "schema",
             "any",
           ]).toContain(input.type);
         });

apps/api/src/runtime/cloudflare-node-registry.ts

@@ -352,8 +352,8 @@ import { LikePostLinkedInNode } from "@dafthunk/runtime/nodes/linkedin/like-post
 import { SharePostLinkedInNode } from "@dafthunk/runtime/nodes/linkedin/share-post-linkedin-node";
 import { ConditionalForkNode } from "@dafthunk/runtime/nodes/logic/conditional-fork-node";
 import { ConditionalJoinNode } from "@dafthunk/runtime/nodes/logic/conditional-join-node";
-import { HitlFormNode } from "@dafthunk/runtime/nodes/logic/hitl-form-node";
-import { HitlWaitNode } from "@dafthunk/runtime/nodes/logic/hitl-wait-node";
+import { CreateFormNode } from "@dafthunk/runtime/nodes/logic/create-form-node";
+import { WaitForFormNode } from "@dafthunk/runtime/nodes/logic/wait-for-form-node";
 import { AbsoluteValueNode } from "@dafthunk/runtime/nodes/math/absolute-value-node";
 import { AdditionNode } from "@dafthunk/runtime/nodes/math/addition-node";
 import { AvgNode } from "@dafthunk/runtime/nodes/math/avg-node";
@@ -674,8 +674,8 @@ export class CloudflareNodeRegistry extends BaseNodeRegistry<Bindings> {
     this.registerImplementation(BooleanInputNode);
     this.registerImplementation(ConditionalForkNode);
     this.registerImplementation(ConditionalJoinNode);
-    this.registerImplementation(HitlFormNode);
-    this.registerImplementation(HitlWaitNode);
+    this.registerImplementation(CreateFormNode);
+    this.registerImplementation(WaitForFormNode);
 
     // Image operations
     this.registerImplementation(PhotonAddNoiseNode);

apps/api/src/utils/encryption.test.ts

@@ -33,7 +33,7 @@ const createMockEnv = (masterKey?: string): Bindings => ({
   WEBSITE_URL: "",
   EMAIL_DOMAIN: "",
   JWT_SECRET: "",
-  HITL_SIGNING_KEY: "test-hitl-signing-key",
+  FORM_SIGNING_KEY: "test-form-signing-key",
   CLOUDFLARE_ENV: "",
   CLOUDFLARE_ACCOUNT_ID: "",
   CLOUDFLARE_API_TOKEN: "",

apps/app/src/components/workflow/use-workflow-execution-state.ts

@@ -231,7 +231,6 @@ export function useWorkflowExecutionState({
             outputs: nodeExecution.outputs || {},
             error: nodeExecution.error,
           });
-
         });
 
         if (execution.status === "exhausted") {