create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,180 @@
+import { createHash, createHmac } from "node:crypto";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { AgentRunAuthorizationSnapshot } from "@southwind-ai/shared";
+import type {
+  AgentRunBinding,
+  AgentRunBindingRepository,
+} from "./run-binding-repository.js";
+
+export interface AgentExecutionAuthorization {
+  readonly binding: AgentRunBinding;
+  readonly token: string;
+}
+
+export class AgentRunAuthorizationStore {
+  constructor(
+    private readonly repository: AgentRunBindingRepository,
+    private readonly secret: string,
+    private readonly now: () => number = Date.now,
+    private readonly retentionMs = 7 * 24 * 60 * 60 * 1_000,
+  ) {
+    if (new TextEncoder().encode(secret).byteLength < 32) {
+      throw new Error("Agent Run Authorization Secret 至少需要 32 字节");
+    }
+  }
+
+  async issue(input: {
+    operationKey: string;
+    releaseId: string;
+    idempotencyKey: string;
+    authorizationSnapshot: AgentRunAuthorizationSnapshot;
+    context: RequestGuardContext;
+  }): Promise<AgentExecutionAuthorization> {
+    const issuedAt = this.now();
+    await this.repository.prune(issuedAt);
+    const scope = captureAuthorizationScope(input.context.actor.scopeContext);
+    const coordinate = [
+      input.context.actor.id,
+      input.operationKey,
+      input.idempotencyKey,
+    ].join("\u0000");
+    const idempotencyHash = this.hmac(`idempotency\u0000${coordinate}`);
+    const token = `grant_${this.hmac(`token\u0000${coordinate}`)}`;
+    const candidate: AgentRunBinding = {
+      bindingId: `binding_${idempotencyHash.slice(0, 40)}`,
+      operationKey: input.operationKey,
+      actorId: input.context.actor.id,
+      idempotencyHash,
+      tokenHash: sha256(token),
+      scopeHash: scope.hash,
+      scopeSnapshot: scope.snapshot,
+      authorizationSnapshot: structuredClone(input.authorizationSnapshot),
+      releaseId: input.releaseId,
+      createdAt: issuedAt,
+      expiresAt: issuedAt + this.retentionMs,
+    };
+    const binding = await this.repository.createOrGet(candidate);
+    if (
+      !sameAuthorization(binding, candidate) ||
+      binding.expiresAt <= issuedAt
+    ) {
+      throw new AgentRunAuthorizationError();
+    }
+    return { binding, token };
+  }
+
+  async bind(
+    authorization: AgentExecutionAuthorization,
+    runId: string,
+  ): Promise<AgentRunBinding> {
+    const binding = await this.repository.bind(
+      authorization.binding.bindingId,
+      runId,
+      this.now(),
+    );
+    if (!binding || binding.expiresAt <= this.now()) {
+      throw new AgentRunAuthorizationError();
+    }
+    return binding;
+  }
+
+  async authorizeTool(token: string, runId: string) {
+    const tokenHash = sha256(token);
+    let binding = await this.repository.findByTokenHash(tokenHash);
+    if (!binding || binding.expiresAt <= this.now()) {
+      throw new AgentRunAuthorizationError();
+    }
+    if (!binding.runId) {
+      binding =
+        (await this.repository.bind(binding.bindingId, runId, this.now())) ??
+        undefined;
+    }
+    if (!binding || binding.runId !== runId) {
+      throw new AgentRunAuthorizationError();
+    }
+    return binding;
+  }
+
+  async authorizeBrowser(
+    operationKey: string,
+    runId: string,
+    context: RequestGuardContext,
+  ) {
+    const binding = await this.repository.findByRunId(runId);
+    if (
+      !binding ||
+      binding.expiresAt <= this.now() ||
+      binding.actorId !== context.actor.id ||
+      binding.operationKey !== operationKey
+    ) {
+      throw new AgentRunAuthorizationError();
+    }
+    const scope = captureAuthorizationScope(context.actor.scopeContext);
+    if (scope.hash !== binding.scopeHash) {
+      throw new AgentRunAuthorizationError();
+    }
+    return binding;
+  }
+
+  assertCurrentScope(
+    binding: AgentRunBinding,
+    context: RequestGuardContext,
+  ): void {
+    const scope = captureAuthorizationScope(context.actor.scopeContext);
+    if (scope.hash !== binding.scopeHash) {
+      throw new AgentRunAuthorizationError();
+    }
+  }
+
+  async discard(authorization: AgentExecutionAuthorization) {
+    await this.repository.deleteUnbound(authorization.binding.bindingId);
+  }
+
+  private hmac(value: string) {
+    return createHmac("sha256", this.secret).update(value).digest("hex");
+  }
+}
+
+export class AgentRunAuthorizationError extends Error {
+  constructor() {
+    super("Agent Run 不存在或不可访问");
+  }
+}
+
+function sameAuthorization(
+  existing: AgentRunBinding,
+  candidate: AgentRunBinding,
+) {
+  return (
+    existing.bindingId === candidate.bindingId &&
+    existing.operationKey === candidate.operationKey &&
+    existing.actorId === candidate.actorId &&
+    existing.tokenHash === candidate.tokenHash &&
+    existing.scopeHash === candidate.scopeHash &&
+    sameSnapshot(
+      existing.authorizationSnapshot,
+      candidate.authorizationSnapshot,
+    ) &&
+    existing.releaseId === candidate.releaseId
+  );
+}
+
+function sameSnapshot(
+  left: AgentRunAuthorizationSnapshot,
+  right: AgentRunAuthorizationSnapshot,
+) {
+  return (
+    left.permissionKey === right.permissionKey &&
+    left.featureKey === right.featureKey &&
+    left.toolNetworkMode === right.toolNetworkMode &&
+    left.allowedToolKeys.length === right.allowedToolKeys.length &&
+    left.allowedToolKeys.every(
+      (key, index) => key === right.allowedToolKeys[index],
+    )
+  );
+}
+
+function sha256(value: string) {
+  return createHash("sha256").update(value).digest("hex");
+}

package/template/apps/server/src/agent/run-binding-repository.ts

@@ -0,0 +1,93 @@
+import type {
+  AgentRunAuthorizationSnapshot,
+  AuthorizationScopeSnapshot,
+} from "@southwind-ai/shared";
+
+export interface AgentRunBinding {
+  readonly bindingId: string;
+  readonly runId?: string;
+  readonly operationKey: string;
+  readonly actorId: string;
+  readonly idempotencyHash: string;
+  readonly tokenHash: string;
+  readonly scopeHash: string;
+  readonly scopeSnapshot: AuthorizationScopeSnapshot;
+  readonly authorizationSnapshot: AgentRunAuthorizationSnapshot;
+  readonly releaseId: string;
+  readonly createdAt: number;
+  readonly boundAt?: number;
+  readonly expiresAt: number;
+}
+
+export interface AgentRunBindingRepository {
+  createOrGet(binding: AgentRunBinding): Promise<AgentRunBinding>;
+  bind(
+    bindingId: string,
+    runId: string,
+    boundAt: number,
+  ): Promise<AgentRunBinding | undefined>;
+  findByRunId(runId: string): Promise<AgentRunBinding | undefined>;
+  findByTokenHash(tokenHash: string): Promise<AgentRunBinding | undefined>;
+  deleteUnbound(bindingId: string): Promise<void>;
+  prune(expiredBefore: number): Promise<void>;
+}
+
+export class InMemoryAgentRunBindingRepository implements AgentRunBindingRepository {
+  readonly #bindings = new Map<string, AgentRunBinding>();
+
+  async createOrGet(binding: AgentRunBinding) {
+    const existing = [...this.#bindings.values()].find(
+      ({ idempotencyHash }) => idempotencyHash === binding.idempotencyHash,
+    );
+    if (existing) return clone(existing);
+    this.#bindings.set(binding.bindingId, clone(binding));
+    return clone(binding);
+  }
+
+  async bind(bindingId: string, runId: string, boundAt: number) {
+    const binding = this.#bindings.get(bindingId);
+    const runOwner = [...this.#bindings.values()].find(
+      (current) => current.runId === runId,
+    );
+    if (
+      !binding ||
+      (binding.runId && binding.runId !== runId) ||
+      (runOwner && runOwner.bindingId !== bindingId)
+    ) {
+      return undefined;
+    }
+    const bound = { ...binding, runId, boundAt };
+    this.#bindings.set(bindingId, bound);
+    return clone(bound);
+  }
+
+  async findByRunId(runId: string) {
+    const found = [...this.#bindings.values()].find(
+      (binding) => binding.runId === runId,
+    );
+    return found ? clone(found) : undefined;
+  }
+
+  async findByTokenHash(tokenHash: string) {
+    const found = [...this.#bindings.values()].find(
+      (binding) => binding.tokenHash === tokenHash,
+    );
+    return found ? clone(found) : undefined;
+  }
+
+  async deleteUnbound(bindingId: string) {
+    if (!this.#bindings.get(bindingId)?.runId) {
+      this.#bindings.delete(bindingId);
+    }
+  }
+
+  async prune(expiredBefore: number) {
+    for (const [id, binding] of this.#bindings) {
+      if (binding.expiresAt <= expiredBefore) this.#bindings.delete(id);
+    }
+  }
+}
+
+function clone(binding: AgentRunBinding): AgentRunBinding {
+  return structuredClone(binding);
+}

package/template/apps/server/src/agent/run-contracts.ts

@@ -1,4 +1,5 @@
 import type {
+  AiOperationInputModality,
   AiProviderDataPolicy,
   AiProviderEgressPolicy,
   AiToolNetworkPolicy,
@@ -6,36 +7,104 @@ import type {
 import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
 
 export interface AgentRuntimeOperation {
+  kind: "agent";
   operationKey: string;
   input: ModuleAiJsonValue;
+  inputModalities: readonly AiOperationInputModality[];
+  requiredCapabilities: readonly string[];
+  artifacts: readonly AgentRuntimeArtifact[];
   instructions: string;
   userPrompt: string;
+  outputSchemaKey: string;
+  outputSchema?: ModuleAiJsonValue;
   allowedTools: Array<{
     key: string;
     label: string;
     description: string;
+    approval: "none" | "required";
+    idempotency: "none" | "supported" | "required";
+    approvalTimeoutSeconds?: number;
   }>;
   limits: {
     maxDurationSeconds: number;
+    maxInputBytes: number;
     maxOutputBytes: number;
+    maxArtifacts?: number;
+    maxPixelsPerArtifact?: number;
   };
   providerEgress: AiProviderEgressPolicy;
   providerDataPolicy: AiProviderDataPolicy;
   toolNetworkPolicy: AiToolNetworkPolicy;
   executionGrant: string;
+  release: AgentRuntimeRelease;
+  traceId: string;
+}
+
+export interface AgentRuntimeRelease {
+  readonly releaseId: string;
+  readonly operationVersion: string;
+  readonly workflowVersion: string;
+  readonly promptVersion: string;
+  readonly routeVersion: string;
+  readonly toolSchemaVersion: string;
+  readonly manifestDigest: string;
+}
+
+export interface AgentRuntimeArtifact {
+  readonly value: string;
+  readonly mediaType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
 }
 
 export interface AgentRuntimeStartResponse {
   runId: string;
-  status: string;
+  status: AgentRuntimeRunStatus;
   eventsUrl: string;
 }
 
+export type AgentRuntimeRunStatus =
+  | "accepted"
+  | "running"
+  | "awaiting-approval"
+  | "completed"
+  | "failed"
+  | "cancelled";
+
+export interface AgentRuntimeStatusResponse {
+  readonly runId: string;
+  readonly status: AgentRuntimeRunStatus;
+  readonly lastSequence: number;
+  readonly terminalEvent?: AgentRuntimeTerminalEvent;
+}
+
+export type AgentRuntimeTerminalEvent =
+  | {
+      readonly type: "run.completed" | "run.cancelled";
+      readonly runId: string;
+      readonly sequence: number;
+    }
+  | {
+      readonly type: "run.failed";
+      readonly runId: string;
+      readonly sequence: number;
+      readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly requestId: string;
+        readonly retryable: boolean;
+      };
+    };
+
 export interface AgentRuntimePort {
   start(
     request: AgentRuntimeOperation,
     idempotencyKey: string,
   ): Promise<AgentRuntimeStartResponse>;
+  status(
+    runId: string,
+    signal?: AbortSignal,
+  ): Promise<AgentRuntimeStatusResponse>;
   events(
     runId: string,
     cursor: number,
@@ -49,3 +118,21 @@ export interface AgentRuntimePort {
   ): Promise<Response>;
   health(signal?: AbortSignal): Promise<Response>;
 }
+
+export class AgentRuntimeError extends Error {
+  constructor(
+    readonly code:
+      | "CAPABILITY_UNAVAILABLE"
+      | "MODEL_ROUTE_UNAVAILABLE"
+      | "RUNTIME_UNAVAILABLE"
+      | "RUN_CONFLICT"
+      | "FORBIDDEN"
+      | "BUDGET_EXCEEDED"
+      | "INVALID_INPUT",
+    message: string,
+    readonly retryable: boolean,
+  ) {
+    super(message);
+    this.name = "AgentRuntimeError";
+  }
+}

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

@@ -0,0 +1,58 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { AgentRuntimeError } from "./run-contracts.js";
+import { AgentRunFacadeError } from "./run-errors.js";
+
+export function toolDefinitions(
+  modules: readonly ModuleManifest[],
+  allowedKeys: readonly string[],
+) {
+  const tools = new Map(
+    modules.flatMap(({ tools }) => tools.map((tool) => [tool.key, tool])),
+  );
+  return allowedKeys.map((key) => {
+    const tool = tools.get(key);
+    if (!tool) throw new Error(`AI Operation 引用了未知 Tool：${key}`);
+    return {
+      key: tool.key,
+      label: tool.label,
+      description: tool.description,
+      approval: tool.approval,
+      idempotency: tool.idempotency,
+      ...(tool.approvalTimeoutSeconds
+        ? { approvalTimeoutSeconds: tool.approvalTimeoutSeconds }
+        : {}),
+    };
+  });
+}
+
+export function assertInputSize(
+  value: ModuleAiJsonValue,
+  maxBytes: number,
+): void {
+  const size = new TextEncoder().encode(JSON.stringify(value)).byteLength;
+  if (size > maxBytes) {
+    throw new AgentRunFacadeError("INVALID_INPUT", "Agent 输入超过上限", 400);
+  }
+}
+
+export function digest(value: unknown): string {
+  return new Bun.CryptoHasher("sha256")
+    .update(JSON.stringify(value))
+    .digest("hex");
+}
+
+export function runtimeErrorStatus(code: AgentRuntimeError["code"]) {
+  if (code === "FORBIDDEN") return 403;
+  if (code === "RUN_CONFLICT") return 409;
+  if (code === "BUDGET_EXCEEDED" || code === "INVALID_INPUT") return 400;
+  return 503;
+}
+
+export function publicRunPath(
+  runId: string,
+  resource: "events" | "result" | "cancel",
+  operationKey: string,
+) {
+  return `/api/agent/runs/${encodeURIComponent(runId)}/${resource}?operationKey=${encodeURIComponent(operationKey)}`;
+}

package/template/apps/server/src/agent/run-errors.ts

@@ -0,0 +1,25 @@
+export class AgentRunFacadeError extends Error {
+  constructor(
+    readonly code:
+      | "OPERATION_NOT_FOUND"
+      | "INVALID_INPUT"
+      | "FORBIDDEN"
+      | "MODEL_ROUTE_UNAVAILABLE"
+      | "CAPABILITY_UNAVAILABLE"
+      | "RUN_CONFLICT"
+      | "BUDGET_EXCEEDED"
+      | "RUNTIME_UNAVAILABLE",
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+  }
+}
+
+export function inaccessibleRun() {
+  return new AgentRunFacadeError(
+    "RUN_CONFLICT",
+    "Agent Run 不存在或不可访问",
+    404,
+  );
+}

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

@@ -1,15 +1,12 @@
 import { describe, expect, test } from "bun:test";
 import type { ModuleManifest } from "@southwind-ai/modules";
 import { featureKey } from "@southwind-ai/shared";
-import type {
-  AgentRuntimeOperation,
-  AgentRuntimePort,
-} from "./run-contracts.js";
 import { buildScopeContext } from "../data-access/context.js";
 import { createRequestGuardContext } from "../guards.js";
 import { initializeModuleHosts } from "../module-host.js";
 import { createServerRuntime } from "../runtime.js";
-import { ExecutionGrantStore } from "./execution-grants.js";
+import { createTestRunAuthorizationStore } from "./run-authorization.test-support.js";
+import { FakeAgentRuntime } from "./fake-runtime.test-support.js";
 import { AgentRunFacade } from "./run-facade.js";
 
 describe("Guarded Agent Run facade", () => {
@@ -25,7 +22,7 @@ describe("Guarded Agent Run facade", () => {
     expect(created).toEqual({
       runId: "run_1",
       status: "accepted",
-      eventsUrl: "/api/agent/runs/run_1/events",
+      eventsUrl: "/api/agent/runs/run_1/events?operationKey=business.answer",
     });
     expect(fixture.remote.started).toHaveLength(1);
     expect(fixture.remote.started[0]).toMatchObject({
@@ -41,13 +38,29 @@ describe("Guarded Agent Run facade", () => {
           expect.objectContaining({ field: "instructions" }),
         ]),
       },
+      release: {
+        operationVersion: "0.1.0",
+        workflowVersion: "workflow-2",
+        promptVersion: "prompt-3",
+        routeVersion: "route-4",
+      },
+    });
+    expect(fixture.remote.started[0]?.release.releaseId).toMatch(
+      /^release_[a-f0-9]{40}$/,
+    );
+    expect(fixture.remote.started[0]?.traceId).toMatch(/^[a-f0-9]{32}$/);
+    expect(fixture.runtime.auditSink.list().at(-1)?.metadata).toMatchObject({
+      releaseId: fixture.remote.started[0]?.release.releaseId,
+      traceId: fixture.remote.started[0]?.traceId,
     });
     expect(fixture.remote.started[0]?.executionGrant).toMatch(/^grant_/);
     expect(fixture.remote.started[0]?.input).toEqual({ question: "你好" });
+    expect(fixture.remote.startedIdempotencyKeys[0]).toMatch(/^[a-f0-9]{64}$/);
+    expect(fixture.remote.startedIdempotencyKeys[0]).not.toBe("request-1");
     expect(JSON.stringify(fixture.prepared)).not.toContain("case-secret");
-    expect(() =>
-      fixture.facade.authorizeRun("run_1", fixture.context),
-    ).not.toThrow();
+    await expect(
+      fixture.facade.authorizeRun("business.answer", "run_1", fixture.context),
+    ).resolves.toBeDefined();
   });
 
   test("客户端输入不能覆盖 Operation、Tool 或授权", async () => {
@@ -83,36 +96,25 @@ describe("Guarded Agent Run facade", () => {
     expect(fixture.remote.started).toEqual([]);
     expect(fixture.prepared).toEqual([]);
   });
-});
 
-class FakeRuntime implements AgentRuntimePort {
-  readonly started: AgentRuntimeOperation[] = [];
+  test("恢复时权限已收回会返回不泄露 Run 存在性的 404", async () => {
+    const fixture = await createFixture();
+    await fixture.facade.start(
+      "business.answer",
+      { question: "稍后恢复" },
+      "request-revoked",
+      fixture.context,
+    );
 
-  start(request: AgentRuntimeOperation) {
-    this.started.push(request);
-    return Promise.resolve({
-      runId: "run_1",
-      status: "accepted",
-      eventsUrl: "/internal/events",
+    await expect(
+      fixture.facade.authorizeRun("business.answer", "run_1", guardContext([])),
+    ).rejects.toMatchObject({
+      code: "RUN_CONFLICT",
+      status: 404,
+      message: "Agent Run 不存在或不可访问",
     });
-  }
-
-  events() {
-    return Promise.resolve(new Response());
-  }
-
-  result() {
-    return Promise.resolve(new Response());
-  }
-
-  cancel() {
-    return Promise.resolve(new Response());
-  }
-
-  health() {
-    return Promise.resolve(new Response());
-  }
-}
+  });
+});
 
 async function createFixture(
   permissionKeys: string[] = ["business.ai.execute", "business.records.read"],
@@ -128,6 +130,11 @@ async function createFixture(
           host.registerAiOperationHandlers([
             {
               operationKey: "business.answer",
+              release: {
+                workflowVersion: "workflow-2",
+                promptVersion: "prompt-3",
+                routeVersion: "route-4",
+              },
               prepare(input, context) {
                 prepared.push({ input, actorId: context.actor.id });
                 const question =
@@ -155,7 +162,20 @@ async function createFixture(
       licenseResolver: { resolve: () => ({ status: "valid" }) },
     },
   );
-  const context = createRequestGuardContext(
+  const context = guardContext(permissionKeys);
+  const remote = new FakeAgentRuntime();
+  const facade = new AgentRunFacade(
+    [module],
+    hosts,
+    runtime,
+    remote,
+    createTestRunAuthorizationStore(),
+  );
+  return { context, facade, prepared, remote, runtime };
+}
+
+function guardContext(permissionKeys: string[]) {
+  return createRequestGuardContext(
     new Request("http://localhost/api/agent/runs"),
     {
       resolveActor: () => ({
@@ -176,15 +196,6 @@ async function createFixture(
       resolveLicense: () => ({ status: "valid" }),
     },
   );
-  const remote = new FakeRuntime();
-  const facade = new AgentRunFacade(
-    [module],
-    hosts,
-    runtime,
-    remote,
-    new ExecutionGrantStore(),
-  );
-  return { context, facade, prepared, remote };
 }
 
 function manifest(): ModuleManifest {