@guuey/create-agentic-app 0.1.3 → 0.2.0

package/README.md

@@ -29,3 +29,13 @@ guuey deploy        # hosted: agent + MCP servers live on guuey
 ```
 npx @guuey/create-agentic-app <dir> [--framework claude-agent-sdk|openai-agents-sdk] [--skip-install]
 ```
+
+## Binding to an existing app
+
+`guuey deploy` (above) creates a new app on first run. To bind this
+scaffold to an app you already have — including a no-code agent built in
+[Studio](https://studio.guuey.com) — run `guuey pull --app-id <id>` instead: it
+refreshes `guuey.json`'s `appId`, and for a Studio no-code app pulls the
+Studio-authored system prompt/model/MCP servers down into the scaffold too.
+There is no `guuey link` command — `guuey pull --app-id` is the only way
+to bind a project to an existing app.

package/dist/templates/claude-agent-sdk/AGENTS.md

@@ -0,0 +1,135 @@
+# AGENTS.md — steering for the coding agent working in this repo
+
+You (the coding agent) are extending a guuey agentic app. Before you reach
+for a database or a cache, read this file. The single most common mistake
+here is standing up local Redis/SQLite/file-based state "just to get
+something working" — **don't.** Every pod this project deploys to
+(`src/worker.ts`'s agent pod — including every `kind: colocated` `mcps/*`
+server auto-spawned inside it, like this scaffold's `mcps/todo` — and every
+`mcps/*` server deployed with `kind: hosted`) is **ephemeral and horizontally
+replaced**: gVisor-isolated,
+scale-to-zero, ordinary process death on every deploy or idle timeout. A
+local file or an in-process `Map` used as a database is not a shortcut —
+it is silent data loss the first time the pod recycles.
+
+Use this table to route persistence decisions. Pick a row, don't invent one.
+
+| Need                                                                                                         | Use                                                                                                                                                                                                                                                                                                                                                                    | Why                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Small per-user state on an MCP server (idempotency keys, rate-limit counters, OAuth nonces, prefs, a few KB) | [`@guuey/state`](https://www.npmjs.com/package/@guuey/state) — `withGuueyContext(scopeFromAuthorization(...), fn)`                                                                                                                                                                                                                                                     | Zero auth code — guuey owns the identity rails. Durable, per-`(user, mcp)`, survives pod restarts.                                                                                                                                                                                                                                      |
+| Large or relational data (rows, queries, joins, anything you'd reach for Postgres/Redis for)                 | An external managed serverless DB — Neon, Upstash, Supabase, or Turso — wired in via `guuey mcp secrets set DATABASE_URL=... --server <id>` (hosted MCP) or `guuey env set DATABASE_URL=...` (the agent worker and its colocated MCP children — the pod's declared env/secrets are handed to every colocated child), consumed through the provider's serverless driver | Guuey **integrates, never operates** databases — that's the platform's hosting policy, not a v1 gap. Pick the provider's **`us-east-1`** region: a guuey-hosted MCP → provider hop is then same-region AWS backbone, single-digit-ms — comparable to a cross-AZ hop, and agent turns are already dominated by seconds of LLM inference. |
+| Local Redis, SQLite, or any file written as a database                                                       | **Never.** Not for v1, not "temporarily."                                                                                                                                                                                                                                                                                                                              | Pods are ephemeral and horizontally replaced — a local store vanishes on the next deploy, restart, or scale event, with no warning to you or the user.                                                                                                                                                                                  |
+| Per-user files/blobs from **inside the agent pod** (`src/worker.ts`)                                         | [`@guuey/fs`](https://www.npmjs.com/package/@guuey/fs)'s `homeDir()`/`appDir()`/`sessionDir()`, or the raw `$GUUEY_HOME_DIR`/`$GUUEY_APP_DIR` env vars + `node:fs`                                                                                                                                                                                                     | Every invoke already gets these three bound directories — `$GUUEY_HOME_DIR` is durable per-user, `$GUUEY_APP_DIR` is read-only shared, cwd is session scratch. No wrapper API required, but the helpers save you the env-var lookups.                                                                                                   |
+| Per-user files/blobs from **inside an MCP server** (`mcps/*`)                                                | Not yet available — `@guuey/files` is planned but not shipped. Fall back to the managed-DB row above (e.g. store blobs in the provider's object storage) until it lands.                                                                                                                                                                                               | Don't build against an API that doesn't exist yet.                                                                                                                                                                                                                                                                                      |
+| Conversation / chat history                                                                                  | **Do not re-implement.** The platform already persists it.                                                                                                                                                                                                                                                                                                             | Guuey writes thread history to DynamoDB and streams it back over AppSync; agents that keep their own transcript store are duplicating (and diverging from) data the platform already owns.                                                                                                                                              |
+
+## `@guuey/state`: the one-line pattern
+
+`@guuey/state` only works inside an MCP server whose `guuey.json` entry is
+**federated** — that's the opt-in. A `kind: colocated` entry (like
+`mcps/todo` in this scaffold) or a `kind: hosted` entry is federated
+automatically. If you add a `kind: external` entry (a server you host
+yourself, reached by URL), you must set `federate: true` on it:
+
+```json
+{
+  "kind": "external",
+  "url": "https://your-server.example.com",
+  "federate": true
+}
+```
+
+Without `federate: true` (or `kind: colocated`/`kind: hosted`/a `ggui`
+URL), guuey has no
+identity to hand your server — a plain external entry with static
+`headers` gets **no token and no state.** The token guuey sends on every
+request to a federated server IS the credential; there is no separate
+API key to provision.
+
+Inside a federated MCP server, wrap each request in
+`withGuueyContext(scopeFromAuthorization(header), fn)` and use the
+barrel-exported `kv` inside `fn` — that's the whole integration. One
+complete, runnable example — an idempotency-key check on a tool call,
+using the raw Node `http` transport this scaffold's `mcps/todo/src/server.ts`
+already uses:
+
+```ts
+import { createHash } from "node:crypto";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { withGuueyContext, scopeFromAuthorization, kv, QuotaExceededError } from "@guuey/state";
+
+// Inside the per-request handler (see mcps/todo/src/server.ts for the
+// full StreamableHTTPServerTransport wiring this drops into):
+async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  const authHeader = req.headers.authorization;
+  if (typeof authHeader !== "string") {
+    res.writeHead(401).end();
+    return;
+  }
+
+  await withGuueyContext(scopeFromAuthorization(authHeader), async () => {
+    // ... hand off to your MCP transport/tool dispatch here; the
+    // AsyncLocalStorage context set above is visible to every `kv.*`
+    // call for the lifetime of this request, however deep the call
+    // stack goes (tool handlers, helper functions, etc.).
+    await handleCreateOrder({ orderPayload: "..." });
+  });
+}
+
+async function handleCreateOrder(input: { orderPayload: string }): Promise<{ duplicate: boolean }> {
+  const idempotencyKey = `order:${createHash("sha256").update(input.orderPayload).digest("hex")}`;
+
+  if (await kv.has(idempotencyKey)) {
+    return { duplicate: true };
+  }
+
+  try {
+    // TTL is required on every `set` — no permanent keys. Pick a window
+    // that covers realistic retry storms; 1 hour is a reasonable default
+    // for an idempotency key.
+    await kv.set(idempotencyKey, true, { ttl: 60 * 60 });
+  } catch (err) {
+    if (err instanceof QuotaExceededError) {
+      // The (user, mcp) scope hit its 1 MiB cap. Surface this to the
+      // caller instead of silently dropping the idempotency guard.
+      throw new Error("state quota exceeded — cannot verify idempotency");
+    }
+    throw err;
+  }
+
+  // ... actually create the order here.
+  return { duplicate: false };
+}
+```
+
+`scopeFromAuthorization` derives `{ userId, mcpId }` from the inbound
+`Authorization: Bearer <jwt>` header guuey sends on every federated call —
+`userId` from the JWT's `sub`, `mcpId` deterministically from its `aud`
+(your server's federated resource URL). You never assert either id
+yourself; a mismatched or missing token is rejected server-side.
+
+## The hard caps (design your data model around these, don't work around them)
+
+`@guuey/state` is a KV, not a database — enforced, not a suggestion:
+
+| Cap                | Value                                         |
+| ------------------ | --------------------------------------------- |
+| Scope size         | 1 MiB (per `(user, mcp)`, key bytes included) |
+| Single value       | 64 KiB                                        |
+| TTL                | required, ≤ 90 days — no permanent keys       |
+| `keys()` page size | ≤ 1000                                        |
+| `mget()` batch     | ≤ 100 keys                                    |
+| Counters           | safe integers only (`increment`/`decrement`)  |
+
+If your data model needs more than this — queries, joins, cross-user
+data, anything past a long tail of small per-user facts — that's the
+signal to use the managed-DB row above, not to fight the cap.
+
+## Chat history: really, don't
+
+If you find yourself writing message transcripts to `@guuey/state`,
+`$GUUEY_HOME_DIR`, or an external DB keyed by conversation, stop — that's
+the platform's job. Guuey persists every thread to DynamoDB and streams
+history back over AppSync subscriptions; the client and Portal already
+read it from there. A parallel, agent-owned history store will drift from
+the platform's copy and confuse users about which one is authoritative.

package/dist/templates/claude-agent-sdk/README.md

@@ -9,7 +9,7 @@ locally with one command, and deployable to guuey with one more.
 ```
 .
 ├── guuey.json          # the deploy contract: agent framework/model, system prompt,
-│                        #   mcpServers (name → local dev port / hosted source), ggui config
+│                        #   mcpServers (name → colocated source + devPort), ggui config
 ├── package.json         # agent deps + the pnpm workspace root (workspaces: mcps/*, web)
 ├── src/worker.ts        # your agent code (code-mode worker); build emits ./guuey.worker.js
 ├── prompts/system.md    # system prompt, referenced from guuey.json#agent.systemPrompt.file
@@ -38,16 +38,19 @@ cp .env.example .env.local   # done automatically on scaffold if .env.local is a
 pnpm dev
 ```
 
-`pnpm dev` (`scripts/dev.mjs`) boots five processes with prefixed, interleaved
+`pnpm dev` (`scripts/dev.mjs`) boots four processes with prefixed, interleaved
 logs. Ctrl-C tears all of them down together.
 
-| process      | port  | what                                                         |
-| ------------ | ----- | ------------------------------------------------------------ |
-| `worker`     | —     | `tsup --watch` — rebuilds `guuey.worker.js` on every save    |
-| `guuey dev`  | :6790 | local router: spawns your worker per turn, streams SSE       |
-| `mcps/todo`  | :6782 | the example MCP server (copy this directory to add your own) |
-| `ggui serve` | :6781 | local generative-UI server, over `ggui/`                     |
-| `web`        | :6890 | the Vite chat SPA                                            |
+| process      | port  | what                                                                                                                                       |
+| ------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `worker`     | —     | `tsup --watch` — rebuilds `guuey.worker.js` on every save                                                                                  |
+| `guuey dev`  | :6790 | local router: spawns your worker per turn, streams SSE; auto-spawns every `colocated` MCP entry — `mcps/todo` lands on its `devPort` :6782 |
+| `ggui serve` | :6781 | local generative-UI server, over `ggui/`                                                                                                   |
+| `web`        | :6890 | the Vite chat SPA                                                                                                                          |
+
+The todo MCP still answers on :6782 — it's just a supervised child of
+`guuey dev` now (copy `mcps/todo/` to add your own server; new `colocated`
+entries in `guuey.json` are auto-spawned the same way).
 
 Open http://localhost:6890 to chat with your agent locally.
 
@@ -68,9 +71,13 @@ that only matter once real users and real money are involved:
   DynamoDB so users can resume a thread.
 
 None of this changes your code — `guuey.json` is the same file in both
-worlds; only how it's resolved differs (`guuey dev` points MCP server names
-at `localhost:<devPort>`, `guuey deploy` points them at the platform's
-federated URLs).
+worlds; only how it's resolved differs. Locally, `guuey dev` auto-spawns each
+`colocated` entry on its `devPort` and points the agent at
+`localhost:<devPort>`; deployed, the same server code runs as a supervised
+child inside your agent's pod, reached over the pod's loopback with a
+per-request federated identity. (`hosted` entries deploy to the platform's
+federated URLs; locally they need a `devPort` pointing at a server you run
+yourself, or they're skipped with a warning.)
 
 ## Deploying
 
@@ -83,17 +90,40 @@ guuey deploy   # ships everything
 anything user-visible changes:
 
 1. **MCP leg** — deploys each `hosted` entry under `guuey.json#agent.mcpServers`
-   (e.g. `mcps/todo`) as its own hosted MCP server (build → deploy → registry),
-   then writes the resulting server id back into `guuey.json`.
+   as its own hosted MCP server (build → deploy → registry), then writes the
+   resulting server id back into `guuey.json`. This scaffold has none — the
+   todo MCP is `colocated`, so this leg is a no-op here.
 2. **ggui asset leg** — pushes `ggui/` (ggui.json, blueprints, themes) to your
    app's guuey-managed ggui instance.
 3. **Agent leg** — builds `src/worker.ts` into `guuey.worker.js`, packs the
-   project root, and deploys it as a gVisor-isolated, scale-to-zero pod.
+   project root (including `mcps/`), and deploys it as a gVisor-isolated,
+   scale-to-zero pod. Each `colocated` entry (e.g. `mcps/todo`) is built into
+   the worker image and auto-spawned as a supervised, sandboxed child at pod
+   boot — no separate server, registry row, or write-back.
 4. **Output** — prints your agent's endpoint URL and a Portal deep link.
 
 Re-running `guuey deploy` converges: unchanged pieces are skipped or reused,
 nothing is duplicated.
 
+## Filesystem + memory
+
+Every deployed invoke gets three bound directories — `$GUUEY_HOME_DIR`
+(durable, per-user), `$GUUEY_APP_DIR` (read-only, shared), and cwd (session
+scratch) — plain `node:fs`, no wrapper API required. Signed-in users get
+durable cross-session memory for free (a platform-owned prompt tells the
+model to read/write `$GUUEY_HOME_DIR/memories/MEMORY.md`); guests never get
+durable storage, by design. **This recall is `claude-agent-sdk`-only today**
+— openai-agents-sdk and google-adk agents get the three bound directories
+but not the automatic memory-file recall; all-framework support arrives
+with guuey's own memory MCP (a platform tool every framework can call over
+its existing MCP channel). Framework-native memory backends (e.g. ADK's
+Vertex MemoryBank) are unsupported on Guuey — they'd store user data
+outside guuey's deletion boundary. Full contract, code examples, and
+rollout status: the "Your agent's filesystem" section of the guuey
+monorepo's `docs/quickstart.md`, or
+[`@guuey/fs`](https://www.npmjs.com/package/@guuey/fs)'s own README — an
+optional, three-helper sugar layer over the same paths.
+
 ## How people talk to your agent
 
 - **guuey Portal** — a Telegram-like agent App Store and universal chat

package/dist/templates/claude-agent-sdk/guuey.json

@@ -6,7 +6,8 @@
     "model": "claude-sonnet-5",
     "systemPrompt": { "file": "prompts/system.md" },
     "mcpServers": {
-      "todo": { "kind": "hosted", "source": "./mcps/todo", "devPort": 6782 }
+      "todo": { "kind": "colocated", "source": "./mcps/todo", "devPort": 6782 },
+      "ggui": { "kind": "external", "url": "https://mcp.ggui.ai", "transport": "http" }
     }
   },
   "ggui": { "configFile": "./ggui/ggui.json" }

package/dist/templates/claude-agent-sdk/mcps/todo/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "tsx src/server.ts",
-    "build": "tsup src/server.ts --format esm -d dist",
+    "build": "tsup",
     "start": "node dist/server.js",
     "typecheck": "tsc --noEmit"
   },

package/dist/templates/claude-agent-sdk/mcps/todo/tsup.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'tsup';
+
+// Self-contained ON PURPOSE — do not delete this file. Without a local
+// config, tsup's upward config discovery finds the scaffold ROOT
+// tsup.config.ts; its bundled form imports 'tsup' from the scaffold root,
+// which the platform image build deliberately leaves un-installed when the
+// bundled guuey.worker.js skips the root install — every colocated build
+// then dies with ERR_MODULE_NOT_FOUND (guuey#19). A config here stops the
+// walk; `defineConfig` resolves from this package's own devDependencies.
+export default defineConfig({
+  entry: ['src/server.ts'],
+  format: 'esm',
+  outDir: 'dist',
+});

package/dist/templates/claude-agent-sdk/package.json

@@ -10,11 +10,11 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.199",
-    "@guuey/config": "0.1.1",
-    "@guuey/worker": "0.1.1"
+    "@guuey/config": "0.2.0",
+    "@guuey/worker": "0.2.0"
   },
   "devDependencies": {
-    "@guuey/cli": "0.1.3",
+    "@guuey/cli": "0.2.0",
     "tsup": "^8.5.0",
     "tsx": "^4.19.0",
     "typescript": "^5.8.0"

package/dist/templates/claude-agent-sdk/scripts/dev.mjs

@@ -29,10 +29,11 @@ if (!existsSync(".env.local"))
   console.warn("hint: cp .env.example .env.local and set your LLM key");
 
 boot("worker", "pnpm", ["exec", "tsup", "--watch"]); // rebuilds guuey.worker.js on change
+// `guuey dev` auto-spawns every `kind: 'colocated'` mcpServers entry itself
+// (name→localhost devPort resolution) — the todo MCP is colocated, so it no
+// longer needs its own boot() here; a manual second spawn would double-bind
+// :6782 and crash with EADDRINUSE.
 boot("agent", "pnpm", ["exec", "guuey", "dev", "--serve", "--port", "6790"]);
-boot("todo", "pnpm", ["--filter", "@agentic-app-template/todo-mcp", "dev"], {
-  env: { ...process.env, PORT: "6782" },
-});
 boot("ggui", "pnpm", ["exec", "ggui", "serve", "--mcp-only", "--dev-allow-all", "--port", "6781"], {
   cwd: "ggui",
 });

package/dist/templates/claude-agent-sdk/src/agent-config.ts

@@ -7,7 +7,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { parseGuueyJson, type GuueyAgent } from "@guuey/config";
-import type { Invoke } from "@guuey/worker";
+import { listCredentials, type Invoke } from "@guuey/worker";
 
 /** GUUEY_AGENT_SNAPSHOT (set by the platform pod and by `guuey dev`) wins; guuey.json is the fallback. */
 export function loadAgent(invoke: Invoke): GuueyAgent {
@@ -26,9 +26,9 @@ export function systemPrompt(invoke: Invoke, agent: GuueyAgent): string | undefi
 
 /**
  * One resolved MCP endpoint this worker may connect to. `transport` rides
- * alongside `url`/`headers` (not hardcoded to `"http"`) because a federation
- * credential file — `<session>/.guuey/credentials/<name>.json`, shape
- * `{url, transport, headers}` per `@guuey/host`'s `CredentialFile` — may
+ * alongside `url`/`headers` (not hardcoded to `"http"`) because a credential
+ * file — `<session>/.guuey/credentials/<name>.json`, shape
+ * `{url, transport, headers}` per `@guuey/worker`'s `CredentialFile` — may
  * resolve a server onto the `sse` transport arm.
  */
 export interface McpEndpoint {
@@ -37,26 +37,33 @@ export interface McpEndpoint {
   headers: Record<string, string>;
 }
 
-/** Lowered entries are `external`; federation credentials (if any) arrive as per-session files. */
+/**
+ * Endpoint set = broker-written credential DIRECTORY (source of truth for
+ * federated + platform-injected servers — incl. guuey-memory/guuey-profile,
+ * invisible to the declared map by design) ∪ declared external entries that
+ * have no credential file (plain endpoints, static headers). Credential wins
+ * per name. One honest log line names both sets — no silent fallback.
+ */
 export function mcpEndpoints(invoke: Invoke, agent: GuueyAgent): Record<string, McpEndpoint> {
   const out: Record<string, McpEndpoint> = {};
   for (const [name, entry] of Object.entries(agent.mcpServers ?? {})) {
+    if (entry === false) continue; // `ggui: false` is the generative-UI opt-out, not a server entry
     if (entry.kind !== "external") continue; // hosted/proxied are lowered to external before a worker ever runs
-    let url = entry.url;
-    let transport: "http" | "sse" = entry.transport ?? "http";
-    let headers: Record<string, string> = { ...(entry.headers ?? {}) };
-    try {
-      const cred = JSON.parse(
-        readFileSync(join(invoke.fs.session, ".guuey", "credentials", `${name}.json`), "utf8")
-      ) as { url: string; transport: "http" | "sse"; headers: Record<string, string> };
-      url = cred.url;
-      transport = cred.transport;
-      headers = cred.headers;
-    } catch {
-      // no credential file — plain external endpoint; static headers apply
-    }
-    out[name] = { url, transport, headers };
+    out[name] = {
+      url: entry.url,
+      transport: entry.transport ?? "http",
+      headers: { ...(entry.headers ?? {}) },
+    };
   }
+  const creds = listCredentials(invoke.fs)();
+  for (const { name, cred } of creds) {
+    out[name] = { url: cred.url, transport: cred.transport, headers: cred.headers };
+  }
+  const credentialed = creds.map((c) => c.name);
+  const declaredOnly = Object.keys(out).filter((n) => !credentialed.includes(n));
+  console.log(
+    `[guuey] mcp endpoints: credentialed=[${credentialed.join(",")}] declared-only=[${declaredOnly.join(",")}]`
+  );
   return out;
 }
 

package/dist/templates/claude-agent-sdk/web/package.json

@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@mcp-ui/client": "^7.1.1",
-    "@silverprotocol/core": "0.3.2",
+    "@silverprotocol/core": "0.4.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },

package/dist/templates/google-adk/AGENTS.md

@@ -0,0 +1,135 @@
+# AGENTS.md — steering for the coding agent working in this repo
+
+You (the coding agent) are extending a guuey agentic app. Before you reach
+for a database or a cache, read this file. The single most common mistake
+here is standing up local Redis/SQLite/file-based state "just to get
+something working" — **don't.** Every pod this project deploys to
+(`src/worker.ts`'s agent pod — including every `kind: colocated` `mcps/*`
+server auto-spawned inside it, like this scaffold's `mcps/todo` — and every
+`mcps/*` server deployed with `kind: hosted`) is **ephemeral and horizontally
+replaced**: gVisor-isolated,
+scale-to-zero, ordinary process death on every deploy or idle timeout. A
+local file or an in-process `Map` used as a database is not a shortcut —
+it is silent data loss the first time the pod recycles.
+
+Use this table to route persistence decisions. Pick a row, don't invent one.
+
+| Need                                                                                                         | Use                                                                                                                                                                                                                                                                                                                                                                    | Why                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Small per-user state on an MCP server (idempotency keys, rate-limit counters, OAuth nonces, prefs, a few KB) | [`@guuey/state`](https://www.npmjs.com/package/@guuey/state) — `withGuueyContext(scopeFromAuthorization(...), fn)`                                                                                                                                                                                                                                                     | Zero auth code — guuey owns the identity rails. Durable, per-`(user, mcp)`, survives pod restarts.                                                                                                                                                                                                                                      |
+| Large or relational data (rows, queries, joins, anything you'd reach for Postgres/Redis for)                 | An external managed serverless DB — Neon, Upstash, Supabase, or Turso — wired in via `guuey mcp secrets set DATABASE_URL=... --server <id>` (hosted MCP) or `guuey env set DATABASE_URL=...` (the agent worker and its colocated MCP children — the pod's declared env/secrets are handed to every colocated child), consumed through the provider's serverless driver | Guuey **integrates, never operates** databases — that's the platform's hosting policy, not a v1 gap. Pick the provider's **`us-east-1`** region: a guuey-hosted MCP → provider hop is then same-region AWS backbone, single-digit-ms — comparable to a cross-AZ hop, and agent turns are already dominated by seconds of LLM inference. |
+| Local Redis, SQLite, or any file written as a database                                                       | **Never.** Not for v1, not "temporarily."                                                                                                                                                                                                                                                                                                                              | Pods are ephemeral and horizontally replaced — a local store vanishes on the next deploy, restart, or scale event, with no warning to you or the user.                                                                                                                                                                                  |
+| Per-user files/blobs from **inside the agent pod** (`src/worker.ts`)                                         | [`@guuey/fs`](https://www.npmjs.com/package/@guuey/fs)'s `homeDir()`/`appDir()`/`sessionDir()`, or the raw `$GUUEY_HOME_DIR`/`$GUUEY_APP_DIR` env vars + `node:fs`                                                                                                                                                                                                     | Every invoke already gets these three bound directories — `$GUUEY_HOME_DIR` is durable per-user, `$GUUEY_APP_DIR` is read-only shared, cwd is session scratch. No wrapper API required, but the helpers save you the env-var lookups.                                                                                                   |
+| Per-user files/blobs from **inside an MCP server** (`mcps/*`)                                                | Not yet available — `@guuey/files` is planned but not shipped. Fall back to the managed-DB row above (e.g. store blobs in the provider's object storage) until it lands.                                                                                                                                                                                               | Don't build against an API that doesn't exist yet.                                                                                                                                                                                                                                                                                      |
+| Conversation / chat history                                                                                  | **Do not re-implement.** The platform already persists it.                                                                                                                                                                                                                                                                                                             | Guuey writes thread history to DynamoDB and streams it back over AppSync; agents that keep their own transcript store are duplicating (and diverging from) data the platform already owns.                                                                                                                                              |
+
+## `@guuey/state`: the one-line pattern
+
+`@guuey/state` only works inside an MCP server whose `guuey.json` entry is
+**federated** — that's the opt-in. A `kind: colocated` entry (like
+`mcps/todo` in this scaffold) or a `kind: hosted` entry is federated
+automatically. If you add a `kind: external` entry (a server you host
+yourself, reached by URL), you must set `federate: true` on it:
+
+```json
+{
+  "kind": "external",
+  "url": "https://your-server.example.com",
+  "federate": true
+}
+```
+
+Without `federate: true` (or `kind: colocated`/`kind: hosted`/a `ggui`
+URL), guuey has no
+identity to hand your server — a plain external entry with static
+`headers` gets **no token and no state.** The token guuey sends on every
+request to a federated server IS the credential; there is no separate
+API key to provision.
+
+Inside a federated MCP server, wrap each request in
+`withGuueyContext(scopeFromAuthorization(header), fn)` and use the
+barrel-exported `kv` inside `fn` — that's the whole integration. One
+complete, runnable example — an idempotency-key check on a tool call,
+using the raw Node `http` transport this scaffold's `mcps/todo/src/server.ts`
+already uses:
+
+```ts
+import { createHash } from "node:crypto";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { withGuueyContext, scopeFromAuthorization, kv, QuotaExceededError } from "@guuey/state";
+
+// Inside the per-request handler (see mcps/todo/src/server.ts for the
+// full StreamableHTTPServerTransport wiring this drops into):
+async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  const authHeader = req.headers.authorization;
+  if (typeof authHeader !== "string") {
+    res.writeHead(401).end();
+    return;
+  }
+
+  await withGuueyContext(scopeFromAuthorization(authHeader), async () => {
+    // ... hand off to your MCP transport/tool dispatch here; the
+    // AsyncLocalStorage context set above is visible to every `kv.*`
+    // call for the lifetime of this request, however deep the call
+    // stack goes (tool handlers, helper functions, etc.).
+    await handleCreateOrder({ orderPayload: "..." });
+  });
+}
+
+async function handleCreateOrder(input: { orderPayload: string }): Promise<{ duplicate: boolean }> {
+  const idempotencyKey = `order:${createHash("sha256").update(input.orderPayload).digest("hex")}`;
+
+  if (await kv.has(idempotencyKey)) {
+    return { duplicate: true };
+  }
+
+  try {
+    // TTL is required on every `set` — no permanent keys. Pick a window
+    // that covers realistic retry storms; 1 hour is a reasonable default
+    // for an idempotency key.
+    await kv.set(idempotencyKey, true, { ttl: 60 * 60 });
+  } catch (err) {
+    if (err instanceof QuotaExceededError) {
+      // The (user, mcp) scope hit its 1 MiB cap. Surface this to the
+      // caller instead of silently dropping the idempotency guard.
+      throw new Error("state quota exceeded — cannot verify idempotency");
+    }
+    throw err;
+  }
+
+  // ... actually create the order here.
+  return { duplicate: false };
+}
+```
+
+`scopeFromAuthorization` derives `{ userId, mcpId }` from the inbound
+`Authorization: Bearer <jwt>` header guuey sends on every federated call —
+`userId` from the JWT's `sub`, `mcpId` deterministically from its `aud`
+(your server's federated resource URL). You never assert either id
+yourself; a mismatched or missing token is rejected server-side.
+
+## The hard caps (design your data model around these, don't work around them)
+
+`@guuey/state` is a KV, not a database — enforced, not a suggestion:
+
+| Cap                | Value                                         |
+| ------------------ | --------------------------------------------- |
+| Scope size         | 1 MiB (per `(user, mcp)`, key bytes included) |
+| Single value       | 64 KiB                                        |
+| TTL                | required, ≤ 90 days — no permanent keys       |
+| `keys()` page size | ≤ 1000                                        |
+| `mget()` batch     | ≤ 100 keys                                    |
+| Counters           | safe integers only (`increment`/`decrement`)  |
+
+If your data model needs more than this — queries, joins, cross-user
+data, anything past a long tail of small per-user facts — that's the
+signal to use the managed-DB row above, not to fight the cap.
+
+## Chat history: really, don't
+
+If you find yourself writing message transcripts to `@guuey/state`,
+`$GUUEY_HOME_DIR`, or an external DB keyed by conversation, stop — that's
+the platform's job. Guuey persists every thread to DynamoDB and streams
+history back over AppSync subscriptions; the client and Portal already
+read it from there. A parallel, agent-owned history store will drift from
+the platform's copy and confuse users about which one is authoritative.