zilmate 1.8.0 → 1.8.5

package/.agents/skills/upstash-workflow-js/basics/client.md

@@ -0,0 +1,180 @@
+# Workflow Client Basics
+
+This skill provides guidance for using the Workflow Client to trigger, cancel, inspect, resume, and manage workflow runs. It focuses on TypeScript usage patterns, argument structures, and common pitfalls.
+
+---
+
+## Core Operations
+
+### Triggering Workflow Runs (`client.trigger`)
+
+Starts one or multiple workflow runs with optional payload, metadata, retry logic, and flow control.
+
+```ts
+// Single and multiple triggers
+const single = await client.trigger({
+  url: "https://your-endpoint/workflow", // required
+  body: { msg: "hello" }, // optional payload
+  headers: { "x-user": "123" }, // optional headers
+  workflowRunId: "custom-id", // custom unique identifier
+  retries: 3, // retry count for steps
+  retryDelay: "1000 * (1 + retried)", // expression-based retry delay
+  delay: "10s", // start later
+  notBefore: Math.floor(Date.now() / 1000) + 60, // absolute schedule
+  label: "my-run", // dashboard filtering
+  disableTelemetry: true, // opt‑out telemetry
+  flowControl: {
+    // concurrency & rate limiting
+    key: "user-key",
+    rate: 10,
+    parallelism: 5,
+    period: "10m",
+  },
+});
+
+const multiple = await client.trigger([
+  { url: "https://api/runA", body: { a: 1 } },
+  { url: "https://api/runB", retries: 5 },
+]);
+```
+
+**Pitfalls**:
+
+- `workflowRunId` must be unique; collisions cause errors.
+- `delay` is ignored if `notBefore` is provided.
+- Using `url` incorrectly (missing protocol or dynamic segments) leads to invalid workflow endpoints.
+
+---
+
+### Canceling Workflow Runs (`client.cancel`)
+
+Cancel runs by ID, by URL prefix, or all active/pending runs.
+
+```ts
+await client.cancel({ ids: ["wfr_123", "wfr_456"] });
+await client.cancel({ urlStartingWith: "https://your-endpoint.com" });
+await client.cancel({ all: true });
+```
+
+- `ids` accepts both string and array, but mixing with other filters is not supported.
+- `urlStartingWith` cancels _all_ descendant paths—use carefully.
+
+---
+
+### Retrieving Logs (`client.logs`)
+
+Fetch workflow execution logs with filtering and cursor-based pagination.
+
+```ts
+const { runs, cursor } = await client.logs({
+  workflowRunId: "wfr_123", // filter a specific run
+  workflowUrl: "https://endpoint", // fetch logs for an endpoint
+  state: "RUN_FAILED", // filter by execution state
+  count: 50, // limit return size
+  workflowCreatedAt: 1700000000, // Unix timestamp
+  cursor: undefined, // pagination
+});
+```
+
+---
+
+### Notifying Events (`client.notify`)
+
+Notify workflows paused at `context.waitForEvent`.
+
+```ts
+await client.notify({
+  eventId: "order-paid",
+  eventData: { orderId: 1 }, // delivered to waiting workflow
+});
+```
+
+**Pitfall**: If no workflow is waiting, no error is thrown.
+
+---
+
+### Fetching Waiting Workflows (`client.getWaiters`)
+
+Retrieve active waiters waiting for a specific event.
+
+```ts
+const waiters = await client.getWaiters({ eventId: "order-paid" });
+```
+
+This is useful for debugging or coordinating external signals.
+
+---
+
+## Dead Letter Queue (DLQ) Operations
+
+### Listing DLQ Messages (`client.dlq.list`)
+
+```ts
+const { messages, cursor } = await client.dlq.list({
+  cursor,
+  count: 20,
+  filter: {
+    fromDate: Date.now() - 86400000,
+    toDate: Date.now(),
+    url: "https://your-endpoint.com",
+    responseStatus: 500,
+  },
+});
+```
+
+- Date fields use Unix **ms**, not seconds.
+
+---
+
+### Retry Failure Callback (`client.dlq.retryFailureFunction`)
+
+If a workflow's `failureFunction`/`failureUrl` call failed:
+
+```ts
+await client.dlq.retryFailureFunction({ dlqId: "dlq-123" });
+```
+
+---
+
+### Restarting DLQ Runs (`client.dlq.restart`)
+
+Restart from the **beginning** of the workflow.
+
+```ts
+await client.dlq.restart({
+  dlqId: ["dlq-1", "dlq-2"],
+  retries: 5,
+  flowControl: {
+    key: "restart-group",
+    parallelism: 10,
+  },
+});
+```
+
+---
+
+### Resuming DLQ Runs (`client.dlq.resume`)
+
+Continue from the **failed step**.
+
+```ts
+await client.dlq.resume({
+  dlqId: "dlq-123",
+  retries: 3,
+  flowControl: {
+    key: "resume-group",
+    rate: 5,
+  },
+});
+```
+
+**Common confusion**:
+
+- `restart` = new run from step 0.
+- `resume` = same run continues at the failed step.
+
+---
+
+## General Tips for TS Consumers
+
+- Use flow control when bulk‑triggering or restarting large batches to avoid rate limits.

package/.agents/skills/upstash-workflow-js/basics/context.md

@@ -0,0 +1,230 @@
+# Workflow Context Basics
+
+This skill documents all workflow context functions available inside a TypeScript workflow. It focuses on how these APIs behave, how their parameters interact, and common pitfalls when composing them into reliable long‑running workflows.
+
+---
+
+## context.api
+
+`context.api` provides typed integrations for OpenAI, Anthropic, and Resend. These calls behave like `context.call` but enforce the correct operation names and body types.
+
+### Key points
+
+- Each provider exposes a `.call(stepName, config)` function.
+- `token` is always required.
+- The `operation` field selects the API method.
+- `body` must match the provider's type definitions.
+- Returns `{ status, body }`.
+
+### Example (combined)
+
+```ts
+// OpenAI + Anthropic + Resend usage
+const openai = await context.api.openai.call("openai chat", {
+  token: process.env.OPENAI_API_KEY!,
+  operation: "chat.completions.create",
+  body: {
+    model: "gpt-4o",
+    messages: [
+      { role: "system", content: "Hello" },
+      { role: "user", content: "Hi" },
+    ],
+  },
+});
+
+const anthropic = await context.api.anthropic.call("anthropic message", {
+  token: process.env.ANTHROPIC_API_KEY!,
+  operation: "messages.create",
+  body: {
+    model: "claude-3-5-sonnet-20241022",
+    max_tokens: 1024,
+    messages: [{ role: "user", content: "Hello" }],
+  },
+});
+
+// Resend email
+const email = await context.api.resend.call("send email", {
+  token: process.env.RESEND_API_KEY!,
+  headers: { "content-type": "application/json" },
+  body: {
+    from: "Acme <onboarding@resend.dev>",
+    to: ["someone@example.com"],
+    subject: "Welcome",
+    html: "<p>Hi!</p>",
+  },
+});
+```
+
+---
+
+## context.call
+
+Performs an HTTP request with long execution windows (up to 12 hours). Always returns a response, even for non‑2xx status codes.
+
+### Important parameters
+
+- `url`: required.
+- `method`: defaults to `GET`.
+- `headers`: object.
+- `body`: body as string.
+- `retries`: number of retry attempts.
+- `retryDelay`: retry delay expression as string or number (in milliseconds).
+- `flowControl`: throttling config.
+- `timeout`: seconds for each attempt.
+- `workflow`: used only when invoking a workflow inside `serveMany`.
+
+### Example (showing most fields)
+
+```ts
+const response = await context.call("sync user", {
+  url: "https://api.example.com/user",
+  method: "POST",
+  headers: { authorization: `Bearer ${process.env.TOKEN}` },
+  body: JSON.stringify({ id: userId, name }),
+  retries: 3,
+  retryDelay: "pow(2, retried)", // exponential
+  timeout: 20,
+  flowControl: {
+    key: "user-sync",
+    rate: 5,
+    parallelism: 2,
+  },
+});
+```
+
+### Pitfalls
+
+- Localhost requests fail unless tunneled.
+
+---
+
+## context.cancel
+
+Cancels the current workflow run.
+
+- Workflow is marked **canceled**, not failed.
+- `failureFunction` does not run.
+- No DLQ entry.
+
+### Example
+
+```ts
+const result = await context.run("check something", () => ...);
+if (result.cancel) await context.cancel();
+```
+
+---
+
+## context.createWebhook
+
+Creates a reusable webhook URL for external systems.
+
+### Example
+
+```ts
+const { webhookUrl, eventId } = await context.createWebhook("create webhook");
+// Use webhookUrl with an external service
+```
+
+---
+
+## context.invoke
+
+Invokes another workflow (must be served under the same `serveMany`) and waits for its completion.
+
+### Key parameters
+
+- `workflow`: the workflow definition.
+- `body`: becomes `requestPayload` of invoked workflow.
+- `headers`: forwarded headers.
+- `workflowRunId`: optional override.
+- `retries`, `retryDelay`, `flowControl`: control invocation retry strategy.
+
+### Example
+
+```ts
+const { body, isFailed, isCanceled } = await context.invoke("invoke child", {
+  workflow: childWorkflow,
+  body: { id: 123 },
+  headers: { foo: "bar" },
+  retries: 2,
+});
+```
+
+---
+
+## context.notify
+
+Notifies waiting workflows created via `context.waitForEvent`.
+
+### Example
+
+```ts
+const { notifyResponse } = await context.notify("notify step", "order-updated", {
+  status: "shipped",
+});
+```
+
+`notifyResponse` lists all workflows resumed by this event.
+
+---
+
+## context.run
+
+Runs custom synchronous or async logic as a step. Values must be JSON‑serializable.
+
+### Example
+
+```ts
+const user = await context.run("load user", () => getUser());
+
+await context.run("process user", () => process(user));
+
+// Running in parallel
+const a = context.run("step A", () => foo());
+const b = context.run("step B", () => bar());
+await Promise.all([a, b]);
+```
+
+### Pitfalls
+
+- Returned class instances lose methods due to serialization. Rehydrate via `Object.assign(new Class(), data)`.
+
+---
+
+## context.sleep
+
+Pauses workflow execution for a duration. String or numeric seconds.
+
+### Example
+
+```ts
+await context.sleep("wait 1 day", "1d");
+```
+
+---
+
+## context.sleepUntil
+
+Pauses execution until a specific `Date`, timestamp, or parseable string.
+
+### Example
+
+```ts
+const ts = new Date(Date.now() + 1000 * 60 * 60);
+await context.sleepUntil("wait until", ts);
+```
+
+---
+
+## context.waitForEvent
+
+Waits for an event (triggered by `context.notify`) or until timeout.
+
+### Example
+
+```ts
+const { eventData, timeout } = await context.waitForEvent("wait for update", "order-updated", {
+  timeout: "2h",
+});
+```

package/.agents/skills/upstash-workflow-js/basics/serve.md

@@ -0,0 +1,70 @@
+This documentation explains how to use `serve()` to expose workflows as HTTP endpoints.
+
+## Core Concept
+
+`serve()` turns an async route function into a workflow endpoint. When a request arrives, a workflow run is created, and the route function defines the execution logic using `context.run()`.
+
+### Full Example With Inline Comments
+
+```typescript
+import { serve } from "@upstash/workflow/nextjs";
+import { z } from "zod";
+import { Client, Receiver } from "@upstash/qstash";
+import { loggingMiddleware } from "@upstash/workflow";
+
+type InitialPayload = { foo: string; bar: number };
+
+const payloadSchema = z.object({ foo: z.string(), bar: z.number() });
+
+export const { POST } = serve<InitialPayload>(
+  async (context) => {
+    const payload = context.requestPayload;
+    await context.run("step-1", async () => `hello ${payload.foo}`);
+  },
+  {
+    // Runs when the workflow fails after all retries
+    failureFunction: async ({ context, failStatus, failResponse, failHeaders, failStack }) =>
+      console.error(failResponse),
+
+    // Hooks for step lifecycle, run lifecycle, and debug events
+    middlewares: [loggingMiddleware],
+
+    // Manually parse the initial request payload before workflow execution
+    initialPayloadParser: (raw) => JSON.parse(raw),
+
+    // Automatically validate + parse the request payload using Zod
+    schema: payloadSchema,
+
+    // Override the full URL used to schedule subsequent workflow steps
+    url: "https://myapp.com/api/workflow",
+
+    // Override only the base portion of the inferred URL (keeps the route path)
+    baseUrl: "https://proxy-url.com",
+
+    // Provide a custom QStash client
+    qstashClient: new Client({ token: process.env.QSTASH_TOKEN! }),
+
+    // Provide a custom QStash Receiver for verifying that requests come from QStash
+    receiver: new Receiver({
+      currentSigningKey: process.env.QSTASH_CURRENT_SIGNING_KEY!,
+      nextSigningKey: process.env.QSTASH_NEXT_SIGNING_KEY!,
+    }),
+
+    // Override environment variables available inside workflow execution
+    env: {
+      QSTASH_URL: "https://qstash.upstash.io",
+      QSTASH_TOKEN: process.env.QSTASH_TOKEN!,
+    },
+
+    // Output detailed execution logs to stdout
+    verbose: true,
+
+    // Disable anonymous telemetry for this workflow endpoint
+    disableTelemetry: true,
+  }
+);
+```
+
+## Common Pitfalls
+
+- **Incorrect URL inference** behind proxies or local tunnels—set `url` or `baseUrl`.

package/.agents/skills/upstash-workflow-js/features/flow-control.md

@@ -0,0 +1,145 @@
+# Flow Control
+
+Flow Control defines how many workflow steps may run or start within a given time, ensuring predictable load and preventing overload of internal or third‑party systems. It applies per **flow control key**, allowing steps across different workflow runs to share the same limits.
+
+This skill documents:
+
+- parallelism
+- rate and period
+- monitoring
+- common behaviors and pitfalls
+
+## Core Concepts
+
+### Flow Control Key
+
+A string identifier grouping related workflow steps under shared limits.
+All steps triggered with the same key share the same concurrency and rate budget.
+
+```ts
+const client = new Client({ token: "<QSTASH_TOKEN>" });
+
+await client.trigger({
+  url: "https://<YOUR_ENDPOINT>",
+  flowControl: {
+    key: "user-onboarding", // Groups steps under this key
+    parallelism: 5, // max concurrent steps
+    rate: 20, // max starts per period
+    period: "1m", // time window
+  },
+});
+```
+
+## Parallelism
+
+Controls **how many steps may run concurrently**.
+Works like a token bucket: each running step consumes one token; when it finishes, the token is released.
+
+- If tokens are available → step starts immediately.
+- If no tokens → step enters the waitlist.
+- Token handoff is **not FIFO**; later steps may start earlier.
+
+### Example Behavior
+
+- `parallelism = 3` → at most 3 steps run at the same time.
+- Step 4 waits until one of the first 3 completes.
+
+Parallelism affects **execution concurrency**, not rate‑of‑start per time window.
+
+## Rate & Period
+
+Controls **how many steps may START within a defined time window**.
+
+```ts
+flowControl: {
+  key: "billing-jobs",
+  rate: 2,           // allow 2 starts
+  period: "10s",    // every 10 seconds
+  parallelism: 1,    // can be combined
+}
+```
+
+Behavior:
+
+- First `rate` steps in each period start immediately.
+- Additional steps wait until the next window.
+- Execution duration **does not** count toward the period; only start time matters.
+
+This is rate limiting, not concurrency control.
+
+## Combining Rate + Parallelism
+
+Both limits apply **independently**.
+A step must satisfy _both_ to run.
+
+Example:
+
+- `rate = 3 per minute`
+- `parallelism = 7`
+
+Even if concurrency slots are free, steps may be delayed by the rate window.
+Even if rate window is open, steps may be delayed by concurrency.
+
+This enables predictable load patterns.
+
+## Monitoring
+
+Flow control queues and waitlists are visible from:
+
+- Console → **FlowControl** tab (waitlist size per key)
+- REST API:
+  - List all keys
+  - Get details for one key
+
+Useful for diagnosing bottlenecks, long queues, or misconfigured limits.
+
+## Important Behaviors & Pitfalls
+
+### Limits are stored on each step
+
+If you deploy new limits, previously published steps keep their original configuration.
+
+### No per‑step config (mostly)
+
+All steps inherit the workflow‑run’s flowControl block.
+Exceptions:
+
+- `context.call` – may define a separate key to isolate API throttling.
+- `context.invoke` – spawns a new workflow run with its own flowControl.
+
+To isolate heavy or sensitive steps, move them into a separate workflow and invoke them.
+
+### Waitlist order is not guaranteed
+
+A later step may receive a token before an earlier one.
+Do not rely on ordering.
+
+### Queueing is automatic
+
+Exceeding limits never rejects steps. Everything is eventually executed.
+
+## Full Example
+
+Demonstrates defining all parameters together and how they interact.
+
+```ts
+import { Client } from "@upstash/workflow";
+
+const client = new Client({ token: "<QSTASH_TOKEN>" });
+
+await client.trigger({
+  url: "https://<YOUR_WORKFLOW_ENDPOINT>/process",
+  flowControl: {
+    key: "media-processing", // Shared grouping key
+    parallelism: 4, // Max 4 at the same time
+    rate: 10, // Max 10 starts
+    period: "60s", // in 60 seconds
+  },
+});
+```
+
+This configuration:
+
+- ensures no more than 4 processing tasks run concurrently
+- ensures no more than 10 tasks start per minute
+- queues everything automatically beyond those limits