create-windy 0.6.11 → 0.6.14

package/template/apps/server/src/agent/tool-registry-composition.ts

@@ -0,0 +1,52 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { findFeature } from "../route-guards.js";
+import type { ModuleToolHandlers, RegisteredTool } from "./tool-registry.js";
+
+export function collectRegisteredTools(
+  modules: readonly ModuleManifest[],
+): RegisteredTool[] {
+  const features = modules.flatMap(({ features }) => features);
+  const schemas = new Map(
+    modules.flatMap((module) =>
+      (module.jsonSchemas ?? []).map((schema) => [schema.key, schema] as const),
+    ),
+  );
+  return modules.flatMap((module) =>
+    module.tools.map((tool) => ({
+      ...tool,
+      module: module.name,
+      feature: required(
+        findFeature(features, tool.featureKey),
+        `Agent Tool ${tool.key} 缺少 Feature`,
+      ),
+      inputSchema: required(
+        schemas.get(tool.inputSchemaKey),
+        `Agent Tool ${tool.key} 缺少输入 Schema`,
+      ).schema,
+      outputSchema: required(
+        schemas.get(tool.outputSchemaKey),
+        `Agent Tool ${tool.key} 缺少输出 Schema`,
+      ).schema,
+    })),
+  );
+}
+
+export function validateToolHandlerContract(
+  tools: readonly RegisteredTool[],
+  handlers: ModuleToolHandlers,
+): void {
+  const declared = new Set(tools.map(({ key }) => key));
+  for (const key of declared) {
+    if (!handlers.has(key)) throw new Error(`Agent Tool ${key} 缺少 Handler`);
+  }
+  for (const key of handlers.keys()) {
+    if (!declared.has(key)) {
+      throw new Error(`Agent Tool Handler 未声明：${key}`);
+    }
+  }
+}
+
+function required<T>(value: T | undefined, message: string): T {
+  if (value === undefined) throw new Error(message);
+  return value;
+}

package/template/apps/server/src/agent/tool-registry.test.ts

@@ -94,14 +94,14 @@ describe("Governed Tool Registry", () => {
     expect(JSON.stringify(event)).not.toContain("permissionKeys");
   });
 
-  test("调试 Tool 审计保留服务主体并标注真实数据用户", async () => {
+  test("委托 Tool 审计保留服务主体并标注投影业务用户", async () => {
     const fixture = await createFixture();
     fixture.context.actor = bindModuleUserProjection(
       {
         ...fixture.context.actor,
-        id: "service_adk_debug",
+        id: "service_page_agent",
         type: "service",
-        name: "ADK 开发调试",
+        name: "PageAgent 客户端",
       },
       "user_dev_admin",
     );
@@ -114,11 +114,11 @@ describe("Governed Tool Registry", () => {
 
     const event = fixture.runtime.auditSink.list().at(-1);
     expect(event?.actor).toMatchObject({
-      id: "service_adk_debug",
+      id: "service_page_agent",
       type: "service",
     });
     expect(event?.metadata).toMatchObject({
-      debugDataActorId: "user_dev_admin",
+      projectedUserId: "user_dev_admin",
     });
   });
 });

package/template/apps/server/src/agent/tool-registry.ts

@@ -12,9 +12,18 @@ import Ajv, { type ValidateFunction } from "ajv";
 import { evaluateAccessGuards } from "../access-guards.js";
 import { isServerScopeContext } from "../data-access/context.js";
 import type { RequestGuardContext } from "../guards.js";
-import { findFeature } from "../route-guards.js";
 import type { createServerRuntime } from "../runtime.js";
 import { sandboxFailureEvent, toolEvent, toolJsonBytes } from "./tool-audit.js";
+import type { GovernedToolExecutionWithAuditReceipt } from "./tool-execution-receipt.js";
+import {
+  collectRegisteredTools,
+  validateToolHandlerContract,
+} from "./tool-registry-composition.js";
+
+export type {
+  GovernedToolAuditReceipt,
+  GovernedToolExecutionWithAuditReceipt,
+} from "./tool-execution-receipt.js";
 
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 
@@ -60,8 +69,8 @@ export class GovernedToolRegistry {
     handlers: ModuleToolHandlers,
     private readonly runtime: ServerRuntime,
   ) {
-    const definitions = collectTools(modules);
-    validateHandlerContract(definitions, handlers);
+    const definitions = collectRegisteredTools(modules);
+    validateToolHandlerContract(definitions, handlers);
     const inputAjv = new Ajv({
       allErrors: true,
       coerceTypes: true,
@@ -121,6 +130,27 @@ export class GovernedToolRegistry {
     context: RequestGuardContext,
     toolCallId = context.requestId,
   ): Promise<ModuleToolResult> {
+    return (
+      await this.executeGoverned(key, rawInput, context, toolCallId, "ordinary")
+    ).result;
+  }
+
+  async executeWithAuditReceipt(
+    key: string,
+    rawInput: ModuleToolInput,
+    context: RequestGuardContext,
+    toolCallId = context.requestId,
+  ): Promise<GovernedToolExecutionWithAuditReceipt> {
+    return this.executeGoverned(key, rawInput, context, toolCallId, "critical");
+  }
+
+  private async executeGoverned(
+    key: string,
+    rawInput: ModuleToolInput,
+    context: RequestGuardContext,
+    toolCallId: string,
+    auditPolicy: "ordinary" | "critical",
+  ): Promise<GovernedToolExecutionWithAuditReceipt> {
     const tool = this.#tools.get(key);
     if (!tool) {
       throw new ToolExecutionError("TOOL_NOT_FOUND", "Agent Tool 不存在");
@@ -191,16 +221,27 @@ export class GovernedToolRegistry {
       }
       throw error;
     }
-    this.runtime.auditSink.recordEvent(
-      toolEvent(
-        context,
-        tool.definition,
-        input,
-        result,
-        tool.handler.executionMode ?? "host",
-      ),
+    const event = toolEvent(
+      context,
+      tool.definition,
+      input,
+      result,
+      tool.handler.executionMode ?? "host",
     );
-    return result;
+    if (auditPolicy === "critical") {
+      await this.runtime.auditSink.recordCriticalEvent(event);
+    } else {
+      this.runtime.auditSink.recordEvent(event);
+    }
+    return {
+      result,
+      auditReceipt: {
+        auditEventId: event.id,
+        toolKey: tool.definition.key,
+        outputSchemaKey: tool.definition.outputSchemaKey,
+        occurredAt: event.occurredAt,
+      },
+    };
   }
 }
 
@@ -221,48 +262,6 @@ export class ToolExecutionError extends Error {
   }
 }
 
-function collectTools(modules: readonly ModuleManifest[]): RegisteredTool[] {
-  const features = modules.flatMap(({ features }) => features);
-  const schemas = new Map(
-    modules.flatMap((module) =>
-      (module.jsonSchemas ?? []).map((schema) => [schema.key, schema] as const),
-    ),
-  );
-  return modules.flatMap((module) =>
-    module.tools.map((tool) => ({
-      ...tool,
-      module: module.name,
-      feature: required(
-        findFeature(features, tool.featureKey),
-        `Agent Tool ${tool.key} 缺少 Feature`,
-      ),
-      inputSchema: required(
-        schemas.get(tool.inputSchemaKey),
-        `Agent Tool ${tool.key} 缺少输入 Schema`,
-      ).schema,
-      outputSchema: required(
-        schemas.get(tool.outputSchemaKey),
-        `Agent Tool ${tool.key} 缺少输出 Schema`,
-      ).schema,
-    })),
-  );
-}
-
-function validateHandlerContract(
-  tools: readonly RegisteredTool[],
-  handlers: ModuleToolHandlers,
-): void {
-  const declared = new Set(tools.map(({ key }) => key));
-  for (const key of declared) {
-    if (!handlers.has(key)) throw new Error(`Agent Tool ${key} 缺少 Handler`);
-  }
-  for (const key of handlers.keys()) {
-    if (!declared.has(key)) {
-      throw new Error(`Agent Tool Handler 未声明：${key}`);
-    }
-  }
-}
-
 async function executeWithTimeout(
   tool: CompiledTool,
   input: ModuleToolInput,
@@ -312,8 +311,3 @@ function validationMessage(validate: ValidateFunction<unknown>): string {
     .join("；");
   return `Agent Tool JSON 不符合 Schema${detail ? `：${detail}` : ""}`;
 }
-
-function required<T>(value: T | undefined, message: string): T {
-  if (value === undefined) throw new Error(message);
-  return value;
-}

package/template/apps/server/src/agent/unavailable-routes.ts

@@ -1,5 +1,30 @@
 import type { RouteApp } from "../system/route-types.js";
 
+const clientSessionUnavailableRoutes = [
+  ["POST", "/agent/client-sessions"],
+  ["GET", "/agent/client-sessions/capabilities"],
+  ["POST", "/agent/client-sessions/revoke"],
+  ["GET", "/agent/client-sessions/:sessionId"],
+  ["GET", "/agent/client-sessions/:sessionId/result"],
+  ["POST", "/agent/client-sessions/:sessionId/v1/chat/completions"],
+  ["POST", "/agent/client-sessions/:sessionId/finalize"],
+  ["POST", "/agent/client-sessions/:sessionId/cancel"],
+] as const;
+
+const longSessionUnavailableRoutes = [
+  ["GET", "/agent/harness/sessions"],
+  ["GET", "/agent/harness/sessions/:sessionId"],
+  ["GET", "/agent/harness/sessions/:sessionId/context-versions"],
+  ["GET", "/agent/harness/sessions/:sessionId/memories"],
+  ["POST", "/agent/harness/sessions"],
+  ["POST", "/agent/harness/sessions/:sessionId/checkpoints"],
+  ["POST", "/agent/harness/sessions/:sessionId/replay"],
+  ["POST", "/agent/harness/sessions/:sessionId/forks"],
+  ["POST", "/agent/harness/sessions/:sessionId/archive"],
+  ["POST", "/internal/agent/context-versions"],
+  ["DELETE", "/agent/harness/sessions/:sessionId/memories/:memoryId"],
+] as const;
+
 const unavailableRoutes = [
   ["GET", "/internal/ai/artifacts"],
   ["POST", "/document/runs"],
@@ -33,14 +58,33 @@ const unavailableRoutes = [
 ] as const;
 
 export function registerUnavailableAiRoutes(app: RouteApp): void {
+  registerUnavailableRoutes(app, unavailableRoutes, "AI Runtime 未启用");
+  registerUnavailableRoutes(
+    app,
+    longSessionUnavailableRoutes,
+    "AI Runtime 未启用",
+  );
+  registerUnavailableClientAgentSessionRoutes(app, "AI Runtime 未启用");
+}
+
+export function registerUnavailableClientAgentSessionRoutes(
+  app: RouteApp,
+  message = "Client Agent Session 未装配",
+): void {
+  registerUnavailableRoutes(app, clientSessionUnavailableRoutes, message);
+}
+
+function registerUnavailableRoutes(
+  app: RouteApp,
+  routes: ReadonlyArray<readonly ["GET" | "POST" | "PUT" | "DELETE", string]>,
+  message: string,
+): void {
   const unavailable = () =>
-    Response.json(
-      { code: "RUNTIME_UNAVAILABLE", message: "AI Runtime 未启用" },
-      { status: 503 },
-    );
-  for (const [method, path] of unavailableRoutes) {
+    Response.json({ code: "RUNTIME_UNAVAILABLE", message }, { status: 503 });
+  for (const [method, path] of routes) {
     if (method === "GET") app.get(path, unavailable);
     else if (method === "PUT") app.put(path, unavailable);
+    else if (method === "DELETE") app.delete(path, unavailable);
     else app.post(path, unavailable);
   }
 }

package/template/apps/server/src/agent/workflow-durable-runtime-input.ts

@@ -0,0 +1,32 @@
+import type { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import { DurableArtifactService } from "../jobs/artifact-service.js";
+import type { DurableJobService } from "../jobs/service.js";
+import type { DurableJobWorker } from "../jobs/worker.js";
+import type { DurableJobRepository } from "../jobs/repository.js";
+
+export function workflowDurableInput([durable, storage, logger]: readonly [
+  {
+    readonly facts: DurableJobRepository;
+    readonly service: DurableJobService;
+    readonly registry: DurableHandlerRegistry;
+    readonly worker: DurableJobWorker;
+  },
+  {
+    readonly blobStore: ConstructorParameters<typeof DurableArtifactService>[1];
+  },
+  {
+    error(fields: Record<string, unknown>, message: string): void;
+  },
+]) {
+  return {
+    jobs: durable.service,
+    jobWorker: durable.worker,
+    jobRegistry: durable.registry,
+    jobArtifacts: new DurableArtifactService(durable.facts, storage.blobStore),
+    onWorkflowContinuationError: (error: unknown) =>
+      logger.error(
+        { event: "agent.workflow.continuation.failed", error },
+        "Agent Workflow continuation 派发失败",
+      ),
+  };
+}

package/template/apps/server/src/agent/workflow-runtime-bootstrap.ts

@@ -0,0 +1,59 @@
+import type { RouteApp } from "../system/routes.js";
+import { composeProductionAgentWorkflowRuntime } from "../agent-workflow/runtime-composition.js";
+import { registerAgentWorkflowRoutes } from "../agent-workflow/routes.js";
+import type { GovernedToolRegistry } from "./tool-registry.js";
+import type { AgentPlatformRuntimeInput } from "./runtime-bootstrap-input.js";
+import type { AgentRuntimePort } from "./run-contracts.js";
+import type { AgentRunFacade } from "./run-facade.js";
+import type { AgentRunAuthorizationStore } from "./run-authorization.js";
+import { RemoteAiRuntimeReportPort } from "../ai-runtime-report/remote-port.js";
+import type { SessionEventLogService } from "./session-log/service.js";
+import type { RequestActor } from "../guards.js";
+import type { AuthoritativeSourceAccessPort } from "./session-invalidation/contracts.js";
+import { resolveProductionEvaluationToolRegistration } from "../agent-workflow/evaluation-tool-registration.js";
+
+export function registerProductionAgentWorkflowRuntime(
+  input: AgentPlatformRuntimeInput,
+  app: RouteApp,
+  tools: GovernedToolRegistry,
+  dependencies?: {
+    readonly agentFacade: AgentRunFacade;
+    readonly agentRemote: AgentRuntimePort;
+    readonly agentAuthorizations: AgentRunAuthorizationStore;
+    readonly agentServerUrl: string;
+    readonly internalToken: string;
+    readonly artifactSources?: AuthoritativeSourceAccessPort;
+    readonly sessionLog?: SessionEventLogService;
+    readonly resolveActor: (
+      actorId: string,
+    ) => Promise<RequestActor | undefined>;
+  },
+) {
+  const runtime = composeProductionAgentWorkflowRuntime({
+    db: input.db,
+    modules: input.modules,
+    runtime: input.runtime,
+    tools,
+    approvalWorkflow: input.workflow,
+    jobs: input.jobs,
+    jobWorker: input.jobWorker,
+    jobRegistry: input.jobRegistry,
+    jobArtifacts: input.jobArtifacts,
+    onContinuationError: input.onWorkflowContinuationError,
+    modelPricingJson: input.platformConfig.agentWorkflow?.modelPricingJson,
+    evaluationTools: resolveProductionEvaluationToolRegistration(tools),
+    workspacePolicies: input.agentWorkflowWorkspacePolicies,
+    ...dependencies,
+    ...(dependencies
+      ? {
+          agentReports: new RemoteAiRuntimeReportPort({
+            baseUrl: dependencies.agentServerUrl,
+            internalToken: dependencies.internalToken,
+          }),
+          artifactAccessSecret: dependencies.internalToken,
+        }
+      : {}),
+  });
+  registerAgentWorkflowRoutes(app, runtime);
+  return runtime;
+}

package/template/apps/server/src/agent-workflow/adapter-dispatch.ts

@@ -0,0 +1,148 @@
+import type {
+  AgentWorkflowArtifactRef,
+  AgentWorkflowNode,
+  AgentWorkflowNodeResultReceipt,
+  AgentWorkflowNodeRun,
+  AgentWorkflowRun,
+  AgentWorkflowSideEffectCommand,
+  AgentWorkflowUsage,
+} from "@southwind-ai/shared";
+import type { WorkflowAuthorizationFence } from "./budget-validation.js";
+import type {
+  WorkflowEffectCommandFence,
+  WorkflowEffectCommandReceipt,
+} from "./effect-command-fence.js";
+
+export interface AgentWorkflowNodeAdapterContext {
+  readonly run: AgentWorkflowRun;
+  readonly nodeRun: AgentWorkflowNodeRun;
+  readonly node: AgentWorkflowNode;
+  readonly inputArtifacts: readonly AgentWorkflowArtifactRef[];
+  readonly inputReceipts: readonly AgentWorkflowNodeResultReceipt[];
+  readonly signal: AbortSignal;
+}
+
+export type AgentWorkflowAdapterPreparation =
+  | {
+      readonly outcome: "direct";
+      readonly result: AgentWorkflowNodeResultReceipt;
+      readonly outputArtifacts: readonly AgentWorkflowArtifactRef[];
+      readonly cumulativeUsage?: AgentWorkflowUsage;
+    }
+  | {
+      readonly outcome: "waiting";
+      readonly adapter: NonNullable<AgentWorkflowNodeRun["adapter"]>;
+    }
+  | {
+      readonly outcome: "effect";
+      readonly effectKind: AgentWorkflowSideEffectCommand["effectKind"];
+      readonly effectKey: string;
+      readonly adapter: AgentWorkflowSideEffectCommand["adapter"];
+      readonly requestDigest: string;
+      readonly budgetReservationId?: string;
+      readonly delegationId?: string;
+    }
+  | {
+      readonly outcome: "failed";
+      readonly safeCode: string;
+      readonly cumulativeUsage?: AgentWorkflowUsage;
+    };
+
+export type AgentWorkflowAdapterDispatchResult =
+  | {
+      readonly outcome: "committed";
+      readonly receipt: WorkflowEffectCommandReceipt;
+      readonly nodeResult: AgentWorkflowNodeResultReceipt;
+      readonly outputArtifacts: readonly AgentWorkflowArtifactRef[];
+      readonly cumulativeUsage?: AgentWorkflowUsage;
+    }
+  | {
+      readonly outcome: "waiting";
+      readonly adapter: NonNullable<AgentWorkflowNodeRun["adapter"]>;
+    }
+  | {
+      readonly outcome: "failed";
+      readonly safeCode: string;
+      readonly cumulativeUsage?: AgentWorkflowUsage;
+    };
+
+export interface AgentWorkflowNodeAdapter {
+  readonly nodeType: AgentWorkflowNode["type"];
+  prepare(
+    context: AgentWorkflowNodeAdapterContext,
+  ): Promise<AgentWorkflowAdapterPreparation>;
+  dispatch?(input: {
+    readonly context: AgentWorkflowNodeAdapterContext;
+    readonly command: AgentWorkflowSideEffectCommand;
+    readonly fence: WorkflowEffectCommandFence;
+  }): Promise<AgentWorkflowAdapterDispatchResult>;
+  reconcile?(
+    input: {
+      readonly context: AgentWorkflowNodeAdapterContext;
+      readonly command: AgentWorkflowSideEffectCommand;
+      readonly authorizationFence: WorkflowAuthorizationFence;
+    } & AgentWorkflowAdapterReconcileCoordinate,
+  ): Promise<
+    AgentWorkflowAdapterDispatchResult | { readonly outcome: "pending" }
+  >;
+  cancel?(input: {
+    readonly context: AgentWorkflowNodeAdapterContext;
+    readonly command?: AgentWorkflowSideEffectCommand;
+  }): Promise<{
+    readonly cancelled: boolean;
+    readonly safeCode?: string;
+    readonly cumulativeUsage?: AgentWorkflowUsage;
+  }>;
+}
+
+export type AgentWorkflowAdapterReconcileCoordinate =
+  | {
+      /** Newly issued fence when the external result exists but no local receipt was committed. */
+      readonly fence: WorkflowEffectCommandFence;
+      readonly committedReceipt?: never;
+    }
+  | {
+      /** Immutable local receipt when only Node Result convergence remains. */
+      readonly fence?: never;
+      readonly committedReceipt: WorkflowEffectCommandReceipt;
+    };
+
+export class AgentWorkflowNodeAdapterRegistry {
+  readonly #adapters = new Map<
+    AgentWorkflowNode["type"],
+    AgentWorkflowNodeAdapter
+  >();
+
+  constructor(adapters: readonly AgentWorkflowNodeAdapter[]) {
+    for (const adapter of adapters) {
+      if (this.#adapters.has(adapter.nodeType)) {
+        throw new Error(`Workflow Node Adapter 重复：${adapter.nodeType}`);
+      }
+      this.#adapters.set(adapter.nodeType, adapter);
+    }
+    const missing = REQUIRED_NODE_TYPES.filter(
+      (type) => !this.#adapters.has(type),
+    );
+    if (missing.length) {
+      throw new Error(`Workflow Node Adapter 未注册：${missing.join(",")}`);
+    }
+  }
+
+  require(type: AgentWorkflowNode["type"]) {
+    return this.#adapters.get(type)!;
+  }
+}
+
+const REQUIRED_NODE_TYPES = [
+  "model",
+  "tool",
+  "subagent",
+  "condition",
+  "parallel",
+  "join",
+  "approval",
+  "job",
+  "wait",
+  "artifact",
+  "final",
+] as const satisfies readonly AgentWorkflowNode["type"][];

package/template/apps/server/src/agent-workflow/approval-node-adapter.ts

@@ -0,0 +1,77 @@
+import { createHash } from "node:crypto";
+import type { WorkItem } from "@southwind-ai/shared";
+import type { WorkflowService } from "../workflow/service.js";
+import type {
+  AgentWorkflowAdapterDispatch,
+  AgentWorkflowApprovalNodeAdapter,
+} from "./node-adapters.js";
+
+/** Adapts the existing Approval Work Item; it does not own approval state. */
+export class ApprovalWorkItemNodeAdapter implements AgentWorkflowApprovalNodeAdapter {
+  constructor(private readonly workflow: WorkflowService) {}
+
+  async dispatch(
+    input: Parameters<AgentWorkflowApprovalNodeAdapter["dispatch"]>[0],
+  ) {
+    const item = await this.workflow.create(
+      {
+        id: approvalId(input.commandId),
+        title: input.title,
+        candidateRoles: input.candidateRoleCodes.map((code) => ({ code })),
+        dueAt: input.dueAt,
+        target: {
+          type: "agent-workflow-run",
+          id: input.runId,
+          route: `/admin/system/agent-workflows?runId=${encodeURIComponent(input.runId)}`,
+        },
+        idempotencyKey: input.idempotencyKey,
+      },
+      input.actor,
+    );
+    return project(item, true);
+  }
+
+  async reconcile(
+    input: Parameters<AgentWorkflowApprovalNodeAdapter["reconcile"]>[0],
+  ) {
+    const item = await this.workflow.get(input.adapterId, input.actor);
+    return item ? project(item, false) : undefined;
+  }
+}
+
+function approvalId(commandId: string) {
+  return `workflow_approval_${createHash("sha256").update(commandId).digest("hex").slice(0, 40)}`;
+}
+
+function project(
+  item: WorkItem,
+  created: boolean,
+): AgentWorkflowAdapterDispatch {
+  const status = item.status;
+  if (status === "pending" || status === "claimed") {
+    return { adapterId: item.id, created, status: "waiting" };
+  }
+  if (status === "approved") {
+    return {
+      adapterId: item.id,
+      created,
+      status: "completed",
+      resultDigest: digest({ id: item.id, status, version: item.version }),
+    };
+  }
+  return {
+    adapterId: item.id,
+    created,
+    status: status === "cancelled" ? "cancelled" : "failed",
+    safeErrorCode:
+      status === "rejected"
+        ? "APPROVAL_REJECTED"
+        : status === "timed-out"
+          ? "APPROVAL_TIMED_OUT"
+          : "APPROVAL_CANCELLED",
+  };
+}
+
+function digest(value: unknown) {
+  return `sha256:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
+}

package/template/apps/server/src/agent-workflow/artifact-access-error.ts

@@ -0,0 +1,9 @@
+export class AgentWorkflowArtifactAccessError extends Error {
+  constructor(
+    readonly code: "ARTIFACT_FORBIDDEN" | "ARTIFACT_TOKEN_INVALID",
+    readonly status: 400 | 403,
+  ) {
+    super(code);
+    this.name = "AgentWorkflowArtifactAccessError";
+  }
+}