create-windy 0.6.11 → 0.6.14

package/template/apps/server/src/agent/client-session/drizzle-repository.ts

@@ -0,0 +1,345 @@
+import {
+  clientAgentReceipts,
+  clientAgentSessions,
+} from "@southwind-ai/database";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import { and, asc, eq, sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type {
+  ClientSessionAdmission,
+  ClientSessionFinalResult,
+  ClientSessionReceiptRecord,
+  ClientSessionRecord,
+  ClientSessionStatus,
+} from "./contracts.js";
+import { receiptMatches, type ClientSessionRepository } from "./repository.js";
+import { sameSecret } from "./digest.js";
+
+type SessionRow = typeof clientAgentSessions.$inferSelect;
+type ReceiptRow = typeof clientAgentReceipts.$inferSelect;
+
+export class DrizzleClientSessionRepository implements ClientSessionRepository {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async recoverInterrupted(now: number): Promise<number> {
+    return this.db.transaction(async (transaction) => {
+      await transaction
+        .update(clientAgentSessions)
+        .set({ status: "expired", activeRequests: 0, pendingAttempts: [] })
+        .where(
+          and(
+            eq(clientAgentSessions.status, "active"),
+            sql`${clientAgentSessions.expiresAt} <= ${now}`,
+          ),
+        );
+      const recovered = await transaction
+        .update(clientAgentSessions)
+        .set({ activeRequests: 0, pendingAttempts: [] })
+        .where(
+          and(
+            eq(clientAgentSessions.status, "active"),
+            sql`${clientAgentSessions.activeRequests} > 0`,
+          ),
+        )
+        .returning({ sessionId: clientAgentSessions.sessionId });
+      return recovered.length;
+    });
+  }
+
+  async create(record: ClientSessionRecord): Promise<void> {
+    await this.db.insert(clientAgentSessions).values(sessionValues(record));
+  }
+
+  find(sessionId: string): Promise<ClientSessionRecord | undefined> {
+    return findRecord(this.db, sessionId);
+  }
+
+  async reserveAttempt(
+    input: Parameters<ClientSessionRepository["reserveAttempt"]>[0],
+  ) {
+    return this.lock(input.sessionId, async (db) => {
+      const record = await findRecord(db, input.sessionId);
+      if (
+        !record ||
+        record.status !== "active" ||
+        record.expiresAt <= input.now ||
+        !sameSecret(record.tokenHash, input.tokenHash) ||
+        record.actorId !== input.actorId ||
+        !sameSecret(record.clientBindingDigest, input.clientBindingDigest) ||
+        !sameSecret(record.hostSessionDigest, input.hostSessionDigest) ||
+        record.attemptCount >= record.limits.maxSteps ||
+        record.activeRequests >= record.limits.maxConcurrentRequests
+      ) {
+        return undefined;
+      }
+      const attempt = record.attemptCount + 1;
+      const [updated] = await db
+        .update(clientAgentSessions)
+        .set({
+          attemptCount: attempt,
+          activeRequests: record.activeRequests + 1,
+          pendingAttempts: [...record.pendingAttempts, attempt],
+        })
+        .where(eq(clientAgentSessions.sessionId, input.sessionId))
+        .returning();
+      return updated ? mapRecord(updated, record.receipts) : undefined;
+    });
+  }
+
+  async completeAttempt(
+    sessionId: string,
+    receipt: ClientSessionReceiptRecord,
+  ) {
+    return this.lock(sessionId, async (db) => {
+      const record = await findRecord(db, sessionId);
+      if (
+        !record ||
+        record.status !== "active" ||
+        record.activeRequests < 1 ||
+        !record.pendingAttempts.includes(receipt.attempt) ||
+        !receiptMatches(record, receipt)
+      ) {
+        return undefined;
+      }
+      await db
+        .insert(clientAgentReceipts)
+        .values(receiptValues(sessionId, receipt));
+      const [updated] = await db
+        .update(clientAgentSessions)
+        .set({
+          activeRequests: record.activeRequests - 1,
+          pendingAttempts: record.pendingAttempts.filter(
+            (attempt) => attempt !== receipt.attempt,
+          ),
+        })
+        .where(eq(clientAgentSessions.sessionId, sessionId))
+        .returning();
+      return updated
+        ? mapRecord(updated, [...record.receipts, receipt])
+        : undefined;
+    });
+  }
+
+  async failAttempt(sessionId: string, attempt: number): Promise<void> {
+    await this.lock(sessionId, async (db) => {
+      const record = await findRecord(db, sessionId);
+      if (
+        !record ||
+        record.activeRequests < 1 ||
+        !record.pendingAttempts.includes(attempt)
+      ) {
+        return;
+      }
+      await db
+        .update(clientAgentSessions)
+        .set({
+          activeRequests: record.activeRequests - 1,
+          pendingAttempts: record.pendingAttempts.filter(
+            (pending) => pending !== attempt,
+          ),
+        })
+        .where(eq(clientAgentSessions.sessionId, sessionId));
+    });
+  }
+
+  async transition(
+    sessionId: string,
+    expected: "active",
+    status: ClientSessionStatus,
+    patch: Pick<ClientSessionRecord, "terminalDigest" | "finalResult"> = {},
+  ) {
+    return this.lock(sessionId, async (db) => {
+      const record = await findRecord(db, sessionId);
+      if (
+        !record ||
+        record.status !== expected ||
+        (status === "completed" && record.activeRequests > 0)
+      ) {
+        return undefined;
+      }
+      const [updated] = await db
+        .update(clientAgentSessions)
+        .set({
+          status,
+          activeRequests: 0,
+          pendingAttempts: [],
+          terminalDigest: patch.terminalDigest,
+          finalResultJson: patch.finalResult as
+            | Record<string, unknown>
+            | undefined,
+        })
+        .where(eq(clientAgentSessions.sessionId, sessionId))
+        .returning();
+      return updated ? mapRecord(updated, record.receipts) : undefined;
+    });
+  }
+
+  revokeActor(actorId: string) {
+    return this.revokeBy(eq(clientAgentSessions.actorId, actorId));
+  }
+
+  revokeBinding(bindingDigest: `sha256:${string}`, actorId: string) {
+    return this.revokeBy(
+      and(
+        eq(clientAgentSessions.actorId, actorId),
+        eq(clientAgentSessions.clientBindingDigest, bindingDigest),
+      )!,
+    );
+  }
+
+  revokeHostSession(hostSessionDigest: `sha256:${string}`, actorId: string) {
+    return this.revokeBy(
+      and(
+        eq(clientAgentSessions.actorId, actorId),
+        eq(clientAgentSessions.hostSessionDigest, hostSessionDigest),
+      )!,
+    );
+  }
+
+  private async revokeBy(
+    predicate: ReturnType<typeof eq>,
+  ): Promise<ClientSessionRecord[]> {
+    const updated = await this.db
+      .update(clientAgentSessions)
+      .set({ status: "revoked", activeRequests: 0, pendingAttempts: [] })
+      .where(and(eq(clientAgentSessions.status, "active"), predicate))
+      .returning();
+    return Promise.all(updated.map((row) => hydrateRecord(this.db, row)));
+  }
+
+  private lock<T>(
+    sessionId: string,
+    callback: (db: NodePgDatabase) => Promise<T>,
+  ): Promise<T> {
+    return this.db.transaction(async (transaction) => {
+      await transaction.execute(
+        sql`select session_id from client_agent_sessions where session_id = ${sessionId} for update`,
+      );
+      return callback(transaction as unknown as NodePgDatabase);
+    });
+  }
+}
+
+async function findRecord(db: NodePgDatabase, sessionId: string) {
+  const [row] = await db
+    .select()
+    .from(clientAgentSessions)
+    .where(eq(clientAgentSessions.sessionId, sessionId))
+    .limit(1);
+  return row ? hydrateRecord(db, row) : undefined;
+}
+
+async function hydrateRecord(db: NodePgDatabase, row: SessionRow) {
+  const receipts = await db
+    .select()
+    .from(clientAgentReceipts)
+    .where(eq(clientAgentReceipts.sessionId, row.sessionId))
+    .orderBy(asc(clientAgentReceipts.attempt));
+  return mapRecord(row, receipts.map(mapReceipt));
+}
+
+function sessionValues(record: ClientSessionRecord) {
+  const admission: ClientSessionAdmission = {
+    actorId: record.actorId,
+    operationKey: record.operationKey,
+    releaseId: record.releaseId,
+    inputCommitment: record.inputCommitment,
+    authorizationDigest: record.authorizationDigest,
+    clientBindingDigest: record.clientBindingDigest,
+    deploymentKey: record.deploymentKey,
+    providerDataPolicy: record.providerDataPolicy,
+    limits: record.limits,
+  };
+  return {
+    sessionId: record.sessionId,
+    clientRunId: record.clientRunId,
+    actorId: record.actorId,
+    operationKey: record.operationKey,
+    releaseId: record.releaseId,
+    tokenHash: record.tokenHash,
+    clientBindingDigest: record.clientBindingDigest,
+    hostSessionDigest: record.hostSessionDigest,
+    modelAlias: record.modelAlias,
+    status: record.status,
+    attemptCount: record.attemptCount,
+    activeRequests: record.activeRequests,
+    pendingAttempts: [...record.pendingAttempts],
+    admissionJson: admission as unknown as Record<string, unknown>,
+    terminalDigest: record.terminalDigest,
+    finalResultJson: record.finalResult as Record<string, unknown> | undefined,
+    createdAt: record.createdAt,
+    expiresAt: record.expiresAt,
+  };
+}
+
+function mapRecord(
+  row: SessionRow,
+  receipts: readonly ClientSessionReceiptRecord[],
+): ClientSessionRecord {
+  const admission = row.admissionJson as unknown as ClientSessionAdmission;
+  return {
+    ...admission,
+    sessionId: row.sessionId,
+    clientRunId: row.clientRunId,
+    actorId: row.actorId,
+    operationKey: row.operationKey,
+    releaseId: row.releaseId,
+    tokenHash: row.tokenHash as `sha256:${string}`,
+    clientBindingDigest: row.clientBindingDigest as `sha256:${string}`,
+    hostSessionDigest: row.hostSessionDigest as `sha256:${string}`,
+    modelAlias: row.modelAlias,
+    status: row.status as ClientSessionStatus,
+    attemptCount: row.attemptCount,
+    activeRequests: row.activeRequests,
+    pendingAttempts: row.pendingAttempts,
+    receipts,
+    createdAt: row.createdAt,
+    expiresAt: row.expiresAt,
+    ...(row.terminalDigest
+      ? { terminalDigest: row.terminalDigest as `sha256:${string}` }
+      : {}),
+    ...(row.finalResultJson
+      ? {
+          finalResult:
+            row.finalResultJson as unknown as ClientSessionFinalResult,
+        }
+      : {}),
+  };
+}
+
+function receiptValues(sessionId: string, receipt: ClientSessionReceiptRecord) {
+  return {
+    receiptId: receipt.receiptId,
+    sessionId,
+    clientRunId: receipt.clientRunId,
+    actorId: receipt.actorId,
+    operationKey: receipt.operationKey,
+    releaseId: receipt.releaseId,
+    clientBindingDigest: receipt.clientBindingDigest,
+    attempt: receipt.attempt,
+    requestDigest: receipt.requestDigest,
+    responseDigest: receipt.responseDigest,
+    deploymentDigest: receipt.deploymentDigest,
+    canonicalResultJson: receipt.canonicalResult,
+    issuedAt: receipt.issuedAt,
+  };
+}
+
+function mapReceipt(row: ReceiptRow): ClientSessionReceiptRecord {
+  return {
+    receiptId: row.receiptId,
+    clientRunId: row.clientRunId,
+    actorId: row.actorId,
+    operationKey: row.operationKey,
+    releaseId: row.releaseId,
+    clientBindingDigest: row.clientBindingDigest as `sha256:${string}`,
+    attempt: row.attempt,
+    requestDigest: row.requestDigest as `sha256:${string}`,
+    responseDigest: row.responseDigest as `sha256:${string}`,
+    deploymentDigest: row.deploymentDigest as `sha256:${string}`,
+    issuedAt: row.issuedAt,
+    ...(row.canonicalResultJson === null
+      ? {}
+      : { canonicalResult: row.canonicalResultJson as ModuleAiJsonValue }),
+  };
+}

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

@@ -0,0 +1,28 @@
+export class ClientAgentSessionError extends Error {
+  constructor(
+    readonly code:
+      | "INVALID_INPUT"
+      | "FORBIDDEN"
+      | "NOT_FOUND"
+      | "CONFLICT"
+      | "LIMIT_EXCEEDED"
+      | "PROVIDER_FAILED",
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = "ClientAgentSessionError";
+  }
+}
+
+export function clientSessionInvalid(message: string) {
+  return new ClientAgentSessionError("INVALID_INPUT", message, 400);
+}
+
+export function clientSessionConflict(message: string) {
+  return new ClientAgentSessionError("CONFLICT", message, 409);
+}
+
+export function clientSessionHidden() {
+  return new ClientAgentSessionError("NOT_FOUND", "会话不存在或不可访问", 404);
+}

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,110 @@
+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 principal = await input.adapter.authenticate({
+          token: hostToken(context.request, path),
+          purpose: isCompletion(path) ? "completion" : "control",
+          signal: context.request.signal,
+        });
+        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, path: string): string {
+  const header = path.includes(":sessionId")
+    ? request.headers.get("x-windy-host-authorization")
+    : request.headers.get("authorization");
+  const token = header?.match(/^Bearer\s+(.+)$/iu)?.[1];
+  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,
+  );
+}