create-windy 0.6.12 → 0.6.15

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

@@ -24,34 +24,41 @@ const error = {
 
 const events: AgentEvent[] = [
   { type: "run.started", runId: "run-1", sequence: 1 },
-  { type: "output.delta", runId: "run-1", sequence: 2, text: "你好" },
+  {
+    type: "input.prepared",
+    runId: "run-1",
+    sequence: 2,
+    artifactCount: 1,
+    inputModalities: ["text", "image"],
+  },
+  { type: "output.delta", runId: "run-1", sequence: 3, text: "你好" },
   {
     type: "tool.requested",
     runId: "run-1",
-    sequence: 3,
+    sequence: 4,
     toolCallId: "call-1",
     toolKey: "work-order.ticket.read",
   },
   {
     type: "approval.required",
     runId: "run-1",
-    sequence: 4,
+    sequence: 5,
     workItemId: "work-1",
     toolCallId: "tool-call-1",
   },
   {
     type: "tool.completed",
     runId: "run-1",
-    sequence: 5,
+    sequence: 6,
     toolCallId: "call-1",
   },
   {
     type: "usage.reported",
     runId: "run-1",
-    sequence: 6,
+    sequence: 7,
     usage: { source: "provider-reported", inputTokens: 10 },
   },
-  { type: "run.completed", runId: "run-1", sequence: 7 },
+  { type: "run.completed", runId: "run-1", sequence: 8 },
   { type: "run.failed", runId: "run-2", sequence: 1, error },
   { type: "run.cancelled", runId: "run-3", sequence: 1 },
 ];
@@ -121,6 +128,41 @@ describe("Agent contract", () => {
     expect(() =>
       parseAgentEvent({ type: "output.delta", runId: "run-1", sequence: 1 }),
     ).toThrow(AgentContractParseError);
+    expect(() =>
+      parseAgentEvent({
+        type: "input.prepared",
+        runId: "run-1",
+        sequence: 2,
+        inputModalities: ["text"],
+      }),
+    ).toThrow(AgentContractParseError);
+    expect(() =>
+      parseAgentEvent({
+        type: "input.prepared",
+        runId: "run-1",
+        sequence: 2,
+        artifactCount: -1,
+        inputModalities: ["text"],
+      }),
+    ).toThrow(AgentContractParseError);
+    expect(() =>
+      parseAgentEvent({
+        type: "input.prepared",
+        runId: "run-1",
+        sequence: 2,
+        artifactCount: 0,
+        inputModalities: ["binary"],
+      }),
+    ).toThrow(AgentContractParseError);
+    expect(() =>
+      parseAgentEvent({
+        type: "input.prepared",
+        runId: "run-1",
+        sequence: 2,
+        artifactCount: 0,
+        inputModalities: [],
+      }),
+    ).toThrow(AgentContractParseError);
     expect(() =>
       parseAgentEvent({
         type: "run.started",
@@ -185,7 +227,7 @@ describe("Agent SSE", () => {
       comment: "heartbeat",
     });
     const event = events[1]!;
-    const frame = `id: 2\nevent: output.delta\ndata: ${JSON.stringify(event)}`;
+    const frame = `id: 2\nevent: input.prepared\ndata: ${JSON.stringify(event)}`;
     expect(decodeAgentSseFrame(frame)).toEqual({
       kind: "event",
       id: 2,

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

@@ -2,11 +2,19 @@ import { parseAgentError, type AgentError } from "./errors.js";
 import { parseAgentUsage, type AgentUsage } from "./usage.js";
 import {
   AgentContractParseError,
+  nonNegativeIntegerAt,
   positiveIntegerAt,
   recordAt,
   stringAt,
 } from "./validation.js";
 
+export type AgentInputModality =
+  | "text"
+  | "image"
+  | "audio"
+  | "video"
+  | "document";
+
 export interface AgentEventBase {
   runId: string;
   sequence: number;
@@ -20,6 +28,12 @@ export interface AgentRunResumedEvent extends AgentEventBase {
   type: "run.resumed";
 }
 
+export interface AgentInputPreparedEvent extends AgentEventBase {
+  type: "input.prepared";
+  artifactCount: number;
+  inputModalities: readonly AgentInputModality[];
+}
+
 export interface AgentOutputDeltaEvent extends AgentEventBase {
   type: "output.delta";
   text: string;
@@ -70,6 +84,7 @@ export interface AgentRunCancelledEvent extends AgentEventBase {
 export type AgentEvent =
   | AgentRunStartedEvent
   | AgentRunResumedEvent
+  | AgentInputPreparedEvent
   | AgentOutputDeltaEvent
   | AgentToolRequestedEvent
   | AgentApprovalRequiredEvent
@@ -89,6 +104,7 @@ export type TerminalAgentEvent =
 const eventTypes: ReadonlySet<string> = new Set<AgentEventType>([
   "run.started",
   "run.resumed",
+  "input.prepared",
   "output.delta",
   "tool.requested",
   "approval.required",
@@ -118,6 +134,25 @@ export function parseAgentEvent(input: unknown): AgentEvent {
     case "run.completed":
     case "run.cancelled":
       return { type: eventType, ...base };
+    case "input.prepared": {
+      const artifactCount = nonNegativeIntegerAt(
+        record,
+        "artifactCount",
+        "event",
+      );
+      if (artifactCount === undefined) {
+        throw new AgentContractParseError(
+          "event.artifactCount",
+          "必须是非负安全整数",
+        );
+      }
+      return {
+        type: eventType,
+        ...base,
+        artifactCount,
+        inputModalities: parseInputModalities(record.inputModalities),
+      };
+    }
     case "output.delta":
       return {
         type: eventType,
@@ -174,6 +209,32 @@ export function parseAgentEvent(input: unknown): AgentEvent {
   }
 }
 
+const inputModalities: ReadonlySet<string> = new Set<AgentInputModality>([
+  "text",
+  "image",
+  "audio",
+  "video",
+  "document",
+]);
+
+function parseInputModalities(input: unknown): AgentInputModality[] {
+  if (!Array.isArray(input) || input.length === 0) {
+    throw new AgentContractParseError(
+      "event.inputModalities",
+      "必须是非空数组",
+    );
+  }
+  return input.map((value, index) => {
+    if (typeof value !== "string" || !inputModalities.has(value)) {
+      throw new AgentContractParseError(
+        `event.inputModalities[${index}]`,
+        "输入模态无效",
+      );
+    }
+    return value as AgentInputModality;
+  });
+}
+
 export function isAgentEvent(input: unknown): input is AgentEvent {
   try {
     parseAgentEvent(input);

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

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

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

@@ -0,0 +1,131 @@
+export type ClientAgentMessageRole = "system" | "user" | "assistant" | "tool";
+
+export const pageAgentClientRunCapability = "pageAgentClientRun" as const;
+export type ClientAgentCapability = typeof pageAgentClientRunCapability;
+
+export type ClientAgentSessionErrorCode =
+  | "INVALID_INPUT"
+  | "FORBIDDEN"
+  | "NOT_FOUND"
+  | "CONFLICT"
+  | "LIMIT_EXCEEDED"
+  | "PROVIDER_FAILED"
+  | "INTERNAL_ERROR";
+
+export interface ClientAgentSessionErrorResponse {
+  readonly code: ClientAgentSessionErrorCode;
+  readonly message: string;
+  readonly retryable: boolean;
+}
+
+export interface ClientAgentMessage {
+  readonly role: ClientAgentMessageRole;
+  readonly content: string;
+  readonly name?: string;
+  readonly tool_call_id?: string;
+  readonly tool_calls?: readonly {
+    readonly id: string;
+    readonly type: "function";
+    readonly function: { readonly name: string; readonly arguments: string };
+  }[];
+}
+
+export interface ClientAgentFunctionTool {
+  readonly type: "function";
+  readonly function: {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters: Record<string, unknown>;
+  };
+}
+
+export interface ClientAgentChatCompletionRequest {
+  readonly model: string;
+  readonly messages: readonly ClientAgentMessage[];
+  readonly tools?: readonly ClientAgentFunctionTool[];
+  readonly tool_choice?:
+    | "auto"
+    | "none"
+    | {
+        readonly type: "function";
+        readonly function: { readonly name: string };
+      };
+  readonly parallel_tool_calls?: false;
+  readonly stream?: boolean;
+}
+
+export interface CreateClientAgentSessionRequest<Input = unknown> {
+  readonly operationKey: string;
+  readonly input: Input;
+  /** 宿主生成的 installation/conversation/tab/document epoch commitment。 */
+  readonly clientBindingDigest: `sha256:${string}`;
+}
+
+export interface ClientAgentSessionLimits {
+  readonly maxSteps: number;
+  readonly maxRequestBytes: number;
+  readonly maxResponseBytes: number;
+  readonly maxDurationSeconds: number;
+  readonly maxConcurrentRequests: number;
+}
+
+export interface ClientAgentSessionGrant {
+  readonly clientRunId: string;
+  readonly sessionId: string;
+  readonly trustedBaseUrl: string;
+  readonly modelAlias: string;
+  readonly limits: ClientAgentSessionLimits;
+  readonly expiresAt: string;
+  /** 单 Run bearer；调用方不得持久化或转交业务 API。 */
+  readonly accessToken: string;
+  readonly capabilities: readonly [typeof pageAgentClientRunCapability];
+}
+
+export interface ClientAgentCapabilityResponse {
+  readonly capabilities: readonly ClientAgentCapability[];
+  readonly modelAlias: string;
+}
+
+export interface ProviderResponseReceipt {
+  readonly receiptId: string;
+  readonly clientRunId: string;
+  readonly attempt: number;
+  readonly requestDigest: `sha256:${string}`;
+  readonly responseDigest: `sha256:${string}`;
+  readonly deploymentDigest: `sha256:${string}`;
+  readonly issuedAt: string;
+}
+
+export type ClientAgentSessionStatus =
+  | "active"
+  | "completed"
+  | "cancelled"
+  | "revoked"
+  | "expired";
+
+export interface FinalizeClientAgentSessionRequest<Result = unknown> {
+  readonly receiptIds: readonly string[];
+  readonly result?: Result;
+}
+
+export interface ClientAgentFinalResult<Result = unknown> {
+  readonly clientRunId: string;
+  readonly status: "completed";
+  readonly result: Result;
+  readonly attestation: {
+    readonly source: "provider-observed" | "client-projected";
+    readonly terminalReceiptId: string;
+    readonly providerAttested: boolean;
+    readonly clientProjected: boolean;
+  };
+}
+
+export interface ClientAgentSessionView<Result = unknown> {
+  readonly clientRunId: string;
+  readonly sessionId: string;
+  readonly operationKey: string;
+  readonly status: ClientAgentSessionStatus;
+  readonly attemptCount: number;
+  readonly expiresAt: string;
+  readonly result?: ClientAgentFinalResult<Result>;
+}

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

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import type { ClientAgentSessionGrant } from "./contracts.js";
+import {
+  clientAgentCompletionRequest,
+  clientAgentSessionHttp,
+} from "./http.js";
+
+describe("Client Agent HTTP adapter contract", () => {
+  test("只把单 Run token 发到受信 session baseURL", () => {
+    const request = clientAgentCompletionRequest(
+      grant(),
+      "bax_installation-session",
+      `sha256:${"b".repeat(64)}`,
+      JSON.stringify({ model: "windy-client-agent-v1", messages: [] }),
+    );
+    expect(request.url).toBe(
+      "https://windy.example/api/agent/client-sessions/cas_1/v1/chat/completions",
+    );
+    expect(request.init.headers).toEqual({
+      authorization: `Bearer car_${"a".repeat(43)}`,
+      "content-type": "application/json",
+      "x-windy-host-authorization": "Bearer bax_installation-session",
+      "x-windy-client-binding-digest": `sha256:${"b".repeat(64)}`,
+    });
+    expect(JSON.stringify(request)).not.toContain("provider-key");
+    expect(clientAgentSessionHttp.revoke).toBe(
+      "/api/agent/client-sessions/revoke",
+    );
+  });
+
+  test("拒绝非本机 HTTP baseURL", () => {
+    expect(() =>
+      clientAgentCompletionRequest(
+        { ...grant(), trustedBaseUrl: "http://evil.example/v1/" },
+        "bax_installation-session",
+        `sha256:${"b".repeat(64)}`,
+        "{}",
+      ),
+    ).toThrow("必须使用 HTTPS");
+  });
+});
+
+function grant(): ClientAgentSessionGrant {
+  return {
+    clientRunId: "carun_1",
+    sessionId: "cas_1",
+    trustedBaseUrl: "https://windy.example/api/agent/client-sessions/cas_1/v1/",
+    modelAlias: "windy-client-agent-v1",
+    limits: {
+      maxSteps: 8,
+      maxRequestBytes: 65_536,
+      maxResponseBytes: 65_536,
+      maxDurationSeconds: 60,
+      maxConcurrentRequests: 1,
+    },
+    expiresAt: "2026-08-26T10:00:00.000Z",
+    accessToken: `car_${"a".repeat(43)}`,
+    capabilities: ["pageAgentClientRun"],
+  };
+}

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

@@ -0,0 +1,66 @@
+import type { ClientAgentSessionGrant } from "./contracts.js";
+
+export const clientAgentSessionHttp = {
+  capabilities: "/api/agent/client-sessions/capabilities",
+  create: "/api/agent/client-sessions",
+  revoke: "/api/agent/client-sessions/revoke",
+  status: (sessionId: string) =>
+    `/api/agent/client-sessions/${encodeURIComponent(sessionId)}`,
+  result: (sessionId: string) =>
+    `/api/agent/client-sessions/${encodeURIComponent(sessionId)}/result`,
+  finalize: (sessionId: string) =>
+    `/api/agent/client-sessions/${encodeURIComponent(sessionId)}/finalize`,
+  cancel: (sessionId: string) =>
+    `/api/agent/client-sessions/${encodeURIComponent(sessionId)}/cancel`,
+} as const;
+
+export function clientAgentCompletionRequest(
+  grant: ClientAgentSessionGrant,
+  hostAccessToken: `bax_${string}`,
+  clientBindingDigest: `sha256:${string}`,
+  body: BodyInit,
+  signal?: AbortSignal,
+): { url: string; init: RequestInit } {
+  const base = new URL(grant.trustedBaseUrl);
+  if (base.protocol !== "https:" && base.hostname !== "localhost") {
+    throw new TypeError("Client Agent baseURL 必须使用 HTTPS");
+  }
+  return {
+    url: new URL("chat/completions", ensureTrailingSlash(base)).toString(),
+    init: {
+      method: "POST",
+      headers: clientAgentSessionHeaders(
+        grant,
+        hostAccessToken,
+        clientBindingDigest,
+      ),
+      body,
+      ...(signal ? { signal } : {}),
+    },
+  };
+}
+
+export function clientAgentHostHeaders(
+  hostAccessToken: `bax_${string}`,
+): Readonly<Record<string, string>> {
+  return { authorization: `Bearer ${hostAccessToken}` };
+}
+
+export function clientAgentSessionHeaders(
+  grant: ClientAgentSessionGrant,
+  hostAccessToken: `bax_${string}`,
+  clientBindingDigest: `sha256:${string}`,
+): Readonly<Record<string, string>> {
+  return {
+    authorization: `Bearer ${grant.accessToken}`,
+    "content-type": "application/json",
+    "x-windy-host-authorization": `Bearer ${hostAccessToken}`,
+    "x-windy-client-binding-digest": clientBindingDigest,
+  };
+}
+
+function ensureTrailingSlash(url: URL): URL {
+  const copy = new URL(url);
+  if (!copy.pathname.endsWith("/")) copy.pathname += "/";
+  return copy;
+}

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

@@ -0,0 +1,4 @@
+export * from "./contracts.js";
+export * from "./http.js";
+export * from "./validation.js";
+export * from "./workflow-artifact/index.js";

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

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ClientAgentContractError,
+  parseClientAgentSessionGrant,
+  parseProviderResponseReceipt,
+} from "./validation.js";
+
+describe("Client Agent public contracts", () => {
+  test("接受不含 Provider 物理信息的受信 session grant", () => {
+    expect(parseClientAgentSessionGrant(grant())).toMatchObject({
+      clientRunId: "carun_1",
+      modelAlias: "windy-default",
+    });
+  });
+
+  test("拒绝不受信 baseURL、伪造 token 与无效 receipt digest", () => {
+    expect(() =>
+      parseClientAgentSessionGrant({
+        ...grant(),
+        trustedBaseUrl: "https://user:secret@evil.example/?key=leak",
+      }),
+    ).toThrow(ClientAgentContractError);
+    expect(() =>
+      parseClientAgentSessionGrant({ ...grant(), accessToken: "grant_secret" }),
+    ).toThrow("accessToken 无效");
+    expect(() =>
+      parseProviderResponseReceipt({
+        receiptId: "receipt_1",
+        clientRunId: "carun_1",
+        attempt: 1,
+        requestDigest: `sha256:${"a".repeat(64)}`,
+        responseDigest: "raw-response",
+        deploymentDigest: `sha256:${"d".repeat(64)}`,
+        issuedAt: new Date().toISOString(),
+      }),
+    ).toThrow("responseDigest 无效");
+  });
+});
+
+function grant() {
+  return {
+    clientRunId: "carun_1",
+    sessionId: "cas_1",
+    trustedBaseUrl: "https://windy.example/api/agent/client-sessions/",
+    modelAlias: "windy-default",
+    limits: {
+      maxSteps: 8,
+      maxRequestBytes: 16_384,
+      maxResponseBytes: 16_384,
+      maxDurationSeconds: 60,
+      maxConcurrentRequests: 1,
+    },
+    expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    accessToken: `car_${"a".repeat(43)}`,
+    capabilities: ["pageAgentClientRun"],
+  };
+}

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

@@ -0,0 +1,152 @@
+import type {
+  ClientAgentSessionGrant,
+  ClientAgentSessionView,
+  ProviderResponseReceipt,
+} from "./contracts.js";
+import { pageAgentClientRunCapability } from "./contracts.js";
+
+export class ClientAgentContractError extends TypeError {
+  constructor(message: string) {
+    super(message);
+    this.name = "ClientAgentContractError";
+  }
+}
+
+export function parseClientAgentSessionGrant(
+  value: unknown,
+): ClientAgentSessionGrant {
+  const record = object(value, "Client Agent Session grant");
+  const limits = object(record.limits, "Client Agent Session limits");
+  if (
+    !Array.isArray(record.capabilities) ||
+    record.capabilities.length !== 1 ||
+    record.capabilities[0] !== pageAgentClientRunCapability
+  ) {
+    throw new ClientAgentContractError("Client Agent capability 无效");
+  }
+  return {
+    clientRunId: text(record.clientRunId, "clientRunId"),
+    sessionId: text(record.sessionId, "sessionId"),
+    trustedBaseUrl: secureBaseUrl(record.trustedBaseUrl),
+    modelAlias: text(record.modelAlias, "modelAlias"),
+    limits: {
+      maxSteps: positive(limits.maxSteps, "maxSteps"),
+      maxRequestBytes: positive(limits.maxRequestBytes, "maxRequestBytes"),
+      maxResponseBytes: positive(limits.maxResponseBytes, "maxResponseBytes"),
+      maxDurationSeconds: positive(
+        limits.maxDurationSeconds,
+        "maxDurationSeconds",
+      ),
+      maxConcurrentRequests: positive(
+        limits.maxConcurrentRequests,
+        "maxConcurrentRequests",
+      ),
+    },
+    expiresAt: timestamp(record.expiresAt, "expiresAt"),
+    accessToken: opaqueToken(record.accessToken),
+    capabilities: [pageAgentClientRunCapability],
+  };
+}
+
+export function parseProviderResponseReceipt(
+  value: unknown,
+): ProviderResponseReceipt {
+  const record = object(value, "Provider receipt");
+  return {
+    receiptId: text(record.receiptId, "receiptId"),
+    clientRunId: text(record.clientRunId, "clientRunId"),
+    attempt: positive(record.attempt, "attempt"),
+    requestDigest: digest(record.requestDigest, "requestDigest"),
+    responseDigest: digest(record.responseDigest, "responseDigest"),
+    deploymentDigest: digest(record.deploymentDigest, "deploymentDigest"),
+    issuedAt: timestamp(record.issuedAt, "issuedAt"),
+  };
+}
+
+export function parseClientAgentSessionView(
+  value: unknown,
+): ClientAgentSessionView {
+  const record = object(value, "Client Agent Session view");
+  const status = record.status;
+  if (
+    status !== "active" &&
+    status !== "completed" &&
+    status !== "cancelled" &&
+    status !== "revoked" &&
+    status !== "expired"
+  ) {
+    throw new ClientAgentContractError("status 无效");
+  }
+  return {
+    clientRunId: text(record.clientRunId, "clientRunId"),
+    sessionId: text(record.sessionId, "sessionId"),
+    operationKey: text(record.operationKey, "operationKey"),
+    status,
+    attemptCount: nonNegative(record.attemptCount, "attemptCount"),
+    expiresAt: timestamp(record.expiresAt, "expiresAt"),
+    ...(record.result === undefined ? {} : { result: record.result as never }),
+  };
+}
+
+function object(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ClientAgentContractError(`${label} 必须是对象`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function text(value: unknown, label: string): string {
+  if (typeof value !== "string" || !value.trim() || value.length > 512) {
+    throw new ClientAgentContractError(`${label} 无效`);
+  }
+  return value;
+}
+
+function positive(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value) || Number(value) <= 0) {
+    throw new ClientAgentContractError(`${label} 必须是正整数`);
+  }
+  return Number(value);
+}
+
+function nonNegative(value: unknown, label: string): number {
+  if (!Number.isSafeInteger(value) || Number(value) < 0) {
+    throw new ClientAgentContractError(`${label} 必须是非负整数`);
+  }
+  return Number(value);
+}
+
+function timestamp(value: unknown, label: string): string {
+  const parsed = text(value, label);
+  if (!Number.isFinite(Date.parse(parsed))) {
+    throw new ClientAgentContractError(`${label} 无效`);
+  }
+  return parsed;
+}
+
+function digest(value: unknown, label: string): `sha256:${string}` {
+  const parsed = text(value, label);
+  if (!/^sha256:[a-f0-9]{64}$/u.test(parsed)) {
+    throw new ClientAgentContractError(`${label} 无效`);
+  }
+  return parsed as `sha256:${string}`;
+}
+
+function opaqueToken(value: unknown): string {
+  const token = text(value, "accessToken");
+  if (!/^car_[A-Za-z0-9_-]{32,}$/u.test(token)) {
+    throw new ClientAgentContractError("accessToken 无效");
+  }
+  return token;
+}
+
+function secureBaseUrl(value: unknown): string {
+  const parsed = new URL(text(value, "trustedBaseUrl"));
+  if (parsed.protocol !== "https:" && parsed.hostname !== "localhost") {
+    throw new ClientAgentContractError("trustedBaseUrl 必须是受信 HTTPS URL");
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new ClientAgentContractError("trustedBaseUrl 不能包含凭据或参数");
+  }
+  return parsed.toString();
+}