@guuey/create-agentic-app 0.9.0 → 0.11.0

package/dist/templates/base/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
+(the agent entry's pod — `src/worker.ts`, or `src/agent.ts` in a google-adk scaffold — 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** (the agent entry)                                         | [`@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/base/google-adk/README.md

@@ -0,0 +1,90 @@
+# Your Google-ADK agent on Guuey
+
+You write **pure [Google ADK](https://google.github.io/adk-docs/) code** —
+`src/agent.ts` exports your agent, and Guuey runs it. There is no Guuey SDK
+to learn, no worker loop, no event plumbing: the platform injects the
+harness around your export, locally (`pnpm dev`) and in production
+(`guuey deploy`) identically.
+
+```ts
+import type { GuueyContext } from "@guuey/config";
+
+export default (guuey: GuueyContext<MCPToolset>) =>
+  new LlmAgent({
+    model: guuey.model,
+    // Wrapped as a function — see the "instruction" row below.
+    instruction: () => guuey.instruction,
+    tools: [myTool, ...guuey.mcpToolsets],
+  });
+```
+
+## Quick start
+
+```bash
+pnpm install
+cp .env.example .env.local      # set GEMINI_API_KEY
+pnpm dev                        # local stack: your agent + the todo MCP + chat
+guuey deploy                    # same code, hosted
+```
+
+## The GuueyContext (everything the platform hands you)
+
+Your factory runs **once per turn** and receives:
+
+| field                                 | what it is                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `model`                               | resolved model id (from `guuey.json`, registry default otherwise)                                                                                                                                                                                                                                                                                                                                 |
+| `instruction`                         | your system prompt **with the conversation preamble already prepended** — feed it to the agent and it is conversational with zero state code. **Pass it as `() => guuey.instruction`, not a bare string** — ADK applies `{var}` session-state substitution to a string instruction, and the preamble embeds prior user messages verbatim; a message containing `{anything}` would crash the turn. |
+| `mcpToolsets`                         | ready-to-use ADK `MCPToolset`s for every server in `guuey.json#mcpServers` — credentials, URLs, and auth headers already resolved by the platform                                                                                                                                                                                                                                                 |
+| `user`                                | the end user this turn serves: `{ id, authMode }` — build multi-tenant behavior on `user.id`                                                                                                                                                                                                                                                                                                      |
+| `files`                               | three storage tiers (absolute paths — see the state map below)                                                                                                                                                                                                                                                                                                                                    |
+| `history` / `memory` / `workingState` | the raw conversation state, if you want to render context yourself instead of using `instruction`                                                                                                                                                                                                                                                                                                 |
+
+## Where state lives (the three-tier map)
+
+| you want to…                                                     | use                                                                                                                            | persistence                                                                                                                                                                                                                   |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| save/read **files** from agent code or tools                     | `guuey.files.home` (per-USER durable) · `guuey.files.session` (per-session scratch) · `guuey.files.app` (read-only app assets) | `home` survives across sessions per user                                                                                                                                                                                      |
+| have the agent **remember the conversation**                     | nothing — `instruction` already carries history + thread memory + working state                                                | automatic (Guuey folds every turn)                                                                                                                                                                                            |
+| store data from your **MCP server's tools** (e.g. the todo list) | `@guuey/state` KV inside the MCP server — scoped per `(user, server)`                                                          | **durable when `GUUEY_KV_URL` is injected — colocated (like `mcps/todo`) and hosted servers get it automatically on deploy**; the scope survives pod restarts and redeploys. Locally (`pnpm dev`) it falls back to in-memory. |
+
+Three honest notes:
+
+- **ADK-native session state does not persist across turns here.** Guuey
+  runs your agent with a fresh `InMemoryRunner` per turn (that's what makes
+  turns cheap and stateless); `session.state` / `outputKey` /
+  `DatabaseSessionService` won't carry data forward. Use the table above —
+  history and thread memory ARE the persistence, and they arrive
+  pre-rendered in `instruction`.
+- **Writing `workingState` for the next turn** is a platform feature in
+  flight; today the fold carries what the conversation itself establishes.
+- **Guuey's cross-session `MEMORY.md` file recall is `claude-agent-sdk`-only
+  today** — ADK agents get `guuey.files.home` for their own reads/writes,
+  but not the platform's automatic recall of it into `instruction`.
+  All-framework support arrives with guuey's own memory MCP. Separately,
+  ADK's own durable-memory feature (Vertex MemoryBank) is unsupported on
+  Guuey — it stores user data in GCP, outside guuey's deletion boundary.
+
+The three `guuey.files` paths above are the same platform-wide filesystem
+contract every framework gets (plain paths, `$GUUEY_HOME_DIR`/
+`$GUUEY_APP_DIR` under the hood) — see the guuey monorepo's
+`docs/quickstart.md` ("Your agent's filesystem") for the full contract,
+memory behavior, and rollout status if you want the framework-neutral
+version.
+
+## MCP servers
+
+`guuey.json#mcpServers` declares them; the platform connects them and hands
+you `guuey.mcpToolsets`. Locally, `pnpm dev`'s `guuey dev` auto-spawns the
+colocated `mcps/todo` server on its `devPort`; deployed, the same code runs
+as a supervised child inside your agent's pod. Note: ADK speaks
+**Streamable HTTP** only — an
+`sse` transport server will be rejected with a clear error.
+
+## When you outgrow the factory
+
+If you need to own the turn loop itself (custom streaming, multiple agents
+per turn, your own protocol), graduate to a full worker: add a
+`guuey.worker.js` build via `@guuey/worker`'s `serveNative()` — see the
+Guuey docs. `agent.entry` and a full worker are mutually exclusive; the
+worker wins if both exist.

package/dist/templates/base/google-adk/ggui/ggui.json

@@ -0,0 +1,15 @@
+{
+  "schema": "1",
+  "protocol": "draft-2026-06-12",
+  "app": {
+    "slug": "agentic-app-template",
+    "name": "agentic-app-template"
+  },
+  "generation": {
+    "model": "anthropic:claude-haiku-4-5-20251001"
+  },
+  "theme": {
+    "preset": "indigo",
+    "mode": "dark"
+  }
+}

package/dist/templates/base/google-adk/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.env.local
+guuey.worker.js
+.guuey-dev/

package/dist/templates/base/google-adk/guuey.app.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "./guuey.app.schema.json",
+  "schema": 1,
+  "bootstrapped": false,
+  "brand": {
+    "name": "agentic-app-template",
+    "tagline": "An agentic app built on guuey",
+    "logoText": "AA"
+  },
+  "theme": {
+    "accent": "#6c5ce7",
+    "mode": "light"
+  },
+  "copy": {
+    "landing": {
+      "headline": "Ask anything.",
+      "sub": "This site has an agent. Open the chat, or use the launcher in the corner."
+    },
+    "login": {
+      "guestHint": "One click, no account — this browser gets its own private thread the agent remembers."
+    }
+  },
+  "auth": {
+    "oidc": null
+  },
+  "link": null,
+  "demoMode": false
+}

package/dist/templates/base/google-adk/guuey.app.schema.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "guuey.app.json",
+  "description": "App-level configuration for this guuey agentic app. Written by `pnpm bootstrap`; safe to hand-edit. Public-safe by construction: nothing in this file is a secret (the appId ships in page HTML by design).",
+  "type": "object",
+  "required": ["schema", "bootstrapped", "brand", "theme", "copy", "auth", "link", "demoMode"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "schema": { "const": 1 },
+    "bootstrapped": {
+      "type": "boolean",
+      "description": "Flipped true by `pnpm bootstrap`. Dev renders a setup screen until then; production builds fail."
+    },
+    "brand": {
+      "type": "object",
+      "required": ["name", "tagline", "logoText"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "tagline": { "type": "string" },
+        "logoText": {
+          "type": "string",
+          "maxLength": 4,
+          "description": "1-4 characters shown in the square brand mark."
+        }
+      }
+    },
+    "theme": {
+      "type": "object",
+      "required": ["accent", "mode"],
+      "additionalProperties": false,
+      "properties": {
+        "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" },
+        "mode": { "enum": ["light", "dark"] }
+      }
+    },
+    "copy": {
+      "type": "object",
+      "required": ["landing", "login"],
+      "additionalProperties": false,
+      "properties": {
+        "landing": {
+          "type": "object",
+          "required": ["headline", "sub"],
+          "additionalProperties": false,
+          "properties": {
+            "headline": { "type": "string" },
+            "sub": { "type": "string" }
+          }
+        },
+        "login": {
+          "type": "object",
+          "required": ["guestHint"],
+          "additionalProperties": false,
+          "properties": {
+            "guestHint": { "type": "string" }
+          }
+        }
+      }
+    },
+    "auth": {
+      "type": "object",
+      "required": ["oidc"],
+      "additionalProperties": false,
+      "properties": {
+        "oidc": {
+          "description": "BYO-OIDC sign-in. null = guest-only. When set, the bound guuey app must be in BYO auth mode for the same issuer: `guuey apps update <appId> --auth-mode byo --issuer-url <issuer> --audience <clientId>`.",
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["issuer", "clientId"],
+              "additionalProperties": false,
+              "properties": {
+                "issuer": { "type": "string", "format": "uri" },
+                "clientId": { "type": "string", "minLength": 1 }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "link": {
+      "description": "The bound guuey app. null until `pnpm bootstrap -- --link`. Every value here is read back from the platform, never derived by hand.",
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "required": [
+            "appId",
+            "env",
+            "apiBaseUrl",
+            "endpointUrl",
+            "widgetOrigin",
+            "portalUrl",
+            "slug",
+            "pageUrl"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "appId": { "type": "string", "minLength": 1 },
+            "env": { "enum": ["dev", "staging", "release"] },
+            "apiBaseUrl": { "type": "string", "format": "uri" },
+            "endpointUrl": { "type": "string", "format": "uri" },
+            "widgetOrigin": { "type": "string", "format": "uri" },
+            "portalUrl": { "type": "string", "format": "uri" },
+            "slug": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
+            "pageUrl": { "oneOf": [{ "type": "string", "format": "uri" }, { "type": "null" }] }
+          }
+        }
+      ]
+    },
+    "demoMode": {
+      "type": "boolean",
+      "description": "Renders the demo chrome (banner + fictional-product honesty strip). Off in every customer clone."
+    }
+  }
+}

package/dist/templates/base/google-adk/guuey.json

@@ -0,0 +1,15 @@
+{
+  "schema": "1",
+  "agent": {
+    "mode": "code",
+    "framework": "google-adk",
+    "model": "gemini-3.6-flash",
+    "entry": "agent.js",
+    "systemPrompt": { "file": "prompts/system.md" },
+    "mcpServers": {
+      "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/base/google-adk/mcps/todo/Dockerfile

@@ -0,0 +1,46 @@
+# todo-mcp — guuey hosted MCP server image.
+#
+# Self-sufficient multi-stage build: `guuey mcp deploy` packs this directory
+# into a tarball and hands it straight to the builder with no external
+# pre-build step and no build args — this Dockerfile installs its own deps
+# and builds itself. (Different from guuey's own first-party MCP servers,
+# which use a "copy-prebuilt" pattern that expects `dist/` + `node_modules/`
+# to already exist before `docker build` runs — that pattern does not apply
+# to a standalone project like this one.)
+#
+# Build + run locally:
+#
+#   docker build -t todo-mcp .
+#   docker run -p 8080:8080 todo-mcp
+#   curl http://localhost:8080/health
+#
+# Deploy to guuey:
+#
+#   cd mcps/todo && guuey mcp deploy
+
+FROM node:22-slim AS build
+WORKDIR /app
+COPY package.json ./
+RUN npm install
+COPY tsconfig.json ./
+COPY src ./src
+RUN npm run build
+
+FROM node:22-slim
+WORKDIR /app
+ENV NODE_ENV=production
+# guuey's hosted-MCP runtime injects PORT=8080 and probes GET /health at that
+# port — this default matches so `docker run` alone also works.
+ENV PORT=8080
+
+COPY package.json ./
+RUN npm install --omit=dev
+COPY --from=build /app/dist ./dist
+
+USER node
+EXPOSE 8080
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD node -e "fetch('http://localhost:' + (process.env.PORT || 8080) + '/health').then(r => { if (!r.ok) throw 1 }).catch(() => process.exit(1))"
+
+CMD ["node", "dist/server.js"]

package/dist/templates/base/google-adk/mcps/todo/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@agentic-app-template/todo-mcp",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx src/server.ts",
+    "build": "tsup",
+    "start": "node dist/server.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.0"
+  }
+}