zilmate 1.8.0 → 1.8.5

package/.agents/skills/upstash/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/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/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/upstash-workflow-js/overview.md

@@ -0,0 +1,55 @@
+# Upstash Workflow SDK
+
+## Quick Start
+
+The Upstash Workflow SDK lets you expose serverless workflow endpoints and run them reliably using QStash under the hood.
+
+Install:
+
+```bash
+npm install @upstash/workflow
+```
+
+Define a simple workflow endpoint:
+
+```ts
+import { serve } from "@upstash/workflow";
+
+export const { POST } = serve(async (context) => {
+  await context.run("step-1", () => console.log("step 1"));
+  await context.run("step-2", () => console.log("step 2"));
+});
+```
+
+Trigger it from your backend:
+
+```ts
+import { Client } from "@upstash/workflow";
+
+const client = new Client({ token: process.env.QSTASH_TOKEN! });
+await client.trigger({ url: "https://your-app.com/api/workflow" });
+```
+
+## Other Skill Files
+
+These files contain the full documentation. Use them for details, patterns, and advanced behavior.
+
+- basics:
+  - **basics/serve** – How to expose workflow endpoints.
+  - **basics/context** – Full API for workflow `context` (steps, waits, webhooks, events, invoke, etc.).
+  - **basics/client** – Using the Workflow client to trigger, cancel, inspect, and notify runs.
+- features:
+  - **features/invoke** – Cross‑workflow invocation.
+  - **features/reliability** – Retries, failure callbacks, and DLQ.
+  - **features/flow-control** – Rate limits, concurrency, and parallelism.
+  - **features/wait-for-event** – Notify and wait-for-event patterns.
+  - **features/webhooks** – Webhook creation and consumption.
+- how to:
+  - **how-to/local-dev** – Local QStash dev server (auto via `QSTASH_DEV=true`) and tunneling.
+  - **how-to/realtime** – Realtime and human‑in‑the‑loop workflows.
+  - **how-to/migrations** – Migrating workflows safely.
+  - **how-to/middleware** – Adding middleware to workflows.
+- other files:
+  - **rest-api** – Low-level REST endpoints for interacting with QStash/Workflow.
+  - **troubleshooting** – Common debugging and environment issues.
+  - **agents** – Using Workflow with agents, orchestrators, and automation patterns.