codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/dbos-typescript/references/pattern-sleep.md

@@ -0,0 +1,59 @@
+---
+title: Use Durable Sleep for Delayed Execution
+impact: MEDIUM
+impactDescription: Enables reliable scheduling across restarts
+tags: pattern, sleep, delay, durable, schedule
+---
+
+## Use Durable Sleep for Delayed Execution
+
+Use `DBOS.sleep()` for durable delays within workflows. The wakeup time is stored in the database, so the sleep survives restarts.
+
+**Incorrect (non-durable sleep):**
+
+```typescript
+async function delayedTaskFn() {
+  // setTimeout is not durable - lost on restart!
+  await new Promise(r => setTimeout(r, 60000));
+  await DBOS.runStep(doWork, { name: "doWork" });
+}
+const delayedTask = DBOS.registerWorkflow(delayedTaskFn);
+```
+
+**Correct (durable sleep):**
+
+```typescript
+async function delayedTaskFn() {
+  // Durable sleep - survives restarts
+  await DBOS.sleep(60000); // 60 seconds in milliseconds
+  await DBOS.runStep(doWork, { name: "doWork" });
+}
+const delayedTask = DBOS.registerWorkflow(delayedTaskFn);
+```
+
+`DBOS.sleep()` takes milliseconds (unlike Python which takes seconds).
+
+Use cases:
+- Scheduling tasks to run in the future
+- Implementing retry delays
+- Delays spanning hours, days, or weeks
+
+```typescript
+async function scheduledTaskFn(task: string) {
+  // Sleep for one week
+  await DBOS.sleep(7 * 24 * 60 * 60 * 1000);
+  await processTask(task);
+}
+```
+
+For getting the current time durably, use `DBOS.now()`:
+
+```typescript
+async function myWorkflowFn() {
+  const now = await DBOS.now(); // Checkpointed as a step
+  // For random UUIDs:
+  const id = await DBOS.randomUUID(); // Checkpointed as a step
+}
+```
+
+Reference: [Durable Sleep](https://docs.dbos.dev/typescript/tutorials/workflow-tutorial#durable-sleep)

package/templates/.agent/skills/dbos-typescript/references/queue-basics.md

@@ -0,0 +1,59 @@
+---
+title: Use Queues for Concurrent Workflows
+impact: HIGH
+impactDescription: Queues provide managed concurrency and flow control
+tags: queue, concurrency, enqueue, workflow
+---
+
+## Use Queues for Concurrent Workflows
+
+Queues run many workflows concurrently with managed flow control. Use them when you need to control how many workflows run at once.
+
+**Incorrect (uncontrolled concurrency):**
+
+```typescript
+async function processTaskFn(task: string) {
+  // ...
+}
+const processTask = DBOS.registerWorkflow(processTaskFn);
+
+// Starting many workflows without control - could overwhelm resources
+for (const task of tasks) {
+  await DBOS.startWorkflow(processTask)(task);
+}
+```
+
+**Correct (using a queue):**
+
+```typescript
+import { DBOS, WorkflowQueue } from "@dbos-inc/dbos-sdk";
+
+const queue = new WorkflowQueue("task_queue");
+
+async function processTaskFn(task: string) {
+  // ...
+}
+const processTask = DBOS.registerWorkflow(processTaskFn);
+
+async function processAllTasksFn(tasks: string[]) {
+  const handles = [];
+  for (const task of tasks) {
+    // Enqueue by passing queueName to startWorkflow
+    const handle = await DBOS.startWorkflow(processTask, {
+      queueName: queue.name,
+    })(task);
+    handles.push(handle);
+  }
+  // Wait for all tasks
+  const results = [];
+  for (const h of handles) {
+    results.push(await h.getResult());
+  }
+  return results;
+}
+const processAllTasks = DBOS.registerWorkflow(processAllTasksFn);
+```
+
+Queues process workflows in FIFO order. All queues should be created before `DBOS.launch()`.
+
+Reference: [DBOS Queues](https://docs.dbos.dev/typescript/tutorials/queue-tutorial)

package/templates/.agent/skills/dbos-typescript/references/queue-concurrency.md

@@ -0,0 +1,53 @@
+---
+title: Control Queue Concurrency
+impact: HIGH
+impactDescription: Prevents resource exhaustion with concurrent limits
+tags: queue, concurrency, workerConcurrency, limits
+---
+
+## Control Queue Concurrency
+
+Queues support worker-level and global concurrency limits to prevent resource exhaustion.
+
+**Incorrect (no concurrency control):**
+
+```typescript
+const queue = new WorkflowQueue("heavy_tasks"); // No limits - could exhaust memory
+```
+
+**Correct (worker concurrency):**
+
+```typescript
+// Each process runs at most 5 tasks from this queue
+const queue = new WorkflowQueue("heavy_tasks", { workerConcurrency: 5 });
+```
+
+**Correct (global concurrency):**
+
+```typescript
+// At most 10 tasks run across ALL processes
+const queue = new WorkflowQueue("limited_tasks", { concurrency: 10 });
+```
+
+**In-order processing (sequential):**
+
+```typescript
+// Only one task at a time - guarantees order
+const serialQueue = new WorkflowQueue("sequential_queue", { concurrency: 1 });
+
+async function processEventFn(event: string) {
+  // ...
+}
+const processEvent = DBOS.registerWorkflow(processEventFn);
+
+app.post("/events", async (req, res) => {
+  await DBOS.startWorkflow(processEvent, { queueName: serialQueue.name })(req.body.event);
+  res.send("Queued!");
+});
+```
+
+Worker concurrency is recommended for most use cases. Take care with global concurrency as any `PENDING` workflow on the queue counts toward the limit, including workflows from previous application versions.
+
+When using worker concurrency, each process must have a unique `executorID` set in configuration (this is automatic with DBOS Conductor or Cloud).
+
+Reference: [Managing Concurrency](https://docs.dbos.dev/typescript/tutorials/queue-tutorial#managing-concurrency)

package/templates/.agent/skills/dbos-typescript/references/queue-deduplication.md

@@ -0,0 +1,51 @@
+---
+title: Deduplicate Queued Workflows
+impact: HIGH
+impactDescription: Prevents duplicate workflow executions
+tags: queue, deduplication, idempotent, duplicate
+---
+
+## Deduplicate Queued Workflows
+
+Set a deduplication ID when enqueuing to prevent duplicate workflow executions. If a workflow with the same deduplication ID is already enqueued or executing, a `DBOSQueueDuplicatedError` is thrown.
+
+**Incorrect (no deduplication):**
+
+```typescript
+// Multiple clicks could enqueue duplicates
+async function handleClick(userId: string) {
+  await DBOS.startWorkflow(processTask, { queueName: queue.name })("task");
+}
+```
+
+**Correct (with deduplication):**
+
+```typescript
+const queue = new WorkflowQueue("task_queue");
+
+async function processTaskFn(task: string) {
+  // ...
+}
+const processTask = DBOS.registerWorkflow(processTaskFn);
+
+async function handleClick(userId: string) {
+  try {
+    await DBOS.startWorkflow(processTask, {
+      queueName: queue.name,
+      enqueueOptions: { deduplicationID: userId },
+    })("task");
+  } catch (e) {
+    // DBOSQueueDuplicatedError - workflow already active for this user
+    console.log("Task already in progress for user:", userId);
+  }
+}
+```
+
+Deduplication is per-queue. The deduplication ID is active while the workflow has status `ENQUEUED` or `PENDING`. Once the workflow completes, a new workflow with the same deduplication ID can be enqueued.
+
+This is useful for:
+- Ensuring one active task per user
+- Preventing duplicate form submissions
+- Idempotent event processing
+
+Reference: [Deduplication](https://docs.dbos.dev/typescript/tutorials/queue-tutorial#deduplication)

package/templates/.agent/skills/dbos-typescript/references/queue-listening.md

@@ -0,0 +1,63 @@
+---
+title: Control Which Queues a Worker Listens To
+impact: HIGH
+impactDescription: Enables heterogeneous worker pools
+tags: queue, listen, worker, process, configuration
+---
+
+## Control Which Queues a Worker Listens To
+
+Configure `listenQueues` in DBOS configuration to make a process only dequeue from specific queues. This enables heterogeneous worker pools.
+
+**Incorrect (all workers process all queues):**
+
+```typescript
+import { DBOS, WorkflowQueue } from "@dbos-inc/dbos-sdk";
+
+const cpuQueue = new WorkflowQueue("cpu_queue");
+const gpuQueue = new WorkflowQueue("gpu_queue");
+
+// Every worker processes both CPU and GPU tasks
+// GPU tasks on CPU workers will fail or be slow!
+DBOS.setConfig({
+  name: "my-app",
+  systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
+});
+await DBOS.launch();
+```
+
+**Correct (selective queue listening):**
+
+```typescript
+import { DBOS, WorkflowQueue } from "@dbos-inc/dbos-sdk";
+
+const cpuQueue = new WorkflowQueue("cpu_queue");
+const gpuQueue = new WorkflowQueue("gpu_queue");
+
+async function main() {
+  const workerType = process.env.WORKER_TYPE; // "cpu" or "gpu"
+
+  const config: any = {
+    name: "my-app",
+    systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
+  };
+
+  if (workerType === "gpu") {
+    config.listenQueues = [gpuQueue];
+  } else if (workerType === "cpu") {
+    config.listenQueues = [cpuQueue];
+  }
+
+  DBOS.setConfig(config);
+  await DBOS.launch();
+}
+```
+
+`listenQueues` only controls dequeuing. A CPU worker can still enqueue tasks onto the GPU queue:
+
+```typescript
+// From a CPU worker, enqueue onto the GPU queue
+await DBOS.startWorkflow(gpuTask, { queueName: gpuQueue.name })("data");
+```
+
+Reference: [Explicit Queue Listening](https://docs.dbos.dev/typescript/tutorials/queue-tutorial#explicit-queue-listening)

package/templates/.agent/skills/dbos-typescript/references/queue-partitioning.md

@@ -0,0 +1,63 @@
+---
+title: Partition Queues for Per-Entity Limits
+impact: HIGH
+impactDescription: Enables per-entity concurrency control
+tags: queue, partition, per-user, dynamic
+---
+
+## Partition Queues for Per-Entity Limits
+
+Partitioned queues apply flow control limits per partition key instead of the entire queue. Each partition acts as a dynamic "subqueue".
+
+**Incorrect (global concurrency for per-user limits):**
+
+```typescript
+// Global concurrency=1 blocks ALL users, not per-user
+const queue = new WorkflowQueue("tasks", { concurrency: 1 });
+```
+
+**Correct (partitioned queue):**
+
+```typescript
+const queue = new WorkflowQueue("tasks", {
+  partitionQueue: true,
+  concurrency: 1,
+});
+
+async function onUserTask(userID: string, task: string) {
+  // Each user gets their own partition - at most 1 task per user
+  // but tasks from different users can run concurrently
+  await DBOS.startWorkflow(processTask, {
+    queueName: queue.name,
+    enqueueOptions: { queuePartitionKey: userID },
+  })(task);
+}
+```
+
+**Two-level queueing (per-user + global limits):**
+
+```typescript
+const concurrencyQueue = new WorkflowQueue("concurrency-queue", { concurrency: 5 });
+const partitionedQueue = new WorkflowQueue("partitioned-queue", {
+  partitionQueue: true,
+  concurrency: 1,
+});
+
+// At most 1 task per user AND at most 5 tasks globally
+async function onUserTask(userID: string, task: string) {
+  await DBOS.startWorkflow(concurrencyManager, {
+    queueName: partitionedQueue.name,
+    enqueueOptions: { queuePartitionKey: userID },
+  })(task);
+}
+
+async function concurrencyManagerFn(task: string) {
+  const handle = await DBOS.startWorkflow(processTask, {
+    queueName: concurrencyQueue.name,
+  })(task);
+  return await handle.getResult();
+}
+const concurrencyManager = DBOS.registerWorkflow(concurrencyManagerFn);
+```
+
+Reference: [Partitioning Queues](https://docs.dbos.dev/typescript/tutorials/queue-tutorial#partitioning-queues)

package/templates/.agent/skills/dbos-typescript/references/queue-priority.md

@@ -0,0 +1,48 @@
+---
+title: Set Queue Priority for Workflows
+impact: HIGH
+impactDescription: Prioritizes important workflows over lower-priority ones
+tags: queue, priority, ordering, importance
+---
+
+## Set Queue Priority for Workflows
+
+Enable priority on a queue to process higher-priority workflows first. Lower numbers indicate higher priority.
+
+**Incorrect (no priority - FIFO only):**
+
+```typescript
+const queue = new WorkflowQueue("tasks");
+// All tasks processed in FIFO order regardless of importance
+```
+
+**Correct (priority-enabled queue):**
+
+```typescript
+const queue = new WorkflowQueue("tasks", { priorityEnabled: true });
+
+async function processTaskFn(task: string) {
+  // ...
+}
+const processTask = DBOS.registerWorkflow(processTaskFn);
+
+// High priority task (lower number = higher priority)
+await DBOS.startWorkflow(processTask, {
+  queueName: queue.name,
+  enqueueOptions: { priority: 1 },
+})("urgent-task");
+
+// Low priority task
+await DBOS.startWorkflow(processTask, {
+  queueName: queue.name,
+  enqueueOptions: { priority: 100 },
+})("background-task");
+```
+
+Priority rules:
+- Range: `1` to `2,147,483,647`
+- Lower number = higher priority
+- Workflows **without** assigned priorities have the highest priority (run first)
+- Workflows with the same priority are dequeued in FIFO order
+
+Reference: [Priority](https://docs.dbos.dev/typescript/tutorials/queue-tutorial#priority)

package/templates/.agent/skills/dbos-typescript/references/queue-rate-limiting.md

@@ -0,0 +1,44 @@
+---
+title: Rate Limit Queue Execution
+impact: HIGH
+impactDescription: Prevents overwhelming external APIs with too many requests
+tags: queue, rate-limit, throttle, api
+---
+
+## Rate Limit Queue Execution
+
+Set rate limits on a queue to control how many workflows start in a given period. Rate limits are global across all DBOS processes.
+
+**Incorrect (no rate limiting):**
+
+```typescript
+const queue = new WorkflowQueue("llm_tasks");
+// Could send hundreds of requests per second to a rate-limited API
+```
+
+**Correct (rate-limited queue):**
+
+```typescript
+const queue = new WorkflowQueue("llm_tasks", {
+  rateLimit: { limitPerPeriod: 50, periodSec: 30 },
+});
+```
+
+This queue starts at most 50 workflows per 30 seconds.
+
+**Combining rate limiting with concurrency:**
+
+```typescript
+// At most 5 concurrent and 50 per 30 seconds
+const queue = new WorkflowQueue("api_tasks", {
+  workerConcurrency: 5,
+  rateLimit: { limitPerPeriod: 50, periodSec: 30 },
+});
+```
+
+Common use cases:
+- LLM API rate limiting (OpenAI, Anthropic, etc.)
+- Third-party API throttling
+- Preventing database overload
+
+Reference: [Rate Limiting](https://docs.dbos.dev/typescript/tutorials/queue-tutorial#rate-limiting)

package/templates/.agent/skills/dbos-typescript/references/step-basics.md

@@ -0,0 +1,63 @@
+---
+title: Use Steps for External Operations
+impact: HIGH
+impactDescription: Steps enable recovery by checkpointing results
+tags: step, external, api, checkpoint
+---
+
+## Use Steps for External Operations
+
+Any function that performs complex operations, accesses external APIs, or has side effects should be a step. Step results are checkpointed, enabling workflow recovery.
+
+**Incorrect (external call in workflow):**
+
+```typescript
+async function myWorkflowFn() {
+  // External API call directly in workflow - not checkpointed!
+  const response = await fetch("https://api.example.com/data");
+  return await response.json();
+}
+const myWorkflow = DBOS.registerWorkflow(myWorkflowFn);
+```
+
+**Correct (external call in step using `DBOS.runStep`):**
+
+```typescript
+async function fetchData() {
+  return await fetch("https://api.example.com/data").then(r => r.json());
+}
+
+async function myWorkflowFn() {
+  const data = await DBOS.runStep(fetchData, { name: "fetchData" });
+  return data;
+}
+const myWorkflow = DBOS.registerWorkflow(myWorkflowFn);
+```
+
+`DBOS.runStep` can also accept an inline arrow function:
+
+```typescript
+async function myWorkflowFn() {
+  const data = await DBOS.runStep(
+    () => fetch("https://api.example.com/data").then(r => r.json()),
+    { name: "fetchData" }
+  );
+  return data;
+}
+```
+
+Alternatively, you can use `DBOS.registerStep` to pre-register a step or `@DBOS.step()` as a class decorator, but `DBOS.runStep` is preferred for most use cases.
+
+Step requirements:
+- Inputs and outputs must be serializable to JSON
+- Cannot call, start, or enqueue workflows from within steps
+- Calling a step from another step makes the called step part of the calling step's execution
+
+When to use steps:
+- API calls to external services
+- File system operations
+- Random number generation
+- Getting current time
+- Any non-deterministic operation
+
+Reference: [DBOS Steps](https://docs.dbos.dev/typescript/tutorials/step-tutorial)

package/templates/.agent/skills/dbos-typescript/references/step-retries.md

@@ -0,0 +1,67 @@
+---
+title: Configure Step Retries for Transient Failures
+impact: HIGH
+impactDescription: Automatic retries handle transient failures without manual code
+tags: step, retry, exponential-backoff, resilience
+---
+
+## Configure Step Retries for Transient Failures
+
+Steps can automatically retry on failure with exponential backoff. This handles transient failures like network issues.
+
+**Incorrect (manual retry logic):**
+
+```typescript
+async function fetchData() {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      return await fetch("https://api.example.com").then(r => r.json());
+    } catch (e) {
+      if (attempt === 2) throw e;
+      await new Promise(r => setTimeout(r, 2 ** attempt * 1000));
+    }
+  }
+}
+```
+
+**Correct (built-in retries with `DBOS.runStep`):**
+
+```typescript
+async function fetchData() {
+  return await fetch("https://api.example.com").then(r => r.json());
+}
+
+async function myWorkflowFn() {
+  const data = await DBOS.runStep(fetchData, {
+    name: "fetchData",
+    retriesAllowed: true,
+    maxAttempts: 10,
+    intervalSeconds: 1,
+    backoffRate: 2,
+  });
+}
+const myWorkflow = DBOS.registerWorkflow(myWorkflowFn);
+```
+
+With an inline arrow function:
+
+```typescript
+async function myWorkflowFn() {
+  const data = await DBOS.runStep(
+    () => fetch("https://api.example.com").then(r => r.json()),
+    { name: "fetchData", retriesAllowed: true, maxAttempts: 10 }
+  );
+}
+```
+
+Retry parameters:
+- `retriesAllowed`: Enable automatic retries (default: `false`)
+- `maxAttempts`: Maximum retry attempts (default: `3`)
+- `intervalSeconds`: Initial delay between retries in seconds (default: `1`)
+- `backoffRate`: Multiplier for exponential backoff (default: `2`)
+
+With defaults, retry delays are: 1s, 2s, 4s, 8s, 16s...
+
+If all retries are exhausted, a `DBOSMaxStepRetriesError` is thrown to the calling workflow.
+
+Reference: [Configurable Retries](https://docs.dbos.dev/typescript/tutorials/step-tutorial#configurable-retries)

package/templates/.agent/skills/dbos-typescript/references/step-transactions.md

@@ -0,0 +1,68 @@
+---
+title: Use Transactions for Database Operations
+impact: HIGH
+impactDescription: Transactions provide exactly-once database execution within workflows
+tags: step, transaction, database, datasource
+---
+
+## Use Transactions for Database Operations
+
+Use datasource transactions for database operations within workflows. Transactions commit exactly once and are checkpointed for recovery.
+
+**Incorrect (raw database query in workflow):**
+
+```typescript
+import { Pool } from "pg";
+const pool = new Pool();
+
+async function myWorkflowFn() {
+  // Direct database access in workflow - not checkpointed!
+  const result = await pool.query("INSERT INTO orders ...");
+}
+```
+
+**Correct (using a datasource transaction):**
+
+Install a datasource package (e.g., Knex):
+```
+npm i @dbos-inc/knex-datasource
+```
+
+Configure the datasource:
+```typescript
+import { KnexDataSource } from "@dbos-inc/knex-datasource";
+
+const config = { client: "pg", connection: process.env.DBOS_DATABASE_URL };
+const dataSource = new KnexDataSource("app-db", config);
+```
+
+Run transactions inline with `runTransaction`:
+```typescript
+async function insertOrderFn(userId: string, amount: number) {
+  const rows = await dataSource
+    .client("orders")
+    .insert({ user_id: userId, amount })
+    .returning("id");
+  return rows[0].id;
+}
+
+async function myWorkflowFn(userId: string, amount: number) {
+  const orderId = await dataSource.runTransaction(
+    () => insertOrderFn(userId, amount),
+    { name: "insertOrder" }
+  );
+  return orderId;
+}
+const myWorkflow = DBOS.registerWorkflow(myWorkflowFn);
+```
+
+You can also pre-register a transaction function with `dataSource.registerTransaction`:
+```typescript
+const insertOrder = dataSource.registerTransaction(insertOrderFn);
+```
+
+Available datasource packages: `@dbos-inc/knex-datasource`, `@dbos-inc/kysely-datasource`, `@dbos-inc/drizzle-datasource`, `@dbos-inc/typeorm-datasource`, `@dbos-inc/prisma-datasource`, `@dbos-inc/nodepg-datasource`, `@dbos-inc/postgres-datasource`.
+
+Datasources require installing the DBOS schema (`transaction_completion` table) via `initializeDBOSSchema`.
+
+Reference: [Transactions & Datasources](https://docs.dbos.dev/typescript/tutorials/transaction-tutorial)