Server: Auto-Generated A2H Forms

[ggondim]

Summary

Implement the auto-generated form system for A2H reply methods 3 and 4. When inline channel primitives are insufficient, OpenThreads generates a temporary web form for the human to respond.

Tasks

• GET /form/:turnId — renders a temporary form page
• Form generation from A2H intent schema:
  • AUTHORIZE → approve/deny buttons with context display
  • COLLECT single field → text input with label
  • COLLECT multiple fields → multi-field form
  • COLLECT closed options → radio buttons or checkboxes
  • Batch (method 4) → all intents grouped on a single page
• Form submission: POST /form/:turnId → validate, store response, resolve blocking intent
• TTL-based expiry: form URL expires with the ephemeral token
• Minimal, responsive UI (Ant Design 5)
• No authentication by default; trust layer adds WebAuthn/OTP when active
• Loading, success, error, and expired states

Acceptance Criteria

• AUTHORIZE intent → form with context + approve/deny buttons
• COLLECT single field → form with labeled text input
• COLLECT multiple fields → multi-field form with validation
• Batch intents → single page with all questions
• Expired form → clear error message
• Form submit resolves the blocking intent and returns response to recipient
• Mobile-responsive layout

Dependencies

• Core: Reply Engine #4 (Core: Reply Engine) — reply engine triggers form generation for methods 3/4
• Server: API Routes & Infrastructure #11 (Server: API Routes) — forms are served by the same Next.js app

References

• VISION.md — Method 3 & 4
• PLAN.md — Phase 4.2

[claude]

@claude Implement this issue.

• Base branch: meta/17
• Target your PR to meta/17
• Include fixes #12 in the PR body

[claude]

Claude finished @claude[bot]'s task in 12m 12s —— View job • claude/17-issue-12-20260410-2244 • Create PR ➔

---

Implementing Issue #12: Server: Auto-Generated A2H Forms

Tasks

• Gather context and explore codebase
• Understand A2H types, turn records, and reply engine
• Add Ant Design 5 dependency to package.json
• Add FormRecord type and CRUD functions to db.ts
• Create global form response registry (lib/form-registry.ts)
• Create GET /form/[formKey] page (server component + client component)
  • AUTHORIZE → approve/deny radio buttons + context display + optional comment
  • COLLECT single free-text field → labeled textarea
  • COLLECT multiple fields → multi-field form with typed inputs
  • COLLECT closed options → Select, Radio.Group, or Checkbox.Group
  • Batch (method 4) → all intents on a single page, one submit
  • Loading, success, error, and expired states
• Create POST /api/form/[formKey] — form submission API
• Update layout.tsx for Ant Design 5 SSR support (AntdRegistry)
• Commit and push changes

What was implemented

New files:

• packages/server/src/app/form/[formKey]/page.tsx — Server component: lazily creates a FormRecord from the turn on first access, checks TTL expiry, passes data to client component
• packages/server/src/app/form/[formKey]/FormClient.tsx — Client component (Ant Design 5): renders AUTHORIZE/COLLECT/batch forms with full validation, handles loading/success/error/expired states
• packages/server/src/app/api/form/[formKey]/route.ts — GET returns form metadata; POST validates response count/shape, marks form submitted in MongoDB, resolves the in-process formRegistry promise to unblock the Reply Engine
• packages/server/src/lib/form-registry.ts — Global singleton FormResponseRegistry (attached to globalThis for hot-reload persistence); the Reply Engine calls .wait(key, intent) and the form API calls .submit(key, response) to unblock it

Modified files:

• packages/server/src/lib/db.ts — Added FormRecord type + createFormRecord/getFormRecord/updateFormRecord, MongoDB forms collection index (unique on formKey, TTL on expiresAt)
• packages/server/src/app/layout.tsx — Wrapped with AntdRegistry for Next.js SSR support
• packages/server/package.json — Added antd ^5, @ant-design/icons ^5, @ant-design/nextjs-registry ^1
• packages/server/next.config.ts — Added optimizePackageImports: ['antd']

Design decisions:

• Form records are created lazily on first GET (no separate creation step needed in the send route)
• TTL matches REPLY_TOKEN_TTL env var (default 24h)
• Batch form uses field name prefix ${intentIndex}_ to namespace fields from different intents
• No auth on form page by default ("trust layer adds WebAuthn/OTP when active" — per spec)
• formRegistry uses globalThis singleton so it survives Next.js module hot-reloads

[github-actions]

⚠️ Task worker failed. View logs

To retry with fix context, comment @claude fix on this issue.

[ggondim]

@claude fix

[claude]

Claude finished @ggondim's task in 7m 22s —— View job • claude/17-issue-12-20260410-2321 • Create PR ➔

---

Fixing Issue #12: Server: Auto-Generated A2H Forms

Tasks

• Gather context and read CLAUDE.md
• Read previous implementation and identify failure — previous job on claude/17-issue-12-20260410-2244 had the correct implementation but the task worker failed; re-applied all changes to this branch
• Apply the full implementation
• Verify TypeScript path aliases and types are consistent
• Commit and push

What was implemented

New files:

• packages/server/src/app/form/[formKey]/page.tsx — Server component: lazily creates a FormRecord from the turn on first access, checks TTL expiry, passes data to client component
• packages/server/src/app/form/[formKey]/FormClient.tsx — Client component (Ant Design 5): renders AUTHORIZE/COLLECT/batch forms with full validation, handles loading/success/error/expired states
• packages/server/src/app/api/form/[formKey]/route.ts — GET returns form metadata; POST validates responses, marks form submitted in MongoDB, resolves the in-process formRegistry promise to unblock the Reply Engine
• packages/server/src/lib/form-registry.ts — Global singleton FormResponseRegistry (attached to globalThis for hot-reload persistence)

Modified files:

• packages/server/src/lib/db.ts — Added FormRecord type + createFormRecord/getFormRecord/updateFormRecord, MongoDB forms collection index (unique on formKey, TTL on expiresAt)
• packages/server/src/app/layout.tsx — Wrapped with AntdRegistry for Next.js SSR support
• packages/server/package.json — Added antd ^5, @ant-design/icons ^5, @ant-design/nextjs-registry ^1
• packages/server/next.config.ts — Added optimizePackageImports: ['antd']

• claude/17-issue-12-20260410-2321

[github-actions]

✅ Fix agent succeeded. View run