@positronic/template-new-project 0.0.61 → 0.0.63

package/index.js

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

package/package.json

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

package/template/.positronic/wrangler.jsonc

@@ -6,6 +6,9 @@
   "compatibility_flags": ["nodejs_compat", "nodejs_compat_populate_process_env"],
   "workers_dev": true,
   "preview_urls": true,
+  "limits": {
+    "cpu_ms": 300000
+  },
   "migrations": [
     {
       "tag": "v1",

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',

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

@@ -157,6 +157,43 @@ const mainBrain = brain('Main Process')
   );
 ```
 
+## Guard Clauses
+
+Use `.guard()` to short-circuit a brain when a condition isn't met. If the predicate returns `true`, execution continues normally. If it returns `false`, all remaining steps are skipped and the brain completes with the current state.
+
+```typescript
+brain('email-checker')
+  .step('Check Emails', async ({ state, client }) => {
+    const emails = await analyzeEmails(client, state);
+    return { ...state, emails };
+  })
+  .guard(({ state }) => state.emails.some(e => e.important))
+  // everything below only runs if guard passes
+  .ui('Review emails', { ... })
+  .step('Notify and wait', ...)
+  .step('Handle response', ...);
+```
+
+Key points:
+- The predicate is synchronous and receives `{ state, options }`
+- Returns `true` to continue, `false` to skip all remaining steps
+- The guard doesn't transform state — if you need to set "early exit" fields, do it in the step before the guard
+- State type is unchanged after a guard (subsequent steps see the same type)
+- Multiple guards can be chained — the first one that fails skips everything after it
+- Halted steps appear as "halted" in the CLI watch view
+- An optional title can be passed as the second argument: `.guard(predicate, 'Check emails exist')`
+
+### Multiple Guards
+
+```typescript
+brain('processor')
+  .step('Init', () => ({ data: [], validated: false }))
+  .guard(({ state }) => state.data.length > 0, 'Has data')
+  .step('Validate', ({ state }) => ({ ...state, validated: true }))
+  .guard(({ state }) => state.validated, 'Is valid')
+  .step('Process', ({ state }) => ({ ...state, processed: true }));
+```
+
 ## Step Parameters
 
 Each step receives these parameters:
@@ -165,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)
@@ -831,12 +868,7 @@ brain('Batch Processor')
     over: (state) => state.items,  // Array to iterate over
     concurrency: 10,               // Parallel requests (default: 10)
     stagger: 100,                  // Delay between requests in ms
-    retry: {
-      maxRetries: 3,
-      backoff: 'exponential',
-      initialDelay: 1000,
-      maxDelay: 30000,
-    },
+    maxRetries: 3,
     error: (item, error) => ({ summary: 'Failed to summarize' })  // Fallback on error
   })
   .step('Process Results', ({ state }) => ({
@@ -854,7 +886,7 @@ brain('Batch Processor')
 - `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
-- `retry: RetryConfig` - Retry configuration for failed requests
+- `maxRetries: number` - Maximum number of retries for failed requests (passed to the AI client SDK)
 - `error: (item, error) => Response` - Fallback function when a request fails
 
 ### Result Format
@@ -917,7 +949,60 @@ brain('Research Assistant')
 Each tool requires:
 - `description: string` - What the tool does
 - `inputSchema: ZodSchema` - Zod schema for the tool's input
-- `execute: (input) => Promise<any>` - Function to execute when the tool is called
+- `execute: (input, context) => Promise<any>` - Function to execute when the tool is called
+- `terminal?: boolean` - If true, calling this tool ends the agent loop
+
+### Tool Webhooks (waitFor)
+
+Tools can pause agent execution and wait for external events by returning `{ waitFor: webhook(...) }` from their `execute` function. This is useful for human-in-the-loop workflows where the agent needs to wait for approval, external API callbacks, or other asynchronous events.
+
+```typescript
+import approvalWebhook from '../webhooks/approval.js';
+
+brain('Support Ticket Handler')
+  .brain('Handle Support Request', {
+    system: 'You are a support agent. Escalate complex issues for human review.',
+    prompt: ({ ticket }) => `Handle this support ticket: <%= '${ticket.description}' %>`,
+    tools: {
+      escalateToHuman: {
+        description: 'Escalate the ticket to a human reviewer for approval',
+        inputSchema: z.object({
+          summary: z.string().describe('Summary of the issue'),
+          recommendation: z.string().describe('Your recommended action'),
+        }),
+        execute: async ({ summary, recommendation }, context) => {
+          // Send notification to human reviewer (e.g., via Slack, email)
+          await notifyReviewer({ summary, recommendation, ticketId: context.state.ticketId });
+
+          // Return waitFor to pause until the webhook fires
+          return {
+            waitFor: approvalWebhook(context.state.ticketId),
+          };
+        },
+      },
+      resolveTicket: {
+        description: 'Mark the ticket as resolved',
+        inputSchema: z.object({
+          resolution: z.string().describe('How the ticket was resolved'),
+        }),
+        terminal: true,
+      },
+    },
+  })
+  .step('Process Result', ({ state, response }) => ({
+    ...state,
+    // response contains the webhook data (e.g., { approved: true, reviewerNote: '...' })
+    approved: response?.approved,
+    reviewerNote: response?.reviewerNote,
+  }));
+```
+
+Key points about tool `waitFor`:
+- Return `{ waitFor: webhook(...) }` to pause the agent and wait for an external event
+- The webhook response is available in the next step via the `response` parameter
+- 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
 
 ### Agent Output Schema
 
@@ -1020,7 +1105,7 @@ The created page object contains:
 
 ## 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
 
@@ -1043,14 +1128,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,
@@ -1066,8 +1150,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
 
@@ -1140,10 +1224,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 },
@@ -1162,10 +1247,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

@@ -105,6 +105,26 @@ kill $(lsof -ti:38291)
 - Always clean up by killing the server process when done
 - The log file contains timestamped entries with [INFO], [ERROR], and [WARN] prefixes
 
+## Guard Clauses
+
+Use `.guard()` to short-circuit a brain when a condition isn't met:
+
+```typescript
+brain('approval-example')
+  .step('Init', () => ({ needsApproval: true, data: [] }))
+  .guard(({ state }) => state.data.length > 0, 'Has data')
+  // everything below only runs if guard passes
+  .step('Process', ({ state }) => ({ ...state, processed: true }))
+  .step('Continue', ({ state }) => ({ ...state, done: true }));
+```
+
+Key rules:
+- Predicate returns `true` to continue, `false` to skip all remaining steps
+- The predicate is synchronous and receives `{ state, options }`
+- State type is unchanged after a guard
+- Optional title as second argument: `.guard(predicate, 'Check condition')`
+- See `/docs/brain-dsl-guide.md` for more details
+
 ## Brain DSL Type Inference
 
 The Brain DSL has very strong type inference capabilities. **Important**: You should NOT explicitly specify types on the state object as it flows through steps. The types are automatically inferred from the previous step.
@@ -187,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';
@@ -211,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,
@@ -226,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.