@seed-app-studio/cli 0.1.1-canary.0

package/examples/react-spa-stories/src/App.tsx

@@ -0,0 +1,440 @@
+import { useEffect, useState } from "react";
+import {
+  createSeedAppClient,
+  createWindowSeedAppTransport,
+  installSeedAppConsoleBridge,
+  type SeedAppAgentStreamEvent,
+  type SeedAppClient,
+  type SeedAppEvent,
+  type SeedAppError,
+  type SeedAppGrantResolution,
+  type SeedAppRpcResponse,
+} from "@seed-app-studio/sdk";
+import { createAgentReplayFixtureDownload } from "./replayFixture.js";
+import {
+  APP_ID,
+  STORIES,
+  type CapabilityStory,
+  type StoryResult,
+  type StoryRuntimeKind,
+} from "./storyData.js";
+
+type EventEntry = {
+  id: string;
+  event: SeedAppEvent;
+};
+
+const initialResults = Object.fromEntries(
+  STORIES.map((story) => [story.id, { state: "idle" }]),
+) as Record<string, StoryResult>;
+
+export function App() {
+  const [client, setClient] = useState<SeedAppClient>();
+  const [grants, setGrants] = useState<SeedAppGrantResolution[]>([]);
+  const [results, setResults] = useState<Record<string, StoryResult>>(initialResults);
+  const [events, setEvents] = useState<EventEntry[]>([]);
+  const [agentEvents, setAgentEvents] = useState<SeedAppAgentStreamEvent[]>([]);
+  const [openCodeStoryId, setOpenCodeStoryId] = useState<string>();
+
+  useEffect(() => {
+    let disposed = false;
+    const activeClient = createSeedAppClient({
+      transport: createWindowSeedAppTransport({ timeoutMs: 8000 }),
+    });
+    setClient(activeClient);
+    const consoleBridge = installSeedAppConsoleBridge();
+    console.log("[seed-app-story] mounting React SPA capability stories");
+    const unsubscribe = activeClient.events.subscribe((event) => {
+      console.info("[seed-app-story] host event", event);
+      setEvents((current) =>
+        [{ id: `${Date.now()}:${current.length}`, event }, ...current].slice(0, 8),
+      );
+    });
+    const unsubscribeAgent = activeClient.agent.subscribe((event) => {
+      setAgentEvents((current) => [event, ...current].slice(0, 16));
+    });
+    void runStoryWithClient(STORIES[0], activeClient, () => disposed);
+    return () => {
+      disposed = true;
+      console.log("[seed-app-story] unmounting React SPA capability stories");
+      consoleBridge.uninstall();
+      unsubscribe();
+      unsubscribeAgent();
+      activeClient.close();
+    };
+  }, []);
+
+  const runStoryWithClient = async (
+    story: CapabilityStory,
+    activeClient: SeedAppClient,
+    isStale: () => boolean = () => false,
+  ) => {
+    if (isStale()) return;
+    setResults((current) => ({ ...current, [story.id]: { state: "running" } }));
+    try {
+      console.log("[seed-app-story] running story", story.id);
+      const payload = await story.run(activeClient);
+      if (isStale()) return;
+      if (story.id === "handshake" && isGrantPayload(payload)) setGrants(payload.grants);
+      if (story.id === "capabilities" && Array.isArray(payload))
+        setGrants(payload as SeedAppGrantResolution[]);
+      if (isGrantPrecedencePayload(payload)) setGrants(payload.fixture);
+      if (isAgentStreamReplayPayload(payload)) {
+        setAgentEvents((current) => [...copyNewestFirst(payload.events), ...current].slice(0, 16));
+      }
+      setResults((current) => ({
+        ...current,
+        [story.id]: { state: "success", runtimeKind: classifySuccessPayload(payload), payload },
+      }));
+      console.info("[seed-app-story] story completed", story.id, payload);
+    } catch (error) {
+      if (isStale()) return;
+      const hostError = isHostBlock(error) ? error : undefined;
+      setResults((current) => ({
+        ...current,
+        [story.id]: {
+          state: hostError ? "blocked" : "failed",
+          runtimeKind: classifyError(hostError),
+          error: error instanceof Error ? error.message : String(error),
+          payload: hostError,
+        },
+      }));
+      console.warn("[seed-app-story] story blocked or failed", story.id, error);
+    }
+  };
+
+  const runStory = (story: CapabilityStory) => {
+    if (!client) return;
+    void runStoryWithClient(story, client);
+  };
+
+  const downloadReplayFixture = () => {
+    const download = createAgentReplayFixtureDownload();
+    const objectUrl = URL.createObjectURL(new Blob([download.text], { type: download.mimeType }));
+    const anchor = document.createElement("a");
+    anchor.href = objectUrl;
+    anchor.download = download.fileName;
+    anchor.click();
+    URL.revokeObjectURL(objectUrl);
+    setAgentEvents((current) =>
+      [...copyNewestFirst(download.fixture.events), ...current].slice(0, 16),
+    );
+    console.info("[seed-app-story] replay fixture downloaded", {
+      fileName: download.fileName,
+      eventCount: download.fixture.expectations.eventCount,
+    });
+  };
+
+  return (
+    <main>
+      <header className="hero">
+        <div>
+          <p className="eyebrow">SEED App Host acceptance SPA</p>
+          <h1>React SPA capability stories</h1>
+          <p className="intro">
+            Load this localhost app in App Studio to verify SDK handshake, brokered capabilities,
+            approval paths, and denied states.
+          </p>
+          <p className="intro zh">
+            将这个本地 React SPA 接入 App Studio，用于验证 SDK
+            握手、宿主代理能力、授权审批路径和拒绝态处理。
+          </p>
+        </div>
+        <div className="identity">
+          <span>App ID</span>
+          <strong>{APP_ID}</strong>
+        </div>
+      </header>
+
+      <section className="layout">
+        <div className="stories">
+          {STORIES.map((story) => (
+            <StoryCard
+              key={story.id}
+              story={story}
+              grant={findGrant(grants, story.capability)}
+              result={results[story.id] ?? { state: "idle" }}
+              disabled={!client}
+              codeVisible={openCodeStoryId === story.id}
+              onRun={() => runStory(story)}
+              onToggleCode={() =>
+                setOpenCodeStoryId((current) => (current === story.id ? undefined : story.id))
+              }
+            />
+          ))}
+        </div>
+
+        <aside>
+          <Panel title="Replay fixture">
+            <p className="muted">
+              Download the same Bridge-projected agent stream used by the replay story.
+            </p>
+            <p className="muted zh">下载与回放 story 使用的同一份 Bridge 投影 Agent 流样例。</p>
+            <div className="fixtureActions">
+              <button type="button" onClick={downloadReplayFixture}>
+                Download JSON
+              </button>
+              <span>
+                Includes message, thought, tool, approval, elicitation, subagent, backup, and turn
+                events.
+              </span>
+              <span className="zh">
+                包含消息、思考、工具、授权、追问、子 Agent、备份和回合事件。
+              </span>
+            </div>
+          </Panel>
+
+          <Panel title="Capability grants">
+            {grants.length === 0 ? (
+              <>
+                <p className="muted">Run handshake or capability snapshot to populate grants.</p>
+                <p className="muted zh">
+                  运行握手或能力快照 story 后，这里会展示宿主返回的授权结果。
+                </p>
+              </>
+            ) : (
+              <div className="grantList">
+                {grants.map((grant) => (
+                  <div key={grant.capability} className={`grant ${grant.policy}`}>
+                    <span>{grant.capability}</span>
+                    <strong>{grant.policy}</strong>
+                    <small>{grant.source}</small>
+                  </div>
+                ))}
+              </div>
+            )}
+          </Panel>
+
+          <Panel title="Agent stream lifecycle">
+            {agentEvents.length === 0 ? (
+              <>
+                <p className="muted">
+                  Run the stream replay story or a live agent stream to populate lifecycle events.
+                </p>
+                <p className="muted zh">
+                  运行流式回放或真实 Agent 流后，这里会显示 Agent 生命周期事件。
+                </p>
+              </>
+            ) : (
+              <div className="agentTimeline">
+                {agentEvents.map((event, index) => (
+                  <div key={`${event.type}:${index}`} className="agentEvent">
+                    <strong>{event.type}</strong>
+                    <span>{formatAgentEventSummary(event)}</span>
+                  </div>
+                ))}
+              </div>
+            )}
+          </Panel>
+
+          <Panel title="Host events">
+            {events.length === 0 ? (
+              <>
+                <p className="muted">Waiting for host events.</p>
+                <p className="muted zh">等待宿主事件，用于观察 iframe 与 App Host 的通信结果。</p>
+              </>
+            ) : (
+              <pre>
+                {JSON.stringify(
+                  events.map((entry) => entry.event),
+                  null,
+                  2,
+                )}
+              </pre>
+            )}
+          </Panel>
+        </aside>
+      </section>
+    </main>
+  );
+}
+
+function StoryCard(props: {
+  story: CapabilityStory;
+  grant?: SeedAppGrantResolution;
+  result: StoryResult;
+  disabled?: boolean;
+  codeVisible: boolean;
+  onRun(): void;
+  onToggleCode(): void;
+}) {
+  const { codeVisible, disabled = false, grant, onRun, onToggleCode, result, story } = props;
+  return (
+    <article className={`story ${result.state}`}>
+      <div className="storyHeader">
+        <div>
+          <span className="capability">{story.capability}</span>
+          <h2>{story.title}</h2>
+        </div>
+        <div className="storyActions">
+          <button type="button" className="secondaryButton" onClick={onToggleCode}>
+            {codeVisible ? "Hide code" : "Code"}
+          </button>
+          <button type="button" onClick={onRun} disabled={disabled || result.state === "running"}>
+            {result.state === "running" ? "Running" : "Run"}
+          </button>
+        </div>
+      </div>
+      <p>{story.intent}</p>
+      <p className="zh">{story.intentZh}</p>
+      {codeVisible ? <pre className="codeExample">{story.codeExample}</pre> : null}
+      <div className="meta">
+        <span>Grant: {grant ? `${grant.policy} from ${grant.source}` : "not loaded"}</span>
+        <span>State: {result.state}</span>
+      </div>
+      <div className="runtimeLine">
+        <span className={`runtimeBadge ${result.runtimeKind ?? "pending"}`}>
+          {runtimeKindLabel(result.runtimeKind ?? "pending")}
+        </span>
+        <small>{runtimeKindCopy(result.runtimeKind ?? "pending")}</small>
+      </div>
+      {result.error ? <p className="error">{result.error}</p> : null}
+      {result.payload ? <pre>{JSON.stringify(result.payload, null, 2)}</pre> : null}
+    </article>
+  );
+}
+
+function Panel(props: { title: string; children: React.ReactNode }) {
+  return (
+    <section className="panel">
+      <h2>{props.title}</h2>
+      {props.children}
+    </section>
+  );
+}
+
+function findGrant(
+  grants: SeedAppGrantResolution[],
+  capability: string,
+): SeedAppGrantResolution | undefined {
+  return grants.find((grant) => grant.capability === capability);
+}
+
+function copyNewestFirst(events: SeedAppAgentStreamEvent[]): SeedAppAgentStreamEvent[] {
+  const ordered: SeedAppAgentStreamEvent[] = [];
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    ordered.push(events[index]);
+  }
+  return ordered;
+}
+
+function isGrantPayload(value: unknown): value is { grants: SeedAppGrantResolution[] } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Array.isArray((value as { grants?: unknown }).grants)
+  );
+}
+
+function isAgentStreamReplayPayload(
+  value: unknown,
+): value is { events: SeedAppAgentStreamEvent[] } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Array.isArray((value as { events?: unknown }).events)
+  );
+}
+
+function isGrantPrecedencePayload(value: unknown): value is { fixture: SeedAppGrantResolution[] } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    Array.isArray((value as { fixture?: unknown }).fixture)
+  );
+}
+
+function isHostBlock(value: unknown): value is SeedAppRpcResponse["error"] {
+  return typeof value === "object" && value !== null && "code" in value && "requestId" in value;
+}
+
+function classifySuccessPayload(payload: unknown): StoryRuntimeKind {
+  if (isRecord(payload) && isStoryRuntimeKind(payload.runtimeKind)) return payload.runtimeKind;
+  if (isRecord(payload) && hasPreviewOnlyOutput(payload)) return "mock";
+  return "live";
+}
+
+function isStoryRuntimeKind(value: unknown): value is StoryRuntimeKind {
+  return (
+    value === "pending" ||
+    value === "live" ||
+    value === "mock" ||
+    value === "policy-block" ||
+    value === "runtime-error"
+  );
+}
+
+function classifyError(error: SeedAppError | undefined): StoryRuntimeKind {
+  if (!error) return "runtime-error";
+  if (
+    error.code === "approval_required" ||
+    error.code === "approval_denied" ||
+    error.code === "capability_denied" ||
+    error.code === "tenant_policy_denied"
+  ) {
+    return "policy-block";
+  }
+  return "runtime-error";
+}
+
+function hasPreviewOnlyOutput(value: Record<string, unknown>): boolean {
+  const output = value.output;
+  return isRecord(output) && output.previewOnly === true;
+}
+
+function runtimeKindLabel(kind: StoryRuntimeKind): string {
+  switch (kind) {
+    case "live":
+      return "Live";
+    case "mock":
+      return "Mock";
+    case "policy-block":
+      return "Policy block";
+    case "runtime-error":
+      return "Runtime error";
+    default:
+      return "Pending";
+  }
+}
+
+function runtimeKindCopy(kind: StoryRuntimeKind): string {
+  switch (kind) {
+    case "live":
+      return "The story returned from a live host capability or brokered SDK path.";
+    case "mock":
+      return "The host returned a preview-only response. Use this for UI work, not capability verification.";
+    case "policy-block":
+      return "The broker rejected or paused the call because policy or approval requires it.";
+    case "runtime-error":
+      return "The host attempted the runtime path but the capability was unavailable or failed.";
+    default:
+      return "Run the story to classify the result.";
+  }
+}
+
+function formatAgentEventSummary(event: SeedAppAgentStreamEvent): string {
+  switch (event.type) {
+    case "agent.message.delta":
+    case "agent.thought.delta":
+    case "agent.user.delta":
+      return event.payload.text;
+    case "agent.tool.started":
+    case "agent.tool.updated":
+      return `${event.payload.toolCallId}${event.payload.status ? ` / ${event.payload.status}` : ""}`;
+    case "agent.permission.required":
+    case "agent.elicitation.required":
+      return event.payload.requestId;
+    case "agent.subagent.anchor":
+    case "agent.subagent.message.delta":
+    case "agent.subagent.status.updated":
+      return event.payload.childSessionId;
+    case "agent.turn.completed":
+      return event.payload.stopReason ?? "turn completed";
+    default:
+      return event.payload.runId;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/examples/react-spa-stories/src/main.tsx

@@ -0,0 +1,10 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App.js";
+import "./styles.css";
+
+createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

package/examples/react-spa-stories/src/replayFixture.ts

@@ -0,0 +1,60 @@
+import type { SeedAppAgentStreamEvent } from "@seed-app-studio/sdk";
+import { AGENT_STREAM_REPLAY_EVENTS, APP_ID } from "./storyData.js";
+
+export type AgentReplayFixtureExport = {
+  schemaVersion: 1;
+  fixtureId: string;
+  appId: string;
+  source: "app-dev-demo";
+  generatedAt: string;
+  events: SeedAppAgentStreamEvent[];
+  expectations: {
+    eventCount: number;
+    eventTypes: string[];
+    terminalEvent: string;
+  };
+};
+
+export type AgentReplayFixtureDownload = {
+  fileName: string;
+  mimeType: "application/json";
+  text: string;
+  fixture: AgentReplayFixtureExport;
+};
+
+export const AGENT_REPLAY_FIXTURE_MIME_TYPE = "application/json";
+
+export function buildAgentReplayFixtureExport(
+  events: SeedAppAgentStreamEvent[] = AGENT_STREAM_REPLAY_EVENTS,
+  generatedAt = new Date("2026-01-01T00:00:00.000Z"),
+): AgentReplayFixtureExport {
+  if (events.length === 0) throw new Error("Replay fixture requires at least one event.");
+  const eventTypes = events.map((event) => event.type);
+  return {
+    schemaVersion: 1,
+    fixtureId: `${APP_ID}:agent-stream-replay`,
+    appId: APP_ID,
+    source: "app-dev-demo",
+    generatedAt: generatedAt.toISOString(),
+    events,
+    expectations: {
+      eventCount: events.length,
+      eventTypes,
+      terminalEvent: eventTypes[eventTypes.length - 1] ?? "unknown",
+    },
+  };
+}
+
+export function serializeAgentReplayFixture(fixture = buildAgentReplayFixtureExport()): string {
+  return `${JSON.stringify(fixture, null, 2)}\n`;
+}
+
+export function createAgentReplayFixtureDownload(): AgentReplayFixtureDownload {
+  const fixture = buildAgentReplayFixtureExport();
+  return {
+    fileName: `${APP_ID}-agent-replay.fixture.json`,
+    mimeType: AGENT_REPLAY_FIXTURE_MIME_TYPE,
+    text: serializeAgentReplayFixture(fixture),
+    fixture,
+  };
+}