create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,315 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../../guards.js";
+import type { RouteApp } from "../../system/routes.js";
+import { validDigest } from "./digest.js";
+import { GovernedClientAgentSessionService } from "./service.js";
+import { ClientAgentSessionError } from "./errors.js";
+import type { ClientAgentCompletionEvent } from "./completion.js";
+import type { ClientAgentHostContext } from "./host-auth.js";
+
+interface RouteContext {
+  body?: unknown;
+  params: Record<string, string | undefined>;
+  request: Request;
+  guardContext: RequestGuardContext;
+  clientAgentHost: ClientAgentHostContext;
+}
+
+export function registerGovernedClientAgentSessionRoutes(
+  app: RouteApp,
+  service: GovernedClientAgentSessionService,
+) {
+  app.get("/agent/client-sessions/capabilities", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      authenticatedActor(context.guardContext);
+      return await service.capabilities(context.request.signal);
+    } catch (error) {
+      return routeError(error);
+    }
+  });
+
+  app.post("/agent/client-sessions", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const body = object(context.body);
+      return await service.create({
+        operationKey: requiredText(body.operationKey, "operationKey"),
+        input: json(body.input),
+        clientBindingDigest: requiredText(
+          body.clientBindingDigest,
+          "clientBindingDigest",
+        ),
+        hostSessionDigest: context.clientAgentHost.hostSessionDigest,
+        actorId: authenticatedActor(context.guardContext),
+      });
+    } catch (error) {
+      return routeError(error);
+    }
+  });
+
+  app.post(
+    "/agent/client-sessions/:sessionId/v1/chat/completions",
+    async (raw) => {
+      const context = raw as RouteContext;
+      try {
+        const result = await service.startCompletion(
+          requiredText(context.params.sessionId, "sessionId"),
+          context.body,
+          caller(context),
+          context.request.signal,
+        );
+        if (!result.stream) {
+          const completed = await consumeCompletion(result.events);
+          const response = withReceipt(completed.response, completed.receipt);
+          return Response.json(response, {
+            headers: {
+              "x-windy-provider-receipt-id": completed.receipt.receiptId,
+            },
+          });
+        }
+        return new Response(completionStream(result), {
+          headers: {
+            "content-type": "text/event-stream",
+            "cache-control": "no-store, no-transform",
+            "x-accel-buffering": "no",
+          },
+        });
+      } catch (error) {
+        return routeError(error);
+      }
+    },
+  );
+
+  app.get("/agent/client-sessions/:sessionId", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      return await service.status(
+        requiredText(context.params.sessionId, "sessionId"),
+        caller(context),
+      );
+    } catch (error) {
+      return routeError(error);
+    }
+  });
+
+  app.get("/agent/client-sessions/:sessionId/result", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const status = await service.status(
+        requiredText(context.params.sessionId, "sessionId"),
+        caller(context),
+      );
+      if (status.status !== "completed" || !status.result) {
+        throw new ClientAgentSessionError(
+          "CONFLICT",
+          "Client Agent Session 尚未完成",
+          409,
+        );
+      }
+      return status.result;
+    } catch (error) {
+      return routeError(error);
+    }
+  });
+
+  app.post("/agent/client-sessions/:sessionId/finalize", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const body = object(context.body);
+      if (
+        !Array.isArray(body.receiptIds) ||
+        body.receiptIds.some((value) => typeof value !== "string")
+      ) {
+        throw new ClientAgentSessionError(
+          "INVALID_INPUT",
+          "receiptIds 无效",
+          400,
+        );
+      }
+      return await service.finalize(
+        requiredText(context.params.sessionId, "sessionId"),
+        caller(context),
+        body.receiptIds as string[],
+        body.result === undefined ? undefined : json(body.result),
+      );
+    } catch (error) {
+      return routeError(error);
+    }
+  });
+
+  app.post("/agent/client-sessions/:sessionId/cancel", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const body = context.body === undefined ? {} : object(context.body);
+      return await service.cancel(
+        requiredText(context.params.sessionId, "sessionId"),
+        caller(context),
+        typeof body.reason === "string" ? body.reason.slice(0, 200) : undefined,
+      );
+    } catch (error) {
+      return routeError(error);
+    }
+  });
+
+  app.post("/agent/client-sessions/revoke", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const body = object(context.body);
+      const actorId = authenticatedActor(context.guardContext);
+      const digest = requiredText(
+        body.clientBindingDigest,
+        "clientBindingDigest",
+      );
+      if (!validDigest(digest)) {
+        throw new ClientAgentSessionError(
+          "INVALID_INPUT",
+          "clientBindingDigest 无效",
+          400,
+        );
+      }
+      return { revoked: await service.revokeBinding(digest, actorId) };
+    } catch (error) {
+      return routeError(error);
+    }
+  });
+}
+
+async function consumeCompletion(
+  events: AsyncIterable<ClientAgentCompletionEvent>,
+) {
+  for await (const event of events) {
+    if (event.type === "complete") return event;
+  }
+  throw new ClientAgentSessionError(
+    "PROVIDER_FAILED",
+    "Provider 未返回终末响应",
+    502,
+  );
+}
+
+function completionStream(input: {
+  events: AsyncIterable<ClientAgentCompletionEvent>;
+  abort(): void;
+}): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  const iterator = input.events[Symbol.asyncIterator]();
+  return new ReadableStream({
+    async pull(controller) {
+      try {
+        const next = await iterator.next();
+        if (next.done) {
+          controller.enqueue(encoder.encode("data: [DONE]\n\n"));
+          controller.close();
+          return;
+        }
+        const event = next.value;
+        controller.enqueue(
+          encoder.encode(
+            event.type === "chunk"
+              ? `data: ${JSON.stringify(event.value)}\n\n`
+              : `event: windy.receipt\ndata: ${JSON.stringify(event.receipt)}\n\n`,
+          ),
+        );
+      } catch (error) {
+        const safe =
+          error instanceof ClientAgentSessionError
+            ? { code: error.code, message: error.message, retryable: false }
+            : {
+                code: "PROVIDER_FAILED",
+                message: "Client Agent Provider 调用失败",
+                retryable: true,
+              };
+        controller.enqueue(
+          encoder.encode(
+            `event: windy.error\ndata: ${JSON.stringify(safe)}\n\n`,
+          ),
+        );
+        controller.close();
+      }
+    },
+    async cancel() {
+      input.abort();
+      await iterator.return?.();
+    },
+  });
+}
+
+function caller(context: RouteContext) {
+  const token = context.request.headers
+    .get("authorization")
+    ?.replace(/^Bearer\s+/u, "");
+  const clientBindingDigest = context.request.headers.get(
+    "x-windy-client-binding-digest",
+  );
+  if (!token?.startsWith("car_") || !validDigest(clientBindingDigest)) {
+    throw new ClientAgentSessionError("NOT_FOUND", "会话不存在或不可访问", 404);
+  }
+  return {
+    token,
+    actorId: authenticatedActor(context.guardContext),
+    clientBindingDigest,
+    hostSessionDigest: context.clientAgentHost.hostSessionDigest,
+  };
+}
+
+function authenticatedActor(context: RequestGuardContext): string {
+  if (context.actor.type === "anonymous") {
+    throw new ClientAgentSessionError("FORBIDDEN", "需要宿主认证", 403);
+  }
+  return context.actor.id;
+}
+
+function withReceipt(value: ModuleAiJsonValue, receipt: object) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ClientAgentSessionError(
+      "PROVIDER_FAILED",
+      "Provider 返回了无效响应",
+      502,
+    );
+  }
+  return { ...value, windy_receipt: receipt };
+}
+
+function object(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ClientAgentSessionError("INVALID_INPUT", "请求体必须是对象", 400);
+  }
+  return value as Record<string, unknown>;
+}
+
+function json(value: unknown): ModuleAiJsonValue {
+  try {
+    return JSON.parse(JSON.stringify(value)) as ModuleAiJsonValue;
+  } catch {
+    throw new ClientAgentSessionError(
+      "INVALID_INPUT",
+      "请求不是合法 JSON",
+      400,
+    );
+  }
+}
+
+function requiredText(value: unknown, label: string): string {
+  if (typeof value !== "string" || !value.trim() || value.length > 512) {
+    throw new ClientAgentSessionError("INVALID_INPUT", `${label} 无效`, 400);
+  }
+  return value;
+}
+
+function routeError(error: unknown): Response {
+  if (error instanceof ClientAgentSessionError) {
+    return Response.json(
+      {
+        code: error.code,
+        message: error.message,
+        retryable: error.code === "PROVIDER_FAILED" && error.status >= 500,
+      },
+      { status: error.status },
+    );
+  }
+  return Response.json(
+    { code: "INTERNAL_ERROR", message: "Client Agent Session 请求失败" },
+    { status: 500 },
+  );
+}

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

@@ -0,0 +1,42 @@
+import { randomUUIDv7 } from "bun";
+import type { AuditEvent } from "@southwind-ai/shared";
+import type { createServerRuntime } from "../../runtime.js";
+import type { ClientSessionAuditPort } from "./contracts.js";
+
+const actions = {
+  create: "agent.client-session.create",
+  "provider-attempt": "agent.client-session.provider-attempt",
+  finalize: "agent.client-session.finalize",
+  cancel: "agent.client-session.cancel",
+  revoke: "agent.client-session.revoke",
+} as const;
+
+export class RuntimeClientSessionAudit implements ClientSessionAuditPort {
+  constructor(
+    private readonly runtime: Pick<
+      ReturnType<typeof createServerRuntime>,
+      "auditSink"
+    >,
+  ) {}
+
+  record(input: Parameters<ClientSessionAuditPort["record"]>[0]) {
+    const event: AuditEvent = {
+      id: randomUUIDv7(),
+      action: actions[input.action],
+      outcome: input.outcome,
+      actor: {
+        id: input.actorId,
+        type: "user",
+        name: input.actorId,
+      },
+      target: {
+        type: "client-agent-run",
+        id: input.clientRunId,
+        label: input.operationKey,
+      },
+      metadata: { ...input.metadata },
+      occurredAt: new Date().toISOString(),
+    };
+    return this.runtime.auditSink.recordCriticalEvent(event);
+  }
+}

package/template/apps/server/src/agent/client-session/service.test-support.ts

@@ -0,0 +1,248 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  ClientAgentProviderPort,
+  ClientSessionAdmissionPort,
+  ClientSessionAttemptAuthorityChecker,
+  ClientSessionAuditPort,
+  ClientSessionCaller,
+  ClientSessionRecord,
+} from "./contracts.js";
+import { digestJson } from "./digest.js";
+import { ClientAgentSessionError } from "./errors.js";
+import { InMemoryClientSessionRepository } from "./repository.js";
+import { GovernedClientAgentSessionService } from "./service.js";
+import { ClientSessionAttemptAuthorityBinding } from "./attempt-authority.js";
+
+export const binding = `sha256:${"b".repeat(64)}` as const;
+export const hostSession = `sha256:${"e".repeat(64)}` as const;
+const deployment = `sha256:${"d".repeat(64)}` as const;
+
+export async function createFixture(
+  options: {
+    now?: number;
+    maxTtlMs?: number;
+    maxSteps?: number;
+    projectProviderResult?: boolean;
+    execute?: (
+      request: ModuleAiJsonValue,
+      signal: AbortSignal,
+    ) => Promise<ModuleAiJsonValue>;
+    providerReady?: boolean;
+    attemptAuthority?: ClientSessionAttemptAuthorityChecker;
+  } = {},
+) {
+  const clock = { value: options.now ?? 1_000 };
+  const repository = new InMemoryClientSessionRepository();
+  const admission = new FakeAdmission(
+    options.maxSteps ?? 4,
+    options.projectProviderResult ?? true,
+  );
+  const provider = new FakeProvider(
+    options.execute,
+    options.providerReady ?? true,
+  );
+  const audits: Parameters<ClientSessionAuditPort["record"]>[0][] = [];
+  const attemptAuthority = new ClientSessionAttemptAuthorityBinding();
+  if (options.attemptAuthority) {
+    attemptAuthority.bind(options.attemptAuthority);
+  }
+  const service = new GovernedClientAgentSessionService(
+    repository,
+    admission,
+    provider,
+    {
+      record: (event) => {
+        audits.push(event);
+      },
+    },
+    "https://windy.example/api/agent/client-sessions/",
+    attemptAuthority,
+    () => clock.value,
+    options.maxTtlMs,
+  );
+  const grant = await service.create({
+    operationKey: "support.answer",
+    input: { question: "hello" },
+    clientBindingDigest: binding,
+    hostSessionDigest: hostSession,
+    actorId: "actor-1",
+  });
+  const caller: ClientSessionCaller = {
+    token: grant.accessToken,
+    actorId: "actor-1",
+    clientBindingDigest: binding,
+    hostSessionDigest: hostSession,
+  };
+  return {
+    service,
+    repository,
+    admission,
+    provider,
+    attemptAuthority,
+    audits,
+    grant,
+    caller,
+    clock,
+    complete: (body: unknown) =>
+      service.complete(grant.sessionId, body, caller),
+  };
+}
+
+class FakeAdmission implements ClientSessionAdmissionPort {
+  allowed = true;
+  constructor(
+    private readonly maxSteps: number,
+    private readonly project: boolean,
+  ) {}
+  async admit(input: {
+    operationKey: string;
+    input: ModuleAiJsonValue;
+    clientBindingDigest: `sha256:${string}`;
+    actorId: string;
+    launchAuthority: "direct" | "workflow-artifact";
+  }) {
+    const expectedAuthority: "direct" | "workflow-artifact" =
+      input.operationKey === "analysis.page-agent"
+        ? "workflow-artifact"
+        : "direct";
+    if (input.launchAuthority !== expectedAuthority) {
+      throw new ClientAgentSessionError(
+        "FORBIDDEN",
+        "launch authority mismatch",
+        403,
+      );
+    }
+    return {
+      actorId: input.actorId,
+      operationKey: input.operationKey,
+      releaseId: "release-1",
+      inputCommitment: digestJson(input.input),
+      authorizationDigest: digestJson({ actorId: input.actorId }),
+      clientBindingDigest: input.clientBindingDigest,
+      deploymentKey: "ai.openai-compatible",
+      providerDataPolicy: {
+        inputFields: [
+          {
+            jsonPointer: "/question",
+            classification: "internal" as const,
+            dlpAction: "redact" as const,
+          },
+        ],
+        envelopeFields: [
+          "instructions",
+          "user-prompt",
+          "tool-definitions",
+          "provider-output",
+          "tool-results",
+        ].map((field) => ({
+          field: field as "instructions",
+          classification: "internal" as const,
+          dlpAction: "redact" as const,
+        })),
+      },
+      limits: {
+        mode: "governed-session" as const,
+        launchAuthority: expectedAuthority,
+        maxSteps: this.maxSteps,
+        maxRequestBytes: 16_384,
+        maxResponseBytes: 16_384,
+        maxConcurrentRequests: 1,
+        maxDurationSeconds: 60,
+      },
+    };
+  }
+  async reauthorize(_session: ClientSessionRecord, _actorId: string) {
+    return this.allowed;
+  }
+  validateResult(_operationKey: string, result: ModuleAiJsonValue) {
+    if (
+      !result ||
+      typeof result !== "object" ||
+      Array.isArray(result) ||
+      typeof result.answer !== "string"
+    ) {
+      throw new ClientAgentSessionError(
+        "INVALID_INPUT",
+        "result schema invalid",
+        400,
+      );
+    }
+  }
+  projectProviderResult(_operationKey: string, response: ModuleAiJsonValue) {
+    if (
+      !this.project ||
+      !response ||
+      typeof response !== "object" ||
+      Array.isArray(response)
+    ) {
+      return undefined;
+    }
+    return { answer: "provider answer" };
+  }
+}
+
+class FakeProvider implements ClientAgentProviderPort {
+  readonly modelAlias = "windy-default";
+  readonly requests: ModuleAiJsonValue[] = [];
+  constructor(
+    private readonly handler:
+      | ((
+          request: ModuleAiJsonValue,
+          signal: AbortSignal,
+        ) => Promise<ModuleAiJsonValue>)
+      | undefined,
+    private readonly available: boolean,
+  ) {}
+  async ready() {
+    return this.available;
+  }
+  async *stream(
+    request: ModuleAiJsonValue,
+    _context: Parameters<ClientAgentProviderPort["stream"]>[1],
+    signal: AbortSignal,
+  ) {
+    this.requests.push(request);
+    const response =
+      (await this.handler?.(request, signal)) ?? providerResponse();
+    yield { type: "meta" as const, deploymentDigest: deployment };
+    yield { type: "chunk" as const, value: responseChunk(response) };
+  }
+}
+
+function responseChunk(response: ModuleAiJsonValue): ModuleAiJsonValue {
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    throw new Error("fake response invalid");
+  }
+  const choice = Array.isArray(response.choices)
+    ? response.choices[0]
+    : undefined;
+  const message =
+    choice && typeof choice === "object" && !Array.isArray(choice)
+      ? choice.message
+      : undefined;
+  return {
+    choices: [
+      {
+        index: 0,
+        delta:
+          message && typeof message === "object" && !Array.isArray(message)
+            ? message
+            : {},
+        finish_reason: "stop",
+      },
+    ],
+  };
+}
+
+export function validCompletion() {
+  return {
+    model: "windy-default",
+    messages: [{ role: "user", content: "hello" }],
+  };
+}
+
+export function providerResponse(): ModuleAiJsonValue {
+  return {
+    choices: [{ message: { role: "assistant", content: "provider answer" } }],
+  };
+}