create-windy 0.6.12 → 0.6.15

package/template/packages/jobs/src/handlers.ts

@@ -1,5 +1,28 @@
 import type { ArtifactRef } from "@southwind-ai/storage";
 
+export interface DurableHandlerArtifactInput {
+  kind: string;
+  artifactRef: ArtifactRef;
+  filename: string;
+  contentType: string;
+  byteSize: number;
+  sha256: string;
+  ownerId: string;
+  expiresAt?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface DurableArtifactPublicationReceipt {
+  readonly schemaVersion: 1;
+  readonly publicationKey: string;
+  readonly artifactId: string;
+  readonly jobId: string;
+  readonly stageKey: string;
+  readonly kind: string;
+  readonly artifactRef: ArtifactRef;
+  readonly sha256: string;
+}
+
 export interface PayloadParser<T> {
   parse(input: unknown): T;
 }
@@ -16,17 +39,11 @@ export interface DurableHandlerContext {
     message?: string;
     metadata?: Record<string, unknown>;
   }): Promise<void>;
-  publishArtifact(input: {
-    kind: string;
-    artifactRef: ArtifactRef;
-    filename: string;
-    contentType: string;
-    byteSize: number;
-    sha256: string;
-    ownerId: string;
-    expiresAt?: string;
-    metadata?: Record<string, unknown>;
-  }): Promise<void>;
+  publishArtifact(input: DurableHandlerArtifactInput): Promise<void>;
+  publishArtifactOnce?(
+    publicationKey: string,
+    artifact: DurableHandlerArtifactInput,
+  ): Promise<DurableArtifactPublicationReceipt>;
 }
 
 export interface DurableHandlerDefinition<T> {

package/template/packages/modules/index.ts

@@ -14,4 +14,6 @@ export * from "./src/project-module-assembly.js";
 export * from "./src/module-host-range.js";
 export * from "./src/admin-ui-manifest.js";
 export * from "./src/system-admin-ui-catalog.js";
+// @windy-module system.agent begin
 export * from "./src/system-agent-supervisor.js";
+// @windy-module system.agent end

package/template/packages/modules/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/modules",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/modules/src/ai-client-execution-composition.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from "bun:test";
+import { validateModuleComposition } from "./composition.js";
+import {
+  operation,
+  providerDataPolicy,
+  fixture,
+} from "./ai-operation-composition.test-support.js";
+
+describe("Client Agent Session Manifest", () => {
+  test("只有显式受治理的 Agent Operation 可开启 client execution", () => {
+    const module = fixture("business");
+    module.aiOperations = [
+      {
+        ...operation("business.generate"),
+        providerEgress: {
+          mode: "configured-endpoint",
+          deploymentKey: "ai.openai-compatible",
+        },
+        providerDataPolicy: clientProviderDataPolicy(),
+        clientExecution: {
+          mode: "governed-session",
+          maxSteps: 8,
+          maxRequestBytes: 1_024,
+          maxResponseBytes: 2_048,
+          maxConcurrentRequests: 1,
+        },
+      },
+    ];
+
+    expect(() =>
+      validateModuleComposition([module], {
+        aiOperations: ["business.generate"],
+      }),
+    ).not.toThrow();
+  });
+
+  test("拒绝未配置 Provider 出网或突破 Operation 上限", () => {
+    const module = fixture("business");
+    const definition = operation("business.generate");
+    module.aiOperations = [
+      {
+        ...definition,
+        clientExecution: {
+          mode: "governed-session",
+          maxSteps: 8,
+          maxRequestBytes: definition.limits.maxInputBytes + 1,
+          maxResponseBytes: definition.limits.maxOutputBytes,
+          maxConcurrentRequests: 1,
+        },
+      },
+    ];
+
+    expect(() =>
+      validateModuleComposition([module], {
+        aiOperations: ["business.generate"],
+      }),
+    ).toThrow("只允许显式 Provider 出网");
+
+    module.aiOperations[0] = {
+      ...module.aiOperations[0]!,
+      providerEgress: {
+        mode: "configured-endpoint",
+        deploymentKey: "ai.openai-compatible",
+      },
+      providerDataPolicy: clientProviderDataPolicy(),
+    };
+    expect(() =>
+      validateModuleComposition([module], {
+        aiOperations: ["business.generate"],
+      }),
+    ).toThrow("超过 Operation 边界");
+  });
+});
+
+function clientProviderDataPolicy() {
+  const policy = providerDataPolicy();
+  return {
+    ...policy,
+    envelopeFields: [
+      ...policy.envelopeFields,
+      {
+        field: "provider-output" as const,
+        classification: "internal" as const,
+        dlpAction: "redact" as const,
+      },
+      {
+        field: "tool-definitions" as const,
+        classification: "internal" as const,
+        dlpAction: "reject" as const,
+      },
+      {
+        field: "tool-results" as const,
+        classification: "internal" as const,
+        dlpAction: "redact" as const,
+      },
+    ],
+  };
+}

package/template/packages/modules/src/ai-client-execution-policy.ts

@@ -0,0 +1,60 @@
+import type { ModuleAiOperationDefinition } from "./manifest.js";
+
+export function validateClientExecution(
+  operation: ModuleAiOperationDefinition,
+): void {
+  const policy = operation.clientExecution;
+  if (!policy) return;
+  if (
+    operation.kind !== "agent" ||
+    operation.providerEgress?.mode !== "configured-endpoint"
+  ) {
+    throw new Error(
+      `${operation.key} Client Agent Session 只允许显式 Provider 出网的 Agent Operation`,
+    );
+  }
+  if (policy.mode !== "governed-session") {
+    throw new Error(`${operation.key} Client Agent Session 模式无效`);
+  }
+  if (
+    policy.launchAuthority !== undefined &&
+    !["direct", "workflow-artifact"].includes(policy.launchAuthority)
+  ) {
+    throw new Error(`${operation.key} Client Agent launch authority 无效`);
+  }
+  const limits = [
+    policy.maxSteps,
+    policy.maxRequestBytes,
+    policy.maxResponseBytes,
+    policy.maxConcurrentRequests,
+  ];
+  if (limits.some((value) => !Number.isSafeInteger(value) || value <= 0)) {
+    throw new Error(`${operation.key} Client Agent Session 上限必须是正整数`);
+  }
+  if (
+    policy.maxSteps > 128 ||
+    policy.maxRequestBytes > operation.limits.maxInputBytes ||
+    policy.maxResponseBytes > operation.limits.maxOutputBytes ||
+    policy.maxConcurrentRequests > 4
+  ) {
+    throw new Error(
+      `${operation.key} Client Agent Session 上限超过 Operation 边界`,
+    );
+  }
+  const envelopeFields: ReadonlySet<string> = new Set(
+    operation.providerDataPolicy?.envelopeFields.map(({ field }) => field),
+  );
+  for (const field of [
+    "instructions",
+    "user-prompt",
+    "provider-output",
+    "tool-definitions",
+    "tool-results",
+  ]) {
+    if (!envelopeFields.has(field)) {
+      throw new Error(
+        `${operation.key} Client Agent Session Provider allowlist 缺少 ${field}`,
+      );
+    }
+  }
+}

package/template/packages/modules/src/ai-operation-composition.ts

@@ -5,6 +5,7 @@ import type {
 import { validateAiNetworkPolicy } from "./ai-network-policy.js";
 import { validateAiOperationReadinessContract } from "./ai-operation-readiness-contract.js";
 import { validateAiScreenshotContext } from "./ai-screenshot-context.js";
+import { validateClientExecution } from "./ai-client-execution-policy.js";
 
 interface AiOperationCatalogs {
   permissions: ReadonlySet<string>;
@@ -105,6 +106,7 @@ function validateOperation(
   validateTools(operation, catalogs.tools);
   validateAiNetworkPolicy(operation);
   validateProviderDataPolicy(operation);
+  validateClientExecution(operation);
   validateLimits(operation);
   validateAiOperationReadinessContract(operation);
   validateAiScreenshotContext(operation);

package/template/packages/modules/src/manifest.ts

@@ -167,6 +167,21 @@ export interface AiOperationLimits {
   maxPixelsPerArtifact?: number;
 }
 
+/**
+ * 允许受治理的宿主客户端在本地编排模型循环。
+ *
+ * 该声明只开放 Windy 固定部署的代理能力，不包含 Provider URL、模型 ID 或凭据。
+ */
+export interface AiClientExecutionPolicy {
+  readonly mode: "governed-session";
+  /** 缺省为 direct；workflow-artifact 只能由固定 Workflow Artifact Host seam 启动。 */
+  readonly launchAuthority?: "direct" | "workflow-artifact";
+  readonly maxSteps: number;
+  readonly maxRequestBytes: number;
+  readonly maxResponseBytes: number;
+  readonly maxConcurrentRequests: number;
+}
+
 /**
  * 可选的 Runtime readiness V1 声明。缺失时保留旧 Operation 的兼容语义；
  * 一旦声明，Host 必须以真实 downstream probe 投影后才允许执行。
@@ -217,6 +232,8 @@ export interface ModuleAiOperationDefinition {
   publicNetworkAccess?: AiOperationPublicNetworkAccess;
   providerEgress?: AiProviderEgressPolicy;
   providerDataPolicy?: AiProviderDataPolicy;
+  /** 缺省不允许浏览器或其它宿主客户端执行本地 Agent 循环。 */
+  clientExecution?: AiClientExecutionPolicy;
   toolNetworkPolicy?: AiToolNetworkPolicy;
   limits: AiOperationLimits;
 }

package/template/packages/modules/src/system-admin-routes.ts

@@ -122,6 +122,14 @@ export const systemAdminRoutes: ModuleManifest["adminRoutes"] = [
   ),
   // @windy-module system.audit end
   // @windy-module system.agent begin
+  route(
+    "system.agent-session",
+    "/admin/system/agent-sessions",
+    "Agent 会话",
+    "sidebar",
+    "system.agent-session.read",
+    "system.agent-session",
+  ),
   route(
     "system.ai-runtime",
     "/admin/system/ai-runtime",
@@ -130,6 +138,14 @@ export const systemAdminRoutes: ModuleManifest["adminRoutes"] = [
     "system.ai-runtime.read",
     "system.ai-runtime",
   ),
+  route(
+    "system.agent-workflow",
+    "/admin/system/agent-workflows",
+    "Agent Workflow",
+    "sidebar",
+    "system.agent-workflow.read",
+    "system.agent-workflow",
+  ),
   // @windy-module system.agent end
   // @windy-module system.operations begin
   route(

package/template/packages/modules/src/system-admin-ui-catalog.ts

@@ -31,7 +31,10 @@ const definitions = [
   ["system.storage", []],
   // @windy-module system.storage end
   // @windy-module system.agent begin
-  ["system.agent", ["system.ai-runtime"]],
+  [
+    "system.agent",
+    ["system.agent-session", "system.ai-runtime", "system.agent-workflow"],
+  ],
   // @windy-module system.agent end
   // @windy-module system.operations begin
   ["system.operations", ["system.ops"]],

package/template/packages/modules/src/system-agent-audit-actions.ts

@@ -0,0 +1,29 @@
+export const agentAuditActionKeys: ReadonlySet<string> = new Set([
+  "agent.session.read",
+  "agent.session.create",
+  "agent.session.checkpoint",
+  "agent.session.replay",
+  "agent.session.fork",
+  "agent.session.archive",
+  "agent.context-version.create",
+  "agent.memory.delete",
+  "agent.client-session.create",
+  "agent.client-session.provider-attempt",
+  "agent.client-session.finalize",
+  "agent.client-session.cancel",
+  "agent.client-session.revoke",
+  "agent.runtime.report.read",
+  "agent.runtime.run.read",
+  "agent.workflow.release.publish",
+  "agent.workflow.readiness.read",
+  "agent.workflow.run.read",
+  "agent.workflow.run.create",
+  "agent.workflow.run.cancel",
+  "agent.workflow.run.recover",
+  "agent.workflow.run.signal",
+  "agent.workflow.evaluation.record",
+  "agent.workflow.artifact.resolve",
+  "agent.workflow.client-artifact.claim",
+  "agent.workflow.client-artifact.advance",
+  "agent.workflow.client-artifact.cancel",
+]);

package/template/packages/modules/src/system-ai-api-bindings.ts

@@ -0,0 +1,277 @@
+import type { ApiPermissionBinding } from "@southwind-ai/shared";
+import { binding } from "./system-api-binding.js";
+
+// @windy-module system.agent begin
+export function systemAiControlPlaneBindings(): ApiPermissionBinding[] {
+  const reports = (
+    [
+      ["/api/system/ai-runtime/summary", "agent.runtime.report.read"],
+      ["/api/system/ai-runtime/runs", "agent.runtime.report.read"],
+      ["/api/system/ai-runtime/runs/:runId", "agent.runtime.run.read"],
+      ["/api/system/ai-runtime/actors", "agent.runtime.report.read"],
+    ] as const
+  ).map(([path, auditAction]) =>
+    binding(
+      "GET",
+      path,
+      "system.ai-runtime.read",
+      "system.ai-runtime",
+      auditAction,
+    ),
+  );
+  const read = [
+    "/api/agent/workflows/readiness",
+    "/api/internal/ai/artifacts",
+    "/api/document/runs/:runId/events",
+    "/api/document/runs/:runId/result",
+    "/api/speech/runs/:runId/events",
+    "/api/speech/runs/:runId/result",
+    "/api/speech/runs/:runId/artifact",
+    "/api/embeddings/runs/:runId/events",
+    "/api/embeddings/runs/:runId/result",
+    "/api/internal/embeddings/runs/:runId/artifacts/:itemId",
+    "/api/agent/runs/:runId/events",
+    "/api/agent/runs/:runId/result",
+  ].map((path) =>
+    binding(
+      "GET",
+      path,
+      "system.agent.read",
+      "system.agent",
+      "data.read",
+      path.startsWith("/api/internal/"),
+    ),
+  );
+  const execute = [
+    "/api/document/runs",
+    "/api/document/runs/:runId/cancel",
+    "/api/speech/runs",
+    "/api/speech/runs/:runId/cancel",
+    "/api/embeddings",
+    "/api/embeddings/runs",
+    "/api/embeddings/runs/:runId/cancel",
+    "/api/agent/runs",
+    "/api/agent/runs/:runId/cancel",
+    "/api/agent/runs/:runId/attach",
+    "/api/agent/screenshots",
+    "/api/agent/screenshots/:token/cancel",
+    "/api/internal/agent/tools/execute",
+  ].map((path) =>
+    binding(
+      "POST",
+      path,
+      "system.agent.read",
+      "system.agent",
+      "agent.operation.execute",
+      path.startsWith("/api/internal/"),
+    ),
+  );
+  return [
+    ...reports,
+    ...read,
+    ...execute,
+    binding(
+      "PUT",
+      "/api/agent/screenshots/:token",
+      "system.agent.read",
+      "system.agent",
+      "agent.operation.execute",
+    ),
+    ...clientSessionBindings(),
+    ...longSessionBindings(),
+    ...workflowBindings(),
+  ];
+}
+
+function workflowBindings(): ApiPermissionBinding[] {
+  const read = [
+    "/api/agent/workflows/releases/:releaseId",
+    "/api/agent/workflows/runs",
+    "/api/agent/workflows/runs/:runId",
+    "/api/agent/workflows/runs/:runId/events",
+    "/api/agent/workflows/evaluations/:evaluationId",
+    "/api/agent/workflows/artifacts/:artifactId/resolve",
+    "/api/agent/workflows/artifacts/open",
+  ];
+  return [
+    ...read.map((path) =>
+      binding(
+        "GET",
+        path,
+        "system.agent-workflow.read",
+        "system.agent-workflow",
+        path.endsWith("/readiness")
+          ? "agent.workflow.readiness.read"
+          : path.includes("/artifacts/")
+            ? "agent.workflow.artifact.resolve"
+            : "agent.workflow.run.read",
+      ),
+    ),
+    binding(
+      "POST",
+      "/api/agent/workflows/releases",
+      "system.agent-workflow.manage",
+      "system.agent-workflow",
+      "agent.workflow.release.publish",
+    ),
+    binding(
+      "POST",
+      "/api/agent/workflows/runs",
+      "system.agent-workflow.manage",
+      "system.agent-workflow",
+      "agent.workflow.run.create",
+    ),
+    binding(
+      "POST",
+      "/api/agent/workflows/runs/:runId/cancel",
+      "system.agent-workflow.manage",
+      "system.agent-workflow",
+      "agent.workflow.run.cancel",
+    ),
+    binding(
+      "POST",
+      "/api/agent/workflows/runs/:runId/recover",
+      "system.agent-workflow.manage",
+      "system.agent-workflow",
+      "agent.workflow.run.recover",
+    ),
+    binding(
+      "POST",
+      "/api/agent/workflows/runs/:runId/nodes/:nodeRunId/signals/:signalKey",
+      "system.agent-workflow.manage",
+      "system.agent-workflow",
+      "agent.workflow.run.signal",
+    ),
+    binding(
+      "POST",
+      "/api/agent/workflows/evaluations",
+      "system.agent-workflow.manage",
+      "system.agent-workflow",
+      "agent.workflow.evaluation.record",
+    ),
+    ...(
+      [
+        ["/api/agent/client-workflow-artifacts/claim", "claim"],
+        ["/api/agent/client-workflow-artifacts/advance", "advance"],
+        ["/api/agent/client-workflow-artifacts/cancel", "cancel"],
+      ] as const
+    ).map(([path, action]) =>
+      binding(
+        "POST",
+        path,
+        "system.agent-workflow.manage",
+        "system.agent-workflow",
+        `agent.workflow.client-artifact.${action}`,
+      ),
+    ),
+  ];
+}
+
+function longSessionBindings(): ApiPermissionBinding[] {
+  const readPaths = [
+    "/api/agent/harness/sessions",
+    "/api/agent/harness/sessions/:sessionId",
+    "/api/agent/harness/sessions/:sessionId/context-versions",
+    "/api/agent/harness/sessions/:sessionId/memories",
+  ];
+  const managePaths = [
+    ["/api/agent/harness/sessions", "agent.session.create"],
+    [
+      "/api/agent/harness/sessions/:sessionId/checkpoints",
+      "agent.session.checkpoint",
+    ],
+    ["/api/agent/harness/sessions/:sessionId/replay", "agent.session.replay"],
+    ["/api/agent/harness/sessions/:sessionId/forks", "agent.session.fork"],
+    ["/api/agent/harness/sessions/:sessionId/archive", "agent.session.archive"],
+  ] as const;
+  return [
+    ...readPaths.map((path) =>
+      binding(
+        "GET",
+        path,
+        "system.agent-session.read",
+        "system.agent-session",
+        "agent.session.read",
+      ),
+    ),
+    ...managePaths.map(([path, auditAction]) =>
+      binding(
+        "POST",
+        path,
+        "system.agent-session.manage",
+        "system.agent-session",
+        auditAction,
+      ),
+    ),
+    binding(
+      "POST",
+      "/api/internal/agent/context-versions",
+      "system.agent-session.manage",
+      "system.agent-session",
+      "agent.context-version.create",
+      true,
+    ),
+    binding(
+      "DELETE",
+      "/api/agent/harness/sessions/:sessionId/memories/:memoryId",
+      "system.agent-session.manage",
+      "system.agent-session",
+      "agent.memory.delete",
+    ),
+  ];
+}
+
+function clientSessionBindings(): ApiPermissionBinding[] {
+  const guarded = (
+    method: "GET" | "POST",
+    path: string,
+    auditAction: string,
+    tokenEndpoint = true,
+  ) =>
+    binding(
+      method,
+      path,
+      "system.agent.read",
+      "system.agent",
+      auditAction,
+      tokenEndpoint,
+    );
+  return [
+    guarded(
+      "GET",
+      "/api/agent/client-sessions/capabilities",
+      "data.read",
+      false,
+    ),
+    guarded(
+      "POST",
+      "/api/agent/client-sessions",
+      "agent.client-session.create",
+      false,
+    ),
+    guarded(
+      "POST",
+      "/api/agent/client-sessions/:sessionId/v1/chat/completions",
+      "agent.client-session.provider-attempt",
+    ),
+    guarded(
+      "POST",
+      "/api/agent/client-sessions/:sessionId/finalize",
+      "agent.client-session.finalize",
+    ),
+    guarded(
+      "POST",
+      "/api/agent/client-sessions/:sessionId/cancel",
+      "agent.client-session.cancel",
+    ),
+    guarded(
+      "POST",
+      "/api/agent/client-sessions/revoke",
+      "agent.client-session.revoke",
+      false,
+    ),
+    guarded("GET", "/api/agent/client-sessions/:sessionId", "data.read"),
+    guarded("GET", "/api/agent/client-sessions/:sessionId/result", "data.read"),
+  ];
+}
+// @windy-module system.agent end