create-windy 0.3.2 → 0.3.5

package/template/apps/server/src/agent/idempotency-key.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { scopedRuntimeIdempotencyKey } from "./idempotency-key.js";
+
+describe("Runtime 幂等键作用域", () => {
+  test("相同客户端键按 Actor 和 Operation 隔离", () => {
+    const base = scopedRuntimeIdempotencyKey(
+      "actor-1",
+      "business.answer",
+      "shared-request",
+    );
+
+    expect(base).toMatch(/^[a-f0-9]{64}$/);
+    expect(
+      scopedRuntimeIdempotencyKey(
+        "actor-2",
+        "business.answer",
+        "shared-request",
+      ),
+    ).not.toBe(base);
+    expect(
+      scopedRuntimeIdempotencyKey(
+        "actor-1",
+        "business.summarize",
+        "shared-request",
+      ),
+    ).not.toBe(base);
+  });
+});

package/template/apps/server/src/agent/idempotency-key.ts

@@ -0,0 +1,11 @@
+import { createHash } from "node:crypto";
+
+export function scopedRuntimeIdempotencyKey(
+  actorId: string,
+  operationKey: string,
+  idempotencyKey: string,
+) {
+  return createHash("sha256")
+    .update(`${actorId}\u0000${operationKey}\u0000${idempotencyKey}`)
+    .digest("hex");
+}

package/template/apps/server/src/agent/remote-runtime.test.ts

@@ -9,6 +9,41 @@ afterEach(() => {
 });
 
 describe("RemoteAgentRuntime", () => {
+  test("读取可恢复 Run 状态和终态事件", async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch() {
+        return Response.json({
+          runId: "run_done",
+          status: "completed",
+          lastSequence: 4,
+          terminalEvent: {
+            type: "run.completed",
+            runId: "run_done",
+            sequence: 4,
+          },
+        });
+      },
+    });
+    servers.push(server);
+    const runtime = new RemoteAgentRuntime({
+      baseUrl: server.url.toString(),
+      internalToken: "test-token",
+      toolHostUrl: "http://server.internal/api/agent/tools",
+    });
+
+    await expect(runtime.status("run_done")).resolves.toEqual({
+      runId: "run_done",
+      status: "completed",
+      lastSequence: 4,
+      terminalEvent: {
+        type: "run.completed",
+        runId: "run_done",
+        sequence: 4,
+      },
+    });
+  });
+
   test("只向 Agent Server 序列化远端支持的运行限制", async () => {
     let received: unknown;
     const server = Bun.serve({
@@ -30,10 +65,15 @@ describe("RemoteAgentRuntime", () => {
       maxOutputBytes: 8_192,
     };
     const operation: AgentRuntimeOperation = {
+      kind: "agent",
       operationKey: "business.answer",
       input: { question: "你好" },
+      inputModalities: ["text"],
+      requiredCapabilities: ["text-generation"],
+      artifacts: [],
       instructions: "只回答当前业务问题。",
       userPrompt: "你好",
+      outputSchemaKey: "business.output.v1",
       allowedTools: [],
       limits: manifestLimits,
       providerEgress: {
@@ -63,6 +103,8 @@ describe("RemoteAgentRuntime", () => {
       },
       toolNetworkPolicy: { mode: "forbidden" },
       executionGrant: "grant_1",
+      release: runtimeRelease(),
+      traceId: "trace_request_1",
     };
     const runtime = new RemoteAgentRuntime({
       baseUrl: server.url.toString(),
@@ -75,6 +117,7 @@ describe("RemoteAgentRuntime", () => {
     expect(received).toMatchObject({
       limits: {
         maxDurationSeconds: 60,
+        maxInputBytes: 4_096,
         maxOutputBytes: 8_192,
       },
       providerEgress: {
@@ -83,13 +126,84 @@ describe("RemoteAgentRuntime", () => {
       },
       providerDataPolicy: operation.providerDataPolicy,
       toolNetworkPolicy: { mode: "forbidden" },
+      release: operation.release,
+      traceId: operation.traceId,
     });
     expect(
       (received as { limits: Record<string, unknown> }).limits,
-    ).not.toHaveProperty("maxInputBytes");
+    ).toHaveProperty("maxInputBytes", 4_096);
     const serialized = JSON.stringify(received);
     expect(serialized).not.toContain("QWEN_");
     expect(serialized).not.toContain("apiKey");
     expect(serialized).not.toContain("baseUrl");
   });
+
+  test("保留 Runtime 的能力拒绝错误码", async () => {
+    const server = Bun.serve({
+      port: 0,
+      fetch() {
+        return Response.json(
+          {
+            code: "MODEL_ROUTE_UNAVAILABLE",
+            message: "模型 Deployment 缺少 Operation 所需能力",
+            retryable: true,
+          },
+          { status: 503 },
+        );
+      },
+    });
+    servers.push(server);
+    const runtime = new RemoteAgentRuntime({
+      baseUrl: server.url.toString(),
+      internalToken: "test-token",
+      toolHostUrl: "http://server.internal/api/agent/tools",
+    });
+    const request: AgentRuntimeOperation = {
+      kind: "agent",
+      operationKey: "business.vision",
+      input: { question: "分析" },
+      inputModalities: ["text", "image"],
+      requiredCapabilities: ["vision"],
+      artifacts: [],
+      instructions: "分析图片",
+      userPrompt: "分析",
+      outputSchemaKey: "business.output.v1",
+      allowedTools: [],
+      limits: {
+        maxDurationSeconds: 60,
+        maxInputBytes: 4096,
+        maxOutputBytes: 4096,
+        maxArtifacts: 1,
+        maxPixelsPerArtifact: 1_000_000,
+      },
+      providerEgress: {
+        mode: "configured-endpoint",
+        deploymentKey: "ai.openai-compatible",
+      },
+      providerDataPolicy: { inputFields: [], envelopeFields: [] },
+      toolNetworkPolicy: { mode: "forbidden" },
+      executionGrant: "grant_1",
+      release: runtimeRelease(),
+      traceId: "trace_request_vision",
+    };
+
+    await expect(
+      runtime.start(request, "request-vision"),
+    ).rejects.toMatchObject({
+      code: "MODEL_ROUTE_UNAVAILABLE",
+      retryable: true,
+    });
+  });
 });
+
+function runtimeRelease(): AgentRuntimeOperation["release"] {
+  return {
+    releaseId: "release_test",
+    operationVersion: "1.0.0",
+    workflowVersion: "workflow-1",
+    promptVersion: "prompt-1",
+    routeVersion: "route-1",
+    toolSchemaVersion: "schema-1",
+    manifestDigest: "0".repeat(64),
+  };
+}

package/template/apps/server/src/agent/remote-runtime.ts

@@ -1,8 +1,12 @@
 import type {
   AgentRuntimeOperation,
   AgentRuntimePort,
+  AgentRuntimeRunStatus,
   AgentRuntimeStartResponse,
+  AgentRuntimeStatusResponse,
+  AgentRuntimeTerminalEvent,
 } from "./run-contracts.js";
+import { AgentRuntimeError } from "./run-contracts.js";
 
 export interface RemoteAgentRuntimeOptions {
   baseUrl: string;
@@ -28,19 +32,38 @@ export class RemoteAgentRuntime implements AgentRuntimePort {
     idempotencyKey: string,
   ): Promise<AgentRuntimeStartResponse> {
     const remoteRequest: RemoteStartRunRequest = {
+      kind: request.kind,
       operationKey: request.operationKey,
       input: request.input,
+      inputModalities: request.inputModalities,
+      requiredCapabilities: request.requiredCapabilities,
+      artifacts: request.artifacts,
       instructions: request.instructions,
       userPrompt: request.userPrompt,
+      outputSchemaKey: request.outputSchemaKey,
+      ...(request.outputSchema === undefined
+        ? {}
+        : { outputSchema: request.outputSchema }),
       allowedTools: request.allowedTools,
       limits: {
         maxDurationSeconds: request.limits.maxDurationSeconds,
+        maxInputBytes: request.limits.maxInputBytes,
         maxOutputBytes: request.limits.maxOutputBytes,
+        ...(request.limits.maxArtifacts === undefined
+          ? {}
+          : { maxArtifacts: request.limits.maxArtifacts }),
+        ...(request.limits.maxPixelsPerArtifact === undefined
+          ? {}
+          : {
+              maxPixelsPerArtifact: request.limits.maxPixelsPerArtifact,
+            }),
       },
       providerEgress: request.providerEgress,
       providerDataPolicy: request.providerDataPolicy,
       toolNetworkPolicy: request.toolNetworkPolicy,
       executionGrant: request.executionGrant,
+      release: request.release,
+      traceId: request.traceId,
       toolHostUrl: this.options.toolHostUrl,
     };
     const response = await this.request("/api/agent/runs", {
@@ -52,7 +75,7 @@ export class RemoteAgentRuntime implements AgentRuntimePort {
       body: JSON.stringify(remoteRequest),
     });
     if (!response.ok) throw await remoteError(response);
-    return (await response.json()) as AgentRuntimeStartResponse;
+    return parseStart(await response.json());
   }
 
   events(runId: string, cursor: number, signal?: AbortSignal) {
@@ -63,6 +86,15 @@ export class RemoteAgentRuntime implements AgentRuntimePort {
     );
   }
 
+  async status(runId: string, signal?: AbortSignal) {
+    const response = await this.request(
+      `/api/agent/runs/${encodeURIComponent(runId)}`,
+      { signal },
+    );
+    if (!response.ok) throw await remoteError(response);
+    return parseStatus(await response.json());
+  }
+
   result(runId: string, signal?: AbortSignal) {
     return this.request(`/api/agent/runs/${encodeURIComponent(runId)}/result`, {
       signal,
@@ -109,10 +141,122 @@ export class RemoteAgentRuntime implements AgentRuntimePort {
   }
 }
 
+function parseStart(value: unknown): AgentRuntimeStartResponse {
+  if (!isRecord(value)) throw new Error("Agent Runtime 创建响应无效");
+  const runId = text(value.runId);
+  const status = text(value.status);
+  const eventsUrl = text(value.eventsUrl);
+  if (!runId || !status || !runStatuses.has(status) || !eventsUrl) {
+    throw new Error("Agent Runtime 创建响应字段无效");
+  }
+  return {
+    runId,
+    status: status as AgentRuntimeRunStatus,
+    eventsUrl,
+  };
+}
+
+function parseStatus(value: unknown): AgentRuntimeStatusResponse {
+  if (!isRecord(value)) throw new Error("Agent Runtime 状态响应无效");
+  const runId = text(value.runId);
+  const status = text(value.status);
+  const lastSequence = value.lastSequence;
+  if (
+    !runId ||
+    !status ||
+    !runStatuses.has(status) ||
+    !Number.isSafeInteger(lastSequence) ||
+    Number(lastSequence) < 0
+  ) {
+    throw new Error("Agent Runtime 状态字段无效");
+  }
+  const terminalEvent =
+    value.terminalEvent === undefined
+      ? undefined
+      : parseTerminalEvent(value.terminalEvent, runId);
+  const terminalStatus = ["completed", "failed", "cancelled"].includes(status);
+  if (
+    terminalStatus !== Boolean(terminalEvent) ||
+    (terminalEvent && terminalEvent.sequence !== Number(lastSequence)) ||
+    (terminalEvent && terminalEvent.type !== `run.${status}`)
+  ) {
+    throw new Error("Agent Runtime 状态与终态事件不一致");
+  }
+  return {
+    runId,
+    status: status as AgentRuntimeRunStatus,
+    lastSequence: Number(lastSequence),
+    ...(terminalEvent ? { terminalEvent } : {}),
+  };
+}
+
+const runStatuses: ReadonlySet<string> = new Set<AgentRuntimeRunStatus>([
+  "accepted",
+  "running",
+  "awaiting-approval",
+  "completed",
+  "failed",
+  "cancelled",
+]);
+
+function parseTerminalEvent(
+  value: unknown,
+  expectedRunId: string,
+): AgentRuntimeTerminalEvent {
+  if (!isRecord(value)) throw new Error("Agent Runtime 终态事件无效");
+  const type = value.type;
+  const runId = text(value.runId);
+  const sequence = value.sequence;
+  if (
+    !["run.completed", "run.failed", "run.cancelled"].includes(String(type)) ||
+    runId !== expectedRunId ||
+    !Number.isSafeInteger(sequence) ||
+    Number(sequence) <= 0
+  ) {
+    throw new Error("Agent Runtime 终态事件字段无效");
+  }
+  if (type !== "run.failed") {
+    return {
+      type: type as "run.completed" | "run.cancelled",
+      runId,
+      sequence: Number(sequence),
+    };
+  }
+  if (!isRecord(value.error)) throw new Error("Agent Runtime 失败事件无效");
+  const code = text(value.error.code);
+  const message = text(value.error.message);
+  const requestId = text(value.error.requestId);
+  if (
+    !code ||
+    !message ||
+    !requestId ||
+    typeof value.error.retryable !== "boolean"
+  ) {
+    throw new Error("Agent Runtime 失败字段无效");
+  }
+  return {
+    type,
+    runId,
+    sequence: Number(sequence),
+    error: { code, message, requestId, retryable: value.error.retryable },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
 interface RemoteStartRunRequest extends Omit<AgentRuntimeOperation, "limits"> {
   limits: {
     maxDurationSeconds: number;
+    maxInputBytes: number;
     maxOutputBytes: number;
+    maxArtifacts?: number;
+    maxPixelsPerArtifact?: number;
   };
   toolHostUrl: string;
 }
@@ -128,22 +272,46 @@ function normalizeInternalUrl(raw: string): string {
   return url.toString().replace(/\/$/, "");
 }
 
-async function remoteError(response: Response): Promise<Error> {
-  const safe = `Agent Runtime 请求失败（HTTP ${response.status}）`;
+async function remoteError(response: Response): Promise<AgentRuntimeError> {
   try {
     const value = (await response.json()) as {
       code?: unknown;
       message?: unknown;
+      retryable?: unknown;
     };
     if (
       typeof value.code === "string" &&
       typeof value.message === "string" &&
+      typeof value.retryable === "boolean" &&
       value.message.length <= 200
     ) {
-      return new Error(`${value.code}: ${value.message}`);
+      return new AgentRuntimeError(
+        knownRemoteCode(value.code),
+        value.message,
+        value.retryable,
+      );
     }
   } catch {
     // Provider 或代理正文不可透传。
   }
-  return new Error(safe);
+  return new AgentRuntimeError(
+    "RUNTIME_UNAVAILABLE",
+    `Agent Runtime 请求失败（HTTP ${response.status}）`,
+    response.status >= 500,
+  );
+}
+
+function knownRemoteCode(
+  code: string,
+): ConstructorParameters<typeof AgentRuntimeError>[0] {
+  return [
+    "CAPABILITY_UNAVAILABLE",
+    "MODEL_ROUTE_UNAVAILABLE",
+    "RUN_CONFLICT",
+    "FORBIDDEN",
+    "BUDGET_EXCEEDED",
+    "INVALID_INPUT",
+  ].includes(code)
+    ? (code as ConstructorParameters<typeof AgentRuntimeError>[0])
+    : "RUNTIME_UNAVAILABLE";
 }

package/template/apps/server/src/agent/run-authorization.test-support.ts

@@ -0,0 +1,9 @@
+import { AgentRunAuthorizationStore } from "./run-authorization.js";
+import { InMemoryAgentRunBindingRepository } from "./run-binding-repository.js";
+
+export function createTestRunAuthorizationStore() {
+  return new AgentRunAuthorizationStore(
+    new InMemoryAgentRunBindingRepository(),
+    "test-agent-run-authorization-secret-32-bytes",
+  );
+}

package/template/apps/server/src/agent/run-authorization.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, test } from "bun:test";
+import { buildScopeContext } from "../data-access/context.js";
+import { createRequestGuardContext } from "../guards.js";
+import { AgentRunAuthorizationStore } from "./run-authorization.js";
+import { InMemoryAgentRunBindingRepository } from "./run-binding-repository.js";
+
+const secret = "agent-run-authorization-test-secret-32-bytes";
+const snapshot = {
+  permissionKey: "business.ai.execute",
+  featureKey: "business.ai",
+  allowedToolKeys: ["business.records.list"],
+  toolNetworkMode: "forbidden" as const,
+};
+
+describe("Agent Run 持久授权绑定", () => {
+  test("幂等重试和平台重启复用同一 Grant 与 Run", async () => {
+    const repository = new InMemoryAgentRunBindingRepository();
+    const firstStore = new AgentRunAuthorizationStore(repository, secret);
+    const first = await firstStore.issue({
+      operationKey: "business.answer",
+      releaseId: "release-1",
+      idempotencyKey: "request-1",
+      authorizationSnapshot: snapshot,
+      context: context("actor-1", "role-1"),
+    });
+    await firstStore.bind(first, "run-1");
+
+    const restartedStore = new AgentRunAuthorizationStore(repository, secret);
+    const retried = await restartedStore.issue({
+      operationKey: "business.answer",
+      releaseId: "release-1",
+      idempotencyKey: "request-1",
+      authorizationSnapshot: snapshot,
+      context: context("actor-1", "role-1"),
+    });
+    const toolBinding = await restartedStore.authorizeTool(
+      retried.token,
+      "run-1",
+    );
+
+    expect(retried.token).toBe(first.token);
+    expect(retried.binding.bindingId).toBe(first.binding.bindingId);
+    expect(toolBinding.runId).toBe("run-1");
+  });
+
+  test("Tool 可先于 Start 响应绑定 provisional Run", async () => {
+    const store = new AgentRunAuthorizationStore(
+      new InMemoryAgentRunBindingRepository(),
+      secret,
+    );
+    const issued = await store.issue({
+      operationKey: "business.answer",
+      releaseId: "release-1",
+      idempotencyKey: "request-fast-tool",
+      authorizationSnapshot: snapshot,
+      context: context("actor-1", "role-1"),
+    });
+
+    const toolBinding = await store.authorizeTool(issued.token, "run-fast");
+    const facadeBinding = await store.bind(issued, "run-fast");
+
+    expect(toolBinding.runId).toBe("run-fast");
+    expect(facadeBinding.runId).toBe("run-fast");
+  });
+
+  test("Actor、Operation、Scope 和过期绑定使用同一种拒绝", async () => {
+    let now = 1_000;
+    const store = new AgentRunAuthorizationStore(
+      new InMemoryAgentRunBindingRepository(),
+      secret,
+      () => now,
+      100,
+    );
+    const issued = await store.issue({
+      operationKey: "business.answer",
+      releaseId: "release-1",
+      idempotencyKey: "request-denied",
+      authorizationSnapshot: snapshot,
+      context: context("actor-1", "role-1"),
+    });
+    await store.bind(issued, "run-denied");
+
+    const attempts: Array<[string, ReturnType<typeof context>]> = [
+      ["business.answer", context("actor-2", "role-1")],
+      ["business.other", context("actor-1", "role-1")],
+      ["business.answer", context("actor-1", "role-2")],
+    ];
+    for (const [operationKey, deniedContext] of attempts) {
+      await expect(
+        store.authorizeBrowser(operationKey, "run-denied", deniedContext),
+      ).rejects.toMatchObject({ message: "Agent Run 不存在或不可访问" });
+    }
+
+    now = 1_101;
+    await expect(
+      store.authorizeBrowser(
+        "business.answer",
+        "run-denied",
+        context("actor-1", "role-1"),
+      ),
+    ).rejects.toMatchObject({
+      message: "Agent Run 不存在或不可访问",
+    });
+  });
+});
+
+function context(actorId: string, roleId: string) {
+  return createRequestGuardContext(new Request("http://localhost"), {
+    resolveActor: () => ({
+      id: actorId,
+      type: "user",
+      name: actorId,
+      roleCodes: ["user"],
+      permissionKeys: ["business.ai.execute"],
+      scopeContext: buildScopeContext(actorId, undefined, [
+        {
+          id: roleId,
+          code: roleId,
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ]),
+    }),
+    resolveLicense: () => ({ status: "valid" }),
+  });
+}