codehava-agent-kit 1.0.1 → 3.0.0

package/templates/.agent/skills/dbos-typescript/references/client-enqueue.md

@@ -0,0 +1,75 @@
+---
+title: Enqueue Workflows from External Applications
+impact: MEDIUM
+impactDescription: Enables external services to submit work to DBOS queues
+tags: client, enqueue, external, queue
+---
+
+## Enqueue Workflows from External Applications
+
+Use `client.enqueue()` to submit workflows from outside your DBOS application. Since `DBOSClient` runs externally, workflow and queue metadata must be specified explicitly.
+
+**Incorrect (trying to use DBOS.startWorkflow from external code):**
+
+```typescript
+// DBOS.startWorkflow requires a full DBOS setup
+await DBOS.startWorkflow(processTask, { queueName: "myQueue" })("data");
+```
+
+**Correct (using DBOSClient.enqueue):**
+
+```typescript
+import { DBOSClient } from "@dbos-inc/dbos-sdk";
+
+const client = await DBOSClient.create({
+  systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
+});
+
+// Basic enqueue
+const handle = await client.enqueue(
+  {
+    workflowName: "processTask",
+    queueName: "task_queue",
+  },
+  "task-data"
+);
+
+// Wait for the result
+const result = await handle.getResult();
+```
+
+**Type-safe enqueue:**
+
+```typescript
+// Import or declare the workflow type
+declare class Tasks {
+  static processTask(data: string): Promise<string>;
+}
+
+const handle = await client.enqueue<typeof Tasks.processTask>(
+  {
+    workflowName: "processTask",
+    workflowClassName: "Tasks",
+    queueName: "task_queue",
+  },
+  "task-data"
+);
+
+// TypeScript infers the result type
+const result = await handle.getResult(); // type: string
+```
+
+**Enqueue options:**
+- `workflowName` (required): Name of the workflow function
+- `queueName` (required): Name of the queue
+- `workflowClassName`: Class name if the workflow is a class method
+- `workflowConfigName`: Instance name if using `ConfiguredInstance`
+- `workflowID`: Custom workflow ID
+- `workflowTimeoutMS`: Timeout in milliseconds
+- `deduplicationID`: Prevent duplicate enqueues
+- `priority`: Queue priority (lower = higher priority)
+- `queuePartitionKey`: Partition key for partitioned queues
+
+Always call `client.destroy()` when done.
+
+Reference: [DBOS Client Enqueue](https://docs.dbos.dev/typescript/reference/client#enqueue)

package/templates/.agent/skills/dbos-typescript/references/client-setup.md

@@ -0,0 +1,60 @@
+---
+title: Initialize DBOSClient for External Access
+impact: MEDIUM
+impactDescription: Enables external applications to interact with DBOS workflows
+tags: client, external, setup, initialization
+---
+
+## Initialize DBOSClient for External Access
+
+Use `DBOSClient` to interact with DBOS from external applications like API servers, CLI tools, or separate services. `DBOSClient` connects directly to the DBOS system database.
+
+**Incorrect (using DBOS directly from an external app):**
+
+```typescript
+// DBOS requires full setup with launch() - too heavy for external clients
+DBOS.setConfig({ ... });
+await DBOS.launch();
+```
+
+**Correct (using DBOSClient):**
+
+```typescript
+import { DBOSClient } from "@dbos-inc/dbos-sdk";
+
+const client = await DBOSClient.create({
+  systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
+});
+
+// Send a message to a workflow
+await client.send(workflowID, "notification", "topic");
+
+// Get an event from a workflow
+const event = await client.getEvent<string>(workflowID, "status");
+
+// Read a stream from a workflow
+for await (const value of client.readStream(workflowID, "results")) {
+  console.log(value);
+}
+
+// Retrieve a workflow handle
+const handle = client.retrieveWorkflow<string>(workflowID);
+const result = await handle.getResult();
+
+// List workflows
+const workflows = await client.listWorkflows({ status: "ERROR" });
+
+// Workflow management
+await client.cancelWorkflow(workflowID);
+await client.resumeWorkflow(workflowID);
+
+// Always destroy when done
+await client.destroy();
+```
+
+Constructor options:
+- `systemDatabaseUrl`: Connection string to the Postgres system database (required)
+- `systemDatabasePool`: Optional custom `node-postgres` connection pool
+- `serializer`: Optional custom serializer (must match the DBOS application's serializer)
+
+Reference: [DBOS Client](https://docs.dbos.dev/typescript/reference/client)

package/templates/.agent/skills/dbos-typescript/references/comm-events.md

@@ -0,0 +1,57 @@
+---
+title: Use Events for Workflow Status Publishing
+impact: MEDIUM
+impactDescription: Enables real-time progress monitoring and interactive workflows
+tags: communication, events, status, key-value
+---
+
+## Use Events for Workflow Status Publishing
+
+Workflows can publish events (key-value pairs) with `DBOS.setEvent`. Other code can read events with `DBOS.getEvent`. Events are persisted and useful for real-time progress monitoring.
+
+**Incorrect (using external state for progress):**
+
+```typescript
+let progress = 0; // Global variable - not durable!
+
+async function processDataFn() {
+  progress = 50; // Not persisted, lost on restart
+}
+const processData = DBOS.registerWorkflow(processDataFn);
+```
+
+**Correct (using events):**
+
+```typescript
+async function processDataFn() {
+  await DBOS.setEvent("status", "processing");
+  await DBOS.runStep(stepOne, { name: "stepOne" });
+  await DBOS.setEvent("progress", 50);
+  await DBOS.runStep(stepTwo, { name: "stepTwo" });
+  await DBOS.setEvent("progress", 100);
+  await DBOS.setEvent("status", "complete");
+}
+const processData = DBOS.registerWorkflow(processDataFn);
+
+// Read events from outside the workflow
+const status = await DBOS.getEvent<string>(workflowID, "status", 0);
+const progress = await DBOS.getEvent<number>(workflowID, "progress", 0);
+// Returns null if the event doesn't exist within the timeout (default 60s)
+```
+
+Events are useful for interactive workflows. For example, a checkout workflow can publish a payment URL for the caller to redirect to:
+
+```typescript
+async function checkoutWorkflowFn() {
+  const paymentURL = await DBOS.runStep(createPayment, { name: "createPayment" });
+  await DBOS.setEvent("paymentURL", paymentURL);
+  // Continue processing...
+}
+const checkoutWorkflow = DBOS.registerWorkflow(checkoutWorkflowFn);
+
+// HTTP handler starts workflow and reads the payment URL
+const handle = await DBOS.startWorkflow(checkoutWorkflow)();
+const url = await DBOS.getEvent<string>(handle.workflowID, "paymentURL", 300);
+```
+
+Reference: [Workflow Events](https://docs.dbos.dev/typescript/tutorials/workflow-communication#workflow-events)

package/templates/.agent/skills/dbos-typescript/references/comm-messages.md

@@ -0,0 +1,55 @@
+---
+title: Use Messages for Workflow Notifications
+impact: MEDIUM
+impactDescription: Enables reliable inter-workflow and external-to-workflow communication
+tags: communication, messages, send, recv, notification
+---
+
+## Use Messages for Workflow Notifications
+
+Use `DBOS.send` to send messages to a workflow and `DBOS.recv` to receive them. Messages are queued per topic and persisted for reliable delivery.
+
+**Incorrect (using external messaging for workflow communication):**
+
+```typescript
+// External message queue is not integrated with workflow recovery
+import { Queue } from "some-external-queue";
+```
+
+**Correct (using DBOS messages):**
+
+```typescript
+async function checkoutWorkflowFn() {
+  // Wait for payment notification (timeout 120 seconds)
+  const notification = await DBOS.recv<string>("payment_status", 120);
+
+  if (notification && notification === "paid") {
+    await DBOS.runStep(fulfillOrder, { name: "fulfillOrder" });
+  } else {
+    await DBOS.runStep(cancelOrder, { name: "cancelOrder" });
+  }
+}
+const checkoutWorkflow = DBOS.registerWorkflow(checkoutWorkflowFn);
+
+// Send a message from a webhook handler
+async function paymentWebhook(workflowID: string, status: string) {
+  await DBOS.send(workflowID, status, "payment_status");
+}
+```
+
+Key behaviors:
+- `recv` waits for and consumes the next message for the specified topic
+- Returns `null` if the wait times out (default timeout: 60 seconds)
+- Messages without a topic can only be received by `recv` without a topic
+- Messages are queued per-topic (FIFO)
+
+**Reliability guarantees:**
+- All messages are persisted to the database
+- Messages sent from workflows are delivered exactly-once
+- Messages sent from non-workflow code can use an idempotency key:
+
+```typescript
+await DBOS.send(workflowID, message, "topic", "idempotency-key-123");
+```
+
+Reference: [Workflow Messaging](https://docs.dbos.dev/typescript/tutorials/workflow-communication#workflow-messaging-and-notifications)

package/templates/.agent/skills/dbos-typescript/references/comm-streaming.md

@@ -0,0 +1,53 @@
+---
+title: Use Streams for Real-Time Data
+impact: MEDIUM
+impactDescription: Enables streaming results from long-running workflows
+tags: communication, stream, real-time, async-generator
+---
+
+## Use Streams for Real-Time Data
+
+Workflows can stream data to clients in real-time using `DBOS.writeStream`, `DBOS.closeStream`, and `DBOS.readStream`. Useful for LLM output streaming or progress reporting.
+
+**Incorrect (accumulating results then returning at end):**
+
+```typescript
+async function processWorkflowFn() {
+  const results: string[] = [];
+  for (const chunk of data) {
+    results.push(await processChunk(chunk));
+  }
+  return results; // Client must wait for entire workflow to complete
+}
+```
+
+**Correct (streaming results as they become available):**
+
+```typescript
+async function processWorkflowFn() {
+  for (const chunk of data) {
+    const result = await DBOS.runStep(() => processChunk(chunk), { name: "process" });
+    await DBOS.writeStream("results", result);
+  }
+  await DBOS.closeStream("results"); // Signal completion
+}
+const processWorkflow = DBOS.registerWorkflow(processWorkflowFn);
+
+// Read the stream from outside
+const handle = await DBOS.startWorkflow(processWorkflow)();
+for await (const value of DBOS.readStream<string>(handle.workflowID, "results")) {
+  console.log(`Received: ${value}`);
+}
+```
+
+Key behaviors:
+- A workflow may have any number of streams, each identified by a unique key
+- Streams are immutable and append-only
+- Writes from workflows happen exactly-once
+- Writes from steps happen at-least-once (retried steps may write duplicates)
+- Streams are automatically closed when the workflow terminates
+- `readStream` returns an async generator that yields values until the stream is closed
+
+You can also read streams from outside the DBOS application using `DBOSClient.readStream`.
+
+Reference: [Workflow Streaming](https://docs.dbos.dev/typescript/tutorials/workflow-communication#workflow-streaming)

package/templates/.agent/skills/dbos-typescript/references/lifecycle-config.md

@@ -0,0 +1,47 @@
+---
+title: Configure and Launch DBOS Properly
+impact: CRITICAL
+impactDescription: Application won't function without proper setup
+tags: configuration, launch, setup, initialization
+---
+
+## Configure and Launch DBOS Properly
+
+Every DBOS application must configure and launch DBOS before running any workflows. All workflows and steps must be registered before calling `DBOS.launch()`.
+
+**Incorrect (missing configuration or launch):**
+
+```typescript
+import { DBOS } from "@dbos-inc/dbos-sdk";
+
+// No configuration or launch!
+async function myWorkflowFn() {
+  // This will fail - DBOS is not launched
+}
+const myWorkflow = DBOS.registerWorkflow(myWorkflowFn);
+await myWorkflow();
+```
+
+**Correct (configure and launch in main):**
+
+```typescript
+import { DBOS } from "@dbos-inc/dbos-sdk";
+
+async function myWorkflowFn() {
+  // workflow logic
+}
+const myWorkflow = DBOS.registerWorkflow(myWorkflowFn);
+
+async function main() {
+  DBOS.setConfig({
+    name: "my-app",
+    systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
+  });
+  await DBOS.launch();
+  await myWorkflow();
+}
+
+main().catch(console.log);
+```
+
+Reference: [DBOS Lifecycle](https://docs.dbos.dev/typescript/reference/dbos-class)

package/templates/.agent/skills/dbos-typescript/references/lifecycle-express.md

@@ -0,0 +1,61 @@
+---
+title: Integrate DBOS with Express
+impact: CRITICAL
+impactDescription: Proper integration ensures workflows survive server restarts
+tags: express, http, integration, server
+---
+
+## Integrate DBOS with Express
+
+Configure and launch DBOS before starting your Express server. Register all workflows and steps before calling `DBOS.launch()`.
+
+**Incorrect (DBOS not launched before server starts):**
+
+```typescript
+import express from "express";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+
+const app = express();
+
+async function processTaskFn(data: string) {
+  // ...
+}
+const processTask = DBOS.registerWorkflow(processTaskFn);
+
+// Server starts without launching DBOS!
+app.listen(3000);
+```
+
+**Correct (launch DBOS first, then start Express):**
+
+```typescript
+import express from "express";
+import { DBOS } from "@dbos-inc/dbos-sdk";
+
+const app = express();
+
+async function processTaskFn(data: string) {
+  // ...
+}
+const processTask = DBOS.registerWorkflow(processTaskFn);
+
+app.post("/process", async (req, res) => {
+  const handle = await DBOS.startWorkflow(processTask)(req.body.data);
+  res.json({ workflowID: handle.workflowID });
+});
+
+async function main() {
+  DBOS.setConfig({
+    name: "my-app",
+    systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
+  });
+  await DBOS.launch();
+  app.listen(3000, () => {
+    console.log("Server running on port 3000");
+  });
+}
+
+main().catch(console.log);
+```
+
+Reference: [Integrating DBOS](https://docs.dbos.dev/typescript/integrating-dbos)

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

@@ -0,0 +1,67 @@
+---
+title: Use DBOS with Class Instances
+impact: MEDIUM
+impactDescription: Enables configurable workflow instances with recovery support
+tags: pattern, class, instance, ConfiguredInstance
+---
+
+## Use DBOS with Class Instances
+
+Class instance methods can be workflows and steps. Classes with workflow methods must extend `ConfiguredInstance` to enable recovery.
+
+**Incorrect (instance workflows without ConfiguredInstance):**
+
+```typescript
+class MyWorker {
+  constructor(private config: any) {}
+
+  @DBOS.workflow()
+  async processTask(task: string) {
+    // Recovery won't work - DBOS can't find the instance after restart
+  }
+}
+```
+
+**Correct (extending ConfiguredInstance):**
+
+```typescript
+import { DBOS, ConfiguredInstance } from "@dbos-inc/dbos-sdk";
+
+class MyWorker extends ConfiguredInstance {
+  cfg: WorkerConfig;
+
+  constructor(name: string, config: WorkerConfig) {
+    super(name); // Unique name required for recovery
+    this.cfg = config;
+  }
+
+  override async initialize(): Promise<void> {
+    // Optional: validate config at DBOS.launch() time
+  }
+
+  @DBOS.workflow()
+  async processTask(task: string): Promise<void> {
+    // Can use this.cfg safely - instance is recoverable
+    const result = await DBOS.runStep(
+      () => fetch(this.cfg.apiUrl).then(r => r.text()),
+      { name: "callApi" }
+    );
+  }
+}
+
+// Create instances BEFORE DBOS.launch()
+const worker1 = new MyWorker("worker-us", { apiUrl: "https://us.api.com" });
+const worker2 = new MyWorker("worker-eu", { apiUrl: "https://eu.api.com" });
+
+// Then launch
+await DBOS.launch();
+```
+
+Key requirements:
+- `ConfiguredInstance` constructor requires a unique `name` per class
+- All instances must be created **before** `DBOS.launch()`
+- The `initialize()` method is called during launch for validation
+- Use `DBOS.runStep` inside instance workflows for step operations
+- Event registration decorators like `@DBOS.scheduled` cannot be applied to instance methods
+
+Reference: [Using TypeScript Objects](https://docs.dbos.dev/typescript/tutorials/instantiated-objects)

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

@@ -0,0 +1,56 @@
+---
+title: Debounce Workflows to Prevent Wasted Work
+impact: MEDIUM
+impactDescription: Prevents redundant workflow executions during rapid triggers
+tags: pattern, debounce, delay, efficiency
+---
+
+## Debounce Workflows to Prevent Wasted Work
+
+Use `Debouncer` to delay workflow execution until some time has passed since the last trigger. This prevents wasted work when a workflow is triggered multiple times in quick succession.
+
+**Incorrect (executing on every trigger):**
+
+```typescript
+async function processInputFn(userInput: string) {
+  // Expensive processing
+}
+const processInput = DBOS.registerWorkflow(processInputFn);
+
+// Every keystroke triggers a new workflow - wasteful!
+async function onInputChange(userInput: string) {
+  await processInput(userInput);
+}
+```
+
+**Correct (using Debouncer):**
+
+```typescript
+import { DBOS, Debouncer } from "@dbos-inc/dbos-sdk";
+
+async function processInputFn(userInput: string) {
+  // Expensive processing
+}
+const processInput = DBOS.registerWorkflow(processInputFn);
+
+const debouncer = new Debouncer({
+  workflow: processInput,
+  debounceTimeoutMs: 120000, // Max wait: 2 minutes
+});
+
+async function onInputChange(userId: string, userInput: string) {
+  // Delays execution by 60 seconds from the last call
+  // Uses the LAST set of inputs when finally executing
+  await debouncer.debounce(userId, 60000, userInput);
+}
+```
+
+Key behaviors:
+- `debounceKey` groups executions that are debounced together (e.g., per user)
+- `debouncePeriodMs` delays execution by this amount from the last call
+- `debounceTimeoutMs` sets a max wait time since the first trigger
+- When the workflow finally executes, it uses the **last** set of inputs
+- After execution begins, the next `debounce` call starts a new cycle
+- Workflows from `ConfiguredInstance` classes cannot be debounced
+
+Reference: [Debouncing Workflows](https://docs.dbos.dev/typescript/tutorials/workflow-tutorial#debouncing-workflows)

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

@@ -0,0 +1,53 @@
+---
+title: Use Workflow IDs for Idempotency
+impact: MEDIUM
+impactDescription: Prevents duplicate side effects like double payments
+tags: pattern, idempotency, workflow-id, deduplication
+---
+
+## Use Workflow IDs for Idempotency
+
+Assign a workflow ID to ensure a workflow executes only once, even if called multiple times. This prevents duplicate side effects like double payments.
+
+**Incorrect (no idempotency):**
+
+```typescript
+async function processPaymentFn(orderId: string, amount: number) {
+  await DBOS.runStep(() => chargeCard(amount), { name: "chargeCard" });
+  await DBOS.runStep(() => updateOrder(orderId), { name: "updateOrder" });
+}
+const processPayment = DBOS.registerWorkflow(processPaymentFn);
+
+// Multiple calls could charge the card multiple times!
+await processPayment("order-123", 50);
+await processPayment("order-123", 50); // Double charge!
+```
+
+**Correct (with workflow ID):**
+
+```typescript
+async function processPaymentFn(orderId: string, amount: number) {
+  await DBOS.runStep(() => chargeCard(amount), { name: "chargeCard" });
+  await DBOS.runStep(() => updateOrder(orderId), { name: "updateOrder" });
+}
+const processPayment = DBOS.registerWorkflow(processPaymentFn);
+
+// Same workflow ID = only one execution
+const workflowID = `payment-${orderId}`;
+await DBOS.startWorkflow(processPayment, { workflowID })("order-123", 50);
+await DBOS.startWorkflow(processPayment, { workflowID })("order-123", 50);
+// Second call returns the result of the first execution
+```
+
+Access the current workflow ID inside a workflow:
+
+```typescript
+async function myWorkflowFn() {
+  const currentID = DBOS.workflowID;
+  console.log(`Running workflow: ${currentID}`);
+}
+```
+
+Workflow IDs must be **globally unique** for your application. If not set, a random UUID is generated.
+
+Reference: [Workflow IDs and Idempotency](https://docs.dbos.dev/typescript/tutorials/workflow-tutorial#workflow-ids-and-idempotency)

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

@@ -0,0 +1,69 @@
+---
+title: Create Scheduled Workflows
+impact: MEDIUM
+impactDescription: Enables recurring tasks with exactly-once-per-interval guarantees
+tags: pattern, scheduled, cron, recurring
+---
+
+## Create Scheduled Workflows
+
+Use `DBOS.registerScheduled` to run workflows on a cron schedule. Each scheduled invocation runs exactly once per interval.
+
+**Incorrect (manual scheduling with setInterval):**
+
+```typescript
+// Manual scheduling is not durable and misses intervals during downtime
+setInterval(async () => {
+  await generateReport();
+}, 60000);
+```
+
+**Correct (using DBOS.registerScheduled):**
+
+```typescript
+import { DBOS } from "@dbos-inc/dbos-sdk";
+
+async function everyThirtySecondsFn(scheduledTime: Date, actualTime: Date) {
+  DBOS.logger.info("Running scheduled task");
+}
+const everyThirtySeconds = DBOS.registerWorkflow(everyThirtySecondsFn);
+DBOS.registerScheduled(everyThirtySeconds, { crontab: "*/30 * * * * *" });
+
+async function dailyReportFn(scheduledTime: Date, actualTime: Date) {
+  await DBOS.runStep(generateReport, { name: "generateReport" });
+}
+const dailyReport = DBOS.registerWorkflow(dailyReportFn);
+DBOS.registerScheduled(dailyReport, { crontab: "0 9 * * *" });
+```
+
+Scheduled workflows must accept exactly two parameters: `scheduledTime` (Date) and `actualTime` (Date).
+
+DBOS crontab supports 5 or 6 fields (optional seconds):
+```text
+┌────────────── second (optional)
+│ ┌──────────── minute
+│ │ ┌────────── hour
+│ │ │ ┌──────── day of month
+│ │ │ │ ┌────── month
+│ │ │ │ │ ┌──── day of week
+* * * * * *
+```
+
+Retroactive execution (for missed intervals):
+
+```typescript
+import { DBOS, SchedulerMode } from "@dbos-inc/dbos-sdk";
+
+async function fridayNightJobFn(scheduledTime: Date, actualTime: Date) {
+  // Runs even if the app was offline during the scheduled time
+}
+const fridayNightJob = DBOS.registerWorkflow(fridayNightJobFn);
+DBOS.registerScheduled(fridayNightJob, {
+  crontab: "0 21 * * 5",
+  mode: SchedulerMode.ExactlyOncePerInterval,
+});
+```
+
+Scheduled workflows cannot be applied to instance methods.
+
+Reference: [Scheduled Workflows](https://docs.dbos.dev/typescript/tutorials/scheduled-workflows)