zilmate 1.8.0 → 1.8.5

package/.agents/skills/upstash/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.

package/.agents/skills/upstash/upstash-workflow-js/troubleshooting.md

@@ -0,0 +1,201 @@
+# Workflow Troubleshooting (TypeScript)
+
+This guide provides clear, TypeScript‑focused patterns for diagnosing and fixing common issues in Upstash Workflow. It highlights correct usage of core workflow features and shows how to avoid pitfalls that commonly occur in real applications.
+
+---
+
+## Steps Inside try/catch
+
+Workflow steps (`context.run`, `context.sleep`, `context.sleepUntil`, `context.call`) intentionally throw `WorkflowAbort` after completing. Catching this error prevents the workflow engine from progressing.
+
+**Correct pattern:** rethrow `WorkflowAbort` or avoid `try/catch` around steps.
+
+```ts
+import { WorkflowAbort } from "@upstash/workflow";
+
+try {
+  // Any step will throw WorkflowAbort
+  const result = await context.run("step", () => "ok");
+} catch (err) {
+  if (err instanceof WorkflowAbort) throw err; // required
+  // handle real errors
+}
+```
+
+If you _must_ handle errors, move the `try/catch` into the function passed to `context.run`.
+
+---
+
+## requestPayload Becoming Undefined
+
+During `context.call`, the workflow endpoint is invoked multiple times internally. Before the first step executes, `context.requestPayload` may appear `undefined`.
+
+**Fix:** capture the payload via a step:
+
+```ts
+export const { POST } = serve(async (context) => {
+  const payload = await context.run("get-payload", () => context.requestPayload);
+
+  // payload remains stable even during context.call
+  await context.call("my-call", {
+    url: "https://example.com",
+    body: payload,
+  });
+});
+```
+
+**Header considerations:** When triggering workflows, ensure payload‑friendly headers like:
+
+- `Content-Type: text/plain`
+- `Content-Type: application/json`
+
+---
+
+## Signature Verification Failures
+
+If QStash request verification fails:
+
+- Ensure the workflow is triggered through QStash (`client.trigger` or publish)
+- Verify `QSTASH_CURRENT_SIGNING_KEY` and `QSTASH_NEXT_SIGNING_KEY`
+- Pass appropriate `Content-Type` headers when triggering
+
+Error looks like:
+
+```
+Failed to verify that the Workflow request comes from QStash: ...
+```
+
+---
+
+## Authorization Errors from Early Returns
+
+If your workflow returns **before running any step**, the SDK interprets this as failed authorization:
+
+```
+HTTP 400 – Failed to authenticate Workflow request.
+```
+
+To safely perform non‑deterministic checks, wrap them in a step:
+
+```ts
+export const { POST } = serve(async (context) => {
+  const shouldExit = await context.run("check-condition", () => Math.random() > 0.5);
+  if (shouldExit) return;
+
+  // remaining workflow
+});
+```
+
+---
+
+## Retry Configuration
+
+Retries come from two locations:
+
+- Workflow start (`client.trigger`): default **3**, applies to workflow steps
+- `context.call`: default **0**
+- `context.invoke`: default **0**
+
+Use these in combination to tune behavior correctly.
+
+---
+
+## Verbose Mode Diagnostics
+
+Enable verbose logging to debug rare edge cases:
+
+```ts
+serve(handler, { verbose: true });
+```
+
+Useful warnings include:
+
+- Localhost in workflow URL
+- Duplicate step execution
+- Network response anomalies
+- Parallel `context.call` race warnings
+
+Each of these indicates environmental or routing issues rather than workflow logic problems.
+
+---
+
+## HTTPS Protocol Issues (Proxy Environments)
+
+If deployed behind a proxy that downgrades HTTPS → HTTP (e.g., Railway), the SDK may infer the wrong protocol.
+
+**Fix:** explicitly set:
+
+```
+UPSTASH_WORKFLOW_URL=https://your-deployment-url
+```
+
+---
+
+## Workflow Stuck on First Step
+
+If the first step appears stuck:
+
+- Check step logs in the dashboard
+- Ensure the endpoint URL is correct and reachable
+- Verify SDK versions
+- If inference is failing, explicitly set `baseUrl`:
+
+```ts
+serve(handler, { baseUrl: "https://your-url" });
+```
+
+---
+
+## Non‑workflow Destination Error
+
+Occurs when triggering a non‑workflow endpoint or using mismatched SDK versions.
+
+```
+detected a non-workflow destination for trigger/invoke
+```
+
+**Ensure:**
+
+- The URL points to a `serve()` workflow endpoint
+- Both caller and workflow endpoint use the latest SDK
+
+---
+
+## Vercel Preview Deployment Protection
+
+Preview deployments block external requests unless bypassed.
+
+**Steps:**
+
+1. Create a bypass secret in Vercel → Deployment Protection
+2. Add it to the QStash client + pass it when triggering
+
+```ts
+import { Client as QStash } from "@upstash/qstash";
+import { serve } from "@upstash/workflow/nextjs";
+
+export const { POST } = serve(
+  async (context) => {
+    // workflow logic
+  },
+  {
+    qstashClient: new QStash({
+      token: process.env.QSTASH_TOKEN!,
+      headers: {
+        "x-vercel-protection-bypass": process.env.VERCEL_AUTOMATION_BYPASS_SECRET!,
+      },
+    }),
+  }
+);
+
+// Triggering
+await client.trigger({
+  url: "https://preview.vercel.app/workflow",
+  headers: {
+    "x-vercel-protection-bypass": process.env.VERCEL_AUTOMATION_BYPASS_SECRET!,
+  },
+  body: "hello",
+});
+```
+
+Both trigger header and client header are required.

package/.agents/skills/upstash-box-js/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: upstash-box-js
+description: Work with the @upstash/box TypeScript/JavaScript SDK for sandboxed cloud containers with AI agents, shell, filesystem, and git. Use when building with Upstash Box, creating sandboxed environments, running AI agents in containers, or orchestrating parallel boxes.
+---
+
+# @upstash/box SDK
+
+Sandboxed cloud containers with built-in AI agents, shell, filesystem, and git.
+
+## Install & Setup
+
+```bash
+npm install @upstash/box
+```
+
+Set `UPSTASH_BOX_API_KEY` env var or pass `apiKey` to constructors.
+
+## Box Lifecycle
+
+```ts
+import { Box, Agent, ClaudeCode, BoxApiKey } from "@upstash/box"
+
+// Create with agent + git + env vars
+const box = await Box.create({
+  runtime: "node", // "node" | "python" | "golang" | "ruby" | "rust"
+  agent: {
+    harness: Agent.ClaudeCode, // Agent.Codex | Agent.OpenCode
+    model: ClaudeCode.Sonnet_4_5,
+    // apiKey options:
+    //   omit          → server decides which key to use
+    //   BoxApiKey.UpstashKey  → use Upstash-provided LLM key
+    //   BoxApiKey.StoredKey   → use key previously stored via Upstash Console
+    //   "sk-..."      → direct API key string
+    apiKey: BoxApiKey.UpstashKey,
+  },
+  git: { // all fields optional
+    token: process.env.GITHUB_TOKEN, // alternatively link your GitHub account via Upstash Console
+    userName: "Bot",
+    userEmail: "bot@example.com",
+  },
+  env: { DATABASE_URL: "..." },
+  skills: ["upstash/qstash-js"], // GitHub repos as agent skills
+})
+
+// Reconnect, list, delete, pause/resume
+const same = await Box.get(box.id)
+const all = await Box.list()
+await box.pause()
+await box.resume()
+await box.delete()  // irreversible
+const { status } = await box.getStatus()
+```
+
+## Agent Runs
+
+```ts
+import { z } from "zod"
+
+// Structured output with Zod schema
+const run = await box.agent.run({
+  prompt: "Review the code for security issues",
+  responseSchema: z.object({
+    verdict: z.enum(["approved", "changes_requested"]),
+    findings: z.array(z.object({
+      severity: z.enum(["high", "medium", "low"]),
+      file: z.string(),
+      issue: z.string(),
+    })),
+  }),
+  timeout: 120_000,
+  maxRetries: 2,
+  onToolUse: (tool) => console.log(tool.name, tool.input),
+})
+
+run.status  // "running" | "completed" | "failed" | "cancelled" | "detached"
+run.result  // typed from schema
+run.cost    // { inputTokens, outputTokens, computeMs, totalUsd }
+
+// Streaming
+const stream = await box.agent.stream({
+  prompt: "Build a REST API",
+})
+for await (const chunk of stream) { console.log(chunk) }
+
+// Fire-and-forget with webhook
+await box.agent.run({
+  prompt: "Run tests",
+  webhook: { url: "https://example.com/hook", headers: { Authorization: "Bearer ..." } },
+})
+```
+
+## Run Fields
+
+Every `run` (agent, command, or code) returns a `Run<T>`:
+
+```ts
+const run = await box.exec.command("npm test")
+run.id        // run ID
+run.status    // "completed" | "failed" | ...
+run.result    // string output (or typed T with responseSchema)
+run.exitCode  // number | null (null for agent runs)
+run.cost      // { inputTokens, outputTokens, computeMs, totalUsd }
+
+await run.cancel()          // cancel a running run
+const logs = await run.logs() // [{ timestamp, level, message }]
+```
+
+## Shell Execution
+
+```ts
+// Run commands
+const run = await box.exec.command("echo hello && ls -la")
+
+// Run code snippets — lang: "js" | "ts" | "python"
+const run2 = await box.exec.code({ code: "console.log(1+1)", lang: "js", timeout: 10_000 })
+
+// Streaming shell
+const stream = await box.exec.stream("npm run build")
+for await (const chunk of stream) {
+  // chunk: { type: "output", data } | { type: "exit", exitCode, cpuNs }
+}
+```
+
+## Filesystem
+
+```ts
+await box.files.write({ path: "/workspace/home/app.js", content: "console.log('hi')" })
+const content = await box.files.read("/workspace/home/app.js")
+const entries = await box.files.list("/workspace/home") // [{ name, path, size, is_dir, mod_time }]
+
+// Binary files — use encoding: "base64" for read and write
+await box.files.write({ path: "/workspace/home/image.png", content: base64String, encoding: "base64" })
+const b64 = await box.files.read("/workspace/home/image.png", { encoding: "base64" })
+
+// Upload local files, download box files
+await box.files.upload([{ path: "./local/file.txt", destination: "/workspace/home/file.txt" }])
+await box.files.download({ folder: "./output" })
+```
+
+## cd / Working Directory
+
+The SDK tracks `cwd` client-side. All operations (exec, files, git, agent) run relative to it.
+
+```ts
+box.cwd // current working directory (starts at /workspace/home)
+await box.cd("my-repo")     // relative to current cwd
+await box.cd("/workspace/home/other") // absolute path
+```
+
+## Git
+
+```ts
+await box.git.clone({ repo: "github.com/org/repo", branch: "main" })
+await box.cd("repo") // cd into cloned repo
+
+const status = await box.git.status()
+const diff = await box.git.diff()
+const { sha } = await box.git.commit({ message: "fix: resolve bug" })
+await box.git.push({ branch: "feature/fix" })
+
+await box.git.checkout({ branch: "release/v2" })
+const pr = await box.git.createPR({ title: "Fix bug", body: "...", base: "main" })
+// pr: { url, number, title, base }
+
+// Arbitrary git commands
+const { output } = await box.git.exec({ args: ["log", "--oneline", "-5"] })
+```
+
+## Snapshots & Fork
+
+```ts
+// Snapshot — checkpoint workspace state
+const snap = await box.snapshot({ name: "after-setup" })
+// snap: { id, name, box_id, size_bytes, status, created_at }
+
+const restored = await Box.fromSnapshot(snap.id)
+const snaps = await box.listSnapshots()
+await box.deleteSnapshot(snap.id)
+
+// Fork — clone live state into a new box
+const forked = await box.fork()
+```
+
+## EphemeralBox
+
+Lightweight, short-lived boxes (max 3 days). No agent, git, snapshot, or fork. Supports exec, files, cd, and snapshots only.
+
+```ts
+import { EphemeralBox } from "@upstash/box"
+
+const ebox = await EphemeralBox.create({
+  runtime: "python",
+  ttl: 3600,  // seconds, max 259200 (3 days)
+  env: { API_KEY: "..." },
+})
+
+ebox.expiresAt // unix timestamp when auto-deleted
+await ebox.exec.command("python -c 'print(1+1)'")
+await ebox.exec.code({ code: "print('hi')", lang: "python" })
+await ebox.files.write({ path: "/workspace/home/data.json", content: "{}" })
+await ebox.cd("subdir")
+await ebox.delete()
+
+// Restore from snapshot
+const ebox2 = await EphemeralBox.fromSnapshot(snap.id, { ttl: 7200 })
+```
+
+## Public URLs
+
+Expose box ports as public URLs with optional auth.
+
+```ts
+const publicURL = await box.getPublicURL(3000)
+// publicURL: { url: "https://{id}-3000.preview.box.upstash.com", port }
+
+const authed = await box.getPublicURL(3000, { bearerToken: true })
+// authed: { url, port, token }
+
+const basic = await box.getPublicURL(3000, { basicAuth: true })
+// basic: { url, port, username, password }
+
+const { publicURLs } = await box.listPublicURLs()
+await box.deletePublicURL(3000)
+```
+
+## MCP Servers
+
+Attach MCP servers to the box agent.
+
+```ts
+const box = await Box.create({
+  agent: { harness: Agent.ClaudeCode, model: ClaudeCode.Sonnet_4_5 },
+  mcpServers: [
+    { name: "fs", package: "@modelcontextprotocol/server-filesystem" },
+    { name: "custom", url: "https://mcp.example.com/sse", headers: { Authorization: "..." } },
+  ],
+})
+```
+
+## Gotchas
+
+- Default working directory is `/workspace/home`, not `/home` or `/`
+- `box.cd()` is client-side tracking — it validates the path exists but doesn't change the box's shell cwd. All SDK methods use it automatically.
+- `EphemeralBox` does NOT support `agent`, `git`, `fork`, or public URLs — use full `Box` for those
+- `run.exitCode` is `null` for agent runs, only available for exec commands
+- `box.delete()` is irreversible — snapshot first if you need the state
+- Git operations require `git.token` in `BoxConfig` for private repos and PRs
+- `Box.fromSnapshot()` creates a new box — it does not modify the original