@positronic/template-new-project 0.0.63 → 0.0.65

package/index.js

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

package/package.json

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

package/template/CLAUDE.md

@@ -111,7 +111,7 @@ export default brain('approval-workflow')
   .step('Request approval', ({ state }) => ({
     ...state, status: 'pending',
   }))
-  .wait('Wait for approval', ({ state }) => approvalWebhook(state.requestId))
+  .wait('Wait for approval', ({ state }) => approvalWebhook(state.requestId), { timeout: '24h' })
   .step('Process approval', ({ state, response }) => ({
     ...state,
     status: response.approved ? 'approved' : 'rejected',
@@ -119,6 +119,18 @@ export default brain('approval-workflow')
   }));
 ```
 
+The optional `timeout` parameter accepts durations like `'30m'`, `'1h'`, `'24h'`, `'7d'`, or a number in milliseconds. If the timeout elapses without a webhook response, the brain is cancelled. Without a timeout, the brain waits indefinitely.
+
+### 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

@@ -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
@@ -1003,6 +999,7 @@ Key points about tool `waitFor`:
 - You can wait for multiple webhooks (first response wins): `{ waitFor: [webhook1(...), webhook2(...)] }`
 - The `execute` function receives a `context` parameter with access to `state`, `options`, `env`, etc.
 - Use this pattern for approvals, external API callbacks, or any human-in-the-loop workflow
+- The built-in `waitForWebhook` tool defaults to a 1-hour timeout. Agents can customize via the `timeout` parameter (e.g., "30m", "24h", "7d"). If the timeout elapses, the brain is cancelled.
 
 ### Agent Output Schema
 
@@ -1103,6 +1100,87 @@ 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), { timeout: '24h' })
+  .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 `.wait()` to pause until the form is submitted.
@@ -1133,8 +1211,8 @@ brain('Feedback Collector')
     await slack.post('#feedback', `Please fill out: <%= '${page.url}' %>`);
     return state;
   })
-  // Wait for form submission
-  .wait('Wait for submission', ({ page }) => page.webhook)
+  // Wait for form submission (timeout after 24 hours, brain is cancelled if no response)
+  .wait('Wait for submission', ({ page }) => page.webhook, { timeout: '24h' })
   // Process the form data (comes through response, not page)
   .step('Process Feedback', ({ state, response }) => ({
     ...state,