@guuey/create-agentic-app 0.9.0 → 0.11.0

package/dist/templates/base/google-adk/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/google-adk/src/agent.ts

@@ -0,0 +1,43 @@
+/**
+ * Your agent — pure Google-ADK code. No Guuey SDK, no harness, no event
+ * plumbing: export it and the platform runs it (locally via `pnpm dev`,
+ * hosted via `guuey deploy`).
+ *
+ * The default export is a FACTORY receiving everything Guuey resolved for
+ * the current turn (`GuueyContext`): the model + instruction from
+ * guuey.json, ready-to-use MCP toolsets for every server declared there,
+ * the end user's identity, file storage paths, and the conversation state.
+ * See the README for the full context tour.
+ */
+import { FunctionTool, LlmAgent, type MCPToolset } from "@google/adk";
+import { z } from "zod";
+import type { GuueyContext } from "@guuey/config";
+
+/** A plain ADK tool — everything the ADK offers works unchanged. */
+const rollDice = new FunctionTool({
+  name: "roll_dice",
+  description: "Roll an N-sided die and return the result.",
+  parameters: z.object({
+    sides: z.number().int().min(2).describe("number of faces on the die"),
+  }),
+  execute: async ({ sides }) => ({
+    result: 1 + Math.floor(Math.random() * sides),
+  }),
+});
+
+export default (guuey: GuueyContext<MCPToolset>) =>
+  new LlmAgent({
+    name: "my_agent",
+    model: guuey.model,
+    // `instruction` already carries your system prompt PLUS the conversation
+    // preamble (history, thread memory, working state) — your agent is
+    // conversational without writing any state code. Wrapped as a function:
+    // ADK applies `{var}` session-state substitution to a STRING instruction,
+    // and the preamble embeds prior user messages verbatim — if one contains
+    // `{anything}`, a string instruction crashes the turn. The function form
+    // bypasses substitution entirely.
+    instruction: () => guuey.instruction,
+    // Your own tools compose with the MCP servers from guuey.json. Drop
+    // `...guuey.mcpToolsets` if you want a fully self-contained agent.
+    tools: [rollDice, ...guuey.mcpToolsets],
+  });

package/dist/templates/base/google-adk/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/google-adk/tsup.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: { agent: "src/agent.ts" },
+  format: ["esm"],
+  outDir: ".",
+  clean: false,
+  // Dependencies stay EXTERNAL (tsup's default): the platform installs them
+  // from the lockfile at image-build time and the Guuey host imports your
+  // agent.js — with @google/adk resolved from YOUR node_modules (your pinned
+  // version wins). Do NOT bundle @google/adk; its dependency tree is not
+  // bundler-safe.
+});

package/dist/templates/base/google-adk/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/{google-adk → base/google-adk}/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,20 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@mcp-ui/client": "^7.1.1",
-    "@silverprotocol/core": "0.5.0",
+    "@guuey/chat": "0.11.0",
+    "oidc-client-ts": "^3.1.0",
+    "qrcode": "^1.5.4",
     "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/qrcode": "^1.5.5",
     "@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/google-adk/web/src/components/AgentChat.tsx

@@ -0,0 +1,91 @@
+/**
+ * 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 type { PlanViewSummary, ViewRefItem } from "@guuey/chat";
+import { agentEndpointUrl, appConfig, historyBaseUrl } from "../config";
+import { currentIdentityMode, ensureGuestSecret } from "../lib/identity";
+import { getBearerToken, currentUser, oidcConfigured } from "../lib/oidc";
+
+/**
+ * The chat-rail bridge (agentic-app shell): with `viewsBridge` set, the
+ * chat runs the kit's CHIPS presentation — generative views collapse to
+ * compact chips in the rail, the full renders belong to the host's main
+ * canvas (fed by `onViewsChange`), and chip clicks re-select
+ * (`onViewRef` → `promotedViewKey`, the browser-history mechanic).
+ */
+export interface ViewsBridge {
+  promotedViewKey?: string | undefined;
+  onViewRef: (item: ViewRefItem) => void;
+  onViewsChange: (views: PlanViewSummary[]) => void;
+}
+
+// Module scope on purpose: props want STABLE identities. An inline
+// `policy={{ … }}` literal (or per-render arrow getters) re-mints every
+// render; the kit stabilizes structurally since 0.11.0, but the template
+// models the correct shape — one identity for the app's whole life.
+const RAIL_POLICY = { view: { timeoutMs: 8000, presentation: "chips" as const } };
+
+export function AgentChat({
+  className,
+  style,
+  viewsBridge,
+}: {
+  className?: string;
+  style?: CSSProperties;
+  viewsBridge?: ViewsBridge;
+}) {
+  // 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,
+    ...(viewsBridge !== undefined
+      ? {
+          policy: RAIL_POLICY,
+          promotedViewKey: viewsBridge.promotedViewKey,
+          onViewRef: viewsBridge.onViewRef,
+          onViewsChange: viewsBridge.onViewsChange,
+        }
+      : {}),
+  };
+
+  // The lib functions ARE the stable getters — no wrapping arrows (a fresh
+  // closure per render is the identity churn RAIL_POLICY exists to avoid).
+  return identity === "oidc" ? (
+    <GuueyChat {...shared} getAccessToken={getBearerToken} />
+  ) : (
+    <GuueyChat {...shared} getGuestSecret={ensureGuestSecret} />
+  );
+}

package/dist/templates/base/google-adk/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/google-adk/web/src/components/QrLink.tsx

@@ -0,0 +1,25 @@
+/** A QR code for a URL, with the plain link beneath — mobile hand-off. */
+import { useEffect, useRef, useState } from "react";
+import QRCode from "qrcode";
+
+export function QrLink({ url, size = 200 }: { url: string; size?: number }) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!canvasRef.current) return;
+    QRCode.toCanvas(canvasRef.current, url, { width: size, margin: 1 }).catch((err: unknown) => {
+      setError(err instanceof Error ? err.message : String(err));
+    });
+  }, [url, size]);
+
+  return (
+    <span className="qr-link">
+      <canvas ref={canvasRef} className="qr" />
+      <a href={url} target="_blank" rel="noreferrer">
+        {url}
+      </a>
+      {error ? <span className="error">QR render failed: {error}</span> : null}
+    </span>
+  );
+}

package/dist/templates/base/google-adk/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/google-adk/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/google-adk/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);
+}

package/dist/templates/base/google-adk/web/src/lib/oidc.ts

@@ -0,0 +1,79 @@
+/**
+ * BYO-OIDC sign-in seam (only active when `auth.oidc` is configured in
+ * guuey.app.json).
+ *
+ * Standard authorization-code + PKCE via oidc-client-ts. The ID TOKEN is
+ * what the guuey pod verifies in BYO auth mode (audience = your client id),
+ * so `getAccessToken` below returns `user.id_token` — forwarding the OAuth
+ * access token instead is the classic mistake (wrong audience → 401).
+ *
+ * Works with any spec-compliant IdP that can host a "Sign in with Google"
+ * (Auth0, AWS Cognito, Okta, Keycloak, …). Configure the IdP's allowed
+ * callback URL to `<your site origin>/login`.
+ */
+import { UserManager, WebStorageStateStore, type User } from "oidc-client-ts";
+import { appConfig, type OidcConfig } from "../config";
+
+let manager: UserManager | null = null;
+
+export function oidcConfigured(): boolean {
+  return appConfig.auth.oidc !== null;
+}
+
+function requireManager(oidc: OidcConfig): UserManager {
+  if (manager) return manager;
+  manager = new UserManager({
+    authority: oidc.issuer,
+    client_id: oidc.clientId,
+    redirect_uri: `${window.location.origin}/login`,
+    response_type: "code",
+    scope: "openid profile email",
+    userStore: new WebStorageStateStore({ store: window.localStorage }),
+  });
+  return manager;
+}
+
+/** Kick off the redirect sign-in flow. */
+export async function signIn(): Promise<void> {
+  const oidc = appConfig.auth.oidc;
+  if (!oidc) throw new Error("auth.oidc is not configured in guuey.app.json");
+  await requireManager(oidc).signinRedirect();
+}
+
+/** Complete the flow when the IdP redirected back to /login?code=… */
+export async function completeSignIn(): Promise<User> {
+  const oidc = appConfig.auth.oidc;
+  if (!oidc) throw new Error("auth.oidc is not configured in guuey.app.json");
+  return requireManager(oidc).signinCallback() as Promise<User>;
+}
+
+export function isSigninCallback(): boolean {
+  const q = new URLSearchParams(window.location.search);
+  return q.has("code") && q.has("state");
+}
+
+export async function currentUser(): Promise<User | null> {
+  const oidc = appConfig.auth.oidc;
+  if (!oidc) return null;
+  const user = await requireManager(oidc).getUser();
+  return user && !user.expired ? user : null;
+}
+
+/**
+ * `getAccessToken` for `<GuueyChat>`: the current stored ID token, or null
+ * when signed out / expired (the chat surfaces it as needs-sign-in; they
+ * never silently fall back to guest — one identity mode per surface).
+ * There is NO silent renew here — when the session expires the user signs
+ * in again via /login. Wiring `automaticSilentRenew` (plus a silent
+ * redirect page) is the documented upgrade if your IdP supports it.
+ */
+export async function getBearerToken(): Promise<string | null> {
+  const user = await currentUser();
+  return user?.id_token ?? null;
+}
+
+export async function signOutOidc(): Promise<void> {
+  const oidc = appConfig.auth.oidc;
+  if (!oidc || !manager) return;
+  await manager.removeUser();
+}