zilmate 1.8.0 → 1.8.5

package/.agents/skills/upstash-workflow-js/how-to/middleware.md

@@ -0,0 +1,166 @@
+# Middlewares
+
+This guide explains how to intercept workflow lifecycle and debug events using middleware. It covers how to attach middlewares, define event handlers, initialize resources, and combine functionality into efficient implementations.
+
+## Overview
+
+Middlewares plug into the workflow engine and listen to:
+
+- Lifecycle events such as run start, run completion, and step execution
+- Debug messages such as errors, warnings, and informational logs
+
+They are useful for logging, monitoring, instrumentation, and integrating with external systems.
+
+## Using Built‑in Middleware
+
+Add middleware inside the `middlewares` array when serving a workflow:
+
+```ts
+import { serve } from "@upstash/workflow/nextjs";
+import { loggingMiddleware } from "@upstash/workflow";
+
+export const { POST } = serve(
+  async (ctx) => {
+    await ctx.run("step-1", () => "Hello World");
+  },
+  {
+    middlewares: [loggingMiddleware], // emits run/step logs
+  }
+);
+```
+
+## Creating Custom Middleware
+
+You define middleware by instantiating `WorkflowMiddleware` with callbacks for the events you want to handle.
+
+### Direct Callback Definitions
+
+All lifecycle and debug events can be defined in one object.
+
+```ts
+import { WorkflowMiddleware } from "@upstash/workflow";
+
+const customMiddleware = new WorkflowMiddleware({
+  name: "custom-logger",
+  callbacks: {
+    // Lifecycle events
+    runStarted: async ({ context }) => {
+      console.log(`Run ${context.workflowRunId} started`);
+    },
+    beforeExecution: async ({ context, stepName }) => {
+      console.log(`→ Executing step: ${stepName}`);
+    },
+    afterExecution: async ({ context, stepName, result }) => {
+      console.log(`✓ Step ${stepName} completed`, result);
+    },
+    runCompleted: async ({ context, result }) => {
+      console.log(`Run ${context.workflowRunId} finished`, result);
+    },
+
+    // Debug events
+    onError: async ({ workflowRunId, error }) => {
+      console.error(`Error in ${workflowRunId}`, error);
+    },
+    onWarning: async ({ workflowRunId, warning }) => {
+      console.warn(`Warning from ${workflowRunId}`, warning);
+    },
+    onInfo: async ({ workflowRunId, info }) => {
+      console.info(`Info from ${workflowRunId}`, info);
+    },
+  },
+});
+```
+
+### Initialization With `init`
+
+Use `init` when you need setup logic (connecting to a DB, creating clients, loading configuration). `init` returns an object containing the callbacks.
+
+```ts
+import { WorkflowMiddleware } from "@upstash/workflow";
+
+const databaseMiddleware = new WorkflowMiddleware({
+  name: "database-logger",
+  init: async () => {
+    const db = await connectToDatabase();
+
+    return {
+      runStarted: async ({ context }) => {
+        await db.insert({ workflowRunId: context.workflowRunId, status: "started" });
+      },
+      runCompleted: async ({ context, result }) => {
+        await db.update({ workflowRunId: context.workflowRunId, status: "completed", result });
+      },
+      onError: async ({ workflowRunId, error }) => {
+        await db.insert({ workflowRunId, level: "error", message: error.message });
+      },
+    };
+  },
+});
+```
+
+## Event Reference
+
+Below is a concise list of supported event handlers and what they receive.
+
+### Lifecycle
+
+- **runStarted**: `{ context }`
+- **beforeExecution**: `{ context, stepName }`
+- **afterExecution**: `{ context, stepName, result }`
+- **runCompleted**: `{ context, result }`
+
+### Debug
+
+- **onError**: `{ workflowRunId?, error }`
+- **onWarning**: `{ workflowRunId?, warning }`
+- **onInfo**: `{ workflowRunId?, info }`
+
+## Combined Example
+
+Single snippet showing typical usage patterns.
+
+```ts
+import { serve } from "@upstash/workflow/nextjs";
+import { WorkflowMiddleware } from "@upstash/workflow";
+
+// Error tracking
+const errorTrackingMiddleware = new WorkflowMiddleware({
+  name: "errors",
+  callbacks: {
+    onError: async ({ workflowRunId, error }) => {
+      await fetch("https://monitoring/errors", {
+        method: "POST",
+        body: JSON.stringify({ workflowRunId, error: error.message }),
+      });
+    },
+  },
+});
+
+// Performance measurement
+const timings = new Map();
+const performanceMiddleware = new WorkflowMiddleware({
+  name: "perf",
+  callbacks: {
+    beforeExecution: ({ stepName }) => timings.set(stepName, Date.now()),
+    afterExecution: ({ stepName }) => {
+      const t = timings.get(stepName);
+      if (t) console.log(`Step ${stepName} took ${Date.now() - t}ms`);
+      timings.delete(stepName);
+    },
+  },
+});
+
+export const { POST } = serve(
+  async (ctx) => {
+    await ctx.run("task", () => "done");
+  },
+  {
+    middlewares: [errorTrackingMiddleware, performanceMiddleware],
+  }
+);
+```
+
+## Pitfalls and Tips
+
+- Ensure `init` returns all callbacks; missing keys simply mean the event is ignored.
+- Debug events may be called without a `workflowRunId` if errors occur before run id is identified.

package/.agents/skills/upstash-workflow-js/how-to/migrations.md

@@ -0,0 +1,201 @@
+# Migration Guide for Upstash Workflow (TypeScript)
+
+This document provides a clear, task-focused overview of migrations between Workflow versions. It highlights breaking changes, how to update your code, and common pitfalls to avoid. Code samples combine multiple parameters in each example to reduce redundancy.
+
+## January 2026 – Major Release 1.0.0
+
+### Agents API → moved to a separate package
+
+The Agents API was removed from the core workflow package and placed into `@upstash/workflow-agents` so the base SDK no longer depends on large AI-related libraries.
+
+**Key changes**:
+
+- Must install and import `agentWorkflow` from the new package.
+- Agents access now happens through an `agents` helper created per workflow invocation.
+
+```ts
+// Before
+import { serve } from "@upstash/workflow/nextjs";
+export const { POST } = serve(async (context) => {
+  const model = context.agents.openai("gpt-3.5-turbo");
+  const agent = context.agents.agent({
+    /* ... */
+  });
+  const task = context.agents.task({
+    /* ... */
+  });
+});
+
+// After
+import { serve } from "@upstash/workflow/nextjs";
+import { agentWorkflow } from "@upstash/workflow-agents";
+export const { POST } = serve(async (context) => {
+  const agents = agentWorkflow(context);
+  const model = agents.openai("gpt-3.5-turbo");
+  const agent = agents.agent({
+    /* ... */
+  });
+  const task = agents.task({
+    /* ... */
+  });
+});
+```
+
+---
+
+### `keepTriggerConfig` and `useFailureFunction` removed
+
+These fields were redundant—both behaviors are now always enabled.
+
+```ts
+// Before
+await client.trigger({
+  url: "...",
+  retries: 3,
+  keepTriggerConfig: true,
+  useFailureFunction: true,
+});
+
+// After
+await client.trigger({ url: "...", retries: 3 });
+```
+
+---
+
+### Configuration moved from `serve()` → `client.trigger()`
+
+Options such as `retries`, `flowControl`, `retryDelay`, and `failureUrl` no longer belong in `serve()`.
+
+```ts
+// Before
+export const { POST } = serve(
+  async (context) => {
+    /* ... */
+  },
+  {
+    retries: 3,
+    retryDelay: "1000 * (1 + retried)",
+    flowControl: { key: "my-key", rate: 10 },
+  }
+);
+await client.trigger({ url: "..." });
+
+// After
+export const { POST } = serve(async (context) => {
+  /* ... */
+});
+await client.trigger({
+  url: "...",
+  retries: 3,
+  retryDelay: "1000 * (1 + retried)",
+  flowControl: { key: "my-key", rate: 10 },
+});
+```
+
+---
+
+### `stringifyBody` removed from `context.call` and `context.invoke`
+
+Bodies must now be strings.
+
+```ts
+// Before
+await context.call("step", {
+  url: "https://api.example.com",
+  method: "POST",
+  body: { key: "value" },
+  stringifyBody: true,
+});
+
+// After
+await context.call("step", {
+  url: "https://api.example.com",
+  method: "POST",
+  body: JSON.stringify({ key: "value" }),
+});
+
+// Same change applies to invoke
+await context.invoke("other", {
+  workflow: otherWorkflow,
+  body: JSON.stringify({ key: "value" }),
+});
+```
+
+---
+
+### Logger removed → middleware system added
+
+Removed `WorkflowLogger` class and added `WorkflowMiddleware`. Updated `verbose` param to only allow `true` (in this case, `loggingMiddleware` will be used which prints to console).
+
+```ts
+import { loggingMiddleware, WorkflowMiddleware } from "@upstash/workflow";
+
+const stepFinish = new WorkflowMiddleware({
+  name: "step-finish",
+  callbacks: {
+    afterExecution: async ({ stepName, result }) =>
+      console.log(`Step ${stepName} finished`, result),
+  },
+});
+
+export const { POST } = serve(
+  async (context) => {
+    /* ... */
+  },
+  {
+    middlewares: [loggingMiddleware, stepFinish],
+  }
+);
+```
+
+---
+
+## October 2024 – Migration from `@upstash/qstash`
+
+### Install the new package
+
+Replace all workflow usage from `@upstash/qstash` with `@upstash/workflow`.
+
+### Serve import and return shape changed
+
+Most environments now require destructuring `{ POST }`.
+
+```ts
+// Before
+import { serve } from "@upstash/qstash/nextjs";
+export const POST = serve(...);
+
+// After
+import { serve } from "@upstash/workflow/nextjs";
+export const { POST } = serve(...);
+```
+
+### `context.call` updated
+
+Now returns `{ status, headers, body }` and **does not fail** the workflow if the HTTP call fails.
+
+```ts
+const { status, headers, body } = await context.call("call-step", {
+  url: "https://example.com/api",
+  method: "POST",
+});
+```
+
+**Pitfall**: Old runs may not contain `status` or `headers` until fully migrated.
+
+### Errors renamed
+
+- `QStashWorkflowError` → `WorkflowError`
+- `QStashWorkflowAbort` → `WorkflowAbort`
+
+---
+
+## Summary of Common Mistakes
+
+- Using `context.agents` instead of the new `agentWorkflow()` helper.
+- Leaving old serve-config options (`retries`, `flowControl`, etc.).
+- Forgetting to `JSON.stringify` bodies.
+- Assuming `context.call` failures stop workflow execution.
+- Mix-and-matching `@upstash/qstash` and `@upstash/workflow` imports.
+
+This guide ensures smooth migration with minimal friction while highlighting where behavioral changes may break existing workflows.

package/.agents/skills/upstash-workflow-js/how-to/realtime.md

@@ -0,0 +1,186 @@
+# Realtime Workflow Integration (TypeScript)
+
+This Skill provides guidance for building real‑time and human‑in‑the‑loop workflows using Upstash Workflow + Upstash Realtime. It covers event schemas, workflow patterns, emitting/receiving updates, and handling interactive pauses.
+
+Key capabilities:
+
+- Emit strongly typed workflow events.
+- Subscribe to live updates in the frontend.
+- Implement pause/resume workflows using `waitForEvent` and `notify`.
+
+---
+
+## Core Concepts
+
+### Realtime schema design
+
+Define all workflow event types in one schema. Keep event definitions minimal and stable.
+
+```ts
+// lib/realtime.ts
+const schema = {
+  workflow: {
+    // Completion events
+    runFinish: z.object({}),
+    stepFinish: z.object({ stepName: z.string(), result: z.unknown().optional() }),
+
+    // Human‑in‑the‑loop events
+    waitingForInput: z.object({ eventId: z.string(), message: z.string() }),
+    inputResolved: z.object({ eventId: z.string() }),
+  },
+};
+
+export const realtime = new Realtime({ schema, redis });
+export type RealtimeEvents = InferRealtimeEvents<typeof realtime>;
+```
+
+Common mistakes:
+
+- Forgetting to wrap events under a namespace (e.g. `workflow.*`).
+
+---
+
+## Emitting Events Inside Workflows
+
+Emit inside `context.run()` whenever possible to avoid duplicate emissions on retries.
+
+```ts
+// app/api/workflow/route.ts
+export const { POST } = serve(async (context) => {
+  const channel = realtime.channel(context.workflowRunId);
+
+  // Emit step updates
+  await context.run("validate", async () => {
+    const result = { ok: true };
+    await channel.emit("workflow.stepFinish", { stepName: "validate", result });
+    return result;
+  });
+
+  // Final event
+  await context.run("finish", () => channel.emit("workflow.runFinish", {}));
+});
+```
+
+Pitfall:
+
+- Emitting events _outside_ of `context.run()` risks duplicate delivery if retries happen.
+
+---
+
+## Human‑in‑the‑Loop Workflows
+
+Use `waitForEvent()` with unique `eventId` values and emit a `waitingForInput` event immediately.
+
+```ts
+// Step that pauses for human input
+const eventId = `approval-${context.workflowRunId}`;
+
+const [{ eventData, timeout }] = await Promise.all([
+  context.waitForEvent("wait-for-approval", eventId, { timeout: "5m" }),
+  context.run("notify-wait", () =>
+    channel.emit("workflow.waitingForInput", {
+      eventId,
+      message: "Waiting for approval...",
+    })
+  ),
+]);
+
+if (timeout) return { success: false, reason: "timeout" };
+
+await context.run("resolved", () => channel.emit("workflow.inputResolved", { eventId }));
+```
+
+Important details:
+
+- Always handle timeout: otherwise the workflow may appear stuck.
+- Emit `inputResolved` so the UI can clear any pending state.
+- Use deterministic `eventId` prefixes per action/approval.
+
+---
+
+## Notify Endpoint (User Response)
+
+The frontend sends input back to the workflow using `client.notify()`.
+
+```ts
+// app/api/notify/route.ts
+export async function POST(req: NextRequest) {
+  const { eventId, eventData } = await req.json();
+
+  await workflowClient.notify({ eventId, eventData }); // resumes workflow
+  return NextResponse.json({ success: true });
+}
+```
+
+Common mistakes:
+
+- Sending the wrong `eventId` → workflow never resumes.
+- Sending `eventData` that doesn’t match the awaited type.
+
+---
+
+## Realtime Subscription in the Frontend
+
+Use a single hook to consume all workflow‑related events and manage state.
+
+```ts
+// lib/realtime-client.ts & useWorkflow hooks
+useRealtime({
+  enabled: !!workflowRunId,
+  channels: [workflowRunId],
+  events: [
+    "workflow.stepFinish",
+    "workflow.runFinish",
+    "workflow.waitingForInput",
+    "workflow.inputResolved",
+  ],
+  onData({ event, data }) {
+    switch (event) {
+      case "workflow.stepFinish":
+        setSteps((prev) => [...prev, data]);
+        break;
+      case "workflow.waitingForInput":
+        setWaitingState(data);
+        break;
+      case "workflow.inputResolved":
+        setWaitingState((prev) => (prev?.eventId === data.eventId ? null : prev));
+        break;
+      case "workflow.runFinish":
+        setIsRunFinished(true);
+    }
+  },
+});
+```
+
+Pitfalls:
+
+- Forgetting to clear waiting state on `inputResolved`.
+- Forgetting to reset state on re‑trigger.
+
+---
+
+## Triggering the Workflow
+
+One simple endpoint triggers both basic and human‑in‑the‑loop flows.
+
+```ts
+// app/api/trigger/route.ts
+export async function POST(req: NextRequest) {
+  const workflowUrl = `${req.nextUrl.origin}/api/workflow`; // or /human-in-loop
+  const { workflowRunId } = await workflowClient.trigger({
+    url: workflowUrl,
+    body: { userId: "123", action: "process" },
+  });
+  return NextResponse.json({ workflowRunId });
+}
+```
+
+---
+
+## Recommended Patterns
+
+- Use one channel per workflow run (`workflowRunId`).
+- Always place event emissions inside `context.run()`.
+- Use stable `eventId` formats for all interactive steps.
+- Subscribe to only the events your UI needs.
+- Reset UI state before every new trigger.

package/.agents/skills/upstash-workflow-js/rest-api.md

@@ -0,0 +1,156 @@
+# Workflow REST API Skill
+
+This Skill provides TypeScript-focused guidance for interacting with the Upstash QStash Workflow Dead Letter Queue (DLQ) REST API. It includes practical usage examples, consolidated patterns, and key considerations for safely restarting, resuming, listing, deleting, and inspecting failed workflow runs.
+
+The goal is to help agents construct correct TypeScript API requests, handle optional fields, and avoid common pitfalls when working with workflow recovery operations.
+
+---
+
+## Core Concepts
+
+• **DLQ Entries** represent failed workflow runs containing metadata such as payload, headers, timestamps, failure callback state, and workflow configuration.  
+• **Restart** recreates the entire workflow run from the beginning (fresh execution, no preserved state).  
+• **Resume** creates a new run continuing from the failed step (preserves successful steps).  
+• **Bulk operations** process up to 50 DLQ entries per request and may return a cursor for pagination.
+• **Flow-Control and Retry Overrides** are passed via headers and apply only to the newly created workflow run.
+
+Be careful: changing workflow code **before** the failed step may cause resume operations to break.
+
+---
+
+# HTTP Endpoints Overview
+
+Below is a complete summary of the API endpoints supported by this skill.
+
+• `GET /v2/workflows/dlq` — List DLQ entries with filtering.  
+• `GET /v2/workflows/dlq/{dlqId}` — Retrieve a single DLQ entry.  
+• `DELETE /v2/workflows/dlq/{dlqId}` — Delete a DLQ entry.  
+• `POST /v2/workflows/dlq/restart/{dlqId}` — Restart a workflow from scratch.  
+• `POST /v2/workflows/dlq/resume/{dlqId}` — Resume a workflow from point of failure.  
+• `POST /v2/workflows/dlq/restart` — Bulk restart (up to 50).  
+• `POST /v2/workflows/dlq/resume` — Bulk resume (up to 50).  
+• `POST /v2/workflows/dlq/callback/{dlqId}` — Rerun a failed failure-callback.  
+• `GET /v2/flowControl` and `/v2/flowControl/{key}` — Flow-control inspection.
+
+---
+
+# TypeScript Usage Patterns
+
+Below is a single integrated example illustrating several endpoints, optional query parameters, header overrides, and response field handling.
+
+```ts
+import fetch from "node-fetch";
+
+const token = process.env.QSTASH_TOKEN;
+const base = "https://qstash.upstash.io/v2";
+
+async function example() {
+  // 1. List DLQ items with filters
+  const list = await fetch(
+    `${base}/workflows/dlq?workflowUrl=https://my.app/workflow&fromDate=1700000000000`,
+    {
+      headers: { Authorization: `Bearer ${token}` },
+    }
+  ).then((r) => r.json());
+
+  const firstDlqId = list.messages?.[0]?.dlqId;
+
+  // 2. Restart or Resume a specific run (headers may override flow control or retries)
+  const restart = await fetch(`${base}/workflows/dlq/restart/${firstDlqId}`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${token}`,
+      "Upstash-Flow-Control-Key": "my-key", // optional
+      "Upstash-Flow-Control-Value": "parallelism=1", // optional
+      "Upstash-Retries": "3", // optional
+    },
+  }).then((r) => r.json());
+
+  // 3. Bulk resume using filters and cursor handling
+  const bulkResume = await fetch(`${base}/workflows/dlq/resume`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}` },
+    body: JSON.stringify({
+      fromDate: 1700000000000,
+      workflowUrl: "https://my.app/workflow",
+      dlqIds: [firstDlqId], // optional; filters also supported
+    }),
+  }).then((r) => r.json());
+
+  // 4. Rerun failure callback
+  const callback = await fetch(`${base}/workflows/dlq/callback/${firstDlqId}`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}` },
+  }).then((r) => r.json());
+
+  // 5. Delete a DLQ entry
+  await fetch(`${base}/workflows/dlq/${firstDlqId}`, {
+    method: "DELETE",
+    headers: { Authorization: `Bearer ${token}` },
+  });
+
+  // 6. Inspect Flow-Control
+  const fc = await fetch(`${base}/flowControl/my-key`, {
+    headers: { Authorization: `Bearer ${token}` },
+  }).then((r) => r.json());
+
+  console.log({ list, restart, bulkResume, callback, fc });
+}
+```
+
+---
+
+# Key Fields and Behaviors
+
+## Request Query Fields
+
+• **dlqIds: string[]** — Exact DLQ IDs for targeting specific failed runs (bulk restart/resume).  
+• **fromDate / toDate: number** — Millisecond timestamps; inclusive range filters.  
+• **workflowUrl: string** — Filters by workflow endpoint URL.  
+• **workflowRunId: string** — Can match full run ID or prefix.  
+• **workflowCreatedAt: number** — Timestamp filter for creation time.  
+• **responseStatus: number** — Filter by HTTP status of failed run.  
+• **callerIP: string** — Filter by origin IP.  
+• **failureCallbackState: string** — Filter runs whose failure callback succeeded or failed.  
+• **cursor: string** — Pagination cursor; returned by list & bulk ops.  
+• **count: number** — Limit for listing DLQ entries (default/max 100).
+
+## Header Overrides
+
+These apply only when creating a **new workflow run** (restart or resume).
+
+• **Upstash-Flow-Control-Key** — Override flow-control key.  
+• **Upstash-Flow-Control-Value** — Override flow-control config (e.g., "parallelism=1").  
+• **Upstash-Retries** — Override step retry configuration.
+
+All are optional; original values are reused if omitted.
+
+## Response Fields
+
+• **cursor?: string** — If returned, additional entries exist.  
+• **workflowRuns: { workflowRunId: string; workflowCreatedAt: number }[]** — Returned by bulk restart/resume.  
+• **message objects** (DLQ list/get) include:
+
+- **workflowRunId, workflowCreatedAt, workflowUrl**
+- **responseStatus, responseHeader, responseBody**
+- **failureCallbackInfo.state** — Identify failed callbacks.
+- **dlqId** — Unique DLQ entry identifier.
+
+---
+
+# Pitfalls & Best Practices
+
+• **Resume only works if workflow code before the failed step stays unchanged**. Any change may cause resume to fail.  
+• **Bulk operations process max 50 items**. Always check `cursor` to continue processing.  
+• **Deleting a DLQ entry is permanent**; once removed, it cannot be resumed or restarted.  
+• **Failure callback reruns are independent** and do not affect workflow execution. They only retry the failure-notification step.  
+• **Prefix matching on workflowRunId** can unintentionally match more runs than expected—use full ID for precision.
+
+---
+
+# Recommended Patterns
+
+• Fetch → Check cursor → Continue looping for bulk operations.  
+• Always log `failureCallbackInfo.state` to determine whether a callback rerun is required.  
+• Apply header overrides sparingly; flow-control misconfiguration may stall large batches.  
+• Prefer filtering in bulk operations instead of manually passing large dlqIds arrays.