create-windy 0.3.2 → 0.3.5

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

@@ -1,16 +1,22 @@
 import type {
   AgentOperation,
   StartAgentRunRequest,
+  TerminalAgentEvent,
+} from "../contracts/index.js";
+import {
+  parseAttachAgentRunResponse,
+  parseStartAgentRunResponse,
 } from "../contracts/index.js";
-import { parseStartAgentRunResponse } from "../contracts/index.js";
 import { AgentClientError, requestError, safeHttpError } from "./error.js";
 import { safeJson } from "./http.js";
 import { HttpAgentRun } from "./run.js";
+import { parseAgentArtifactRef } from "./artifact.js";
 import type {
   AgentCaller,
   AgentClientOptions,
   AgentFetch,
   AgentRun,
+  AttachAgentRunOptions,
   StartAgentRunOptions,
 } from "./types.js";
 
@@ -62,6 +68,9 @@ export class HttpAgentCaller implements AgentCaller {
     const request: StartAgentRunRequest<Input> = {
       operationKey: operation.key,
       input,
+      ...(options.artifacts?.length
+        ? { artifacts: options.artifacts.map(parseAgentArtifactRef) }
+        : {}),
     };
     let response: Response;
     try {
@@ -89,18 +98,94 @@ export class HttpAgentCaller implements AgentCaller {
     if (!response.ok) throw await safeHttpError(response, "创建 Agent Run");
 
     const created = parseCreatedRun(await safeJson(response, "创建 Agent Run"));
-    const eventsUrl = this.endpoint(created.eventsUrl);
+    return this.createRun(operation, created.runId, created.eventsUrl, {
+      signal: options.signal,
+    });
+  }
+
+  async attach<Input, Output>(
+    operation: AgentOperation<Input, Output>,
+    runId: string,
+    options: AttachAgentRunOptions = {},
+  ): Promise<AgentRun<Output>> {
+    assertOperationAndRun(operation, runId);
+    const cursor = nonNegativeInteger(options.cursor, 0, "cursor");
+    let response: Response;
+    try {
+      response = await this.fetch(
+        this.endpoint(`${this.runsPath}/${encodeURIComponent(runId)}/attach`),
+        {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ operationKey: operation.key, cursor }),
+          signal: options.signal,
+        },
+      );
+    } catch (error) {
+      if (options.signal?.aborted) {
+        throw new AgentClientError(
+          "CANCELLED",
+          "恢复 Agent Run 已取消",
+          false,
+          runId,
+          { cause: error },
+        );
+      }
+      throw requestError(error, "恢复 Agent Run", runId);
+    }
+    if (!response.ok) {
+      throw await safeHttpError(response, "恢复 Agent Run", runId);
+    }
+    const attached = parseAttachedRun(
+      await safeJson(response, "恢复 Agent Run", runId),
+    );
+    if (attached.runId !== runId) {
+      throw new AgentClientError(
+        "INVALID_RESPONSE",
+        "恢复 Agent Run 响应引用了错误的 Run",
+        false,
+        runId,
+      );
+    }
+    return this.createRun(operation, runId, attached.eventsUrl, {
+      signal: options.signal,
+      initialSequence: cursor,
+      initialTerminal: attached.terminalEvent,
+    });
+  }
+
+  resume<Input, Output>(
+    operation: AgentOperation<Input, Output>,
+    runId: string,
+    options?: AttachAgentRunOptions,
+  ): Promise<AgentRun<Output>> {
+    return this.attach(operation, runId, options);
+  }
+
+  private createRun<Input, Output>(
+    operation: AgentOperation<Input, Output>,
+    runId: string,
+    eventsPath: string,
+    state: {
+      signal?: AbortSignal;
+      initialSequence?: number;
+      initialTerminal?: TerminalAgentEvent;
+    },
+  ): AgentRun<Output> {
+    const operationQuery = `operationKey=${encodeURIComponent(operation.key)}`;
     return new HttpAgentRun<Output>({
-      id: created.runId,
-      eventsUrl,
+      id: runId,
+      eventsUrl: this.endpoint(eventsPath),
       resultUrl: this.endpoint(
-        `${this.runsPath}/${encodeURIComponent(created.runId)}/result`,
+        `${this.runsPath}/${encodeURIComponent(runId)}/result?${operationQuery}`,
       ),
       cancelUrl: this.endpoint(
-        `${this.runsPath}/${encodeURIComponent(created.runId)}/cancel`,
+        `${this.runsPath}/${encodeURIComponent(runId)}/cancel?${operationQuery}`,
       ),
       fetch: this.fetch,
-      signal: options.signal,
+      signal: state.signal,
+      initialSequence: state.initialSequence,
+      initialTerminal: state.initialTerminal,
       maxReconnects: this.maxReconnects,
       reconnectDelayMs: this.reconnectDelayMs,
       wait: this.wait,
@@ -121,6 +206,19 @@ export class HttpAgentCaller implements AgentCaller {
   }
 }
 
+function assertOperationAndRun<Input, Output>(
+  operation: AgentOperation<Input, Output>,
+  runId: string,
+): void {
+  if (!operation.key.trim() || !runId.trim() || runId.length > 160) {
+    throw new AgentClientError(
+      "INVALID_CONFIGURATION",
+      "Agent Operation 或 Run ID 无效",
+      false,
+    );
+  }
+}
+
 function parseCreatedRun(value: unknown) {
   try {
     return parseStartAgentRunResponse(value);
@@ -135,6 +233,20 @@ function parseCreatedRun(value: unknown) {
   }
 }
 
+function parseAttachedRun(value: unknown) {
+  try {
+    return parseAttachAgentRunResponse(value);
+  } catch (error) {
+    throw new AgentClientError(
+      "INVALID_RESPONSE",
+      "恢复 Agent Run 响应格式无效",
+      false,
+      undefined,
+      { cause: error },
+    );
+  }
+}
+
 function validateBaseUrl(value: string | URL): URL {
   const url = new URL(value);
   if (url.protocol !== "http:" && url.protocol !== "https:") {

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

@@ -21,6 +21,8 @@ interface HttpAgentRunOptions<Output> {
   reconnectDelayMs: number;
   wait(milliseconds: number, signal?: AbortSignal): Promise<void>;
   parseOutput(value: unknown): Output;
+  initialSequence?: number;
+  initialTerminal?: TerminalAgentEvent;
 }
 
 type TerminalOutcome =
@@ -47,6 +49,18 @@ export class HttpAgentRun<Output> implements AgentRun<Output> {
     this.terminalOutcome = new Promise((resolve) => {
       this.resolveTerminal = resolve;
     });
+    this.lastSequence = options.initialSequence ?? 0;
+    if (
+      options.initialTerminal &&
+      options.initialTerminal.sequence <= this.lastSequence
+    ) {
+      if (options.initialTerminal.runId !== this.id) {
+        throw this.protocolViolation("恢复的 Agent Run 终态引用了错误的 Run");
+      }
+      this.terminal = options.initialTerminal;
+      this.queue.close();
+      this.resolveTerminal({ terminal: options.initialTerminal });
+    }
 
     if (options.signal?.aborted) {
       void this.cancel("调用方已取消").catch(() => undefined);

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

@@ -1,7 +1,15 @@
 import type { AgentEvent, AgentOperation } from "../contracts/index.js";
+import type { ArtifactRef } from "../../artifact-ref.js";
 
 export interface StartAgentRunOptions {
   idempotencyKey: string;
+  /** 仅接受平台签发的 opaque ArtifactRef；客户端不上传 Base64 或任意 URL。 */
+  artifacts?: readonly ArtifactRef[];
+  signal?: AbortSignal;
+}
+
+export interface AttachAgentRunOptions {
+  cursor?: number;
   signal?: AbortSignal;
 }
 
@@ -18,6 +26,16 @@ export interface AgentCaller {
     input: Input,
     options: StartAgentRunOptions,
   ): Promise<AgentRun<Output>>;
+  attach<Input, Output>(
+    operation: AgentOperation<Input, Output>,
+    runId: string,
+    options?: AttachAgentRunOptions,
+  ): Promise<AgentRun<Output>>;
+  resume<Input, Output>(
+    operation: AgentOperation<Input, Output>,
+    runId: string,
+    options?: AttachAgentRunOptions,
+  ): Promise<AgentRun<Output>>;
 }
 
 export type AgentFetch = (

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

@@ -0,0 +1,53 @@
+import { describe, expect, test } from "bun:test";
+import { createAgentCaller, defineAgentOperation } from "../index.js";
+import { AgentClientError } from "./error.js";
+
+const operation = defineAgentOperation<{ text: string }, unknown>(
+  "evidence.image.inspect",
+  (value) => value,
+);
+
+describe("Agent Vision Client", () => {
+  test("只提交经过校验的 opaque ArtifactRef", async () => {
+    let body: unknown;
+    const caller = createAgentCaller({
+      baseUrl: "https://agent.internal",
+      fetch: async (_input, init) => {
+        body = JSON.parse(String(init?.body));
+        return Response.json({
+          runId: "run-vision",
+          status: "accepted",
+          eventsUrl: "/api/agent/runs/run-vision/events",
+        });
+      },
+    });
+    const artifact = {
+      value: "opaque-artifact",
+      mediaType: "image/png",
+      byteSize: 128,
+      sha256: "a".repeat(64),
+    };
+
+    await caller.start(
+      operation,
+      { text: "分析图片" },
+      { idempotencyKey: "vision-1", artifacts: [artifact] },
+    );
+    expect(body).toEqual({
+      operationKey: "evidence.image.inspect",
+      input: { text: "分析图片" },
+      artifacts: [artifact],
+    });
+
+    await expect(
+      caller.start(
+        operation,
+        { text: "分析图片" },
+        {
+          idempotencyKey: "vision-invalid",
+          artifacts: [{ ...artifact, value: "https://evil.example/a.png" }],
+        },
+      ),
+    ).rejects.toBeInstanceOf(AgentClientError);
+  });
+});

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

@@ -37,6 +37,7 @@ const events: AgentEvent[] = [
     runId: "run-1",
     sequence: 4,
     workItemId: "work-1",
+    toolCallId: "tool-call-1",
   },
   {
     type: "tool.completed",

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

@@ -16,6 +16,10 @@ export interface AgentRunStartedEvent extends AgentEventBase {
   type: "run.started";
 }
 
+export interface AgentRunResumedEvent extends AgentEventBase {
+  type: "run.resumed";
+}
+
 export interface AgentOutputDeltaEvent extends AgentEventBase {
   type: "output.delta";
   text: string;
@@ -30,6 +34,14 @@ export interface AgentToolRequestedEvent extends AgentEventBase {
 export interface AgentApprovalRequiredEvent extends AgentEventBase {
   type: "approval.required";
   workItemId: string;
+  toolCallId: string;
+}
+
+export interface AgentApprovalResolvedEvent extends AgentEventBase {
+  type: "approval.resolved";
+  workItemId: string;
+  toolCallId: string;
+  outcome: "approved" | "rejected" | "cancelled" | "timed-out";
 }
 
 export interface AgentToolCompletedEvent extends AgentEventBase {
@@ -57,9 +69,11 @@ export interface AgentRunCancelledEvent extends AgentEventBase {
 
 export type AgentEvent =
   | AgentRunStartedEvent
+  | AgentRunResumedEvent
   | AgentOutputDeltaEvent
   | AgentToolRequestedEvent
   | AgentApprovalRequiredEvent
+  | AgentApprovalResolvedEvent
   | AgentToolCompletedEvent
   | AgentUsageReportedEvent
   | AgentRunCompletedEvent
@@ -74,9 +88,11 @@ export type TerminalAgentEvent =
 
 const eventTypes: ReadonlySet<string> = new Set<AgentEventType>([
   "run.started",
+  "run.resumed",
   "output.delta",
   "tool.requested",
   "approval.required",
+  "approval.resolved",
   "tool.completed",
   "usage.reported",
   "run.completed",
@@ -98,6 +114,7 @@ export function parseAgentEvent(input: unknown): AgentEvent {
 
   switch (eventType) {
     case "run.started":
+    case "run.resumed":
     case "run.completed":
     case "run.cancelled":
       return { type: eventType, ...base };
@@ -119,7 +136,23 @@ export function parseAgentEvent(input: unknown): AgentEvent {
         type: eventType,
         ...base,
         workItemId: stringAt(record, "workItemId", "event"),
+        toolCallId: stringAt(record, "toolCallId", "event"),
+      };
+    case "approval.resolved": {
+      const outcome = stringAt(record, "outcome", "event");
+      if (
+        !["approved", "rejected", "cancelled", "timed-out"].includes(outcome)
+      ) {
+        throw new AgentContractParseError("event.outcome", "审批结果无效");
+      }
+      return {
+        type: eventType,
+        ...base,
+        workItemId: stringAt(record, "workItemId", "event"),
+        toolCallId: stringAt(record, "toolCallId", "event"),
+        outcome: outcome as AgentApprovalResolvedEvent["outcome"],
       };
+    }
     case "tool.completed":
       return {
         type: eventType,

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

@@ -1,4 +1,10 @@
 import { AgentContractParseError, recordAt, stringAt } from "./validation.js";
+import type { ArtifactRef } from "../../artifact-ref.js";
+import {
+  isTerminalAgentEvent,
+  parseAgentEvent,
+  type TerminalAgentEvent,
+} from "./events.js";
 
 export type AgentRunStatus =
   | "accepted"
@@ -11,6 +17,7 @@ export type AgentRunStatus =
 export interface StartAgentRunRequest<Input> {
   operationKey: string;
   input: Input;
+  artifacts?: readonly ArtifactRef[];
 }
 
 export interface StartAgentRunResponse {
@@ -19,6 +26,14 @@ export interface StartAgentRunResponse {
   eventsUrl: string;
 }
 
+export interface AttachAgentRunResponse {
+  runId: string;
+  status: AgentRunStatus;
+  lastSequence: number;
+  eventsUrl: string;
+  terminalEvent?: TerminalAgentEvent;
+}
+
 const terminalStatuses: ReadonlySet<AgentRunStatus> = new Set([
   "completed",
   "failed",
@@ -51,6 +66,62 @@ export function parseStartAgentRunResponse(
   };
 }
 
+export function parseAttachAgentRunResponse(
+  input: unknown,
+): AttachAgentRunResponse {
+  const record = recordAt(input, "attachAgentRunResponse");
+  const status = stringAt(record, "status", "attachAgentRunResponse");
+  if (!runStatuses.has(status)) {
+    throw new AgentContractParseError(
+      "attachAgentRunResponse.status",
+      "Run 状态无效",
+    );
+  }
+  if (
+    !Number.isSafeInteger(record.lastSequence) ||
+    Number(record.lastSequence) < 0
+  ) {
+    throw new AgentContractParseError(
+      "attachAgentRunResponse.lastSequence",
+      "事件序列无效",
+    );
+  }
+  const runId = stringAt(record, "runId", "attachAgentRunResponse");
+  const terminalEvent =
+    record.terminalEvent === undefined
+      ? undefined
+      : parseAgentEvent(record.terminalEvent);
+  if (
+    terminalEvent &&
+    (!isTerminalAgentEvent(terminalEvent) ||
+      terminalEvent.runId !== runId ||
+      terminalEvent.sequence !== Number(record.lastSequence))
+  ) {
+    throw new AgentContractParseError(
+      "attachAgentRunResponse.terminalEvent",
+      "终态事件无效",
+    );
+  }
+  if (
+    isTerminalAgentRunStatus(status as AgentRunStatus) !==
+    Boolean(terminalEvent)
+  ) {
+    throw new AgentContractParseError(
+      "attachAgentRunResponse.terminalEvent",
+      "终态与事件不一致",
+    );
+  }
+  return {
+    runId,
+    status: status as AgentRunStatus,
+    lastSequence: Number(record.lastSequence),
+    eventsUrl: stringAt(record, "eventsUrl", "attachAgentRunResponse"),
+    ...(terminalEvent && isTerminalAgentEvent(terminalEvent)
+      ? { terminalEvent }
+      : {}),
+  };
+}
+
 export function isTerminalAgentRunStatus(
   status: AgentRunStatus,
 ): status is Extract<AgentRunStatus, "completed" | "failed" | "cancelled"> {

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

@@ -1,4 +1,5 @@
 export * from "./client/index.js";
+export type { ArtifactRef } from "../artifact-ref.js";
 export {
   defineAgentOperation,
   isTerminalAgentEvent,

package/template/packages/ai-client/src/artifact-ref.ts

@@ -0,0 +1,8 @@
+export interface ArtifactRef {
+  /** 平台签发的不透明短时引用；业务不得解析、拼接或持久化底层地址。 */
+  readonly value: string;
+  readonly mediaType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+  readonly expiresAt?: string;
+}

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

@@ -0,0 +1,114 @@
+import { describe, expect, test } from "bun:test";
+import { createDocumentAiClient } from "./client.js";
+import type { DocumentResult } from "./contracts.js";
+import { DocumentClientError } from "./error.js";
+
+const artifact = {
+  value: "artifact_opaque",
+  mediaType: "application/pdf",
+  byteSize: 128,
+  sha256: "a".repeat(64),
+};
+
+describe("Document AI Client", () => {
+  test("提交、页级事件、结果与取消使用稳定 Document 协议", async () => {
+    const requests: Array<{ url: string; init?: RequestInit }> = [];
+    const client = createDocumentAiClient({
+      baseUrl: "https://windy.example",
+      fetch: async (input, init) => {
+        const url = String(input);
+        requests.push({ url, init });
+        if (url.endsWith("/api/document/runs")) {
+          return Response.json({
+            runId: "doc-run-1",
+            status: "accepted",
+            eventsUrl: "/api/document/runs/doc-run-1/events",
+          });
+        }
+        if (url.includes("/events")) {
+          return new Response(
+            [
+              'data: {"type":"run.started","runId":"doc-run-1","sequence":1}',
+              "",
+              'data: {"type":"document.page.completed","runId":"doc-run-1","sequence":2,"pageNumber":1,"completedPages":1,"totalPages":1}',
+              "",
+              'data: {"type":"run.completed","runId":"doc-run-1","sequence":3}',
+              "",
+              "",
+            ].join("\n"),
+          );
+        }
+        if (url.endsWith("/result")) {
+          return Response.json({
+            output: {
+              pages: [],
+              tables: [],
+              artifacts: [],
+              metadata: { engine: "local" },
+            },
+          });
+        }
+        return Response.json({ runId: "doc-run-1", status: "cancelled" });
+      },
+    });
+    const run = await client.submit(
+      {
+        key: "document.ocr.fast",
+        parseOutput(value) {
+          return value as DocumentResult;
+        },
+      },
+      { source: artifact, options: { outputs: ["pages"] } },
+      { idempotencyKey: "document-1" },
+    );
+
+    const events = [];
+    for await (const event of run.events) events.push(event);
+    expect(events.map(({ type }) => type)).toEqual([
+      "run.started",
+      "document.page.completed",
+      "run.completed",
+    ]);
+    expect(await run.result()).toEqual({
+      pages: [],
+      tables: [],
+      artifacts: [],
+      metadata: { engine: "local" },
+    });
+    await run.cancel("不再需要");
+    expect(JSON.parse(String(requests[0]?.init?.body))).toEqual({
+      operationKey: "document.ocr.fast",
+      source: artifact,
+      options: { outputs: ["pages"] },
+    });
+    expect(requests[0]?.init?.headers).toMatchObject({
+      "idempotency-key": "document-1",
+    });
+  });
+
+  test("拒绝无效 ArtifactRef 和跨 Origin events URL", async () => {
+    const client = createDocumentAiClient({
+      baseUrl: "https://windy.example",
+      fetch: async () =>
+        Response.json({
+          runId: "doc-run-1",
+          status: "accepted",
+          eventsUrl: "https://evil.example/events",
+        }),
+    });
+    await expect(
+      client.submit(
+        { key: "document.ocr.fast", parseOutput: (value) => value },
+        { source: { ...artifact, sha256: "invalid" } },
+        { idempotencyKey: "document-invalid" },
+      ),
+    ).rejects.toBeInstanceOf(DocumentClientError);
+    await expect(
+      client.submit(
+        { key: "document.ocr.fast", parseOutput: (value) => value },
+        { source: artifact },
+        { idempotencyKey: "document-origin" },
+      ),
+    ).rejects.toBeInstanceOf(DocumentClientError);
+  });
+});