@guuey/create-agentic-app 0.8.1 → 0.10.0

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

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+// pnpm dev — boots the whole local stack. Ctrl-C tears everything down.
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+
+const procs = [];
+function boot(name, command, args, opts = {}) {
+  const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"], ...opts });
+  const prefix = `[${name}]`.padEnd(9);
+  child.stdout.on("data", (d) => process.stdout.write(String(d).replace(/^/gm, prefix)));
+  child.stderr.on("data", (d) => process.stderr.write(String(d).replace(/^/gm, prefix)));
+  child.on("exit", (code) => {
+    if (code !== 0 && !shuttingDown) shutdown(`${name} exited (${code})`, 1);
+  });
+  procs.push(child);
+}
+let shuttingDown = false;
+function shutdown(reason, code = 0) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  console.log(`\n${reason} — shutting down`);
+  for (const p of procs) p.kill("SIGTERM");
+  setTimeout(() => process.exit(code), 500);
+}
+process.on("SIGINT", () => shutdown("interrupted"));
+process.on("SIGTERM", () => shutdown("terminated"));
+
+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("ggui", "pnpm", ["exec", "ggui", "serve", "--mcp-only", "--dev-allow-all", "--port", "6781"], {
+  cwd: "ggui",
+});
+boot("web", "pnpm", ["--filter", "@agentic-app-template/web", "dev"], {
+  env: { ...process.env, PORT: "6890" },
+});
+
+console.log("\n  agent  http://localhost:6790   todo-mcp http://localhost:6782");
+console.log("  ggui   http://localhost:6781   web      http://localhost:6890\n");

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

@@ -0,0 +1,77 @@
+/**
+ * Snapshot + system-prompt + MCP-endpoint resolution shared by both framework
+ * overlays. Duplicated verbatim in `templates-src/frameworks/openai-agents-sdk`
+ * by design — template code must be self-contained (no cross-overlay imports),
+ * so keep the two copies byte-identical when editing either one.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseGuueyJson, type GuueyAgent } from "@guuey/config";
+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 {
+  const env = process.env.GUUEY_AGENT_SNAPSHOT;
+  if (env) return JSON.parse(env) as GuueyAgent;
+  const raw = JSON.parse(readFileSync(join(invoke.fs.app, "guuey.json"), "utf8"));
+  return parseGuueyJson(raw).agent;
+}
+
+export function systemPrompt(invoke: Invoke, agent: GuueyAgent): string | undefined {
+  const sp = agent.systemPrompt;
+  if (typeof sp === "string") return sp;
+  if (sp?.file) return readFileSync(join(invoke.fs.app, sp.file), "utf8");
+  return undefined;
+}
+
+/**
+ * One resolved MCP endpoint this worker may connect to. `transport` rides
+ * 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 {
+  url: string;
+  transport: "http" | "sse";
+  headers: Record<string, string>;
+}
+
+/**
+ * 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/colocated are lowered to external before a worker ever runs
+    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;
+}
+
+/** Fold prior turns into a prompt preamble (v1 keep-it-simple history handling). */
+export function withHistory(invoke: Invoke): string {
+  if (invoke.history.length === 0) return invoke.input;
+  const lines = invoke.history.map(
+    (h) => `${h.role === "agent" ? "Assistant" : "User"}: ${h.text}`
+  );
+  return `<conversation_history>\n${lines.join("\n")}\n</conversation_history>\n\n${invoke.input}`;
+}

package/dist/templates/base/claude-agent-sdk/src/worker.ts

@@ -0,0 +1,89 @@
+/**
+ * agentic-app-template's code-mode worker entry (Claude Agent SDK). Reads the
+ * resolved agent snapshot + MCP endpoints via `./agent-config.js`, drives one
+ * `query()` per invoke, and streams every native SDK message to the Router
+ * via `emit.native` (the field spellings below — `mcpServers`/`systemPrompt`/
+ * `allowedTools`/`maxTurns`, and the `type === "result" && subtype ===
+ * "success"` result-detection — mirror `@guuey/host`'s `buildOptions` /
+ * `runInvoke`, the platform's own consumer of this exact snapshot shape).
+ */
+import { createRequire } from "node:module";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { serveNative } from "@guuey/worker";
+import { loadAgent, systemPrompt, mcpEndpoints, withHistory } from "./agent-config.js";
+
+/**
+ * This worker is tsup-bundled (`noExternal`), which breaks the SDK's own
+ * native-CLI lookup: the SDK resolves `claude-agent-sdk-<platform>-<arch>`
+ * relative to its OWN module location, and once inlined into
+ * `guuey.worker.js` that location is the bundle's — where no node_modules
+ * has the binary. Resolution order here:
+ *   1. `GUUEY_CLAUDE_CODE_EXECUTABLE` — set by the guuey pod Router, pointing
+ *      at the platform image's binary (a deployed `/worker` has no
+ *      node_modules at all).
+ *   2. Anchored resolve — find the *installed* SDK from the bundle's location
+ *      (it is this app's direct dependency), then resolve the platform binary
+ *      package from the SDK's real location, exactly as the unbundled SDK
+ *      would. Covers local `guuey dev --serve`, where the bundle runs next to
+ *      the app's node_modules.
+ *   3. undefined — let the SDK try (and fail with its actionable error).
+ */
+function claudeExecutable(): string | undefined {
+  if (process.env.GUUEY_CLAUDE_CODE_EXECUTABLE) return process.env.GUUEY_CLAUDE_CODE_EXECUTABLE;
+  try {
+    const sdkEntry = createRequire(import.meta.url).resolve("@anthropic-ai/claude-agent-sdk");
+    return createRequire(sdkEntry).resolve(
+      `@anthropic-ai/claude-agent-sdk-${process.platform}-${process.arch}/claude`
+    );
+  } catch {
+    return undefined;
+  }
+}
+const pathToClaudeCodeExecutable = claudeExecutable();
+
+await serveNative(
+  async (invoke, emit) => {
+    const agent = loadAgent(invoke);
+    const mcpServers = Object.fromEntries(
+      Object.entries(mcpEndpoints(invoke, agent)).map(([name, ep]) => [
+        name,
+        // `alwaysLoad` — this agent's declared MCP servers ARE its tool
+        // surface; without it the CLI defers MCP tools behind its ToolSearch
+        // built-in (absent here — see `tools: []` below), leaving the model
+        // tool-less.
+        { type: ep.transport, url: ep.url, headers: ep.headers, alwaysLoad: true },
+      ])
+    );
+    let result = "";
+    for await (const message of query({
+      prompt: withHistory(invoke),
+      options: {
+        ...(agent.model ? { model: agent.model } : {}),
+        ...(systemPrompt(invoke, agent) ? { systemPrompt: systemPrompt(invoke, agent) } : {}),
+        mcpServers,
+        // Same posture as `@guuey/host`'s `buildOptions` (options.ts):
+        // - allowedTools: the snapshot allowlist verbatim, else every tool
+        //   from every declared server (`mcp__<server>` prefix match) — MCP
+        //   calls would otherwise hit the SDK's interactive ask stage, which
+        //   nothing answers headless, so they'd be silently denied.
+        // - tools: [] — purely MCP-driven; no Bash/file/search built-ins.
+        // - settingSources: [] — never load the machine's ~/.claude or
+        //   project settings into this worker (a dev box's logged-in Claude
+        //   Code MCPs/plugins would leak into the tool catalog).
+        // - strictMcpConfig: true — the snapshot's servers only; ignore
+        //   .mcp.json / user settings / plugins.
+        allowedTools: agent.tools?.allowlist ?? Object.keys(mcpServers).map((s) => `mcp__${s}`),
+        tools: [],
+        settingSources: [],
+        strictMcpConfig: true,
+        ...(agent.runtime?.maxTurns ? { maxTurns: agent.runtime.maxTurns } : {}),
+        ...(pathToClaudeCodeExecutable ? { pathToClaudeCodeExecutable } : {}),
+      },
+    })) {
+      emit.native(JSON.parse(JSON.stringify(message)));
+      if (message.type === "result" && message.subtype === "success") result = message.result;
+    }
+    return result;
+  },
+  { framework: "claude-agent-sdk", sdkName: "@anthropic-ai/claude-agent-sdk" }
+);

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

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -0,0 +1,9 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: { "guuey.worker": "src/worker.ts" },
+  format: ["esm"],
+  outDir: ".",
+  clean: false,
+  noExternal: [/./], // bundle everything — the deploy tarball must be runnable via `node guuey.worker.js`
+});

package/dist/templates/base/claude-agent-sdk/web/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>agentic-app-template</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/dist/templates/{claude-agent-sdk → base/claude-agent-sdk}/web/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agentic-app-template/web",
-  "version": "0.0.0",
   "private": true,
+  "version": "0.0.0",
   "type": "module",
   "scripts": {
     "dev": "vite --port 6890",
@@ -9,17 +9,18 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@mcp-ui/client": "^7.1.1",
-    "@silverprotocol/core": "0.5.0",
+    "@guuey/chat": "0.10.0",
+    "oidc-client-ts": "^3.1.0",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.1.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^24.0.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "@vitejs/plugin-react": "^4.3.0",
-    "typescript": "^5.8.0",
-    "vite": "^6.0.0"
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "^5.7.2",
+    "vite": "^7.0.0"
   }
 }

package/dist/templates/base/claude-agent-sdk/web/src/components/AgentChat.tsx

@@ -0,0 +1,53 @@
+/**
+ * The configured `<GuueyChat>` for this app — distribution way #2, the
+ * embedded chat SDK. One place wires endpoint, history, identity and theme;
+ * every chat surface (the /chat page here, the fullscreen agent canvas in
+ * the agentic-app template) renders this.
+ *
+ * Identity rule: ONE mode per surface. When OIDC is configured AND a
+ * session exists, the bearer wins; otherwise the client-minted guest
+ * secret. Never both.
+ */
+import { useEffect, useState, type CSSProperties } from "react";
+import { GuueyChat } from "@guuey/chat/react";
+import { agentEndpointUrl, appConfig, historyBaseUrl } from "../config";
+import { currentIdentityMode, ensureGuestSecret } from "../lib/identity";
+import { getBearerToken, currentUser, oidcConfigured } from "../lib/oidc";
+
+export function AgentChat({ className, style }: { className?: string; style?: CSSProperties }) {
+  // The user's CHOSEN mode wins: an explicit "Continue as guest" must never
+  // be shadowed by a cached OIDC session. Only when no choice is recorded
+  // does a live session imply oidc.
+  const chosen = currentIdentityMode();
+  const [identity, setIdentity] = useState<"resolving" | "guest" | "oidc">(
+    chosen === "guest" || !oidcConfigured() ? "guest" : chosen === "oidc" ? "oidc" : "resolving",
+  );
+
+  useEffect(() => {
+    if (identity !== "resolving") return;
+    let cancelled = false;
+    void currentUser().then((user) => {
+      if (!cancelled) setIdentity(user ? "oidc" : "guest");
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [identity]);
+
+  if (identity === "resolving") return null;
+
+  const shared = {
+    endpointUrl: agentEndpointUrl(),
+    appId: appConfig.link?.appId ?? "local",
+    apiBaseUrl: historyBaseUrl(),
+    mode: appConfig.theme.mode,
+    className,
+    style,
+  };
+
+  return identity === "oidc" ? (
+    <GuueyChat {...shared} getAccessToken={() => getBearerToken()} />
+  ) : (
+    <GuueyChat {...shared} getGuestSecret={() => ensureGuestSecret()} />
+  );
+}

package/dist/templates/base/claude-agent-sdk/web/src/components/BootstrapGate.tsx

@@ -0,0 +1,30 @@
+/**
+ * Dev-time gate: until `pnpm bootstrap` has run, every page renders this
+ * setup screen instead of a half-configured app. Production builds are
+ * gated harder — vite.config.ts fails the build outright.
+ */
+import type { ReactNode } from "react";
+import { appConfig } from "../config";
+
+export function BootstrapGate({ children }: { children: ReactNode }) {
+  if (appConfig.bootstrapped) return <>{children}</>;
+  return (
+    <main className="gate">
+      <div className="gate-card">
+        <h1>Run bootstrap first</h1>
+        <p>
+          This project has not been configured yet. From the project root:
+        </p>
+        <pre>
+          <code>pnpm bootstrap</code>
+        </pre>
+        <p>
+          That writes <code>guuey.app.json</code> (brand, theme, copy) and
+          regenerates <code>AGENTS.md</code>. Then start the local stack with{" "}
+          <code>pnpm dev</code>. When you are ready to bind a deployed guuey
+          app: <code>pnpm bootstrap -- --link</code>.
+        </p>
+      </div>
+    </main>
+  );
+}

package/dist/templates/base/claude-agent-sdk/web/src/components/Shell.tsx

@@ -0,0 +1,50 @@
+/**
+ * Base-template chrome: brand header + nav + auth affordance. Pages render
+ * inside via the router outlet.
+ */
+import { Link, NavLink, Outlet, useLocation, useNavigate } from "react-router-dom";
+import { appConfig } from "../config";
+import { CHAT_PATH, HOME_PATH } from "../routes";
+import { currentIdentityMode, logOut } from "../lib/identity";
+import { oidcConfigured, signOutOidc } from "../lib/oidc";
+
+export function Shell() {
+  const navigate = useNavigate();
+  // Subscribing to the location re-renders this chrome on every navigation,
+  // so the render-time read below stays fresh after login/logout. (A
+  // `storage` listener would NOT work — that event only fires in OTHER
+  // tabs, never the one that wrote the change.)
+  useLocation();
+  const mode = currentIdentityMode();
+
+  async function handleLogOut() {
+    if (mode === "oidc" && oidcConfigured()) await signOutOidc();
+    logOut();
+    navigate("/");
+  }
+
+  return (
+    <div className="shell">
+      <header className="topbar">
+        <Link to="/" className="brand">
+          <span className="brand-mark">{appConfig.brand.logoText}</span>
+          <span>{appConfig.brand.name}</span>
+        </Link>
+        <nav>
+          <NavLink to={CHAT_PATH}>Chat</NavLink>
+          <NavLink to={HOME_PATH}>Home</NavLink>
+          {mode === null ? (
+            <NavLink to="/login" className="btn btn-accent">
+              Sign in
+            </NavLink>
+          ) : (
+            <button type="button" className="btn" onClick={() => void handleLogOut()}>
+              Log out{mode === "guest" ? " (guest)" : ""}
+            </button>
+          )}
+        </nav>
+      </header>
+      <Outlet />
+    </div>
+  );
+}

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

@@ -0,0 +1,148 @@
+/**
+ * Typed access to `guuey.app.json` — the ONE file `pnpm bootstrap` writes.
+ *
+ * The JSON is validated structurally here (not just cast) so a hand-edited
+ * config fails with a named path instead of an undefined-deep-in-React
+ * crash. The schema is documented in `../guuey.app.schema.json`.
+ */
+import rawConfig from "../../guuey.app.json";
+
+export interface OidcConfig {
+  /** OIDC issuer URL (https). Discovery via /.well-known/openid-configuration. */
+  issuer: string;
+  clientId: string;
+}
+
+export interface AppLink {
+  appId: string;
+  env: "dev" | "staging" | "release";
+  /** Public API base ending in /v1 — history + persisted-card reads. */
+  apiBaseUrl: string;
+  /** The agent pod's public origin — live chat + health probe. */
+  endpointUrl: string;
+  /** Widget host origin serving /v1.js for this environment. */
+  widgetOrigin: string;
+  /** Portal web origin (the "talk on mobile" target). */
+  portalUrl: string;
+  slug: string | null;
+  /** The agent's own hosted page (https://<slug>.agents...), when slugged. */
+  pageUrl: string | null;
+}
+
+export interface AppConfig {
+  schema: number;
+  bootstrapped: boolean;
+  brand: { name: string; tagline: string; logoText: string };
+  theme: { accent: string; mode: "light" | "dark" };
+  copy: {
+    landing: { headline: string; sub: string };
+    login: { guestHint: string };
+  };
+  auth: { oidc: OidcConfig | null };
+  link: AppLink | null;
+  demoMode: boolean;
+}
+
+class ConfigError extends Error {
+  constructor(path: string, expected: string) {
+    super(`guuey.app.json: ${path} — expected ${expected}. Re-run \`pnpm bootstrap\` or fix the file by hand (schema: guuey.app.schema.json).`);
+  }
+}
+
+function str(v: unknown, path: string): string {
+  if (typeof v !== "string" || v.length === 0) throw new ConfigError(path, "a non-empty string");
+  return v;
+}
+
+function bool(v: unknown, path: string): boolean {
+  if (typeof v !== "boolean") throw new ConfigError(path, "a boolean");
+  return v;
+}
+
+function obj(v: unknown, path: string): Record<string, unknown> {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) throw new ConfigError(path, "an object");
+  return v as Record<string, unknown>;
+}
+
+function validate(raw: unknown): AppConfig {
+  const root = obj(raw, "$");
+  if (root.schema !== 1) throw new ConfigError("schema", "the literal 1");
+
+  const brand = obj(root.brand, "brand");
+  const theme = obj(root.theme, "theme");
+  const mode = theme.mode;
+  if (mode !== "light" && mode !== "dark") throw new ConfigError("theme.mode", '"light" | "dark"');
+  const copy = obj(root.copy, "copy");
+  const landing = obj(copy.landing, "copy.landing");
+  const login = obj(copy.login, "copy.login");
+  const auth = obj(root.auth, "auth");
+
+  let oidc: OidcConfig | null = null;
+  if (auth.oidc !== null && auth.oidc !== undefined) {
+    const o = obj(auth.oidc, "auth.oidc");
+    oidc = { issuer: str(o.issuer, "auth.oidc.issuer"), clientId: str(o.clientId, "auth.oidc.clientId") };
+  }
+
+  let link: AppLink | null = null;
+  if (root.link !== null && root.link !== undefined) {
+    const l = obj(root.link, "link");
+    const env = l.env;
+    if (env !== "dev" && env !== "staging" && env !== "release") {
+      throw new ConfigError("link.env", '"dev" | "staging" | "release"');
+    }
+    link = {
+      appId: str(l.appId, "link.appId"),
+      env,
+      apiBaseUrl: str(l.apiBaseUrl, "link.apiBaseUrl"),
+      // Normalize to the ORIGIN whatever shape was stored: the platform's
+      // deployment records carry the full `…/agent/invoke` URL, while this
+      // contract (and the probe) wants the base. The chat kit accepts
+      // either, so normalizing here makes both consumers correct.
+      endpointUrl: str(l.endpointUrl, "link.endpointUrl").replace(/\/agent\/invoke\/?$/, ""),
+      widgetOrigin: str(l.widgetOrigin, "link.widgetOrigin"),
+      portalUrl: str(l.portalUrl, "link.portalUrl"),
+      slug: typeof l.slug === "string" ? l.slug : null,
+      pageUrl: typeof l.pageUrl === "string" ? l.pageUrl : null,
+    };
+  }
+
+  return {
+    schema: 1,
+    bootstrapped: bool(root.bootstrapped, "bootstrapped"),
+    brand: {
+      name: str(brand.name, "brand.name"),
+      tagline: str(brand.tagline, "brand.tagline"),
+      logoText: str(brand.logoText, "brand.logoText"),
+    },
+    theme: { accent: str(theme.accent, "theme.accent"), mode },
+    copy: {
+      landing: { headline: str(landing.headline, "copy.landing.headline"), sub: str(landing.sub, "copy.landing.sub") },
+      login: { guestHint: str(login.guestHint, "copy.login.guestHint") },
+    },
+    auth: { oidc },
+    link,
+    demoMode: bool(root.demoMode ?? false, "demoMode"),
+  };
+}
+
+export const appConfig: AppConfig = validate(rawConfig);
+
+/** The local `guuey dev --serve` router (scripts/dev.mjs boots it). */
+export const DEV_AGENT_URL = "http://localhost:6790";
+
+export const isLinked: boolean = appConfig.link !== null;
+
+/** Live-chat base: the bound pod when linked, the local dev router otherwise. */
+export function agentEndpointUrl(): string {
+  return appConfig.link?.endpointUrl ?? DEV_AGENT_URL;
+}
+
+/**
+ * History/read-plane base. When linked this is the public API (`…/v1`);
+ * in local dev, `guuey dev --serve` exposes the same read-plane route
+ * shape (`/threads/:id/messages`) on its own origin, so history and
+ * rehydration work locally too.
+ */
+export function historyBaseUrl(): string {
+  return appConfig.link?.apiBaseUrl ?? DEV_AGENT_URL;
+}

package/dist/templates/base/claude-agent-sdk/web/src/lib/identity.ts

@@ -0,0 +1,67 @@
+/**
+ * End-user identity for this app's chat surfaces.
+ *
+ * ONE mode per surface — never both resolvers at once (a bearer + a guest
+ * secret on the same request is a silent-downgrade hazard the platform
+ * refuses to guess about):
+ *
+ * - **Guest** (always available): a client-minted 64-hex secret stored at
+ *   `localStorage["guuey:guest-secret:<appId>"]` and sent as the
+ *   `x-guuey-guest` header. Per-browser and persistent, so the agent
+ *   remembers the visitor across reloads. This is the same mechanic the
+ *   guuey widget uses. "Log out" deletes the secret — a fresh one next
+ *   visit is a fresh person as far as the agent is concerned.
+ * - **Signed in** (when `auth.oidc` is configured in guuey.app.json): an
+ *   OIDC ID token from your IdP (see ./oidc.ts), sent as a Bearer. The
+ *   bound guuey app must be in BYO auth mode for the same issuer
+ *   (`guuey apps update <appId> --auth-mode byo --issuer-url … --audience <clientId>`).
+ */
+import { appConfig } from "../config";
+
+export type IdentityMode = "guest" | "oidc";
+
+const scope = appConfig.link?.appId ?? "local";
+const GUEST_KEY = `guuey:guest-secret:${scope}`;
+const MODE_KEY = `guuey:identity-mode:${scope}`;
+
+function mintSecret(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** The stored guest secret, minting one on first use. */
+export function ensureGuestSecret(): string {
+  const existing = localStorage.getItem(GUEST_KEY);
+  if (existing && /^[0-9a-f]{64}$/.test(existing)) return existing;
+  const fresh = mintSecret();
+  localStorage.setItem(GUEST_KEY, fresh);
+  return fresh;
+}
+
+export function getStoredGuestSecret(): string | null {
+  const v = localStorage.getItem(GUEST_KEY);
+  return v && /^[0-9a-f]{64}$/.test(v) ? v : null;
+}
+
+export function currentIdentityMode(): IdentityMode | null {
+  const v = localStorage.getItem(MODE_KEY);
+  return v === "guest" || v === "oidc" ? v : null;
+}
+
+export function setIdentityMode(mode: IdentityMode | null): void {
+  if (mode === null) localStorage.removeItem(MODE_KEY);
+  else localStorage.setItem(MODE_KEY, mode);
+}
+
+/** "Continue as guest": ensure a secret exists and select guest mode. */
+export function continueAsGuest(): void {
+  ensureGuestSecret();
+  setIdentityMode("guest");
+}
+
+/** Log out of whichever mode is active. Guest logout forgets the secret. */
+export function logOut(): void {
+  if (currentIdentityMode() === "guest") localStorage.removeItem(GUEST_KEY);
+  setIdentityMode(null);
+}