@positronic/template-new-project 0.0.49 → 0.0.52

package/index.js

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

package/package.json

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

package/template/.positronic/src/index.ts

@@ -8,10 +8,13 @@ import {
   ScheduleDO,
   PositronicManifest,
 } from "@positronic/cloudflare";
-// Import the generated manifest - NOTE the .js extension for runtime compatibility
+// Import the generated manifests - NOTE the .js extension for runtime compatibility
 // @ts-expect-error - _manifest.js is generated during template processing
 import { manifest as brainManifest } from "./_manifest.js";
+// @ts-expect-error - _webhookManifest.js is generated during template processing
+import { webhookManifest } from "./_webhookManifest.js";
 import { runner } from "./runner.js";
+
 // Configure the manifest to use the statically generated list
 const manifest = new PositronicManifest({
   manifest: brainManifest,
@@ -19,12 +22,7 @@ const manifest = new PositronicManifest({
 
 setManifest(manifest);
 setBrainRunner(runner);
-
-// Register webhooks here if your brains use waitFor with webhooks
-// Example:
-// import { myWebhook } from '../../webhooks/my-webhook.js';
-// setWebhookManifest({ 'my-webhook': myWebhook });
-setWebhookManifest({});
+setWebhookManifest(webhookManifest);
 
 // Define Env type based on wrangler.jsonc bindings
 interface Env {

package/template/CLAUDE.md

@@ -9,6 +9,7 @@ This is a Positronic project - an AI-powered framework for building and running
 ## Project Structure
 
 - **`/brains`** - AI workflow definitions using the Brain DSL
+- **`/webhooks`** - Webhook definitions for external integrations (auto-discovered)
 - **`/resources`** - Files and documents that brains can access via the resource system
 - **`/tests`** - Test files for brains (kept separate to avoid deployment issues)
 - **`/docs`** - Documentation including brain testing guide
@@ -61,6 +62,69 @@ export default myBrain;
 
 Resources are files that brains can access during execution. They're stored in the `/resources` directory and are automatically typed based on the manifest.
 
+## Webhooks
+
+Webhooks allow brains to pause execution and wait for external events (like form submissions, API callbacks, or user approvals). Webhooks are auto-discovered from the `/webhooks` directory.
+
+### Creating a Webhook
+
+Create a file in the `/webhooks` directory with a default export:
+
+```typescript
+// webhooks/approval.ts
+import { createWebhook } from '@positronic/core';
+import { z } from 'zod';
+
+const approvalWebhook = createWebhook(
+  'approval',  // webhook name (should match filename)
+  z.object({   // response schema - what the webhook returns to the brain
+    approved: z.boolean(),
+    reviewerNote: z.string().optional(),
+  }),
+  async (request: Request) => {
+    // Parse the incoming request and return identifier + response
+    const body = await request.json();
+    return {
+      type: 'webhook',
+      identifier: body.requestId,  // matches the identifier used in waitFor
+      response: {
+        approved: body.approved,
+        reviewerNote: body.note,
+      },
+    };
+  }
+);
+
+export default approvalWebhook;
+```
+
+### Using Webhooks in Brains
+
+Import the webhook and use it with `waitFor`:
+
+```typescript
+import { brain } from '../brain.js';
+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
+  }))
+  .step('Process approval', ({ state, response }) => ({
+    ...state,
+    status: response.approved ? 'approved' : 'rejected',
+    reviewerNote: response.reviewerNote,
+  }));
+```
+
+### How Auto-Discovery Works
+
+- Place webhook files in `/webhooks` directory
+- Each file must have a default export using `createWebhook()`
+- The dev server generates `_webhookManifest.ts` automatically
+- Webhook name comes from the filename (e.g., `approval.ts` → `'approval'`)
+
 ## Development Workflow
 
 1. Define your brain in `/brains`