@positronic/template-new-project 0.0.61 → 0.0.62

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.62';
+    let cloudflareVersion = '^0.0.62';
+    let clientVercelVersion = '^0.0.62';
+    let genUIComponentsVersion = '^0.0.62';
 
     // 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.62",
   "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/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:
@@ -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
 

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.