Update to Vercel

{
  "description": "Vercel Queues guidance — durable topics with at-least-once delivery, independent consumer groups, retries, delays, and idempotency keys via @vercel/queue (JS) or vercel-queue (Python). Use when deferring background work, buffering traffic, fanning out events, or choosing between Queues and Workflows.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 97
    }
  ],
  "name": "queues",
  "skill_md_contents": "---\nname: queues\ndescription: Vercel Queues guidance — durable topics with at-least-once delivery, independent consumer groups, retries, delays, and idempotency keys via @vercel/queue (JS) or vercel-queue (Python). Use when deferring background work, buffering traffic, fanning out events, or choosing between Queues and Workflows.\nsummary: \"Vercel Queues (beta) publishes JSON messages to durable topics with `send()` from `@vercel/queue`; consumers are Vercel Functions exported with `handleCallback()` and registered in vercel.json under `functions.<path>.experimentalTriggers` as `{ type: 'queue/v2beta', topic: '<name>' }`. Delivery is at-least-once with automatic retries; use Workflows instead for multi-step durable logic.\"\nmetadata:\n  priority: 6\n  docs:\n    - \"https://vercel.com/docs/queues\"\n    - \"https://vercel.com/docs/queues/sdk\"\n  sitemap: \"https://vercel.com/sitemap.xml\"\n  pathPatterns:\n    - 'app/api/queues/**'\n    - 'src/app/api/queues/**'\n    - 'pages/api/queues/**'\n    - 'lib/queue.*'\n    - 'src/lib/queue.*'\n    - 'lib/queues/**'\n    - 'src/lib/queues/**'\n  bashPatterns:\n    - '\\bnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/queue\\b'\n    - '\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/queue\\b'\n    - '\\bbun\\s+(install|i|add)\\s+[^\\n]*@vercel/queue\\b'\n    - '\\byarn\\s+add\\s+[^\\n]*@vercel/queue\\b'\n    - '\\b(pip|uv)\\s+(install|add)\\s+[^\\n]*vercel-queue\\b'\n  importPatterns:\n    - \"@vercel/queue\"\n  promptSignals:\n    phrases:\n      - \"vercel queues\"\n      - \"@vercel/queue\"\n      - \"background job\"\n      - \"background jobs\"\n      - \"message queue\"\n      - \"job queue\"\n      - \"consumer group\"\n    allOf:\n      - [vercel, queues]\n      - [queue, topic]\n      - [queue, consumer]\n      - [queue, buffer]\n      - [fan, out]\n    anyOf:\n      - \"queue\"\n      - \"topic\"\n      - \"retry\"\n      - \"consumer\"\n      - \"buffer\"\n      - \"background\"\n    noneOf:\n      - \"build queue\"\n      - \"deployment queue\"\n      - \"queued deployment\"\n      - \"deployments stuck\"\n      - \"queues up deployments\"\n      - \"queue up deployments\"\n      - \"queues my deployments\"\n      - \"queues our deployments\"\n      - \"queues your deployments\"\n      - \"queues the deployments\"\n      - \"queues deployments\"\n      - \"queues builds\"\n      - \"queues my builds\"\n    minScore: 6\nretrieval:\n  aliases:\n    - queues\n    - message queue\n    - background jobs\n    - event streaming\n    - pub sub\n  intents:\n    - defer work to a queue\n    - process background jobs\n    - fan out events to consumers\n    - retry failed jobs\n    - buffer traffic spikes\n  entities:\n    - Vercel Queues\n    - \"@vercel/queue\"\n    - topic\n    - consumer group\n    - handleCallback\n    - experimentalTriggers\nchainTo:\n  -\n    pattern: '\"use workflow\"|\"use step\"|from\\s+[''\"]workflow[''\"]'\n    targetSkill: workflow\n    message: 'Workflow SDK code alongside Queues — Workflows is built on Queues and adds durable steps, sleep, and hooks. Loading Workflow guidance.'\n  -\n    pattern: 'from\\s+[''\"](bullmq|bull|bee-queue|agenda)[''\"]|@aws-sdk/client-sqs'\n    targetSkill: queues\n    message: 'Third-party job queue detected — Vercel Queues provides durable topics with retries and fan-out without running a broker. Loading Queues guidance.'\n    skipIfFileContains: '@vercel/queue'\n\n---\n\n# Vercel Queues\n\nYou are an expert in Vercel Queues, the durable message topics that power background work and agent events on Vercel.\n\n## What It Is\n\nVercel Queues (public beta) gives you durable, append-only topics. Producers publish JSON messages, and every subscribed consumer group receives every message with at-least-once delivery and automatic retries. New consumer groups can join later and replay non-expired history. Queues is the primitive under Vercel Workflows; use Queues directly when you need control over publishing, consumption, and routing.\n\n- **Topic**: a named durable log of messages, created on first publish\n- **Consumer group**: an independent subscriber that receives every message on a topic\n- **Delivery**: at-least-once; handlers must be idempotent\n- **Retention**: 24 hours by default, up to 7 days; delivery can be delayed up to the retention period\n- **Modes**: push (Vercel invokes your function) or poll (your own workers pull messages from any environment)\n\n## Choose Queues or Workflows\n\n| Need | Use | Why |\n|------|-----|-----|\n| Fire-and-forget background job, fan-out, buffering | **Queues** | Direct publish/consume, independent consumer groups |\n| Multi-step logic with sleep, hooks, or human approval | **Workflows** (`⤳ skill: workflow`) | Durable steps and replay built on top of Queues |\n| Scheduled invocation on a cron | Cron Jobs (`⤳ skill: vercel-functions`) | Time-based trigger, not message-based |\n\n## Quickstart (Next.js App Router)\n\nInstall the SDK:\n\n```bash\nnpm install @vercel/queue\n```\n\nPublish from any route, Server Action, or function:\n\n```ts\n// app/api/orders/route.ts\nimport { send } from '@vercel/queue';\n\nexport async function POST(request: Request) {\n  const body = await request.json();\n  const { messageId } = await send('orders', { orderId: body.orderId, action: 'process' });\n  return Response.json({ messageId });\n}\n```\n\nConsume with a push-mode handler. Messages are acknowledged when the handler returns and retried when it throws:\n\n```ts\n// app/api/queues/process-order/route.ts\nimport { handleCallback } from '@vercel/queue';\n\nexport const POST = handleCallback(async (message, metadata) => {\n  await processOrder(message);\n  console.log('processed', metadata.messageId, 'delivery', metadata.deliveryCount);\n});\n```\n\nRegister the consumer in `vercel.json` (or `vercel.ts`) so Vercel routes the topic to that function:\n\n```json filename=\"vercel.json\"\n{\n  \"functions\": {\n    \"app/api/queues/process-order/route.ts\": {\n      \"experimentalTriggers\": [{ \"type\": \"queue/v2beta\", \"topic\": \"orders\" }]\n    }\n  }\n}\n```\n\nRun `vercel link` and `vercel env pull` before local development so the SDK can authenticate.\n\n## Send Options\n\n```ts\nawait send('orders', payload, {\n  region: 'sfo1',            // target a specific region\n  retentionSeconds: 3600,    // message TTL; min 60, max 604800 (7 days); default 24 hours\n  delaySeconds: 60,          // delay first delivery; max 7 days, capped at the TTL\n  idempotencyKey: 'order-123', // duplicates within min(retention, 24 hours) are dropped\n  headers: { 'x-trace-id': 'abc-123' },\n});\n```\n\nCreate a `QueueClient` when you need defaults, a fixed region, or multiple clients:\n\n```ts\n// lib/queue.ts\nimport { QueueClient } from '@vercel/queue';\n\nconst queue = new QueueClient({ region: 'sfo1' });\nexport const { send, handleCallback } = queue;\n```\n\n## Consumer Options and Retries\n\n`handleCallback(handler, options)` accepts:\n\n| Option | Default | Notes |\n|--------|---------|-------|\n| `visibilityTimeoutSeconds` | 300 | How long a message stays in flight; the SDK re-extends the lease while the handler runs |\n| `retry` | trigger `retryAfterSeconds` (60s) | `(error, metadata) => { afterSeconds } \\| { acknowledge: true } \\| undefined` |\n\nHandle poison messages by acknowledging after a delivery-count threshold:\n\n```ts\nexport const POST = handleCallback(processOrder, {\n  retry: (error, metadata) => {\n    if (metadata.deliveryCount > 5) return { acknowledge: true }; // stop retrying\n    return { afterSeconds: Math.min(300, 2 ** metadata.deliveryCount * 5) };\n  },\n});\n```\n\n`metadata` includes `messageId`, `deliveryCount`, `createdAt`, `expiresAt`, `topicName`, `consumerGroup`, and `region`.\n\nFor Express, Connect, or Next.js Pages Router handlers use `queue.handleNodeCallback(async (message, metadata) => ...)` from a `QueueClient` instance, which takes `(req, res)`.\n\n## Other Runtimes and Frameworks\n\n- **Python**: `vercel-queue` publishes and consumes with the same topic model, and FastAPI, Flask, and Django apps can use it; Celery and Dramatiq integrations are documented under the Python backend frameworks.\n- **Nitro / Nuxt**: declare `vercel.queues.triggers` in `nitro.config.ts` and handle messages with the `vercel:queue` runtime hook; `send` from `@vercel/queue` works in any server route.\n- **Poll mode**: pull messages from your own workers in any environment when push delivery to a Vercel Function does not fit.\n- **Payloads**: JSON by default; use `BufferTransport` for binary or `StreamTransport` for large bodies when constructing a `QueueClient`.\n\n## Errors\n\n`@vercel/queue` exports typed errors: `UnauthorizedError`, `BadRequestError`, `MessageNotFoundError`, and `QueueEmptyError`. Duplicate idempotency keys do not throw; the duplicate is silently dropped.\n\n## Common Pitfalls\n\n1. **Missing trigger**: a `handleCallback` route with no `experimentalTriggers` entry never receives messages. Register every consumer in `vercel.json`/`vercel.ts`.\n2. **Non-idempotent handlers**: delivery is at-least-once. Key side effects on `metadata.messageId` or your own `idempotencyKey`.\n3. **Retrying forever**: without a `retry` policy that acknowledges poison messages or a trigger `maxDeliveries` cap, a permanently failing message is redelivered until it expires.\n4. **Using Queues for multi-step logic**: if you need sleep, hooks, or approvals between steps, use Workflows instead of chaining topics by hand.\n5. **Local dev without credentials**: run `vercel link` and `vercel env pull` first; otherwise `send()` throws `Failed to get OIDC token for local development`.\n\n## References\n\n- 📖 docs: https://vercel.com/docs/queues\n- 📖 JS SDK: https://vercel.com/docs/queues/sdk\n- 📖 Python SDK: https://vercel.com/docs/queues/python-sdk\n- 📖 poll mode: https://vercel.com/docs/queues/poll-mode\n- 📖 pricing and limits: https://vercel.com/docs/queues/pricing\n"
}