@positronic/template-new-project 0.0.62 → 0.0.64

package/index.js

@@ -53,10 +53,10 @@ module.exports = {
   ],
   setup: async ctx => {
     const devRootPath = process.env.POSITRONIC_LOCAL_PATH;
-    let coreVersion = '^0.0.62';
-    let cloudflareVersion = '^0.0.62';
-    let clientVercelVersion = '^0.0.62';
-    let genUIComponentsVersion = '^0.0.62';
+    let coreVersion = '^0.0.64';
+    let cloudflareVersion = '^0.0.64';
+    let clientVercelVersion = '^0.0.64';
+    let genUIComponentsVersion = '^0.0.64';
 
     // Map backend selection to package names
     const backendPackageMap = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@positronic/template-new-project",
-  "version": "0.0.62",
+  "version": "0.0.64",
   "publishConfig": {
     "access": "public"
   },

package/template/CLAUDE.md

@@ -101,7 +101,7 @@ export default approvalWebhook;
 
 ### Using Webhooks in Brains
 
-Import the webhook and use it with `waitFor`:
+Import the webhook and use `.wait()` to pause execution:
 
 ```typescript
 import { brain } from '../brain.js';
@@ -109,9 +109,9 @@ import approvalWebhook from '../webhooks/approval.js';
 
 export default brain('approval-workflow')
   .step('Request approval', ({ state }) => ({
-    state: { ...state, status: 'pending' },
-    waitFor: [approvalWebhook(state.requestId)],  // pause and wait
+    ...state, status: 'pending',
   }))
+  .wait('Wait for approval', ({ state }) => approvalWebhook(state.requestId))
   .step('Process approval', ({ state, response }) => ({
     ...state,
     status: response.approved ? 'approved' : 'rejected',
@@ -119,6 +119,16 @@ export default brain('approval-workflow')
   }));
 ```
 
+### CSRF Tokens for Pages with Forms
+
+If your brain generates a custom HTML page with a form that submits to a webhook, you must include a CSRF token. Without a token, the server will reject the submission.
+
+1. Generate a token with `generateFormToken()` from `@positronic/core`
+2. Add `<input type="hidden" name="__positronic_token" value="${token}">` to the form
+3. Pass the token when creating the webhook registration: `myWebhook(identifier, token)`
+
+The `.ui()` step handles this automatically. See `/docs/brain-dsl-guide.md` for full examples.
+
 ### How Auto-Discovery Works
 
 - Place webhook files in `/webhooks` directory

package/template/_gitignore

@@ -5,6 +5,7 @@ node_modules/
 
 # Local development server directory
 .positronic/
+.positronic-auth.json
 .env
 
 # Cloudflare Wrangler state and temp files

package/template/docs/brain-dsl-guide.md

@@ -202,7 +202,7 @@ Each step receives these parameters:
 - `client` - AI client for generating structured objects
 - `resources` - Loaded resources (files, documents, etc.)
 - `options` - Runtime options passed to the brain
-- `response` - Webhook response data (available after `waitFor` completes)
+- `response` - Webhook response data (available after `.wait()` completes)
 - `page` - Generated page object (available after `.ui()` step)
 - `pages` - Pages service for HTML page management
 - `env` - Runtime environment containing `origin` (base URL) and `secrets` (typed secrets object)
@@ -867,8 +867,6 @@ brain('Batch Processor')
   }, {
     over: (state) => state.items,  // Array to iterate over
     concurrency: 10,               // Parallel requests (default: 10)
-    stagger: 100,                  // Delay between requests in ms
-    maxRetries: 3,
     error: (item, error) => ({ summary: 'Failed to summarize' })  // Fallback on error
   })
   .step('Process Results', ({ state }) => ({
@@ -884,9 +882,7 @@ brain('Batch Processor')
 ### Batch Options
 
 - `over: (state) => T[]` - Function returning the array to iterate over
-- `concurrency: number` - Maximum parallel requests (default: 10)
-- `stagger: number` - Milliseconds to wait between starting requests
-- `maxRetries: number` - Maximum number of retries for failed requests (passed to the AI client SDK)
+- `concurrency: number` - Maximum number of items processed in parallel (default: 10)
 - `error: (item, error) => Response` - Fallback function when a request fails
 
 ### Result Format
@@ -1103,9 +1099,90 @@ The created page object contains:
 - `url: string` - Public URL to access the page
 - `webhook: WebhookConfig` - Webhook configuration for handling form submissions
 
+### Custom Pages with Forms (CSRF Token)
+
+When building custom HTML pages with forms, you must include a CSRF token to prevent unauthorized submissions. The `.ui()` step handles this automatically, but custom pages require manual setup. This applies whether you submit to the built-in `ui-form` endpoint or to a custom webhook.
+
+#### Using a Custom Webhook
+
+If your page submits to a custom webhook (e.g., `/webhooks/archive`), pass the token as the second argument when creating the webhook registration:
+
+```typescript
+import { generateFormToken } from '@positronic/core';
+import archiveWebhook from '../webhooks/archive.js';
+
+brain('Archive Workflow')
+  .step('Create Page', async ({ state, pages, env }) => {
+    const formToken = generateFormToken();
+
+    const html = `<html>
+      <body>
+        <form method="POST" action="<%= '${env.origin}' %>/webhooks/archive">
+          <input type="hidden" name="__positronic_token" value="<%= '${formToken}' %>">
+          <input type="text" name="name" placeholder="Your name">
+          <button type="submit">Submit</button>
+        </form>
+      </body>
+    </html>`;
+
+    await pages.create('my-page', html);
+    return { ...state, formToken };
+  })
+  .wait('Wait for submission', ({ state }) => archiveWebhook(state.sessionId, state.formToken))
+  .step('Process', ({ state, response }) => ({
+    ...state,
+    name: response.name,
+  }));
+```
+
+#### Using the System `ui-form` Endpoint
+
+If your page submits to the built-in `ui-form` endpoint, include the token in the webhook registration object:
+
+```typescript
+import { generateFormToken } from '@positronic/core';
+
+brain('Custom Form')
+  .step('Create Form Page', async ({ state, pages, env }) => {
+    const formToken = generateFormToken();
+    const webhookIdentifier = `custom-form-<%= '${Date.now()}' %>`;
+    const formAction = `<%= '${env.origin}' %>/webhooks/system/ui-form?identifier=<%= '${encodeURIComponent(webhookIdentifier)}' %>`;
+
+    const page = await pages.create('my-form', `<html>
+      <body>
+        <form method="POST" action="<%= '${formAction}' %>">
+          <input type="hidden" name="__positronic_token" value="<%= '${formToken}' %>">
+          <input type="text" name="name" placeholder="Your name">
+          <button type="submit">Submit</button>
+        </form>
+      </body>
+    </html>`);
+
+    return {
+      ...state,
+      pageUrl: page.url,
+      webhook: { slug: 'ui-form', identifier: webhookIdentifier, token: formToken },
+    };
+  })
+  .wait('Wait for form', ({ state }) => state.webhook)
+  .step('Process', ({ state, response }) => ({
+    ...state,
+    name: response.name,
+  }));
+```
+
+#### Summary
+
+The three required pieces for any custom page with a form:
+1. Call `generateFormToken()` to get a token
+2. Add `<input type="hidden" name="__positronic_token" value="...">` to your form
+3. Include the `token` in your webhook registration — either as the second argument to a custom webhook function (e.g., `myWebhook(identifier, token)`) or in the registration object for `ui-form`
+
+Without a token, the server will reject the form submission.
+
 ## UI Steps
 
-UI steps allow brains to generate dynamic user interfaces using AI. The `.ui()` step generates a page and provides a `page` object to the next step. You then notify users and use `waitFor` to pause until the form is submitted.
+UI steps allow brains to generate dynamic user interfaces using AI. The `.ui()` step generates a page and provides a `page` object to the next step. You then notify users and use `.wait()` to pause until the form is submitted.
 
 ### Basic UI Step
 
@@ -1128,14 +1205,13 @@ brain('Feedback Collector')
       comments: z.string(),
     }),
   })
-  // Notify user and wait for submission
-  .step('Notify and Wait', async ({ state, page, slack }) => {
+  // Notify user
+  .step('Notify', async ({ state, page, slack }) => {
     await slack.post('#feedback', `Please fill out: <%= '${page.url}' %>`);
-    return {
-      state,
-      waitFor: [page.webhook],
-    };
+    return state;
   })
+  // Wait for form submission
+  .wait('Wait for submission', ({ page }) => page.webhook)
   // Process the form data (comes through response, not page)
   .step('Process Feedback', ({ state, response }) => ({
     ...state,
@@ -1151,8 +1227,8 @@ brain('Feedback Collector')
 2. **AI Generation**: The AI creates a component tree based on the prompt
 3. **Page Object**: Next step receives `page` with `url` and `webhook`
 4. **Notification**: You notify users however you want (Slack, email, etc.)
-5. **Wait**: Use `waitFor: [page.webhook]` to pause until form submission
-6. **Form Data**: Step after `waitFor` receives form data via `response`
+5. **Wait**: Use `.wait('title', ({ page }) => page.webhook)` to pause until form submission
+6. **Form Data**: Step after `.wait()` receives form data via `response`
 
 ### The `page` Object
 
@@ -1225,10 +1301,11 @@ brain('User Onboarding')
       dob: z.string(),
     }),
   })
-  .step('Wait for Personal', async ({ state, page, notify }) => {
+  .step('Notify Personal', async ({ state, page, notify }) => {
     await notify(`Step 1: <%= '${page.url}' %>`);
-    return { state, waitFor: [page.webhook] };
+    return state;
   })
+  .wait('Wait for Personal', ({ page }) => page.webhook)
   .step('Save Personal', ({ state, response }) => ({
     ...state,
     userData: { ...state.userData, ...response },
@@ -1247,10 +1324,11 @@ brain('User Onboarding')
       contactMethod: z.enum(['email', 'phone', 'sms']),
     }),
   })
-  .step('Wait for Preferences', async ({ state, page, notify }) => {
+  .step('Notify Preferences', async ({ state, page, notify }) => {
     await notify(`Step 2: <%= '${page.url}' %>`);
-    return { state, waitFor: [page.webhook] };
+    return state;
   })
+  .wait('Wait for Preferences', ({ page }) => page.webhook)
   .step('Complete', ({ state, response }) => ({
     ...state,
     userData: { ...state.userData, preferences: response },

package/template/docs/tips-for-agents.md

@@ -207,8 +207,8 @@ Most generated brains should not have try-catch blocks. Only use them when the e
 When you need to collect user input, use the `.ui()` method. The pattern is:
 1. `.ui()` generates the page
 2. Next step gets `page.url` and `page.webhook`
-3. Notify users and use `waitFor: [page.webhook]`
-4. Step after `waitFor` gets form data in `response`
+3. Notify users, then use `.wait()` with `page.webhook`
+4. Step after `.wait()` gets form data in `response`
 
 ```typescript
 import { z } from 'zod';
@@ -231,11 +231,13 @@ brain('feedback-collector')
       comments: z.string(),
     }),
   })
-  // Notify and wait for submission
+  // Notify users
   .step('Notify', async ({ state, page, slack }) => {
     await slack.post('#feedback', `Fill out: <%= '${page.url}' %>`);
-    return { state, waitFor: [page.webhook] };
+    return state;
   })
+  // Wait for form submission
+  .wait('Wait for submission', ({ page }) => page.webhook)
   // Form data comes through response (not page)
   .step('Process', ({ state, response }) => ({
     ...state,
@@ -246,8 +248,8 @@ brain('feedback-collector')
 
 Key points:
 - `page.url` - where to send users
-- `page.webhook` - use with `waitFor` to pause for submission
-- `response` - form data arrives here (in step after `waitFor`)
+- `page.webhook` - use with `.wait()` to pause for submission
+- `response` - form data arrives here (in step after `.wait()`)
 - You control how users are notified (Slack, email, etc.)
 
 See `/docs/brain-dsl-guide.md` for more UI step examples.