create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/agent/client-session/fixtures/page-agent-1.12.2-request.json

@@ -0,0 +1,52 @@
+{
+  "model": "windy-client-agent-v1",
+  "messages": [
+    { "role": "system", "content": "你是网页操作代理。" },
+    { "role": "user", "content": "读取页面并返回标题。" },
+    {
+      "role": "assistant",
+      "content": null,
+      "tool_calls": [
+        {
+          "id": "call_read_1",
+          "type": "function",
+          "function": { "name": "read_page", "arguments": "{}" }
+        }
+      ]
+    },
+    {
+      "role": "tool",
+      "tool_call_id": "call_read_1",
+      "name": "read_page",
+      "content": "{\"title\":\"Windy\"}"
+    }
+  ],
+  "tools": [
+    {
+      "type": "function",
+      "function": {
+        "name": "read_page",
+        "description": "读取当前页面",
+        "parameters": { "type": "object", "properties": {} }
+      }
+    },
+    {
+      "type": "function",
+      "function": {
+        "name": "AgentOutput",
+        "description": "提交最终回答",
+        "parameters": {
+          "type": "object",
+          "properties": { "answer": { "type": "string" } },
+          "required": ["answer"]
+        }
+      }
+    }
+  ],
+  "tool_choice": {
+    "type": "function",
+    "function": { "name": "AgentOutput" }
+  },
+  "parallel_tool_calls": false,
+  "stream": true
+}

package/template/apps/server/src/agent/client-session/host-auth.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleClientAgentHostAuthAdapter } from "@southwind-ai/server-sdk";
+import { createServerRuntime } from "../../runtime.js";
+import type { RouteApp } from "../../system/route-types.js";
+import {
+  createClientAgentHostAuthRouteApp,
+  type ClientAgentHostContext,
+} from "./host-auth.js";
+
+describe("Browser Assistant Host Auth Adapter", () => {
+  test("bax_ 只在 Client Agent route 解析 canonical Actor", async () => {
+    const fixture = createFixture();
+    fixture.app.get("/agent/client-sessions/capabilities", (raw) => {
+      const context = raw as {
+        guardContext: { actor: { id: string; permissionKeys: string[] } };
+        clientAgentHost: ClientAgentHostContext;
+      };
+      return {
+        actorId: context.guardContext.actor.id,
+        permissions: context.guardContext.actor.permissionKeys,
+        digest: context.clientAgentHost.hostSessionDigest,
+      };
+    });
+    const response = await fixture.invoke(
+      "/agent/client-sessions/capabilities",
+      new Request(
+        "https://windy.example/api/agent/client-sessions/capabilities",
+        {
+          headers: { authorization: "Bearer bax_paired" },
+        },
+      ),
+    );
+    expect(response).toMatchObject({
+      actorId: "actor-1",
+      permissions: ["system.agent.read"],
+    });
+    expect(fixture.purposes).toEqual(["control"]);
+  });
+
+  test("completion 分离 car_ 与 bax_，错误 token fail closed", async () => {
+    const fixture = createFixture();
+    const path = "/agent/client-sessions/:sessionId/v1/chat/completions";
+    fixture.app.post(path, () => ({ ok: true }));
+    const accepted = await fixture.invoke(
+      path,
+      new Request(
+        "https://windy.example/api/agent/client-sessions/cas_1/v1/chat/completions",
+        {
+          method: "POST",
+          headers: {
+            authorization: "Bearer car_single-run",
+            "x-windy-host-authorization": "Bearer bax_paired",
+          },
+        },
+      ),
+    );
+    expect(accepted).toEqual({ ok: true });
+    expect(fixture.purposes).toEqual(["completion"]);
+
+    const rejected = await fixture.invoke(
+      path,
+      new Request(
+        "https://windy.example/api/agent/client-sessions/cas_1/v1/chat/completions",
+        {
+          method: "POST",
+          headers: { authorization: "Bearer car_single-run" },
+        },
+      ),
+    );
+    expect(rejected).toBeInstanceOf(Response);
+    expect((rejected as Response).status).toBe(404);
+  });
+
+  test("Host Auth 未 ready 时 capability 不协商", async () => {
+    const fixture = createFixture(false);
+    fixture.app.get("/agent/client-sessions/capabilities", () => ({
+      capabilities: ["pageAgentClientRun"],
+    }));
+    const response = await fixture.invoke(
+      "/agent/client-sessions/capabilities",
+      new Request(
+        "https://windy.example/api/agent/client-sessions/capabilities",
+        {
+          headers: { authorization: "Bearer bax_paired" },
+        },
+      ),
+    );
+    expect(response).toBeInstanceOf(Response);
+    expect((response as Response).status).toBe(503);
+  });
+});
+
+function createFixture(ready = true) {
+  const handlers = new Map<string, (context: unknown) => unknown>();
+  const routes: RouteApp = {
+    get: (path, handler) => handlers.set(path, handler),
+    post: (path, handler) => handlers.set(path, handler),
+    put: (path, handler) => handlers.set(path, handler),
+    delete: (path, handler) => handlers.set(path, handler),
+  };
+  const purposes: string[] = [];
+  const adapter: ModuleClientAgentHostAuthAdapter = {
+    ready: async () => ready,
+    async authenticate(input) {
+      purposes.push(input.purpose);
+      return input.token === "bax_paired"
+        ? {
+            actorId: "actor-1",
+            installationId: "installation-1",
+            sessionId: "session-1",
+          }
+        : undefined;
+    },
+    bindRevocations: () => () => undefined,
+  };
+  const runtime = createServerRuntime(
+    { NODE_ENV: "test" },
+    { licenseEnforced: false },
+  );
+  const app = createClientAgentHostAuthRouteApp({
+    app: routes,
+    adapter,
+    runtime,
+    resolveActor: async (actorId) => ({
+      id: actorId,
+      type: "user",
+      name: "利剑用户",
+      roleCodes: ["operator"],
+      permissionKeys: ["system.agent.read"],
+    }),
+  });
+  return {
+    app,
+    purposes,
+    async invoke(path: string, request: Request) {
+      const handler = handlers.get(path);
+      if (!handler) throw new Error("route missing");
+      return handler({
+        request,
+        guardContext: await runtime.createGuardContext(request),
+      });
+    },
+  };
+}

package/template/apps/server/src/agent/client-session/host-auth.ts

@@ -0,0 +1,122 @@
+import type {
+  ModuleClientAgentHostAuthAdapter,
+  ModuleClientAgentHostPrincipal,
+} from "@southwind-ai/server-sdk";
+import type { RequestActor, RequestGuardContext } from "../../guards.js";
+import type { createServerRuntime } from "../../runtime.js";
+import type { RouteApp } from "../../system/route-types.js";
+import { digestJson } from "./digest.js";
+import { ClientAgentSessionError } from "./errors.js";
+
+export interface ClientAgentHostContext {
+  readonly principal: ModuleClientAgentHostPrincipal;
+  readonly hostSessionDigest: `sha256:${string}`;
+}
+
+export function hostSessionDigest(
+  principal: ModuleClientAgentHostPrincipal,
+): `sha256:${string}` {
+  return digestJson({
+    actorId: principal.actorId,
+    installationId: principal.installationId,
+    sessionId: principal.sessionId,
+  });
+}
+
+export function createClientAgentHostAuthRouteApp(input: {
+  app: RouteApp;
+  adapter: ModuleClientAgentHostAuthAdapter;
+  runtime: ReturnType<typeof createServerRuntime>;
+  resolveActor(actorId: string): Promise<RequestActor | undefined>;
+}): RouteApp {
+  const wrap =
+    (path: string, handler: (context: unknown) => unknown) =>
+    async (raw: unknown) => {
+      try {
+        const context = raw as {
+          request: Request;
+          guardContext: RequestGuardContext;
+        };
+        if (!(await input.adapter.ready(context.request.signal)))
+          throw unavailable();
+        const purpose = isCompletion(path) ? "completion" : "control";
+        const token = hostToken(context.request);
+        const principal = token
+          ? await input.adapter.authenticate({
+              token,
+              purpose,
+              signal: context.request.signal,
+            })
+          : context.guardContext.actor.type !== "anonymous"
+            ? await input.adapter.authenticateCurrentSession?.({
+                request: context.request,
+                actorId: context.guardContext.actor.id,
+                purpose,
+                signal: context.request.signal,
+              })
+            : undefined;
+        const actor = principal
+          ? await input.resolveActor(principal.actorId)
+          : undefined;
+        if (!principal || !actor || actor.type === "anonymous") throw hidden();
+        const guardContext = await input.runtime.createGuardContextForActor(
+          context.request,
+          actor,
+          { clientIp: context.guardContext.clientIp },
+        );
+        return handler({
+          ...(raw as object),
+          guardContext,
+          clientAgentHost: {
+            principal,
+            hostSessionDigest: hostSessionDigest(principal),
+          } satisfies ClientAgentHostContext,
+        });
+      } catch (error) {
+        if (error instanceof ClientAgentSessionError) {
+          return Response.json(
+            { code: error.code, message: error.message, retryable: false },
+            { status: error.status },
+          );
+        }
+        return Response.json(
+          { code: "INTERNAL_ERROR", message: "Host Auth 校验失败" },
+          { status: 500 },
+        );
+      }
+    };
+  return {
+    get: (path, handler) => input.app.get(path, wrap(path, handler)),
+    post: (path, handler, options) =>
+      input.app.post(path, wrap(path, handler), options),
+    put: (path, handler, options) =>
+      input.app.put(path, wrap(path, handler), options),
+    delete: (path, handler) => input.app.delete(path, wrap(path, handler)),
+  };
+}
+
+function hostToken(request: Request): string | undefined {
+  const header =
+    request.headers.get("x-windy-host-authorization") ??
+    request.headers.get("authorization");
+  const token = header?.match(/^Bearer\s+(.+)$/iu)?.[1];
+  if (!token || token.startsWith("car_")) return undefined;
+  if (!token.startsWith("bax_")) throw hidden();
+  return token;
+}
+
+function isCompletion(path: string): boolean {
+  return path.endsWith("/v1/chat/completions");
+}
+
+function hidden(): ClientAgentSessionError {
+  return new ClientAgentSessionError("NOT_FOUND", "会话不存在或不可访问", 404);
+}
+
+function unavailable(): ClientAgentSessionError {
+  return new ClientAgentSessionError(
+    "PROVIDER_FAILED",
+    "Browser Assistant Host Auth 尚未就绪",
+    503,
+  );
+}

package/template/apps/server/src/agent/client-session/host-revocation-composition.test.ts

@@ -0,0 +1,77 @@
+import { expect, test } from "bun:test";
+import type {
+  ModuleClientAgentHostAuthAdapter,
+  ModuleClientAgentHostPrincipal,
+} from "@southwind-ai/server-sdk";
+import { bindClientAgentHostRevocations } from "./host-revocation-composition.js";
+
+test("单监听 Host Auth Adapter 通过 Composition fan-out 撤销 Session 与 Workflow", async () => {
+  let listener:
+    | ((principal: ModuleClientAgentHostPrincipal) => Promise<void> | void)
+    | undefined;
+  const adapter = {
+    ready: async () => true,
+    authenticate: async () => undefined,
+    bindRevocations(next) {
+      listener = next;
+      return () => {
+        listener = undefined;
+      };
+    },
+  } satisfies ModuleClientAgentHostAuthAdapter;
+  const calls: string[] = [];
+  const dispose = bindClientAgentHostRevocations({
+    adapter,
+    revokeSessionHost: async () => {
+      calls.push("session");
+    },
+    revokeWorkflowHost: async () => {
+      calls.push("workflow");
+    },
+  });
+
+  await listener?.({
+    actorId: "actor-1",
+    installationId: "installation-1",
+    sessionId: "host-session-1",
+  });
+  expect(calls).toEqual(["session", "workflow"]);
+  dispose?.();
+  expect(listener).toBeUndefined();
+});
+
+test("Session 撤销失败时仍尝试 Workflow 撤销并汇总失败", async () => {
+  let listener:
+    | ((principal: ModuleClientAgentHostPrincipal) => Promise<void> | void)
+    | undefined;
+  const adapter = {
+    ready: async () => true,
+    authenticate: async () => undefined,
+    bindRevocations(next) {
+      listener = next;
+      return () => {
+        listener = undefined;
+      };
+    },
+  } satisfies ModuleClientAgentHostAuthAdapter;
+  const calls: string[] = [];
+  bindClientAgentHostRevocations({
+    adapter,
+    revokeSessionHost: async () => {
+      calls.push("session");
+      throw new Error("session revoke failed");
+    },
+    revokeWorkflowHost: async () => {
+      calls.push("workflow");
+    },
+  });
+
+  await expect(
+    listener?.({
+      actorId: "actor-1",
+      installationId: "installation-1",
+      sessionId: "host-session-1",
+    }),
+  ).rejects.toBeInstanceOf(AggregateError);
+  expect(calls).toEqual(["session", "workflow"]);
+});

package/template/apps/server/src/agent/client-session/host-revocation-composition.ts

@@ -0,0 +1,28 @@
+import type {
+  ModuleClientAgentHostAuthAdapter,
+  ModuleClientAgentHostPrincipal,
+} from "@southwind-ai/server-sdk";
+
+export function bindClientAgentHostRevocations(input: {
+  adapter?: ModuleClientAgentHostAuthAdapter;
+  revokeSessionHost?(
+    principal: ModuleClientAgentHostPrincipal,
+  ): Promise<unknown>;
+  revokeWorkflowHost?(
+    principal: ModuleClientAgentHostPrincipal,
+  ): Promise<unknown>;
+}) {
+  return input.adapter?.bindRevocations(async (principal) => {
+    const errors: unknown[] = [];
+    for (const revoke of [input.revokeSessionHost, input.revokeWorkflowHost]) {
+      try {
+        await revoke?.(principal);
+      } catch (error) {
+        errors.push(error);
+      }
+    }
+    if (errors.length) {
+      throw new AggregateError(errors, "Client Agent Host 撤销未完全收敛");
+    }
+  });
+}

package/template/apps/server/src/agent/client-session/launch-authority.contract.test.ts

@@ -0,0 +1,21 @@
+import { expect, test } from "bun:test";
+import { createFixture } from "./service.test-support.js";
+import { binding, hostSession } from "./service.test-support.js";
+
+test("普通 Client Session create 不能启动 workflow-only Operation", async () => {
+  const fixture = await createFixture();
+  const input = {
+    operationKey: "analysis.page-agent",
+    input: { question: "绕过 Workflow" },
+    clientBindingDigest: binding,
+    hostSessionDigest: hostSession,
+    actorId: "actor-1",
+  } as const;
+
+  await expect(fixture.service.create(input)).rejects.toMatchObject({
+    code: "FORBIDDEN",
+  });
+  await expect(fixture.service.createWorkflow(input)).resolves.toMatchObject({
+    capabilities: ["pageAgentClientRun"],
+  });
+});

package/template/apps/server/src/agent/client-session/manifest-admission.ts

@@ -0,0 +1,251 @@
+import Ajv, { type ValidateFunction } from "ajv";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import { evaluateAccessGuards } from "../../access-guards.js";
+import { captureAuthorizationScope } from "../../data-access/scope-snapshot.js";
+import type { RequestGuardContext } from "../../guards.js";
+import type { InitializedModuleHosts } from "../../module-host.js";
+import type { createServerRuntime } from "../../runtime.js";
+import {
+  governProviderInput,
+  projectProviderInput,
+  ProviderInputGovernanceError,
+} from "../provider-input-governance.js";
+import {
+  buildRegisteredOperations,
+  type RegisteredOperation,
+} from "../run-operation-registry.js";
+import type {
+  ClientSessionAdmissionPort,
+  ClientSessionRecord,
+} from "./contracts.js";
+import { digestJson, sameSecret } from "./digest.js";
+import { ClientAgentSessionError } from "./errors.js";
+
+type ServerRuntime = Pick<
+  ReturnType<typeof createServerRuntime>,
+  "recordDecisions" | "resolveFeature"
+>;
+
+export class ManifestClientSessionAdmission implements ClientSessionAdmissionPort {
+  readonly #operations: Map<string, RegisteredOperation>;
+  readonly #inputValidators = new Map<string, ValidateFunction>();
+  readonly #validators = new Map<string, ValidateFunction>();
+
+  constructor(
+    modules: readonly ModuleManifest[],
+    hosts: InitializedModuleHosts,
+    private readonly runtime: ServerRuntime,
+    private readonly resolveContext: (
+      actorId: string,
+    ) => Promise<RequestGuardContext>,
+  ) {
+    this.#operations = buildRegisteredOperations(modules, hosts);
+    const ajv = new Ajv({ allErrors: true, strict: true });
+    const schemas = new Map(
+      modules.flatMap(({ jsonSchemas }) =>
+        (jsonSchemas ?? []).map(({ key, schema }) => [key, schema] as const),
+      ),
+    );
+    for (const [key, operation] of this.#operations) {
+      const inputSchema = schemas.get(operation.definition.inputSchemaKey);
+      if (inputSchema) {
+        this.#inputValidators.set(key, ajv.compile(inputSchema));
+      }
+      if (operation.outputSchema) {
+        this.#validators.set(key, ajv.compile(operation.outputSchema));
+      }
+    }
+  }
+
+  async admit(input: {
+    operationKey: string;
+    input: ModuleAiJsonValue;
+    clientBindingDigest: `sha256:${string}`;
+    actorId: string;
+    launchAuthority: "direct" | "workflow-artifact";
+  }) {
+    const operation = this.operation(input.operationKey);
+    if (
+      (operation.definition.clientExecution!.launchAuthority ?? "direct") !==
+      input.launchAuthority
+    ) {
+      throw new ClientAgentSessionError(
+        "FORBIDDEN",
+        "Operation 不允许从当前入口启动 Client Agent Session",
+        403,
+      );
+    }
+    const context = await this.resolveContext(input.actorId);
+    await this.authorize(operation, context, input.actorId);
+    const inputBytes = new TextEncoder().encode(
+      JSON.stringify(input.input),
+    ).byteLength;
+    if (
+      inputBytes > operation.definition.limits.maxInputBytes ||
+      !this.#inputValidators.get(input.operationKey)?.(input.input)
+    ) {
+      throw new ClientAgentSessionError(
+        "INVALID_INPUT",
+        "Client Agent 输入不符合 Operation schema 或字节上限",
+        400,
+      );
+    }
+    const policy = operation.definition.providerDataPolicy!;
+    try {
+      governProviderInput(input.input, policy);
+    } catch (error) {
+      if (error instanceof ProviderInputGovernanceError) {
+        throw new ClientAgentSessionError(
+          error.code,
+          error.message,
+          error.code === "FORBIDDEN" ? 403 : 400,
+        );
+      }
+      throw error;
+    }
+    return {
+      actorId: input.actorId,
+      operationKey: input.operationKey,
+      releaseId: operation.release.releaseId,
+      inputCommitment: digestJson(projectProviderInput(input.input, policy)),
+      authorizationDigest: authorizationDigest(context, operation),
+      clientBindingDigest: input.clientBindingDigest,
+      deploymentKey: configuredDeploymentKey(operation),
+      providerDataPolicy: policy,
+      limits: {
+        ...operation.definition.clientExecution!,
+        maxDurationSeconds: operation.definition.limits.maxDurationSeconds,
+      },
+    };
+  }
+
+  async reauthorize(
+    session: ClientSessionRecord,
+    actorId: string,
+  ): Promise<boolean> {
+    try {
+      const operation = this.operation(session.operationKey);
+      if (operation.release.releaseId !== session.releaseId) return false;
+      const context = await this.resolveContext(actorId);
+      await this.authorize(operation, context, actorId);
+      return sameSecret(
+        authorizationDigest(context, operation),
+        session.authorizationDigest,
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  validateResult(operationKey: string, result: ModuleAiJsonValue): void {
+    const validate = this.#validators.get(operationKey);
+    if (!validate || !validate(result)) {
+      throw new ClientAgentSessionError(
+        "INVALID_INPUT",
+        "Client Agent 公开结果不符合 Operation output schema",
+        400,
+      );
+    }
+  }
+
+  projectProviderResult(
+    operationKey: string,
+    response: ModuleAiJsonValue,
+  ): ModuleAiJsonValue | undefined {
+    const content = firstAssistantContent(response);
+    if (content === undefined) return undefined;
+    const candidates: ModuleAiJsonValue[] = [];
+    try {
+      candidates.push(JSON.parse(content) as ModuleAiJsonValue);
+    } catch {
+      candidates.push({ text: content });
+    }
+    const validate = this.#validators.get(operationKey);
+    return candidates.find((candidate) => validate?.(candidate));
+  }
+
+  private operation(operationKey: string): RegisteredOperation {
+    const operation = this.#operations.get(operationKey);
+    if (
+      !operation ||
+      operation.definition.kind !== "agent" ||
+      !operation.definition.clientExecution ||
+      operation.definition.providerEgress?.mode !== "configured-endpoint" ||
+      !operation.definition.providerDataPolicy
+    ) {
+      throw new ClientAgentSessionError(
+        "FORBIDDEN",
+        "Operation 未开放 Client Agent Session",
+        403,
+      );
+    }
+    return operation;
+  }
+
+  private async authorize(
+    operation: RegisteredOperation,
+    context: RequestGuardContext,
+    actorId: string,
+  ): Promise<void> {
+    if (context.actor.id !== actorId || context.actor.type === "anonymous") {
+      throw new ClientAgentSessionError("FORBIDDEN", "Actor 认证失效", 403);
+    }
+    const decision = await evaluateAccessGuards(this.runtime, context, {
+      permission: { permissionKey: operation.definition.permissionKey },
+      feature: operation.feature,
+    });
+    if (!decision.decision.allowed) {
+      throw new ClientAgentSessionError(
+        "FORBIDDEN",
+        "无权执行 Client Agent Operation",
+        403,
+      );
+    }
+  }
+}
+
+function configuredDeploymentKey(operation: RegisteredOperation): string {
+  const egress = operation.definition.providerEgress;
+  if (egress?.mode !== "configured-endpoint") {
+    throw new ClientAgentSessionError(
+      "FORBIDDEN",
+      "Operation 未配置 Provider Deployment",
+      403,
+    );
+  }
+  return egress.deploymentKey;
+}
+
+function authorizationDigest(
+  context: RequestGuardContext,
+  operation: RegisteredOperation,
+): `sha256:${string}` {
+  return digestJson({
+    actorId: context.actor.id,
+    permissionKey: operation.definition.permissionKey,
+    featureKey: operation.definition.featureKey,
+    permissionKeys: [...context.actor.permissionKeys].sort(),
+    scopeHash: captureAuthorizationScope(context.actor.scopeContext).hash,
+    licenseVersion: context.license?.versionKey ?? null,
+    licenseStatus: context.license?.status ?? null,
+    releaseId: operation.release.releaseId,
+  });
+}
+
+function firstAssistantContent(
+  response: ModuleAiJsonValue,
+): string | undefined {
+  if (!isRecord(response) || !Array.isArray(response.choices)) return undefined;
+  const first = response.choices[0];
+  if (!isRecord(first) || !isRecord(first.message)) return undefined;
+  return typeof first.message.content === "string"
+    ? first.message.content
+    : undefined;
+}
+
+function isRecord(
+  value: ModuleAiJsonValue,
+): value is Record<string, ModuleAiJsonValue> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}