create-windy 0.6.14 → 0.6.15

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

@@ -0,0 +1,161 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../../guards.js";
+import type { RouteApp } from "../../system/routes.js";
+import type { ClientAgentHostContext } from "../client-session/host-auth.js";
+import { ClientAgentWorkflowArtifactError } from "./error.js";
+import type { GovernedClientAgentWorkflowArtifactService } from "./service.js";
+
+interface RouteContext {
+  readonly body?: unknown;
+  readonly request: Request;
+  readonly guardContext: RequestGuardContext;
+  readonly clientAgentHost: ClientAgentHostContext;
+}
+
+export function registerClientAgentWorkflowArtifactRoutes(
+  app: RouteApp,
+  service: GovernedClientAgentWorkflowArtifactService,
+) {
+  app.post("/agent/client-workflow-artifacts/claim", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const body = object(context.body, [
+        "workflowRunId",
+        "clientBindingDigest",
+      ]);
+      return await service.claim({
+        workflowRunId: text(body.workflowRunId),
+        clientBindingDigest: text(body.clientBindingDigest),
+        principal: context.clientAgentHost.principal,
+        guardContext: context.guardContext,
+        signal: context.request.signal,
+      });
+    } catch (error) {
+      return routeError(error);
+    }
+  });
+
+  app.post("/agent/client-workflow-artifacts/advance", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const body = object(context.body, [
+        "workId",
+        "claimToken",
+        "claimVersion",
+        "receiptIds",
+        "result",
+      ]);
+      return await service.advance({
+        workId: text(body.workId),
+        claimToken: text(body.claimToken),
+        claimVersion: integer(body.claimVersion),
+        receiptIds: receiptIds(body.receiptIds),
+        ...(body.result === undefined
+          ? {}
+          : { result: body.result as ModuleAiJsonValue }),
+        principal: context.clientAgentHost.principal,
+        guardContext: context.guardContext,
+        signal: context.request.signal,
+      });
+    } catch (error) {
+      return routeError(error);
+    }
+  });
+
+  app.post("/agent/client-workflow-artifacts/cancel", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const body = object(context.body, [
+        "workId",
+        "claimToken",
+        "claimVersion",
+      ]);
+      return await service.cancelClaim({
+        workId: text(body.workId),
+        claimToken: text(body.claimToken),
+        claimVersion: integer(body.claimVersion),
+        principal: context.clientAgentHost.principal,
+        guardContext: context.guardContext,
+        signal: context.request.signal,
+      });
+    } catch (error) {
+      return routeError(error);
+    }
+  });
+}
+
+function object(value: unknown, allowed: readonly string[]) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw invalid();
+  }
+  const record = value as Record<string, unknown>;
+  if (Object.keys(record).some((key) => !allowed.includes(key)))
+    throw invalid();
+  return record;
+}
+
+function text(value: unknown) {
+  if (typeof value !== "string" || !value.trim() || value.length > 512) {
+    throw invalid();
+  }
+  return value;
+}
+
+function integer(value: unknown) {
+  if (!Number.isSafeInteger(value) || Number(value) < 0) throw invalid();
+  return Number(value);
+}
+
+function receiptIds(value: unknown) {
+  if (
+    !Array.isArray(value) ||
+    value.length < 1 ||
+    value.length > 128 ||
+    value.some((item) => typeof item !== "string" || !item.trim()) ||
+    new Set(value).size !== value.length
+  ) {
+    throw invalid();
+  }
+  return value as string[];
+}
+
+function invalid() {
+  return new ClientAgentWorkflowArtifactError(
+    "INVALID_INPUT",
+    "Client Agent Workflow 请求无效",
+    400,
+  );
+}
+
+function routeError(error: unknown) {
+  if (error instanceof ClientAgentWorkflowArtifactError) {
+    return Response.json(
+      {
+        code: error.code,
+        message: error.message,
+        safeCode: safeCode(error),
+        retryable: error.status >= 500,
+      },
+      { status: error.status },
+    );
+  }
+  return Response.json(
+    {
+      code: "INTERNAL_ERROR",
+      message: "Client Agent Workflow 调用失败",
+      safeCode: "INTERNAL_ERROR",
+      retryable: false,
+    },
+    { status: 500 },
+  );
+}
+
+function safeCode(error: ClientAgentWorkflowArtifactError) {
+  if (error.code === "NOT_FOUND") return "WORK_NOT_FOUND";
+  if (error.code === "CANCELLED") return "WORK_CANCELLED";
+  if (error.code === "ARTIFACT_TOO_LARGE") return "ARTIFACT_REJECTED";
+  if (error.code === "PROVIDER_FAILED") return "HOST_UNAVAILABLE";
+  if (error.code === "RECEIPT_REJECTED") return "RECEIPT_REJECTED";
+  if (error.code === "CONFLICT") return "CLAIM_CONFLICT";
+  return "INTERNAL_ERROR";
+}

package/template/apps/server/src/agent/client-workflow-artifact/runtime-composition.ts

@@ -0,0 +1,101 @@
+import type { ModuleAuthoritativeSourceAdapterRegistration } from "../context-memory/authoritative-source-registry.js";
+import type { AgentPlatformRuntimeInput } from "../runtime-bootstrap-input.js";
+import type { ClientSessionRepository } from "../client-session/repository.js";
+import type { GovernedClientAgentSessionService } from "../client-session/service.js";
+import type { ClientSessionAttemptAuthorityBinding } from "../client-session/attempt-authority.js";
+import type { StaticRouteAuthorizer } from "../../module-host/static-route-authorization.js";
+import type { RouteApp } from "../../system/routes.js";
+import { registerUnavailableClientAgentWorkflowArtifactRoutes } from "../unavailable-routes.js";
+import { createClientAgentWorkflowArtifactRuntime } from "./bootstrap.js";
+import { DrizzleClientAgentWorkflowArtifactRepository } from "./drizzle-repository.js";
+
+export function attachClientAgentWorkflowArtifactRuntime(input: {
+  readonly platform: AgentPlatformRuntimeInput;
+  readonly aiRouteApp: RouteApp;
+  readonly hostApp?: RouteApp;
+  readonly routeAuthorizer: StaticRouteAuthorizer;
+  readonly sessions?: GovernedClientAgentSessionService;
+  readonly sessionRepository?: ClientSessionRepository;
+  readonly attemptAuthority?: ClientSessionAttemptAuthorityBinding;
+}) {
+  if (!input.attemptAuthority) {
+    registerUnavailableClientAgentWorkflowArtifactRoutes(input.aiRouteApp);
+    return {
+      authoritativeSources:
+        [] as readonly ModuleAuthoritativeSourceAdapterRegistration[],
+      revokeHost: undefined,
+      dispose: undefined,
+      bindTaskArtifacts: undefined,
+    };
+  }
+  const authorityRepository = input.platform.db
+    ? new DrizzleClientAgentWorkflowArtifactRepository(input.platform.db)
+    : undefined;
+  let workflowRuntimeReady = false;
+  const classify = (decision: "ordinary" | "current" | "revoked") =>
+    !workflowRuntimeReady && decision === "current" ? "revoked" : decision;
+  const authorityInput = (
+    facts: Parameters<ClientSessionAttemptAuthorityBinding["check"]>[0],
+    now: number,
+  ) => ({
+    clientSessionId: facts.sessionId,
+    actorId: facts.actorId,
+    operationKey: facts.operationKey,
+    clientBindingDigest: facts.clientBindingDigest,
+    hostSessionDigest: facts.hostSessionDigest,
+    now,
+  });
+  const unbindAuthority = input.attemptAuthority.bind({
+    async check(facts) {
+      if (!authorityRepository) return "ordinary";
+      return classify(
+        await authorityRepository.authorizeClientSessionAttempt(
+          authorityInput(facts, Date.now()),
+        ),
+      );
+    },
+    async checkTransaction(transaction, facts, now) {
+      if (!authorityRepository) return "ordinary";
+      return classify(
+        await authorityRepository.authorizeClientSessionAttemptInTransaction(
+          transaction,
+          authorityInput(facts, now),
+        ),
+      );
+    },
+  });
+  const runtime = createClientAgentWorkflowArtifactRuntime({
+    db: input.platform.db,
+    hostApp: input.hostApp,
+    routeAuthorizer: input.routeAuthorizer,
+    bindings: input.platform.clientAgentWorkflowArtifactBindings,
+    sessions: input.sessions,
+    sessionRepository: input.sessionRepository,
+    jobs: input.platform.jobs,
+    jobRegistry: input.platform.jobRegistry,
+    blobs: input.platform.storage.blobStore,
+  });
+  if (!runtime) {
+    registerUnavailableClientAgentWorkflowArtifactRoutes(input.aiRouteApp);
+    return {
+      authoritativeSources:
+        [] as readonly ModuleAuthoritativeSourceAdapterRegistration[],
+      revokeHost: undefined,
+      dispose: unbindAuthority,
+      bindTaskArtifacts: undefined,
+    };
+  }
+  workflowRuntimeReady = true;
+  return {
+    authoritativeSources: [
+      {
+        moduleKey: "system.agent-workflow",
+        access: runtime.sourceAccess,
+      },
+    ] satisfies readonly ModuleAuthoritativeSourceAdapterRegistration[],
+    revokeHost: (principal: Parameters<typeof runtime.service.revokeHost>[0]) =>
+      runtime.service.revokeHost(principal).then(() => {}),
+    dispose: unbindAuthority,
+    bindTaskArtifacts: runtime.bindTaskArtifacts,
+  };
+}

package/template/apps/server/src/agent/client-workflow-artifact/scope-authority.ts

@@ -0,0 +1,39 @@
+import type { DurableJobSnapshot } from "@southwind-ai/jobs";
+import type { AuthorizationScopeSnapshot } from "@southwind-ai/shared";
+import { authorizationScopeContains } from "../../data-access/scope-containment.js";
+import { hashAuthorizationScope } from "../../data-access/scope-snapshot.js";
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+import { clientAgentWorkflowArtifactTaskKey } from "./contracts.js";
+
+/** Reads the immutable Run authorization from its real Durable Job, never from a client claim. */
+export function requireClientWorkflowFrozenScope(
+  record: ClientAgentWorkflowArtifactRecord,
+  snapshot: DurableJobSnapshot | undefined,
+): AuthorizationScopeSnapshot {
+  const job = snapshot?.job;
+  if (
+    !job ||
+    job.id !== record.durableJobId ||
+    job.handlerKey !== clientAgentWorkflowArtifactTaskKey ||
+    job.requestedBy !== record.actorId ||
+    !job.authorizationScope ||
+    `sha256:${hashAuthorizationScope(job.authorizationScope)}` !==
+      record.scopeDigest
+  ) {
+    throw new Error("CLIENT_WORKFLOW_FROZEN_SCOPE_INVALID");
+  }
+  return structuredClone(job.authorizationScope);
+}
+
+/** Equality is only a fast path; a current wider scope may contain the frozen Run scope. */
+export function currentClientWorkflowScopeContains(input: {
+  readonly current: AuthorizationScopeSnapshot;
+  readonly currentDigest: string;
+  readonly frozen: AuthorizationScopeSnapshot;
+  readonly frozenDigest: string;
+}): boolean {
+  return (
+    input.currentDigest === input.frozenDigest ||
+    authorizationScopeContains(input.current, input.frozen)
+  );
+}

package/template/apps/server/src/agent/client-workflow-artifact/service-authorization.ts

@@ -0,0 +1,117 @@
+import type { ModuleClientAgentHostPrincipal } from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../../guards.js";
+import { captureAuthorizationScope } from "../../data-access/scope-snapshot.js";
+import type { ClientSessionRepository } from "../client-session/repository.js";
+import { digestText } from "../client-session/digest.js";
+import { hostSessionDigest } from "../client-session/host-auth.js";
+import type { ClientAgentWorkflowArtifactRecord } from "./contracts.js";
+import { clientWorkflowPayloadOf } from "./presentation.js";
+import type { ClientAgentWorkflowArtifactRepository } from "./repository.js";
+import { sameWorkflowArtifactIdentity } from "./repository.js";
+import {
+  requiredWorkflowArtifactText as required,
+  workflowArtifactActor as actor,
+  workflowArtifactHidden as hidden,
+  workflowArtifactInvalid as invalid,
+} from "./service-support.js";
+import type { ClientAgentWorkflowFactsLoader } from "./workflow-loader.js";
+import { currentClientWorkflowScopeContains } from "./scope-authority.js";
+
+export async function requireClientWorkflowClaim(input: {
+  workId: string;
+  claimVersion: number;
+  claimToken: string;
+  principal: ModuleClientAgentHostPrincipal;
+  guardContext: RequestGuardContext;
+  repository: ClientAgentWorkflowArtifactRepository;
+  sessionRepository: ClientSessionRepository;
+  now: number;
+}) {
+  if (
+    !input.claimToken.startsWith("cawc_") ||
+    !Number.isSafeInteger(input.claimVersion) ||
+    input.claimVersion < 1
+  ) {
+    throw invalid("领取凭据无效");
+  }
+  const current = await input.repository.find(required(input.workId));
+  if (
+    !current ||
+    current.actorId !== actor(input.guardContext) ||
+    input.principal.actorId !== actor(input.guardContext) ||
+    current.claimGeneration !== input.claimVersion ||
+    current.claimTokenHash !== digestText(input.claimToken) ||
+    current.installationId !== input.principal.installationId ||
+    current.hostSessionDigest !== hostSessionDigest(input.principal) ||
+    !current.clientSessionId ||
+    !["claimed", "completed", "cancelled"].includes(current.status)
+  ) {
+    throw hidden();
+  }
+  if (
+    current.status === "claimed" &&
+    (!current.claimExpiresAt || current.claimExpiresAt <= input.now)
+  ) {
+    const session = await input.sessionRepository.find(current.clientSessionId);
+    if (session?.status !== "completed") throw hidden();
+  }
+  return current;
+}
+
+export async function requireCurrentClientWorkflowArtifact(input: {
+  record: ClientAgentWorkflowArtifactRecord;
+  context: RequestGuardContext;
+  signal: AbortSignal;
+  loader: ClientAgentWorkflowFactsLoader;
+}) {
+  const facts = await input.loader.load({
+    jobId: input.record.durableJobId,
+    payload: clientWorkflowPayloadOf(input.record),
+    signal: input.signal,
+  });
+  if (!sameWorkflowArtifactIdentity(input.record, facts.record)) throw hidden();
+  requireCurrentActor(input.record, input.context, facts.frozenScope);
+  return facts;
+}
+
+export async function requireTerminalClientWorkflowArtifact(input: {
+  record: ClientAgentWorkflowArtifactRecord;
+  context: RequestGuardContext;
+  signal: AbortSignal;
+  loader: ClientAgentWorkflowFactsLoader;
+}) {
+  try {
+    const facts = await input.loader.loadTerminal({
+      record: input.record,
+      signal: input.signal,
+    });
+    requireCurrentActor(input.record, input.context, facts.frozenScope);
+    return facts;
+  } catch {
+    throw hidden();
+  }
+}
+
+function requireCurrentActor(
+  record: ClientAgentWorkflowArtifactRecord,
+  context: RequestGuardContext,
+  frozenScope: import("@southwind-ai/shared").AuthorizationScopeSnapshot,
+) {
+  try {
+    const scope = captureAuthorizationScope(context.actor.scopeContext);
+    if (
+      context.actor.id !== record.actorId ||
+      !context.actor.permissionKeys.includes("system.agent-workflow.manage") ||
+      !currentClientWorkflowScopeContains({
+        current: scope.snapshot,
+        currentDigest: `sha256:${scope.hash}`,
+        frozen: frozenScope,
+        frozenDigest: record.scopeDigest,
+      })
+    ) {
+      throw hidden();
+    }
+  } catch {
+    throw hidden();
+  }
+}

package/template/apps/server/src/agent/client-workflow-artifact/service-support.ts

@@ -0,0 +1,28 @@
+import type { RequestGuardContext } from "../../guards.js";
+import { ClientAgentWorkflowArtifactError } from "./error.js";
+
+export function workflowArtifactActor(context: RequestGuardContext) {
+  if (context.actor.type === "anonymous") throw workflowArtifactHidden();
+  return context.actor.id;
+}
+
+export function requiredWorkflowArtifactText(value: string) {
+  if (!value.trim()) throw workflowArtifactInvalid("必填字段不能为空");
+  return value;
+}
+
+export function workflowArtifactHidden() {
+  return new ClientAgentWorkflowArtifactError(
+    "NOT_FOUND",
+    "Workflow Client Agent 任务不存在或不可访问",
+    404,
+  );
+}
+
+export function workflowArtifactInvalid(message: string) {
+  return new ClientAgentWorkflowArtifactError("INVALID_INPUT", message, 400);
+}
+
+export function workflowArtifactConflict(message: string) {
+  return new ClientAgentWorkflowArtifactError("CONFLICT", message, 409);
+}