@guuey/create-agentic-app 0.1.0

package/dist/templates/claude-agent-sdk/web/sandbox-proxy.ts

@@ -0,0 +1,239 @@
+/**
+ * MCP-Apps sandbox proxy for local dev — a Vite plugin that serves the
+ * spec-canonical `sandbox.html` on a SECOND localhost port (:6891), i.e. a
+ * different origin from the SPA (:6890).
+ *
+ * # Why a second origin
+ *
+ * The MCP Apps spec's double-iframe sandbox architecture mandates that the
+ * host page and the sandbox iframe live on DIFFERENT origins: the host wraps
+ * the sandbox iframe, the sandbox iframe wraps the untrusted app HTML, and
+ * the origin split means a compromised app cannot reach the host's APIs via
+ * same-origin DOM access. `@mcp-ui/client`'s `<AppRenderer>` takes a
+ * `sandbox: { url }` prop pointing at this page. A different localhost PORT
+ * is a different origin, so one extra listener is all local dev needs.
+ *
+ * # Reference impl
+ *
+ * The HTML below is adapted from the spec's reference host
+ * (`github.com/modelcontextprotocol/ext-apps/examples/basic-host/` —
+ * sandbox.html + src/sandbox.ts + serve.ts), matching the pattern
+ * `@ggui-ai/agent-server`'s bundled sandbox proxy uses. CSP arrives as a
+ * `?csp=<urlencoded-json>` query param and is applied via HTTP HEADERS
+ * (tamper-proof — a `<meta>` CSP could be overridden by injected inline
+ * scripts), which is why this must be a real server, not a static file.
+ *
+ * # Deploying `web/`
+ *
+ * This plugin only runs under `vite` dev (`apply: "serve"`). A deployed
+ * build must point `VITE_SANDBOX_URL` at a hosted copy of this page on its
+ * own origin (see `.env.example`); without it the app falls back to a
+ * "UI resource received" notice instead of mounting UI same-origin.
+ */
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import type { Plugin } from "vite";
+
+/**
+ * The sandbox proxy's dev port. web/ runs on :6890; keep the `6891` literal
+ * in `src/App.tsx` (`DEV_SANDBOX_URL`) in sync — App.tsx cannot import this
+ * module (it would drag `node:http` into the browser bundle).
+ */
+export const SANDBOX_PROXY_PORT = 6891;
+
+/** CSP shape `<AppRenderer>` forwards on the sandbox URL's `?csp=` param. */
+interface McpUiResourceCsp {
+  readonly resourceDomains?: readonly string[];
+  readonly connectDomains?: readonly string[];
+  readonly frameDomains?: readonly string[];
+  readonly baseUriDomains?: readonly string[];
+}
+
+/** Drop CSP entries carrying directive-injection characters (`;`, newlines, quotes, spaces). */
+function sanitizeCspDomains(domains: readonly string[] | undefined): readonly string[] {
+  if (!domains) return [];
+  return domains.filter((d) => typeof d === "string" && !/[;\r\n'" ]/.test(d));
+}
+
+/** Build the CSP header value — mirrors the upstream basic-host `serve.ts`. */
+function buildCspHeader(csp: McpUiResourceCsp | undefined): string {
+  const resourceDomains = sanitizeCspDomains(csp?.resourceDomains).join(" ");
+  const connectDomains = sanitizeCspDomains(csp?.connectDomains).join(" ");
+  const frameDomains = sanitizeCspDomains(csp?.frameDomains).join(" ");
+  const baseUriDomains = sanitizeCspDomains(csp?.baseUriDomains).join(" ");
+  return [
+    "default-src 'self' 'unsafe-inline'",
+    `script-src 'self' 'unsafe-inline' 'unsafe-eval' blob: data: ${resourceDomains}`.trim(),
+    `style-src 'self' 'unsafe-inline' blob: data: ${resourceDomains}`.trim(),
+    `img-src 'self' data: blob: ${resourceDomains}`.trim(),
+    `font-src 'self' data: blob: ${resourceDomains}`.trim(),
+    `media-src 'self' data: blob: ${resourceDomains}`.trim(),
+    `connect-src 'self' ${connectDomains}`.trim(),
+    `worker-src 'self' blob: ${resourceDomains}`.trim(),
+    frameDomains.length > 0 ? `frame-src ${frameDomains}` : "frame-src 'none'",
+    "object-src 'none'",
+    baseUriDomains.length > 0 ? `base-uri ${baseUriDomains}` : "base-uri 'none'",
+  ].join("; ");
+}
+
+/**
+ * The self-contained sandbox.html. The inlined script:
+ *
+ *   1. Asserts iframe isolation (throws if it can reach `window.top`).
+ *   2. Creates an inner iframe sandboxed with `allow-scripts
+ *      allow-same-origin allow-forms`.
+ *   3. On `ui/notifications/sandbox-resource-ready` from the parent, writes
+ *      the app HTML into the inner iframe.
+ *   4. Relays every other postMessage bidirectionally, origin-checked.
+ *   5. Posts `ui/notifications/sandbox-proxy-ready` once attached.
+ */
+const SANDBOX_HTML = `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="color-scheme" content="light dark">
+    <title>sandbox proxy</title>
+    <style>
+      html, body { margin: 0; height: 100vh; height: 100dvh; width: 100%; background-color: transparent; }
+      body { display: flex; flex-direction: column; }
+      * { box-sizing: border-box; }
+      iframe {
+        background-color: transparent;
+        border: 0px none transparent;
+        padding: 0px;
+        overflow: hidden;
+        flex-grow: 1;
+        color-scheme: inherit;
+      }
+    </style>
+  </head>
+  <body>
+    <script>
+(function(){
+  'use strict';
+  if (window.self === window.top) {
+    throw new Error('This file is only to be used in an iframe sandbox.');
+  }
+  if (!document.referrer) {
+    throw new Error('No referrer, cannot validate embedding site.');
+  }
+  var EXPECTED_HOST_ORIGIN = new URL(document.referrer).origin;
+  var OWN_ORIGIN = new URL(window.location.href).origin;
+  // Security self-test: top access MUST throw (sandbox attribute strips same-origin).
+  try {
+    window.top.alert('If you see this, the sandbox is not setup securely.');
+    throw 'FAIL';
+  } catch (e) {
+    if (e === 'FAIL') {
+      throw new Error('The sandbox is not setup securely.');
+    }
+  }
+  // Inner iframe — the untrusted app HTML lands here.
+  var inner = document.createElement('iframe');
+  inner.style = 'width:100%; height:100%; border:none;';
+  inner.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-forms');
+  document.body.appendChild(inner);
+  var RESOURCE_READY = 'ui/notifications/sandbox-resource-ready';
+  var PROXY_READY = 'ui/notifications/sandbox-proxy-ready';
+  window.addEventListener('message', function(event) {
+    if (event.source === window.parent) {
+      if (event.origin !== EXPECTED_HOST_ORIGIN) {
+        console.error('[Sandbox] Rejecting parent message from unexpected origin:', event.origin);
+        return;
+      }
+      if (event.data && event.data.method === RESOURCE_READY) {
+        var params = event.data.params || {};
+        var html = params.html;
+        var sandboxAttr = params.sandbox;
+        if (typeof sandboxAttr === 'string') {
+          inner.setAttribute('sandbox', sandboxAttr);
+        }
+        if (typeof html === 'string') {
+          var doc = inner.contentDocument || (inner.contentWindow && inner.contentWindow.document);
+          if (doc) {
+            doc.open();
+            doc.write(html);
+            doc.close();
+          } else {
+            inner.srcdoc = html;
+          }
+        }
+      } else {
+        if (inner && inner.contentWindow) {
+          inner.contentWindow.postMessage(event.data, '*');
+        }
+      }
+    } else if (event.source === inner.contentWindow) {
+      if (event.origin !== OWN_ORIGIN) {
+        console.error('[Sandbox] Rejecting inner message from unexpected origin:', event.origin);
+        return;
+      }
+      window.parent.postMessage(event.data, EXPECTED_HOST_ORIGIN);
+    }
+  });
+  window.parent.postMessage({
+    jsonrpc: '2.0',
+    method: PROXY_READY,
+    params: {},
+  }, EXPECTED_HOST_ORIGIN);
+})();
+    </script>
+  </body>
+</html>`;
+
+function handleRequest(req: IncomingMessage, res: ServerResponse): void {
+  const url = new URL(req.url ?? "/", "http://placeholder");
+  if (req.method === "GET" && (url.pathname === "/" || url.pathname === "/sandbox.html")) {
+    let csp: McpUiResourceCsp | undefined;
+    const cspParam = url.searchParams.get("csp");
+    if (cspParam !== null) {
+      try {
+        const parsed: unknown = JSON.parse(cspParam);
+        if (parsed !== null && typeof parsed === "object") {
+          csp = parsed as McpUiResourceCsp;
+        }
+      } catch {
+        // Malformed ?csp= — fall through to the default (self-only) header;
+        // an app loading external resources will surface a CSP violation in
+        // the console rather than silently widening the policy.
+      }
+    }
+    res.setHeader("Content-Security-Policy", buildCspHeader(csp));
+    res.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
+    res.setHeader("Content-Type", "text/html; charset=utf-8");
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.statusCode = 200;
+    res.end(SANDBOX_HTML);
+    return;
+  }
+  res.statusCode = 404;
+  res.setHeader("Content-Type", "text/plain; charset=utf-8");
+  res.end("sandbox proxy: only GET /sandbox.html is served here\n");
+}
+
+/**
+ * Vite plugin: boot the sandbox proxy alongside `vite` dev, tear it down
+ * with it. Dev-only (`apply: "serve"`); deployed builds set
+ * `VITE_SANDBOX_URL` instead.
+ */
+export function sandboxProxyPlugin(): Plugin {
+  let server: Server | undefined;
+  return {
+    name: "agentic-app-template:mcp-apps-sandbox-proxy",
+    apply: "serve",
+    configureServer(vite) {
+      server = createServer(handleRequest);
+      server.on("error", (err) => {
+        vite.config.logger.error(`[sandbox-proxy] ${String(err)}`);
+      });
+      server.listen(SANDBOX_PROXY_PORT, "127.0.0.1", () => {
+        vite.config.logger.info(
+          `  sandbox proxy: http://127.0.0.1:${SANDBOX_PROXY_PORT}/sandbox.html`
+        );
+      });
+      vite.httpServer?.on("close", () => {
+        server?.close();
+        server = undefined;
+      });
+    },
+  };
+}

package/dist/templates/claude-agent-sdk/web/src/App.tsx

@@ -0,0 +1,272 @@
+/**
+ * Minimal-but-real local dev chat client: message list folded from the
+ * reducer's `AgReduceResult.messages` (via `useAgentChat`) + an input box.
+ * Tool-result blocks that carry an inlined MCP-Apps UI resource (the
+ * `_meta.ui.resource` convention landing on `AgBlock.tool-result.uiData` —
+ * opaque JSON on the wire, so it's structurally validated below rather than
+ * cast) render through `@mcp-ui/client`'s `AppRenderer`, the spec-canonical
+ * MCP Apps host.
+ *
+ * `onCallTool`/`onReadResource` are typed via `ComponentProps<typeof
+ * AppRenderer>` instead of importing `@modelcontextprotocol/sdk`'s request
+ * types directly — that keeps this file honest against whatever the
+ * installed `@mcp-ui/client` version actually expects, with zero guessing.
+ *
+ * Sandbox origin (MCP Apps spec, double-iframe architecture): the untrusted
+ * app HTML must be mounted from a DIFFERENT origin than this page. In dev,
+ * `vite.config.ts`'s `sandboxProxyPlugin` serves the spec-canonical
+ * `sandbox.html` on :6891 (a different localhost port = a different origin);
+ * deployed builds must set `VITE_SANDBOX_URL` to a hosted copy (see
+ * `../sandbox-proxy.ts` + `.env.example`). Without a resolvable sandbox URL,
+ * UI resources fall back to a visible notice — NEVER a same-origin mount.
+ */
+import {
+  Fragment,
+  useCallback,
+  useState,
+  type ComponentProps,
+  type FormEvent,
+  type ReactNode,
+} from "react";
+import { AppRenderer } from "@mcp-ui/client";
+import type { AgBlock, AgMessage, JsonValue } from "@silverprotocol/core";
+import { AGENT_URL, envUrl, useAgentChat } from "./useAgentChat";
+
+type AppRendererProps = ComponentProps<typeof AppRenderer>;
+type CallToolHandler = NonNullable<AppRendererProps["onCallTool"]>;
+type ReadResourceHandler = NonNullable<AppRendererProps["onReadResource"]>;
+
+/**
+ * The dev sandbox proxy served by `vite.config.ts`'s `sandboxProxyPlugin`.
+ * The `6891` literal mirrors `SANDBOX_PROXY_PORT` in `../sandbox-proxy.ts`
+ * (not imported — that module pulls in `node:http`, which must never enter
+ * the browser bundle). Keep the two in sync.
+ */
+const DEV_SANDBOX_URL = "http://127.0.0.1:6891/sandbox.html";
+
+/**
+ * The sandbox origin UI resources mount from. `VITE_SANDBOX_URL` (a deployed
+ * copy of the sandbox page on its own origin) wins; in dev the local proxy
+ * is the fallback. `undefined` (a production build without the env) shows
+ * the plain-text fallback below instead — the untrusted HTML is never
+ * mounted same-origin. `envUrl` treats an empty `VITE_SANDBOX_URL=`
+ * declaration as unset (it loads as `""`, which would defeat `??` and make
+ * `new URL("")` throw mid-render).
+ */
+const SANDBOX_URL: string | undefined =
+  envUrl(import.meta.env.VITE_SANDBOX_URL) ?? (import.meta.env.DEV ? DEV_SANDBOX_URL : undefined);
+
+// ── MCP-embedded-resource narrowing (opaque JsonValue → typed payload) ──────
+
+interface McpUiResourcePayload {
+  uri: string;
+  mimeType?: string;
+  text?: string;
+  blob?: string;
+}
+
+function isJsonObject(v: JsonValue): v is { [key: string]: JsonValue } {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function asResourcePayload(v: JsonValue): McpUiResourcePayload | undefined {
+  if (!isJsonObject(v)) return undefined;
+  if (typeof v.uri !== "string") return undefined;
+  if (typeof v.text !== "string" && typeof v.blob !== "string") return undefined;
+  return {
+    uri: v.uri,
+    ...(typeof v.mimeType === "string" ? { mimeType: v.mimeType } : {}),
+    ...(typeof v.text === "string" ? { text: v.text } : {}),
+    ...(typeof v.blob === "string" ? { blob: v.blob } : {}),
+  };
+}
+
+/**
+ * Does a tool-result's `uiData` carry an MCP embedded UI resource? Accepts
+ * either the resource inlined directly, or wrapped as `{ resource: {...} }`
+ * (the shape an MCP `resource` content block carries).
+ */
+function asUiResource(uiData: JsonValue | undefined): McpUiResourcePayload | undefined {
+  if (uiData === undefined || !isJsonObject(uiData)) return undefined;
+  const direct = asResourcePayload(uiData);
+  if (direct) return direct;
+  const nested = uiData.resource;
+  return nested !== undefined ? asResourcePayload(nested) : undefined;
+}
+
+/**
+ * The resource's HTML: inline `text` wins; else base64-decode `blob`.
+ * `atob` alone yields a Latin-1 string (mojibake on multibyte UTF-8), so
+ * decode via bytes + `TextDecoder`.
+ */
+function resourceHtml(resource: McpUiResourcePayload): string | undefined {
+  if (resource.text !== undefined) return resource.text;
+  if (resource.blob !== undefined) {
+    try {
+      return new TextDecoder().decode(Uint8Array.from(atob(resource.blob), (c) => c.charCodeAt(0)));
+    } catch {
+      return undefined; // not valid base64 — treat as no renderable payload
+    }
+  }
+  return undefined;
+}
+
+/** The tool name for a tool-result block, read off its paired tool-call block in the same message. */
+function toolNameFor(message: AgMessage, toolCallId: string): string {
+  const call = message.content.find(
+    (b): b is Extract<AgBlock, { type: "tool-call" }> =>
+      b.type === "tool-call" && b.toolCallId === toolCallId
+  );
+  return call?.name ?? "tool";
+}
+
+function renderBlock(
+  message: AgMessage,
+  block: AgBlock,
+  handlers: { onCallTool: CallToolHandler; onReadResource: ReadResourceHandler }
+): ReactNode {
+  switch (block.type) {
+    case "text":
+      return block.text ? <p className="block block-text">{block.text}</p> : null;
+    case "reasoning":
+      return block.text ? <p className="block block-reasoning">{block.text}</p> : null;
+    case "tool-call":
+      return (
+        <p className="block block-tool-call">
+          → calling <code>{block.name}</code>…
+        </p>
+      );
+    case "tool-result": {
+      const resource = asUiResource(block.uiData);
+      const html = resource !== undefined ? resourceHtml(resource) : undefined;
+      if (html !== undefined) {
+        if (SANDBOX_URL === undefined) {
+          // No second-origin sandbox available (production build without
+          // VITE_SANDBOX_URL). Never mount the untrusted HTML same-origin —
+          // degrade to a visible notice instead.
+          return (
+            <p className="block block-tool-result">
+              ← UI resource received — set <code>VITE_SANDBOX_URL</code> to render it (see{" "}
+              <code>.env.example</code>).
+            </p>
+          );
+        }
+        return (
+          <div className="block block-ui-resource">
+            <AppRenderer
+              key={block.toolCallId}
+              toolName={toolNameFor(message, block.toolCallId)}
+              sandbox={{ url: new URL(SANDBOX_URL) }}
+              html={html}
+              onCallTool={handlers.onCallTool}
+              onReadResource={handlers.onReadResource}
+              onError={(err: unknown) => console.warn("[AppRenderer]", err)}
+            />
+          </div>
+        );
+      }
+      return (
+        <p className={`block block-tool-result${block.isError ? " is-error" : ""}`}>
+          ← {block.isError ? "tool error" : "tool result"}
+        </p>
+      );
+    }
+    default:
+      return null;
+  }
+}
+
+export function App() {
+  const { result, busy, error, needsResync, send } = useAgentChat();
+  const [draft, setDraft] = useState("");
+
+  // Neither relay exists in this minimal template — this worker only exposes
+  // `POST /agent/invoke` (see useAgentChat.ts), not a general tool-call/
+  // resource-read relay. Rendered UI resources that DON'T round-trip through
+  // the model (most simple cards/forms) still work; ones that do get a clear
+  // error here instead of a silent hang.
+  const onCallTool = useCallback<CallToolHandler>(async (params) => {
+    throw new Error(
+      `tool-call relay is not wired in this template (requested "${params.name}") — ` +
+        `add a relay endpoint on your worker for full MCP Apps interactivity.`
+    );
+  }, []);
+  const onReadResource = useCallback<ReadResourceHandler>(async (params) => {
+    throw new Error(`resource-read relay is not wired in this template (requested "${params.uri}")`);
+  }, []);
+
+  const onSubmit = (e: FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    const text = draft.trim();
+    if (!text || busy) return;
+    setDraft("");
+    void send(text);
+  };
+
+  return (
+    <div className="app">
+      <style>{`
+        :root { color-scheme: light dark; }
+        body { margin: 0; font-family: system-ui, sans-serif; }
+        .app { display: flex; flex-direction: column; height: 100vh; max-width: 720px; margin: 0 auto; }
+        header { padding: 12px 16px; border-bottom: 1px solid #8884; }
+        header h1 { font-size: 15px; margin: 0; }
+        header p { font-size: 12px; opacity: 0.6; margin: 2px 0 0; }
+        .history { flex: 1; overflow-y: auto; padding: 12px 16px; display: flex; flex-direction: column; gap: 10px; }
+        .empty { opacity: 0.5; font-size: 13px; }
+        .message { max-width: 85%; }
+        .message-user { align-self: flex-end; text-align: right; }
+        .message-assistant, .message-tool { align-self: flex-start; }
+        .block { margin: 0; padding: 6px 10px; border-radius: 8px; background: #8882; white-space: pre-wrap; }
+        .message-user .block-text { background: #4c8bf522; }
+        .block-tool-call, .block-tool-result { font-size: 12px; opacity: 0.7; background: none; padding: 0; }
+        .block-tool-result.is-error { color: #d33; }
+        .block-ui-resource { padding: 0; background: none; }
+        .block-ui-resource iframe { width: 100%; min-height: 240px; border: 1px solid #8884; border-radius: 8px; }
+        .banner { margin: 0 16px 8px; padding: 6px 10px; border-radius: 6px; font-size: 12px; }
+        .banner-error { background: #d3333322; color: #d33; }
+        .banner-warn { background: #d3901922; color: #b8720f; }
+        .composer { display: flex; gap: 8px; padding: 12px 16px; border-top: 1px solid #8884; }
+        .composer input { flex: 1; padding: 8px 10px; border-radius: 6px; border: 1px solid #8886; }
+        .composer button { padding: 8px 14px; border-radius: 6px; border: none; background: #4c8bf5; color: white; }
+        .composer button:disabled { opacity: 0.5; }
+      `}</style>
+      <header>
+        <h1>agentic-app-template</h1>
+        <p>{AGENT_URL}</p>
+      </header>
+
+      <main className="history" role="log" aria-live="polite">
+        {result.messages.length === 0 ? (
+          <p className="empty">Say something to your agent.</p>
+        ) : (
+          result.messages.map((message) => (
+            <div key={message.id} className={`message message-${message.role}`}>
+              {message.content.map((block, i) => (
+                <Fragment key={i}>{renderBlock(message, block, { onCallTool, onReadResource })}</Fragment>
+              ))}
+            </div>
+          ))
+        )}
+      </main>
+
+      {needsResync ? (
+        <p className="banner banner-warn">Stream fell out of sync — reload to resync.</p>
+      ) : null}
+      {error ? <p className="banner banner-error">{error}</p> : null}
+
+      <form className="composer" onSubmit={onSubmit}>
+        <input
+          value={draft}
+          onChange={(e) => setDraft(e.target.value)}
+          placeholder="Message your agent…"
+          disabled={busy}
+          autoFocus
+        />
+        <button type="submit" disabled={busy || !draft.trim()}>
+          {busy ? "Sending…" : "Send"}
+        </button>
+      </form>
+    </div>
+  );
+}

package/dist/templates/claude-agent-sdk/web/src/main.tsx

@@ -0,0 +1,12 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+
+const root = document.getElementById("root");
+if (!root) throw new Error("#root element missing from index.html");
+
+createRoot(root).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);

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

@@ -0,0 +1,122 @@
+/**
+ * The from-scratch AgJSON client for the local dev chat SPA. Talks directly
+ * to the agent's `POST /agent/invoke` endpoint (SSE response), parses each
+ * `event: session|message|done|error` / `data: <JSON>` frame off the wire,
+ * and folds `message` frames (AgJSON `AgEvent[]`) through `@silverprotocol/
+ * core`'s `Reducer` into the normative `{messages, turns, artifacts, memory}`
+ * snapshot `App.tsx` renders from.
+ *
+ * Real `@silverprotocol/core` API (verified against `core/README.md` +
+ * `core/src/reduce.ts:79`): `new Reducer()` + `reducer.push(event)` are
+ * correct, but the fold is read back via `reducer.result()` — there is no
+ * `reducer.state` accessor. `ingestAgEvents` is the library's own
+ * parse-known-else-skip validator; used here instead of an `as AgEvent[]`
+ * cast so a malformed/foreign wire object degrades to "silently skipped"
+ * rather than a runtime type lie.
+ */
+import { useCallback, useRef, useState } from "react";
+import { Reducer, ingestAgEvents, type AgReduceResult, type JsonValue } from "@silverprotocol/core";
+
+/**
+ * Normalize a `VITE_*` env URL: an empty/whitespace declaration (e.g. a
+ * `VITE_X=` line copied from `.env.example`) loads as `""`, not `undefined`,
+ * which would defeat a `??` fallback — treat it as unset. Shared by this
+ * file's `AGENT_URL` and `App.tsx`'s `SANDBOX_URL` so both read sites agree.
+ */
+export function envUrl(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export const AGENT_URL =
+  envUrl(import.meta.env.VITE_AGENT_ENDPOINT_URL) ?? "http://localhost:6790";
+
+/** Parse complete SSE frame blocks ("event: x\ndata: {...}") out of a growing buffer. */
+function parseFrames(buffer: string): {
+  frames: Array<{ event: string; data: string }>;
+  rest: string;
+} {
+  const parts = buffer.split("\n\n");
+  const rest = parts.pop() ?? "";
+  const frames = parts.map((block) => {
+    const event = /^event: (.*)$/m.exec(block)?.[1] ?? "message";
+    const data = /^data: (.*)$/m.exec(block)?.[1] ?? "";
+    return { event, data };
+  });
+  return { frames, rest };
+}
+
+export interface UseAgentChatResult {
+  /** The reducer's current folded state — fresh on every `message` frame. */
+  result: AgReduceResult;
+  /** True while a `send()` request is streaming. */
+  busy: boolean;
+  /** Last transport/agent error, or `null`. */
+  error: string | null;
+  /** True when the reducer detected a sequence gap and parked (needs a `messages.snapshot` to recover). */
+  needsResync: boolean;
+  send: (text: string) => Promise<void>;
+}
+
+export function useAgentChat(): UseAgentChatResult {
+  const reducerRef = useRef(new Reducer());
+  // No payload — just a re-render trigger every time the mutable reducer
+  // advances, so `reducerRef.current.result()` below re-derives fresh state.
+  const [, bump] = useState(0);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const send = useCallback(async (text: string) => {
+    setBusy(true);
+    setError(null);
+    const res = await fetch(`${AGENT_URL}/agent/invoke`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ input: text }),
+    });
+    if (!res.ok || !res.body) {
+      setError(`agent returned ${res.status}`);
+      setBusy(false);
+      return;
+    }
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const reader = res.body.getReader();
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const { frames, rest } = parseFrames(buffer);
+      buffer = rest;
+      for (const frame of frames) {
+        if (frame.event === "message") {
+          let raw: JsonValue;
+          try {
+            raw = JSON.parse(frame.data) as JsonValue;
+          } catch {
+            continue; // malformed frame — skip rather than crash the stream
+          }
+          const events = ingestAgEvents(Array.isArray(raw) ? raw : []);
+          for (const ev of events) reducerRef.current.push(ev);
+          bump((v) => v + 1);
+        } else if (frame.event === "error") {
+          try {
+            const payload = JSON.parse(frame.data) as { message?: string };
+            setError(payload.message ?? "agent error");
+          } catch {
+            setError("agent error");
+          }
+        }
+      }
+    }
+    setBusy(false);
+  }, []);
+
+  return {
+    result: reducerRef.current.result(),
+    busy,
+    error,
+    needsResync: reducerRef.current.needsResync,
+    send,
+  };
+}

package/dist/templates/claude-agent-sdk/web/src/vite-env.d.ts

@@ -0,0 +1,27 @@
+/// <reference types="vite/client" />
+
+/**
+ * Typed Vite env vars. `import.meta.env` is Vite's analog of Next.js's
+ * `process.env.NEXT_PUBLIC_*` — anything declared here is exposed to the
+ * browser bundle at build time.
+ */
+interface ImportMetaEnv {
+  /**
+   * The agent's base URL (e.g. `http://localhost:6790` in local dev, via
+   * `guuey dev`). Falls back to that same local-dev default when unset —
+   * see `useAgentChat.ts`.
+   */
+  readonly VITE_AGENT_ENDPOINT_URL?: string;
+  /**
+   * Second-origin MCP-Apps sandbox page URL for `<AppRenderer>` (e.g.
+   * `https://sandbox.example.com/sandbox.html`). Optional in dev — the
+   * `sandboxProxyPlugin` in `vite.config.ts` serves one on :6891. REQUIRED
+   * for deployed builds that render UI resources: without it the app shows
+   * a plain-text notice instead (see `App.tsx` + `../sandbox-proxy.ts`).
+   */
+  readonly VITE_SANDBOX_URL?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}