CSM Playbooks API

Express API to define playbooks with dependent steps and execute them with parallelism and failure handling.

Quick Start

Prereqs: Node.js v22+

1. Install dependencies:

   npm install

2. Build and start the server (TypeScript):

   npm run build && npm start

   • For development with live TypeScript execution:

     npm run dev

Project Structure

• src/server.ts: Bootstrap and HTTP server
• src/web/app.ts: Express app factory, middleware wiring
• src/web/config/env.ts: Environment parsing/validation (zod)
• src/web/middleware/*: Not-found and error handlers
• src/web/utils/asyncHandler.ts: Async route wrapper
• src/web/routes/*: Route definitions (v1, health)
• src/web/controllers/*: Request validation and orchestration
• src/services/*: Core services (executor, storage)
• src/types.ts: Shared domain types

3. Health check:

   curl http://localhost:3000/health

API

• POST /api/v1/playbooks – Create a playbook
• GET /api/v1/playbooks – List playbooks
• GET /api/v1/playbooks/:id – Fetch a playbook
• POST /api/v1/runs – Trigger a run
• GET /api/v1/runs/:id – Fetch run status/logs
• GET /health – Health check

Example

Create a playbook:

curl -X POST http://localhost:3000/api/v1/playbooks
-H "Content-Type: application/json"
-d '{ "name": "Customer Health Check", "steps": [ {"id": "fetch-metrics", "type": "transform", "config": {"metric": "login_frequency"}}, {"id": "fetch-support", "type": "transform", "config": {"source": "support_tickets"}}, {"id": "analyze-health", "type": "llm", "config": {"prompt": "Analyze customer health from metrics and support tickets"}, "dependencies": ["fetch-metrics", "fetch-support"]} ] }'

Trigger a run:

curl -X POST http://localhost:3000/api/v1/runs
-H "Content-Type: application/json"
-d '{"playbookId": "", "context": {"customerId": "cust_789"}}'

Check status:

curl http://localhost:3000/api/v1/runs/

Execution Engine

Dependency resolution

• Validates step IDs are unique and all dependencies reference existing steps.
• Runs steps in parallel "waves": any steps whose dependencies are completed start together.
• Detects deadlocks/cycles: if no runnable steps remain while steps are unfinished, the run fails.

Step behavior

• transform: sleeps 1–3s, returns { transformed: true, input }.
• llm (default mock): returns { text: "mocked output", prompt, input }.
• Failure simulation: each step has a 10% chance to fail; on first failure the run is marked failed and no further steps are scheduled (in-flight steps may still complete).

Inputs/outputs

• Each step receives { config, context, deps } where deps is a map of dependency step outputs.
• Run status includes per-step status and output; top-level output aggregates all step outputs.

Notes

• Storage is in-memory and resets on restart.
• The llm step type returns a mocked response by default.