@guuey/create-agentic-app 0.1.0

package/dist/templates/openai-agents-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/openai-agents-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/openai-agents-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/openai-agents-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;
+}

package/dist/templates/openai-agents-sdk/web/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "useDefineForClassFields": true,
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "types": ["vite/client"]
+  },
+  "include": ["src", "vite.config.ts", "sandbox-proxy.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/dist/templates/openai-agents-sdk/web/vite.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { sandboxProxyPlugin } from "./sandbox-proxy";
+
+// Port is passed via the `dev` script's `--port 6890` flag (see package.json)
+// so it stays visible in one place; `scripts/dev.mjs` boots this on the same
+// port. The sandbox proxy plugin serves the MCP-Apps sandbox page on :6891 —
+// a SECOND origin, as the spec's double-iframe architecture requires (see
+// ./sandbox-proxy.ts).
+export default defineConfig({
+  plugins: [react(), sandboxProxyPlugin()],
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@guuey/create-agentic-app",
+  "version": "0.1.0",
+  "description": "Scaffold a guuey agentic app: code-mode agent + custom MCP + ggui + web, local pnpm dev, one-command guuey deploy.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-agentic-app": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.4",
+    "@guuey/config": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withguuey/guuey-sdks.git",
+    "directory": "packages/create-agentic-app"
+  },
+  "homepage": "https://guuey.com",
+  "scripts": {
+    "build": "tsup && node scripts/build-templates.mjs && node scripts/check-templates.mjs",
+    "pretest": "node scripts/build-templates.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src --ext .ts",
+    "smoke": "node scripts/scaffold-smoke.mjs",
+    "smoke:verdaccio": "node scripts/verdaccio-smoke.mjs"
+  }
+}