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

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

@@ -0,0 +1,661 @@
+import {
+  createSeedAppAgentStreamEvent,
+  type SeedAppAgentRunResult,
+  type SeedAppAgentStreamEvent,
+  type SeedAppBridgeDiagnostics,
+  type SeedAppClient,
+  type SeedAppError,
+  type SeedAppGrantResolution,
+} from "@seed-app-studio/sdk";
+
+export type StoryState = "idle" | "running" | "success" | "blocked" | "failed";
+export type StoryRuntimeKind = "pending" | "live" | "mock" | "policy-block" | "runtime-error";
+
+export type StoryResult = {
+  state: StoryState;
+  runtimeKind?: StoryRuntimeKind;
+  payload?: unknown;
+  error?: string;
+};
+
+export type CapabilityStory = {
+  id: string;
+  title: string;
+  capability: string;
+  intent: string;
+  intentZh: string;
+  codeExample: string;
+  run(client: SeedAppClient): Promise<unknown>;
+};
+
+export type AgentRunAndWatchStoryPayload = {
+  runtimeKind: "live" | "mock";
+  run: SeedAppAgentRunResult;
+  events: SeedAppAgentStreamEvent[];
+  fallbackReason?: string;
+};
+
+export type ConsoleBridgeScenarioMessage = {
+  level: "log" | "info" | "warn" | "error" | "debug";
+  marker: string;
+  payload: {
+    sequence: number;
+    area: string;
+    retryable?: boolean;
+    traceId?: string;
+  };
+};
+
+export type ConsoleBridgeScenarioPayload = {
+  runtimeKind: "live";
+  expectedOrder: string[];
+  emitted: readonly ConsoleBridgeScenarioMessage[];
+};
+
+export type UnsupportedCapabilityProbe =
+  | {
+      method: "seed.calendar.read";
+      ok: true;
+      result: unknown;
+    }
+  | {
+      method: "seed.calendar.read";
+      ok: false;
+      error: {
+        code: string;
+        message: string;
+        requestId?: string;
+        retryable?: boolean;
+      };
+    };
+
+export type BridgeDiagnosticsStoryPayload = {
+  runtimeKind: "live" | "mock";
+  diagnostics: SeedAppBridgeDiagnostics;
+  unsupportedProbe: UnsupportedCapabilityProbe;
+  fallbackReason?: string;
+};
+
+export type BrainBundlePreviewStoryPayload = {
+  runtimeKind: "live" | "mock";
+  response: unknown;
+  fallbackReason?: string;
+};
+
+export const APP_ID = "seed.react-spa-stories";
+
+export const GRANT_PRECEDENCE_ORDER = ["host", "tenant", "user", "manifest", "default"] as const;
+
+export const CAPABILITY_GRANT_PRECEDENCE_FIXTURE: SeedAppGrantResolution[] = [
+  { capability: "workspace.write", policy: "disabled", source: "host" },
+  { capability: "mcp.callTool", policy: "disabled", source: "tenant" },
+  { capability: "agent.run", policy: "enabled", source: "user" },
+  { capability: "memory.search", policy: "enabled", source: "manifest" },
+  { capability: "agent.stream", policy: "ask", source: "default" },
+];
+
+export const CONSOLE_BRIDGE_SCENARIO_MESSAGES: readonly ConsoleBridgeScenarioMessage[] = [
+  { level: "log", marker: "console-order-1", payload: { sequence: 1, area: "story-start" } },
+  { level: "info", marker: "console-order-2", payload: { sequence: 2, area: "host-event" } },
+  { level: "warn", marker: "console-order-3", payload: { sequence: 3, area: "approval-required" } },
+  {
+    level: "error",
+    marker: "console-order-4",
+    payload: { sequence: 4, area: "runtime-error", retryable: true },
+  },
+  {
+    level: "debug",
+    marker: "console-order-5",
+    payload: { sequence: 5, area: "diagnostics", traceId: "console-story" },
+  },
+];
+
+export const AGENT_STREAM_REPLAY_EVENTS: SeedAppAgentStreamEvent[] = [
+  createSeedAppAgentStreamEvent({
+    type: "agent.run.started",
+    payload: {
+      runId: "replay-run",
+      sessionId: "replay-session",
+      inputSummary: "Review renewal risk",
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.message.delta",
+    payload: {
+      runId: "replay-run",
+      sessionId: "replay-session",
+      messageId: "msg-1",
+      text: "I will inspect CRM context.",
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.thought.delta",
+    payload: {
+      runId: "replay-run",
+      sessionId: "replay-session",
+      messageId: "thought-1",
+      text: "Need account status and next action.",
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.tool.started",
+    payload: {
+      runId: "replay-run",
+      sessionId: "replay-session",
+      toolCallId: "tool-1",
+      title: "Search account memory",
+      kind: "read",
+      status: "pending",
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.tool.updated",
+    payload: {
+      runId: "replay-run",
+      sessionId: "replay-session",
+      toolCallId: "tool-1",
+      status: "completed",
+      redactedOutput: { count: 3 },
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.permission.required",
+    payload: {
+      runId: "replay-run",
+      sessionId: "replay-session",
+      requestId: "approval-1",
+      toolCallId: "tool-2",
+      description: "Write a follow-up note to workspace.",
+      options: [{ id: "allow" }, { id: "deny" }],
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.elicitation.required",
+    payload: {
+      runId: "replay-run",
+      sessionId: "replay-session",
+      requestId: "elicitation-1",
+      message: "Which renewal segment should the assistant prioritize?",
+      choices: ["enterprise", "mid-market"],
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.subagent.anchor",
+    payload: {
+      runId: "replay-run",
+      sessionId: "replay-session",
+      parentToolCallId: "tool-3",
+      childSessionId: "child-session-1",
+      title: "Pricing analyst",
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.subagent.message.delta",
+    payload: {
+      runId: "replay-run",
+      sessionId: "replay-session",
+      childSessionId: "child-session-1",
+      childEntryIndex: 1,
+      text: "Discount guardrail is 8%.",
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.config.updated",
+    payload: {
+      runId: "replay-run",
+      sessionId: "replay-session",
+      options: [{ id: "provider_custom_signal", value: "redacted" }],
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.turn.completed",
+    payload: { runId: "replay-run", sessionId: "replay-session", stopReason: "end_turn" },
+  }),
+];
+
+export const AGENT_RUN_AND_WATCH_MOCK_EVENTS: SeedAppAgentStreamEvent[] = [
+  createSeedAppAgentStreamEvent({
+    type: "agent.run.started",
+    payload: {
+      runId: "mock-watch-run",
+      sessionId: "mock-watch-session",
+      inputSummary: "Draft renewal plan",
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.message.delta",
+    payload: {
+      runId: "mock-watch-run",
+      sessionId: "mock-watch-session",
+      messageId: "mock-msg-1",
+      text: "I found two renewal risks and one expansion signal.",
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.tool.started",
+    payload: {
+      runId: "mock-watch-run",
+      sessionId: "mock-watch-session",
+      toolCallId: "mock-tool-1",
+      title: "Read account memory",
+      kind: "read",
+      status: "pending",
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.tool.updated",
+    payload: {
+      runId: "mock-watch-run",
+      sessionId: "mock-watch-session",
+      toolCallId: "mock-tool-1",
+      status: "completed",
+      redactedOutput: { memories: 2 },
+    },
+  }),
+  createSeedAppAgentStreamEvent({
+    type: "agent.run.completed",
+    payload: {
+      runId: "mock-watch-run",
+      sessionId: "mock-watch-session",
+      outputSummary: "Prepared a renewal plan with risk, next action, and owner.",
+    },
+  }),
+];
+
+async function runAgentRunAndWatchStory(
+  client: SeedAppClient,
+): Promise<AgentRunAndWatchStoryPayload> {
+  const events: SeedAppAgentStreamEvent[] = [];
+  try {
+    const run = await client.agent.runAndWatch(
+      {
+        assistantId: "sales-copilot",
+        input: "Watch a renewal-risk assistant run until the terminal stream event.",
+        metadata: { story: "agent-run-watch" },
+      },
+      { onEvent: (event) => events.push(event) },
+      { requestTimeoutMs: 8000, streamTimeoutMs: 8000 },
+    );
+    return { runtimeKind: "live", run, events };
+  } catch (error) {
+    if (!isSeedAppError(error) || error.code !== "handshake_timeout") throw error;
+    return {
+      runtimeKind: "mock",
+      run: { runId: "mock-watch-run", status: "completed", output: { previewOnly: true } },
+      events: AGENT_RUN_AND_WATCH_MOCK_EVENTS,
+      fallbackReason: error.message,
+    };
+  }
+}
+
+async function runConsoleBridgeScenario(): Promise<ConsoleBridgeScenarioPayload> {
+  CONSOLE_BRIDGE_SCENARIO_MESSAGES.forEach((entry) => {
+    console[entry.level](`[seed-app-console-scenario] ${entry.marker}`, entry.payload);
+  });
+  return {
+    runtimeKind: "live",
+    expectedOrder: CONSOLE_BRIDGE_SCENARIO_MESSAGES.map((entry) => entry.marker),
+    emitted: CONSOLE_BRIDGE_SCENARIO_MESSAGES,
+  };
+}
+
+async function runBridgeDiagnosticsStory(
+  client: SeedAppClient,
+): Promise<BridgeDiagnosticsStoryPayload> {
+  try {
+    const diagnostics = await client.diagnostics.snapshot(
+      { includeMethods: true, includeTransports: true },
+      { timeoutMs: 2500 },
+    );
+    return {
+      runtimeKind: "live",
+      diagnostics,
+      unsupportedProbe: await probeUnsupportedCapability(client),
+    };
+  } catch (error) {
+    if (!isSeedAppError(error)) throw error;
+    return {
+      runtimeKind: "mock",
+      diagnostics: createFallbackBridgeDiagnostics(error.message),
+      unsupportedProbe: createUnsupportedCapabilityError(
+        "seed.calendar.read",
+        "capability_denied",
+        error.requestId,
+      ),
+      fallbackReason: error.message,
+    };
+  }
+}
+
+async function runBrainBundlePreviewStory(
+  client: SeedAppClient,
+): Promise<BrainBundlePreviewStoryPayload> {
+  try {
+    return {
+      runtimeKind: "live",
+      response: await client.brainBundle.previewSummaries(
+        {
+          conversationId: `appstudio:${APP_ID}`,
+          format: "rollup",
+          sort: "updatedAt_desc",
+        },
+        { timeoutMs: 2500 },
+      ),
+    };
+  } catch (error) {
+    if (!isSeedAppError(error)) throw error;
+    return {
+      runtimeKind: "mock",
+      response: {
+        schemaVersion: "brain-bundle-preview-summary-rollup.v0",
+        conversationId: `appstudio:${APP_ID}`,
+        total: 0,
+        byStatus: {},
+        byState: {},
+        blockedReasons: {},
+        rawBlobIncluded: false,
+      },
+      fallbackReason: error.message,
+    };
+  }
+}
+
+async function probeUnsupportedCapability(
+  client: SeedAppClient,
+): Promise<UnsupportedCapabilityProbe> {
+  try {
+    const result = await client.request(
+      "seed.calendar.read",
+      { range: "today" },
+      { timeoutMs: 2500 },
+    );
+    return { method: "seed.calendar.read", ok: true, result };
+  } catch (error) {
+    if (!isSeedAppError(error)) {
+      return createUnsupportedCapabilityError("seed.calendar.read", "host_unavailable");
+    }
+    return createUnsupportedCapabilityError(
+      "seed.calendar.read",
+      error.code,
+      error.requestId,
+      error.retryable,
+    );
+  }
+}
+
+function createFallbackBridgeDiagnostics(reason: string): SeedAppBridgeDiagnostics {
+  return {
+    appId: APP_ID,
+    hostVersion: "fallback-demo",
+    runtime: "mock",
+    transport: "mock",
+    grants: { total: 0, enabled: 0, ask: 0, disabled: 0 },
+    methods: [
+      { method: "seed.handshake", support: "mock" },
+      { method: "seed.capabilities.query", support: "mock" },
+      { method: "seed.bridge.diagnostics", capability: "bridge.diagnostics", support: "mock" },
+    ],
+    transports: [{ id: "mock", supportsStreaming: true, supportsBroadcast: true }],
+    unsupportedMethods: ["seed.calendar.read"],
+    checks: [
+      {
+        id: "diagnostics-fallback",
+        status: "warning",
+        message: reason,
+      },
+      {
+        id: "unsupported-method",
+        status: "blocked",
+        message: "seed.calendar.read is intentionally outside this app manifest.",
+      },
+    ],
+  };
+}
+
+function createUnsupportedCapabilityError(
+  method: "seed.calendar.read",
+  code: string,
+  requestId: string = method,
+  retryable = false,
+): UnsupportedCapabilityProbe {
+  return {
+    method,
+    ok: false,
+    error: {
+      code,
+      message: `${method} is not declared by this playground manifest.`,
+      requestId,
+      retryable,
+    },
+  };
+}
+
+export const STORIES: CapabilityStory[] = [
+  {
+    id: "handshake",
+    title: "Host handshake",
+    capability: "seed.handshake",
+    intent: "Confirms that the sandbox can talk to the SEED host.",
+    intentZh: "确认沙箱 iframe 能够与 SEED 宿主建立握手，并拿到基础授权信息。",
+    codeExample: `const handshake = await client.handshake({
+  appId: APP_ID,
+  sdkVersion: '0.1.0',
+});`,
+    run: (client) => client.handshake({ appId: APP_ID, sdkVersion: "0.1.0" }),
+  },
+  {
+    id: "capabilities",
+    title: "Capability snapshot",
+    capability: "seed.capabilities.query",
+    intent: "Shows enabled, approval-required, and disabled grants declared by the manifest.",
+    intentZh: "展示 manifest 中声明的已启用、需要审批和已禁用能力授权快照。",
+    codeExample: `const grants = await client.capabilities.query();`,
+    run: (client) => client.capabilities.query(),
+  },
+  {
+    id: "grant-precedence",
+    title: "Grant precedence fixture",
+    capability: "seed.capabilities.query",
+    intent:
+      "Shows the host > tenant > user > manifest > default policy order with deterministic sample grants.",
+    intentZh: "用固定样例展示宿主、租户、用户、manifest、默认策略之间的授权优先级。",
+    codeExample: `const liveGrants = await client.capabilities.query();
+
+return {
+  liveGrants,
+  precedence: ['host', 'tenant', 'user', 'manifest', 'default'],
+  fixture: CAPABILITY_GRANT_PRECEDENCE_FIXTURE,
+};`,
+    run: async (client) => ({
+      liveGrants: await client.capabilities.query(),
+      precedence: GRANT_PRECEDENCE_ORDER,
+      fixture: CAPABILITY_GRANT_PRECEDENCE_FIXTURE,
+    }),
+  },
+  {
+    id: "console-bridge",
+    title: "Console bridge scenario",
+    capability: "host.console",
+    intent:
+      "Emits ordered console levels so App Studio can verify forwarding, serialization, and diagnostics.",
+    intentZh: "按顺序触发 log、info、warn、error、debug，验证 App Studio 的控制台转发和序列化。",
+    codeExample: `CONSOLE_BRIDGE_SCENARIO_MESSAGES.forEach((entry) => {
+  console[entry.level](
+    \`[seed-app-console-scenario] \${entry.marker}\`,
+    entry.payload
+  );
+});`,
+    run: runConsoleBridgeScenario,
+  },
+  {
+    id: "bridge-diagnostics",
+    title: "Bridge diagnostics",
+    capability: "bridge.diagnostics",
+    intent:
+      "Reports runtime transport health and probes an unsupported capability through the same SDK path.",
+    intentZh: "报告运行时传输状态，并通过同一条 SDK 路径探测一个未声明能力。",
+    codeExample: `const diagnostics = await client.diagnostics.snapshot(
+  { includeMethods: true, includeTransports: true },
+  { timeoutMs: 2500 }
+);
+
+const unsupportedProbe = await client.request(
+  'seed.calendar.read',
+  { range: 'today' },
+  { timeoutMs: 2500 }
+);`,
+    run: runBridgeDiagnosticsStory,
+  },
+  {
+    id: "agent-run",
+    title: "Agent run",
+    capability: "agent.run",
+    intent: "Starts a vertical assistant task through the SDK.",
+    intentZh: "通过 SDK 启动一个垂直场景助手任务，用来验证 agent.run 能力。",
+    codeExample: `const result = await client.agent.run({
+  assistantId: 'sales-copilot',
+  input: 'Draft a three-bullet account plan for a renewal risk.',
+  metadata: { story: 'agent-run' },
+});`,
+    run: (client) =>
+      client.agent.run({
+        assistantId: "sales-copilot",
+        input: "Draft a three-bullet account plan for a renewal risk.",
+        metadata: { story: "agent-run" },
+      }),
+  },
+  {
+    id: "agent-run-watch",
+    title: "Agent run and watch",
+    capability: "agent.run",
+    intent:
+      "Starts a watched agent run and falls back to a deterministic mock stream when no terminal stream arrives.",
+    intentZh: "启动可监听的 Agent 运行；如果没有收到终态流事件，则回退到确定性的模拟流。",
+    codeExample: `const events: SeedAppAgentStreamEvent[] = [];
+
+const run = await client.agent.runAndWatch(
+  {
+    assistantId: 'sales-copilot',
+    input: 'Watch a renewal-risk assistant run until the terminal stream event.',
+    metadata: { story: 'agent-run-watch' },
+  },
+  { onEvent: (event) => events.push(event) },
+  { requestTimeoutMs: 8000, streamTimeoutMs: 8000 }
+);`,
+    run: runAgentRunAndWatchStory,
+  },
+  {
+    id: "agent-stream-replay",
+    title: "Agent stream replay",
+    capability: "agent.stream",
+    intent:
+      "Replays the Bridge-projected lifecycle: message, thought, tool, permission, elicitation, subagent, backup, and turn barrier.",
+    intentZh:
+      "回放由 Bridge 投影的生命周期事件，包括消息、思考、工具、授权、追问、子 Agent、备份和回合结束。",
+    codeExample: `return {
+  runId: 'replay-run',
+  source: 'local-fixture',
+  events: AGENT_STREAM_REPLAY_EVENTS,
+};`,
+    run: async () => ({
+      runId: "replay-run",
+      source: "local-fixture",
+      events: AGENT_STREAM_REPLAY_EVENTS,
+    }),
+  },
+  {
+    id: "memory-search",
+    title: "Memory search",
+    capability: "memory.search",
+    intent: "Queries host memory without directly reading local files.",
+    intentZh: "通过宿主记忆接口查询上下文，不直接读取本地文件。",
+    codeExample: `const memories = await client.memory.search({
+  namespace: 'demo.customer',
+  query: 'renewal risk and last contact',
+  limit: 3,
+});`,
+    run: (client) =>
+      client.memory.search({
+        namespace: "demo.customer",
+        query: "renewal risk and last contact",
+        limit: 3,
+      }),
+  },
+  {
+    id: "brain-bundle-preview",
+    title: "Brain bundle preview",
+    capability: "brain-bundle.preview-summaries",
+    intent:
+      "Reads metadata-only business brain bundle summaries through the host without exposing raw bundle blobs.",
+    intentZh: "通过宿主读取 metadata-only 的企业大脑 bundle 摘要，不暴露原始 bundle blob。",
+    codeExample: `const preview = await client.brainBundle.previewSummaries({
+  conversationId: \`appstudio:\${APP_ID}\`,
+  format: 'rollup',
+  sort: 'updatedAt_desc',
+});`,
+    run: runBrainBundlePreviewStory,
+  },
+  {
+    id: "mcp-list-tools",
+    title: "MCP list tools",
+    capability: "mcp.listTools",
+    intent: "Lists brokered host tools without exposing server secrets.",
+    intentZh: "列出由宿主代理的 MCP 工具，同时避免暴露服务端密钥和内部配置。",
+    codeExample: `const tools = await client.mcp.listTools({
+  server: 'seed.knowledgebase',
+});`,
+    run: (client) => client.mcp.listTools({ server: "seed.knowledgebase" }),
+  },
+  {
+    id: "mcp-call-tool",
+    title: "MCP call tool",
+    capability: "mcp.callTool",
+    intent: "Calls a brokered read-only MCP tool and exercises the approval path.",
+    intentZh: "调用一个只读 MCP 工具，并验证需要用户授权的 ask 流程。",
+    codeExample: `const result = await client.mcp.callTool({
+  server: 'seed.knowledgebase',
+  toolName: 'kb_search',
+  input: {
+    query: 'renewal risk and last contact',
+    limit: 3,
+  },
+});`,
+    run: (client) =>
+      client.mcp.callTool({
+        server: "seed.knowledgebase",
+        toolName: "kb_search",
+        input: { query: "renewal risk and last contact", limit: 3 },
+      }),
+  },
+  {
+    id: "workspace-denied",
+    title: "Denied workspace write",
+    capability: "workspace.write",
+    intent: "Demonstrates a blocked capability that must not crash the SPA.",
+    intentZh: "演示被策略拒绝的 workspace.write 能力，确认 SPA 不会因此崩溃。",
+    codeExample: `await client.request('seed.workspace.write', {
+  path: 'notes/customer-plan.md',
+  content: 'This should be denied by default.',
+});`,
+    run: (client) =>
+      client.request("seed.workspace.write", {
+        path: "notes/customer-plan.md",
+        content: "This should be denied by default.",
+      }),
+  },
+  {
+    id: "unknown-capability",
+    title: "Undeclared capability",
+    capability: "calendar.read",
+    intent: "Shows how the host rejects a capability missing from manifest.",
+    intentZh: "展示宿主如何拒绝 manifest 中未声明的能力调用。",
+    codeExample: `await client.request('seed.calendar.read', {
+  range: 'today',
+});`,
+    run: (client) => client.request("seed.calendar.read", { range: "today" }),
+  },
+];
+
+function isSeedAppError(value: unknown): value is SeedAppError {
+  return typeof value === "object" && value !== null && "code" in value && "message" in value;
+}