create-windy 0.5.2 → 0.6.1

package/template/docs/platform/vision-ai-runtime.md

@@ -1,6 +1,6 @@
 # Vision AI Runtime
 
-更新时间：2026-07-27。
+更新时间：2026-08-06。
 
 Windy 的首个 Vision 切片在现有 Agent canonical Run 上增加受治理的图片 Artifact 输入，
 用于图片内容理解和结构化视觉提取。它不新增由业务选择模型的 `vision` kind：
@@ -21,6 +21,42 @@ Windy 的首个 Vision 切片在现有 Agent canonical Run 上增加受治理的
 - 每次 Provider attempt 都要求 `artifact-content` allowlist、执行字段 DLP，并记录
   Deployment、Operation、Run、attempt、分类、发送字节和 allow/redact/reject 决策。
 
+## 页面截图 Intake V2
+
+项目只在 project-owned Registry 中把 `pageId + contextDigest` 映射到已注册的 Vision
+Operation。Windy 不解析业务 DOM、Modal、表单正文或 URL，也不接收项目提供的
+Artifact、Run ID、文件路径或 Provider 信息；未知页面、上下文摘要漂移及未声明
+Operation 一律失败关闭。
+
+新 Operation 可通过 `screenshotContext.contractVersion=1` 和固定
+`contextInputPointer` 显式启用上下文同源证明。Web 对锁定时冻结的结构化 JSON 调用
+`@southwind-ai/shared` 的 `computeScreenshotContextDigestV1` 创建 intake；Run admission 不读取客户端自报的
+“已验证”字段，而是从 Manifest pointer 指向的 Run input 取值，用同一套 key 排序、array
+保序、UTF-8、SHA-256 算法重算，再与 token 中的 digest 恒时比较。pointer 缺失、值不是
+结构化 object、格式无效或内容漂移都会消费计划并返回稳定不可用错误；日志与审计不记录
+page、Modal、form 或 input 内容。
+
+```ts
+{
+  screenshotContext: {
+    contractVersion: 1,
+    contextInputPointer: "/uiContext"
+  }
+}
+```
+
+该字段是 additive opt-in：未声明它的 0.6.0 Screenshot Operation 仍保留原有
+Actor/scope/purpose/pin/TTL/一次性 token 边界；声明后的 Operation 才额外强制结构化上下文
+证明。项目迁移时应先让 Web 与 Run input 复用同一个冻结对象，再打开 Manifest binding。
+
+Host 以 60 秒 TTL 持久化 token 哈希、Actor/scope 绑定、Operation、专用 purpose、
+Deployment pin 与 Storage file binding。数据库不保存截图字节、Blob locator、Secret、
+页面正文或表单值。Server/Route 重启后，Host 会按当前 Actor/scope、Feature、Permission
+和 Manifest pin 重新授权，从持久 file binding 重新签发 opaque ArtifactRef；相同图片
+摘要的 upload 重试、相同 Operation/pin 的 reserve 重试及相同 canonical Run ID 的 bind
+重试保持幂等，任一绑定或 Run ID 改变均拒绝。未完成记录按 TTL 有界清理，优雅停机不会
+把仍有效的持久 intake 误取消。
+
 ## Manifest
 
 Vision Operation 必须显式声明输入模态、能力和双重资源上限：
@@ -90,8 +126,17 @@ return {
 AI_ARTIFACT_URL=http://server:9747/api/internal/ai/artifacts
 AI_PROVIDER_CAPABILITIES=text-generation,vision
 AI_PROVIDER_INPUT_MODALITIES=text,image
+AI_PROVIDER_MAX_CONCURRENT_RUNS=1
+AI_PROVIDER_MAX_QUEUE_DEPTH=0
 ```
 
 VLM 可以是 localhost、内网或经 allowlist 授权的 HTTPS Deployment。完全断网环境使用
 本地/内网 OpenAI-compatible VLM；图片回取与 Provider 调用均不需要公网。未配置 VLM
 能力时普通文本 Agent、Document、Speech 和非 AI 业务继续独立运行。
+
+readiness offer 中的 `maxConcurrentRuns` 和 `maxQueueDepth` 与 Agent Server 实际 admission
+使用同一份 Provider 配置。服务最多同时执行前者指定的 Run，并只接受后者指定数量的
+等待 Run；容量满时在创建 durable Run 前返回固定、可重试的 `RUNTIME_UNAVAILABLE`。
+已存在的相同幂等请求不重复占用容量，仍返回原 canonical Run；不同请求指纹继续返回
+`RUN_CONFLICT`。重启恢复也只领取当前容量容许的数量，其余 durable Run 留待下一轮恢复，
+不会绕过执行并发上限。

package/template/package.json

@@ -18,6 +18,7 @@
     "dev:agent": "docker compose --profile agent up --build",
     "dev:document": "PLATFORM_ENABLE_AI=true DOCUMENT_SERVER_URL=http://document-server:8090 docker compose --profile agent --profile document up --build",
     "dev:speech": "PLATFORM_ENABLE_AI=true SPEECH_SERVER_URL=http://speech-server:8091 docker compose --profile agent --profile speech up --build",
+    "speech:pins": "bun run scripts/provision-speech-readiness.ts",
     "dev:embedding": "PLATFORM_ENABLE_AI=true EMBEDDING_SERVER_URL=http://embedding-server:8092 docker compose --profile agent --profile embedding up --build",
     "dev:adk-web": "bun run scripts/dev-adk-web.ts",
     "dev:search": "OPENSEARCH_URL=http://opensearch:9200 docker compose --profile search up --build",
@@ -40,7 +41,9 @@
     "test:db:license-bootstrap": "bun run scripts/license-bootstrap-postgres-regression.ts",
     "test:db:migrations": "bun run scripts/database-migration-regression.ts",
     "test:db:config": "bun run scripts/module-configuration-postgres-regression.ts",
-    "test:db:release": "bun run test:db:migrations && bun run test:db:auth && bun run test:db:data-scope && bun run test:db:organization && bun run test:db:notification && bun run test:db:governance && bun run test:db:legacy-license && bun run test:db:license-bootstrap && bun run test:db:config",
+    "test:db:storage": "bun run scripts/storage-postgres-regression.ts",
+    "test:db:ai-output-artifact": "bun run scripts/ai-output-artifact-postgres-regression.ts",
+    "test:db:release": "bun run test:db:migrations && bun run test:db:auth && bun run test:db:data-scope && bun run test:db:organization && bun run test:db:notification && bun run test:db:governance && bun run test:db:legacy-license && bun run test:db:license-bootstrap && bun run test:db:config && bun run test:db:storage && bun run test:db:ai-output-artifact",
     "test:redis:health": "bun run scripts/redis-health-regression.ts",
     "test:vault:signing": "bun run scripts/vault-signing-regression.ts",
     "test:docker:license-signing": "bun run scripts/license-signing-compose-regression.ts",

package/template/packages/ai-client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/ai-client",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/ai-client/src/agent/client/client.ts

@@ -71,6 +71,9 @@ export class HttpAgentCaller implements AgentCaller {
       ...(options.artifacts?.length
         ? { artifacts: options.artifacts.map(parseAgentArtifactRef) }
         : {}),
+      ...(options.screenshotIntakeToken
+        ? { screenshotIntakeToken: options.screenshotIntakeToken }
+        : {}),
     };
     let response: Response;
     try {

package/template/packages/ai-client/src/agent/client/index.ts

@@ -1,3 +1,4 @@
 export * from "./client.js";
 export * from "./error.js";
+export * from "./screenshot.js";
 export type * from "./types.js";

package/template/packages/ai-client/src/agent/client/screenshot.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+import { HttpScreenshotIntakeClient } from "./screenshot.js";
+
+describe("Screenshot Intake Client", () => {
+  test("只发送页面摘要和原始图片 bytes", async () => {
+    const calls: Array<{ url: URL; init?: RequestInit }> = [];
+    const client = new HttpScreenshotIntakeClient({
+      baseUrl: "https://windy.internal",
+      fetch: async (input, init) => {
+        calls.push({ url: new URL(String(input)), init });
+        return calls.length === 1
+          ? Response.json({
+              contractVersion: 2,
+              intakeToken: "018f4a68-92cb-4d03-8a77-3c1b5e9d4f04",
+              expiresAt: "2030-01-01T00:00:00.000Z",
+            })
+          : new Response(null, { status: 204 });
+      },
+    });
+    const input = {
+      pageId: "case-detail",
+      contextDigest: `sha256:${"a".repeat(64)}`,
+      mediaType: "image/png" as const,
+      byteSize: 3,
+      pixels: 1,
+    };
+    const plan = await client.create(input);
+    await plan.upload(new Uint8Array([1, 2, 3]));
+    await plan.cancel();
+
+    expect(JSON.parse(String(calls[0]?.init?.body))).toEqual(input);
+    expect(calls[1]?.url.pathname).toBe(
+      "/api/agent/screenshots/018f4a68-92cb-4d03-8a77-3c1b5e9d4f04",
+    );
+    expect(calls[1]?.init?.body).toBeInstanceOf(Uint8Array);
+    expect(calls[2]?.url.pathname).toBe(
+      "/api/agent/screenshots/018f4a68-92cb-4d03-8a77-3c1b5e9d4f04/cancel",
+    );
+  });
+});

package/template/packages/ai-client/src/agent/client/screenshot.ts

@@ -0,0 +1,146 @@
+import { AgentClientError, requestError, safeHttpError } from "./error.js";
+import type { AgentFetch } from "./types.js";
+
+export interface ScreenshotIntakeCreateInput {
+  readonly pageId: string;
+  readonly contextDigest: string;
+  readonly mediaType: "image/png";
+  readonly byteSize: number;
+  readonly pixels: number;
+}
+
+export interface ScreenshotIntakePlan {
+  readonly intakeToken: string;
+  readonly expiresAt: string;
+  upload(bytes: Uint8Array, signal?: AbortSignal): Promise<void>;
+  cancel(signal?: AbortSignal): Promise<void>;
+}
+
+export class HttpScreenshotIntakeClient {
+  readonly #baseUrl: URL;
+  readonly #fetch: AgentFetch;
+  readonly #path: string;
+
+  constructor(options: {
+    readonly baseUrl: string | URL;
+    readonly fetch?: AgentFetch;
+    readonly path?: string;
+  }) {
+    this.#baseUrl = new URL(options.baseUrl);
+    this.#fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+    this.#path = options.path ?? "/api/agent/screenshots";
+  }
+
+  async create(
+    input: ScreenshotIntakeCreateInput,
+    signal?: AbortSignal,
+  ): Promise<ScreenshotIntakePlan> {
+    validate(input);
+    let response: Response;
+    try {
+      response = await this.#fetch(this.endpoint(this.#path), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(input),
+        signal,
+      });
+    } catch (error) {
+      throw requestError(error, "创建 Screenshot Intake");
+    }
+    if (!response.ok)
+      throw await safeHttpError(response, "创建 Screenshot Intake");
+    const plan = await response.json();
+    if (!validPlan(plan)) {
+      throw new AgentClientError(
+        "INVALID_RESPONSE",
+        "Screenshot Intake 响应无效",
+        false,
+      );
+    }
+    return Object.freeze({
+      intakeToken: plan.intakeToken,
+      expiresAt: plan.expiresAt,
+      upload: (bytes: Uint8Array, uploadSignal?: AbortSignal) =>
+        this.upload(plan.intakeToken, input, bytes, uploadSignal),
+      cancel: (cancelSignal?: AbortSignal) =>
+        this.cancel(plan.intakeToken, cancelSignal),
+    });
+  }
+
+  private async upload(
+    token: string,
+    input: ScreenshotIntakeCreateInput,
+    bytes: Uint8Array,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    if (bytes.byteLength !== input.byteSize) {
+      throw new AgentClientError(
+        "INVALID_CONFIGURATION",
+        "Screenshot 字节数与创建声明不一致",
+        false,
+      );
+    }
+    let response: Response;
+    try {
+      response = await this.#fetch(
+        this.endpoint(`${this.#path}/${encodeURIComponent(token)}`),
+        {
+          method: "PUT",
+          headers: { "content-type": input.mediaType },
+          body: bytes as unknown as BodyInit,
+          signal,
+        },
+      );
+    } catch (error) {
+      throw requestError(error, "上传 Screenshot");
+    }
+    if (!response.ok) throw await safeHttpError(response, "上传 Screenshot");
+  }
+
+  private async cancel(token: string, signal?: AbortSignal): Promise<void> {
+    let response: Response;
+    try {
+      response = await this.#fetch(
+        this.endpoint(`${this.#path}/${encodeURIComponent(token)}/cancel`),
+        { method: "POST", signal },
+      );
+    } catch (error) {
+      throw requestError(error, "取消 Screenshot Intake");
+    }
+    if (!response.ok)
+      throw await safeHttpError(response, "取消 Screenshot Intake");
+  }
+
+  private endpoint(path: string): URL {
+    return new URL(path, this.#baseUrl);
+  }
+}
+
+function validate(input: ScreenshotIntakeCreateInput): void {
+  if (
+    !input.pageId.trim() ||
+    !/^sha256:[a-f0-9]{64}$/.test(input.contextDigest) ||
+    input.byteSize < 1 ||
+    !Number.isSafeInteger(input.byteSize) ||
+    input.pixels < 1 ||
+    !Number.isSafeInteger(input.pixels)
+  ) {
+    throw new AgentClientError(
+      "INVALID_CONFIGURATION",
+      "Screenshot Intake 创建参数无效",
+      false,
+    );
+  }
+}
+function validPlan(
+  value: unknown,
+): value is { intakeToken: string; expiresAt: string } {
+  return Boolean(
+    value &&
+    typeof value === "object" &&
+    typeof (value as { intakeToken?: unknown }).intakeToken === "string" &&
+    /^[0-9a-f-]{36}$/i.test((value as { intakeToken: string }).intakeToken) &&
+    typeof (value as { expiresAt?: unknown }).expiresAt === "string" &&
+    Number.isFinite(Date.parse((value as { expiresAt: string }).expiresAt)),
+  );
+}

package/template/packages/ai-client/src/agent/client/types.ts

@@ -5,6 +5,8 @@ export interface StartAgentRunOptions {
   idempotencyKey: string;
   /** 仅接受平台签发的 opaque ArtifactRef；客户端不上传 Base64 或任意 URL。 */
   artifacts?: readonly ArtifactRef[];
+  /** Host-issued one-shot screenshot intake; never an Artifact URL or Run owner. */
+  screenshotIntakeToken?: string;
   signal?: AbortSignal;
 }
 

package/template/packages/ai-client/src/agent/contracts/runs.ts

@@ -18,6 +18,7 @@ export interface StartAgentRunRequest<Input> {
   operationKey: string;
   input: Input;
   artifacts?: readonly ArtifactRef[];
+  screenshotIntakeToken?: string;
 }
 
 export interface StartAgentRunResponse {

package/template/packages/ai-client/src/embedding/client.test.ts

@@ -74,4 +74,56 @@ describe("Embedding Client", () => {
       ),
     ).rejects.toBeInstanceOf(EmbeddingClientError);
   });
+
+  test("提交可恢复 Run 并消费结果与取消接口", async () => {
+    const requests: string[] = [];
+    const client = createEmbeddingClient({
+      baseUrl: "https://windy.example",
+      fetch: async (input, init) => {
+        const url = String(input);
+        requests.push(`${init?.method ?? "GET"} ${url}`);
+        if (url.endsWith("/api/embeddings/runs")) {
+          return Response.json(
+            {
+              runId: "embedding_1",
+              eventsUrl: "/api/embeddings/runs/embedding_1/events",
+            },
+            { status: 202 },
+          );
+        }
+        if (url.endsWith("/result")) {
+          return Response.json({
+            output: {
+              batchId: "embed_1",
+              items: [
+                { id: "text-1", vector: [1], inputSha256: "a".repeat(64) },
+              ],
+              metadata: {
+                deploymentAlias: "local",
+                model: "model",
+                version: "v1",
+                dimensions: 1,
+                normalized: true,
+              },
+            },
+          });
+        }
+        return Response.json({ runId: "embedding_1", status: "cancelled" });
+      },
+    });
+
+    const run = await client.submit(
+      { key: "analysis.embedding.text" },
+      { items: [{ id: "text-1", text: "测试" }] },
+      { idempotencyKey: "run-1" },
+    );
+    expect(run.id).toBe("embedding_1");
+    expect((await run.result()).batchId).toBe("embed_1");
+    await run.cancel("无需继续");
+    expect(requests).toEqual([
+      "POST https://windy.example/api/embeddings/runs",
+      "GET https://windy.example/api/embeddings/runs/embedding_1/result",
+      "POST https://windy.example/api/embeddings/runs/embedding_1/cancel",
+    ]);
+  });
 });

package/template/packages/ai-client/src/embedding/client.ts

@@ -5,6 +5,7 @@ import type {
   EmbeddingInput,
 } from "./contracts.js";
 import { EmbeddingClientError, embeddingHttpError } from "./error.js";
+import { HttpEmbeddingRun } from "./run.js";
 import { normalizeInputs, parseBatchResult } from "./validation.js";
 
 export interface EmbeddingClientOptions {
@@ -85,6 +86,74 @@ export class HttpEmbeddingClient implements EmbeddingClient {
     }
     return result;
   }
+
+  async submit<Options>(
+    operation: EmbeddingOperation<Options>,
+    input: {
+      readonly items: readonly EmbeddingInput[];
+      readonly options?: Options;
+    },
+    context: { readonly idempotencyKey: string; readonly signal?: AbortSignal },
+  ) {
+    if (!operation.key.trim() || !context.idempotencyKey.trim()) {
+      throw invalidConfiguration("Embedding Operation 与幂等键不能为空");
+    }
+    const items = normalizeInputs(input.items);
+    const options =
+      input.options === undefined
+        ? undefined
+        : (operation.parseOptions?.(input.options) ?? input.options);
+    let response: Response;
+    try {
+      response = await this.#fetch(
+        new URL("/api/embeddings/runs", this.#baseUrl),
+        {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            "idempotency-key": context.idempotencyKey,
+          },
+          body: JSON.stringify({
+            operationKey: operation.key,
+            items,
+            ...(options === undefined ? {} : { options }),
+          }),
+          signal: context.signal,
+        },
+      );
+    } catch (error) {
+      throw new EmbeddingClientError(
+        context.signal?.aborted ? "RUN_CANCELLED" : "RUNTIME_UNAVAILABLE",
+        context.signal?.aborted
+          ? "Embedding 请求已取消"
+          : "Embedding Runtime 暂不可用",
+        !context.signal?.aborted,
+        undefined,
+        { cause: error },
+      );
+    }
+    if (!response.ok)
+      throw await embeddingHttpError(response, "Embedding 请求失败");
+    const body = (await response.json()) as Record<string, unknown>;
+    if (
+      typeof body.runId !== "string" ||
+      !body.runId ||
+      typeof body.eventsUrl !== "string" ||
+      !body.eventsUrl.startsWith("/")
+    ) {
+      throw new EmbeddingClientError(
+        "INVALID_RESPONSE",
+        "Embedding Run 响应无效",
+        false,
+      );
+    }
+    return new HttpEmbeddingRun({
+      fetch: this.#fetch,
+      baseUrl: this.#baseUrl,
+      runId: body.runId,
+      eventsUrl: body.eventsUrl,
+    });
+  }
 }
 
 export function createEmbeddingClient(options: EmbeddingClientOptions) {

package/template/packages/ai-client/src/embedding/contracts.ts

@@ -34,6 +34,45 @@ export interface EmbeddingBatchResult {
   readonly metadata: EmbeddingMetadata;
 }
 
+export type EmbeddingRunStatus =
+  | "accepted"
+  | "running"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+export type EmbeddingEvent =
+  | {
+      readonly type: "run.started";
+      readonly runId: string;
+      readonly sequence: number;
+    }
+  | {
+      readonly type: "run.completed" | "run.cancelled";
+      readonly runId: string;
+      readonly sequence: number;
+    }
+  | {
+      readonly type: "run.failed";
+      readonly runId: string;
+      readonly sequence: number;
+      readonly error: EmbeddingErrorPayload;
+    };
+
+export interface EmbeddingErrorPayload {
+  readonly code: string;
+  readonly message: string;
+  readonly requestId: string;
+  readonly retryable: boolean;
+}
+
+export interface EmbeddingRun {
+  readonly id: string;
+  readonly events: AsyncIterable<EmbeddingEvent>;
+  result(): Promise<EmbeddingBatchResult>;
+  cancel(reason?: string): Promise<void>;
+}
+
 export interface EmbeddingClient {
   embed<Options>(
     operation: EmbeddingOperation<Options>,
@@ -43,4 +82,12 @@ export interface EmbeddingClient {
     },
     context: { readonly idempotencyKey: string; readonly signal?: AbortSignal },
   ): Promise<EmbeddingBatchResult>;
+  submit<Options>(
+    operation: EmbeddingOperation<Options>,
+    input: {
+      readonly items: readonly EmbeddingInput[];
+      readonly options?: Options;
+    },
+    context: { readonly idempotencyKey: string; readonly signal?: AbortSignal },
+  ): Promise<EmbeddingRun>;
 }

package/template/packages/ai-client/src/embedding/index.ts

@@ -1,3 +1,4 @@
 export * from "./client.js";
 export * from "./contracts.js";
 export * from "./error.js";
+export * from "./run.js";

package/template/packages/ai-client/src/embedding/run.ts

@@ -0,0 +1,130 @@
+import type {
+  EmbeddingBatchResult,
+  EmbeddingEvent,
+  EmbeddingFetch,
+  EmbeddingRun,
+} from "./contracts.js";
+import { EmbeddingClientError, embeddingHttpError } from "./error.js";
+import { parseBatchResult } from "./validation.js";
+
+export interface HttpEmbeddingRunInput {
+  readonly fetch: EmbeddingFetch;
+  readonly baseUrl: URL;
+  readonly runId: string;
+  readonly eventsUrl: string;
+}
+
+export class HttpEmbeddingRun implements EmbeddingRun {
+  readonly id: string;
+
+  constructor(private readonly input: HttpEmbeddingRunInput) {
+    this.id = input.runId;
+  }
+
+  get events(): AsyncIterable<EmbeddingEvent> {
+    return readEvents(this.input);
+  }
+
+  async result(): Promise<EmbeddingBatchResult> {
+    const response = await this.input.fetch(
+      new URL(`/api/embeddings/runs/${this.id}/result`, this.input.baseUrl),
+    );
+    if (!response.ok)
+      throw await embeddingHttpError(response, "Embedding 结果不可用");
+    const body = record(await response.json());
+    return parseBatchResult(body.output);
+  }
+
+  async cancel(reason?: string): Promise<void> {
+    const response = await this.input.fetch(
+      new URL(`/api/embeddings/runs/${this.id}/cancel`, this.input.baseUrl),
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(reason?.trim() ? { reason } : {}),
+      },
+    );
+    if (!response.ok)
+      throw await embeddingHttpError(response, "Embedding 取消失败");
+  }
+}
+
+async function* readEvents(
+  input: HttpEmbeddingRunInput,
+): AsyncIterable<EmbeddingEvent> {
+  const response = await input.fetch(new URL(input.eventsUrl, input.baseUrl), {
+    headers: { accept: "text/event-stream" },
+  });
+  if (!response.ok)
+    throw await embeddingHttpError(response, "Embedding 事件流不可用");
+  if (!response.body) throw invalid("Embedding Runtime 未返回事件流");
+  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
+  let pending = "";
+  while (true) {
+    const { done, value } = await reader.read();
+    pending += value ?? "";
+    const messages = pending.split("\n\n");
+    pending = messages.pop() ?? "";
+    for (const message of messages) {
+      const data = message
+        .split("\n")
+        .find((line) => line.startsWith("data:"))
+        ?.slice(5)
+        .trim();
+      if (!data) continue;
+      yield parseEvent(JSON.parse(data) as unknown);
+    }
+    if (done) return;
+  }
+}
+
+function parseEvent(value: unknown): EmbeddingEvent {
+  const item = record(value);
+  if (
+    typeof item.type !== "string" ||
+    typeof item.runId !== "string" ||
+    !Number.isSafeInteger(item.sequence) ||
+    Number(item.sequence) < 1
+  ) {
+    throw invalid("Embedding 事件字段无效");
+  }
+  if (["run.started", "run.completed", "run.cancelled"].includes(item.type)) {
+    return {
+      type: item.type as "run.started" | "run.completed" | "run.cancelled",
+      runId: item.runId,
+      sequence: Number(item.sequence),
+    };
+  }
+  if (item.type === "run.failed") {
+    const error = record(item.error);
+    if (
+      typeof error.code !== "string" ||
+      typeof error.message !== "string" ||
+      typeof error.requestId !== "string" ||
+      typeof error.retryable !== "boolean"
+    )
+      throw invalid("Embedding 失败事件无效");
+    return {
+      type: "run.failed",
+      runId: item.runId,
+      sequence: Number(item.sequence),
+      error: {
+        code: error.code,
+        message: error.message,
+        requestId: error.requestId,
+        retryable: error.retryable,
+      },
+    };
+  }
+  throw invalid("Embedding 事件类型无效");
+}
+
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw invalid("Embedding 响应字段无效");
+  return value as Record<string, unknown>;
+}
+
+function invalid(message: string) {
+  return new EmbeddingClientError("INVALID_RESPONSE", message, false);
+}