v3: framework-agnostic deploy pipeline + standalone service clients

.agents/skills/file-infra-issue/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: file-infra-issue
+description: File a bug or enhancement on the agentuity/infra repo when the SDK's behavior is being broken or made worse by something on the platform side (Catalyst, Sandbox runtime, Ion, Gluon, Hadron, region routing, auth surfaces). Use this when an SDK debugging session ends with "this is the platform's fault, not ours" — unhelpful error messages from the API, opaque 5xx responses, behavior that contradicts the docs, missing capabilities the SDK is documented to expose. Always checks for duplicates first and refuses to file if the issue is actually an SDK bug.
+---
+
+# File Infra Issue
+
+When the SDK is breaking because of an infra-side problem (bad error responses, missing endpoints, misrouting, unauthorized where authorized was expected, etc.), file a clean, deduplicated issue on `agentuity/infra`.
+
+## When to use this skill
+
+Use it when **all** of the following are true:
+
+1. You hit a real failure (CI red, smoke test red, manual repro red), and
+2. The root cause sits on the **platform side** — Catalyst HTTP API, sandbox runtime images, Ion, Gluon, Hadron, region routing, auth/permission surfaces — not in SDK code, and
+3. The fix has to happen in `agentuity/infra` (or its downstream services), not in this repo.
+
+Concrete examples that qualify:
+
+- The API returns `500 Internal Server Error` for a user-input error that should be a structured 4xx.
+- An endpoint returns `401 Unauthorized` when the resource simply doesn't exist (should be `404`).
+- The SDK is documented to use SDK-key auth, but the endpoint silently rejects SDK keys and only accepts CLI tokens.
+- A sandbox runtime image is missing a binary the docs claim it ships.
+- An endpoint requires the caller to supply a piece of state (region, project id) that the platform should be able to resolve from existing context.
+- Error responses are missing context the user needs to debug (no session id, empty stderr, no message body).
+- Cross-region routing falls back in a confusing way (e.g., wrong host returns 401 instead of 421 misdirected).
+
+## When NOT to use this skill
+
+Refuse / suggest a different action if:
+
+- The bug is in **SDK code** (wrong types, bad URL construction, wrong header name on the SDK side, schema mismatch in our zod definitions, etc.) — fix it in this repo instead.
+- The "issue" is actually a **feature request** for the SDK that the platform already supports — file it on `agentuity/sdk` (or just implement it).
+- The behavior is **as documented** in the platform's own contract — the SDK is the wrong layer to be surprised by it; either update the SDK to match or update SDK docs.
+- You only **suspect** it's infra but haven't confirmed (e.g., didn't curl the endpoint directly, didn't compare against CLI behavior, didn't check whether SDK code is constructing a bad request). Confirm first.
+- The platform behavior is annoying but **intentional** (e.g., SDK keys can't list all orgs by design — that's an auth-model decision, not a bug).
+
+If unsure, prefer **not filing**. Duplicates and noise in `agentuity/infra` cost the team more than missing a marginal report.
+
+## Workflow
+
+### 1. Confirm it's actually infra
+
+Before doing anything else, answer all of these in writing (in your reasoning, not in the issue):
+
+- What does the SDK code do? (Read it. Don't guess.)
+- What does the platform return? (Reproduce with `curl` or a minimal script — not via the SDK — so the SDK isn't a confounding variable.)
+- Does the same call work from another client (CLI, browser, raw curl with a different token)? If yes, what's different?
+- Is there a documented contract (in `docs/`, the openapi spec, the platform's own README) that the platform is violating? Or are you the one who made an assumption?
+
+If after answering these you can't write **one sentence** describing what the platform should do differently, stop. The issue isn't ready.
+
+### 2. Check for duplicates
+
+Run **all three** searches before drafting. Different keyword sets catch different existing issues.
+
+```bash
+# Open issues, broad keyword
+gh issue list --repo agentuity/infra --state open --search "<short-keyword-from-symptom>" --limit 20 \
+  --json number,title,state,labels,updatedAt
+
+# Closed issues, same keyword (catches "fixed but still broken" cases)
+gh issue list --repo agentuity/infra --state closed --search "<short-keyword-from-symptom>" --limit 10 \
+  --json number,title,state,labels,closedAt
+
+# Component-scoped search (catalyst | sandbox | ion | gluon | hadron)
+gh issue list --repo agentuity/infra --state all --search "<component>" --limit 30 \
+  --json number,title,state,updatedAt
+```
+
+For each candidate, run `gh issue view <number> --repo agentuity/infra` and decide:
+
+- **Exact dupe** — don't file. Add a comment on the existing issue with the new repro, the new failing CI run link, or any extra detail you have. Use `gh issue comment <number> --repo agentuity/infra --body-file ...`.
+- **Related but distinct** — file the new one and reference the related issue with `Related: agentuity/infra#NNN` near the top of the body.
+- **Closed but you're hitting it again** — comment on the closed issue with the fresh repro and ask whether it should be reopened. Don't open a new one until that's been answered.
+
+### 3. Pick a label
+
+Match the symptom to the closest existing label (run `gh label list --repo agentuity/infra` if unsure):
+
+| Symptom | Label |
+|---|---|
+| Bad / unhelpful behavior, wrong status codes, broken endpoints | `bug` |
+| Missing endpoint / capability the SDK needs | `enhancement` |
+| Sandbox runtime, sandbox API, runtime images | (no specific label exists yet — use `bug` or `enhancement` and put `Sandbox:` in the title) |
+| Catalyst HTTP routing, region routing, auth surface | `bug` (or `enhancement` for new endpoints) |
+| Ion-specific | `Ion` |
+| Gluon-specific | `gluon` |
+| Hadron-specific | `hadron` |
+| Production outage right now | `outage` (only if it's actively broken in prod, not just CI) |
+
+If multiple apply, use multiple. Don't invent new labels.
+
+### 4. Write the issue
+
+Use this structure. Keep it short — engineers who triage these issues are busy. Aim for under 60 lines of body.
+
+```markdown
+## Problem
+
+<One paragraph. What does the platform do, and why is that wrong from the SDK's perspective? Be specific about endpoint, status codes, response shape.>
+
+## Reproduction
+
+<Minimal reproduction. Prefer raw `curl` so the SDK isn't a variable. Include the exact URL, method, headers (mask tokens), and the response status + body.>
+
+```bash
+curl -sS -i "https://catalyst-usc.agentuity.cloud/<endpoint>" \
+  -H "Authorization: Bearer <ck_live_...>" \
+  -H "Accept: application/json"
+# → HTTP/2 <status>
+# → <body>
+```
+
+## What we'd want instead
+
+<One short paragraph or a numbered list. Concrete: status code, response shape, behavior. Don't write essays — bullet points beat prose here.>
+
+## Why this matters
+
+<One short paragraph. What SDK code path / user workflow is broken because of this? Link the failing CI run, the SDK file, the docs page that contradicts the current behavior.>
+
+## References
+
+- SDK code: <link to file on github.com/agentuity/sdk at the current branch>
+- Failing run / repro: <link>
+- Related: agentuity/infra#NNN  _(only if there's a related-but-distinct issue)_
+```
+
+Style rules:
+
+- **No essays.** If the body is over ~60 lines, you're padding.
+- **No SDK debugging narrative.** They don't need to read your debugging session — they need the platform-facing facts.
+- **No "this is urgent" / "P0" framing** unless it's an actual prod outage. Use the `outage` label instead.
+- **Mask tokens.** Replace real `ck_live_...` values with `<ck_live_...>` placeholders.
+- **Title format**: `<Component>: <short symptom>`. Examples:
+  - `Catalyst: DB endpoints should resolve region server-side`
+  - `Sandbox: unhelpful errors when spawning a missing binary (500 from createJob, empty stderr from execute)`
+  - `Catalyst: 401 Unauthorized for missing resources should be 404`
+
+### 5. File it
+
+Write the body to a tempfile, then create:
+
+```bash
+gh issue create \
+  --repo agentuity/infra \
+  --title "<Component>: <short symptom>" \
+  --body-file /tmp/infra-issue.md \
+  --label bug   # or enhancement, or both
+```
+
+Capture the URL from the response. Reference it in:
+
+- The CI workflow comment that gates the failing test off (so future readers see the link)
+- The relevant SDK source file's comments (so future maintainers see why something looks weird)
+- Any tracking memory / project doc
+
+### 6. Loop back into the SDK
+
+If you gated a test off / added a workaround / hardcoded a value because of the platform issue, leave a code comment that:
+
+1. Explains what's currently broken on the platform side.
+2. Links the infra issue.
+3. Describes how to revert the workaround once the issue is fixed.
+
+Example:
+
+```yaml
+# Disabled: SDK keys can't currently auth against DB /resource endpoints.
+# See agentuity/infra#120. Re-enable by removing this `if: false` once the
+# issue is closed.
+if: false
+```
+
+## Scope guard
+
+Before filing, ask one last time: _"If a backend engineer reads this issue, will they immediately know what's broken, where it is, and what to change?"_ If not, the issue isn't ready — keep iterating before filing.

.agents/skills/service-docs-sync/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: service-docs-sync
+description: When editing files under packages/{keyvalue,vector,queue,email,db,schedule,task,webhook,sandbox,stream}/src/**, check whether the change is user-facing and, if so, update the matching page under docs/src/web/content/services/. Run after any commit that touches a service-client package — no exceptions, silently skipping docs is how they rot.
+version: 1.0.0
+---
+
+# Service Docs Sync
+
+When you change a service-client package, the docs site almost always needs a
+matching update. This skill catches the common failure mode where a PR ships
+new behaviour but the public docs keep describing the old API.
+
+## Scope
+
+Applies only to the following packages — the ones whose APIs end up in user
+code:
+
+| Package | Docs page(s) |
+| --- | --- |
+| `@agentuity/keyvalue` | `docs/src/web/content/services/storage/key-value.mdx` |
+| `@agentuity/vector` | `docs/src/web/content/services/storage/vector.mdx` |
+| `@agentuity/stream` | `docs/src/web/content/services/storage/durable-streams.mdx` |
+| `@agentuity/queue` | `docs/src/web/content/services/queues.mdx` |
+| `@agentuity/email` | `docs/src/web/content/services/email.mdx` |
+| `@agentuity/db` | `docs/src/web/content/services/database/index.mdx`, `postgres.mdx`, `drizzle.mdx` |
+| `@agentuity/schedule` | `docs/src/web/content/services/schedules.mdx` |
+| `@agentuity/task` | `docs/src/web/content/services/tasks.mdx` |
+| `@agentuity/webhook` | `docs/src/web/content/services/webhooks.mdx` |
+| `@agentuity/sandbox` | `docs/src/web/content/services/sandbox/index.mdx`, `sdk-usage.mdx`, `snapshots.mdx` |
+
+Not in scope:
+- Other packages (`cli`, `hono`, `adapter`, `core`, `schema`, `postgres`,
+  `drizzle`, `telemetry`, `analytics`, `coder`, `coder-tui`, `vscode`,
+  `claude-code`, `opencode`, `migrate`, `local`, `test-utils`, `runtime`,
+  `server`). Those have their own docs story owned elsewhere.
+- Test files (`test/**`, `*.test.ts`), tsconfig, package.json changes that
+  don't alter runtime behaviour.
+
+## When to activate
+
+Run this skill immediately after you change any file under
+`packages/<service>/src/**` for a service in the table above, before you
+open (or finalize) a PR. Don't skip it "just this once" — missed docs
+updates compound.
+
+## What counts as "user-facing"
+
+Use judgement; these are the categories that almost always require a docs
+update. If any of them apply, update the docs.
+
+### Almost always user-facing
+
+- **New public export** — any new `export` from `src/index.ts` (function,
+  class, type, const, enum). Even if it's an overload or a narrower variant
+  of an existing export.
+- **Changed signature on an existing export** — added/removed/renamed
+  parameters, changed parameter types, changed return type, added
+  overloads.
+- **Changed default value** — any argument default or option default that
+  users rely on.
+- **New or changed option on a config/options object** — e.g. adding
+  `timeout?: number` to a client constructor. Users discover these through
+  docs.
+- **New or changed error type** — new `StructuredError` variant, new
+  thrown class, new error shape returned. Affects user error-handling
+  code.
+- **Renamed public export** — even with a re-export alias for
+  compatibility, the docs need the new name.
+- **New environment variable read by the client** — e.g. the client now
+  reads `AGENTUITY_FOO_URL`. Users need to know it exists.
+- **Changed wire format** — request/response body shape, query-string
+  params, HTTP method, status codes users observe.
+- **Changed CLI output** for any CLI surface documented in the docs site.
+
+### Sometimes user-facing — judge with care
+
+- **Changed error messages** — if users grep logs or parse strings, yes.
+  If the message is informational only, probably no.
+- **Performance characteristics** — mention only if the docs claim a
+  specific SLA / latency / throughput that's no longer true.
+- **New retry/backoff behaviour** — yes if observable (timing, logs); no
+  if pure internal.
+
+### Not user-facing — skip the skill
+
+- Internal refactors that leave the public export list and signatures
+  identical.
+- Comment / JSDoc edits that are not part of the exported API surface.
+- Test-only changes.
+- Build/tooling changes (tsconfig, bunfig, package.json scripts).
+- Dependency bumps that don't change behaviour users observe.
+
+When in doubt, treat it as user-facing and update the docs. Docs debt is
+expensive; a 3-minute docs PR isn't.
+
+## Workflow
+
+### 1. Identify what you changed
+
+```bash
+# From the root of the repo
+git diff --stat HEAD -- 'packages/<service>/src/**'
+```
+
+Focus on changes to:
+- `packages/<service>/src/index.ts` (most user-facing)
+- Files exported from `index.ts` (follow re-exports)
+- Type definition files
+- Any file that defines a class, function, or const that is re-exported
+
+### 2. Read the matching docs page(s)
+
+From the table above. Open the full page, not just grep for your symbol —
+user-facing code changes often cascade (example code gets stale, option
+tables get out of date, "see also" links shift).
+
+### 3. Decide: does any category in "Almost always user-facing" apply?
+
+If yes → update docs this PR. Don't leave a TODO.
+If no and "Sometimes" category matches → make the judgement call; bias
+toward updating.
+If no to everything → skip, note why in the PR description if the diff
+looks alarming ("refactors internals of X, no public API change").
+
+### 4. Update the docs
+
+Typical edits you'll make in the `.mdx` files:
+- Update code samples to use the new signature / options
+- Add an entry for a new export to the page's symbol reference (if it
+  lists them)
+- Add / update the option table for a changed options object
+- Add a short migration note at the top of the page if behaviour
+  silently changes
+- Fix cross-page links if you moved or renamed a symbol
+
+Docs pages use MDX; front-matter keys like `title`, `description`, and
+`order` at the top should be preserved exactly.
+
+### 5. Verify
+
+Before committing docs:
+```bash
+cd docs && bun run typecheck
+```
+
+The SDK Explorer has its own dev server if you want a visual check:
+```bash
+cd docs && bun run dev
+```
+
+### 6. Commit
+
+Include the docs update in the same PR as the code change — not a
+follow-up. Split the commit if you prefer
+(`feat(queue): add idempotency key option` + `docs(queue): document
+idempotency option`), but keep them in the same PR so review catches any
+drift between the two.
+
+## Anti-patterns
+
+- **"I'll update docs after this merges"** — you won't. Someone else will
+  discover stale docs three releases later.
+- **"Docs are owned by someone else"** — true at the macro scale (full
+  rewrites), false for incremental API changes. If you changed
+  `packages/keyvalue/src/index.ts`, you own the matching paragraph in
+  `key-value.mdx`.
+- **"It's only a bug fix"** — if the bug changed observable behaviour,
+  the docs need to match the new (correct) behaviour.
+- **Updating only the code example and not the surrounding prose** —
+  examples become stale because the prose around them still describes
+  the old API. Re-read the whole page section, not just the fenced
+  block.
+
+## If the docs page doesn't exist
+
+If you're introducing an entirely new service client (rare), create a
+new `.mdx` page under `docs/src/web/content/services/` mirroring the
+structure of an existing one (e.g. `queues.mdx` is a good template),
+and add it to the nav in `docs/src/web/components/docs/nav-data.ts`.
+
+## Memory pointers
+
+- Memory #105 (docs rewrite) covers the broader *structural* docs
+  cleanup — not this skill's concern. This skill is purely about
+  keeping specific pages in sync with specific code as changes land.
+- Memory #78 (v3 overview) explains what each service package is for.

.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
 	},
 	"metadata": {
 		"description": "Agentuity plugins for Claude Code",
-		"version": "2.0.16"
+		"version": "3.0.0-beta.2"
 	},
 	"plugins": [
 		{
 			"name": "agentuity",
 			"source": "./packages/claude-code",
 			"description": "Deploy websites, apps, and AI agents to Agentuity — with managed databases, storage, queues, and more",
-			"version": "2.0.16",
+			"version": "3.0.0-beta.2",
 			"author": {
 				"name": "Agentuity"
 			},

.github/workflows/biome.yml

@@ -8,12 +8,15 @@ on:
       - "release/**"
   pull_request:
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   check:
     name: Format & Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - uses: oven-sh/setup-bun@v2
         with: