create-windy 0.6.14 → 0.6.15

package/template/packages/database/drizzle/meta/_journal.json

@@ -435,6 +435,13 @@
       "when": 1787795894000,
       "tag": "0061_agent_workflow",
       "breakpoints": true
+    },
+    {
+      "idx": 62,
+      "version": "7",
+      "when": 1787904000000,
+      "tag": "0062_client_agent_workflow_artifact",
+      "breakpoints": true
     }
   ]
 }

package/template/packages/database/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/database",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/database/src/agent-runtime-schema.test.ts

@@ -11,6 +11,7 @@ import {
   agentRuntimeRuns,
   clientAgentReceipts,
   clientAgentSessions,
+  clientAgentWorkflowArtifacts,
 } from "./schema/index.js";
 
 test("Agent Run 固定不可变 Release 并持久化恢复租约", async () => {
@@ -65,6 +66,76 @@ test("Agent Run 固定不可变 Release 并持久化恢复租约", async () => {
   expect(getTableConfig(clientAgentReceipts).name).toBe(
     "client_agent_receipts",
   );
+  expect(getTableConfig(clientAgentWorkflowArtifacts).name).toBe(
+    "client_agent_workflow_artifacts",
+  );
+  expect(clientAgentWorkflowArtifacts.bindingDigest.notNull).toBe(true);
+  expect(clientAgentWorkflowArtifacts.effectKind.notNull).toBe(true);
+  expect(clientAgentWorkflowArtifacts.effectFenceTokenDigest.notNull).toBe(
+    true,
+  );
+  expect(clientAgentWorkflowArtifacts.terminalRequestDigest.notNull).toBe(
+    false,
+  );
+  const workflowArtifactConfig = getTableConfig(clientAgentWorkflowArtifacts);
+  expect(
+    workflowArtifactConfig.foreignKeys
+      .map((foreignKey) => foreignKey.getName())
+      .sort(),
+  ).toEqual([
+    "client_agent_workflow_artifacts_client_session_id_client_agent_sessions_session_id_fk",
+    "client_agent_workflow_artifacts_durable_job_id_durable_jobs_id_fk",
+    "fk_client_agent_workflow_effect_fence",
+  ]);
+  const effectFenceForeignKey = workflowArtifactConfig.foreignKeys.find(
+    (foreignKey) =>
+      foreignKey.getName() === "fk_client_agent_workflow_effect_fence",
+  );
+  expect(
+    effectFenceForeignKey?.reference().columns.map(({ name }) => name),
+  ).toEqual([
+    "command_id",
+    "run_id",
+    "node_run_id",
+    "effect_kind",
+    "effect_generation",
+    "request_digest",
+    "effect_fence_token_digest",
+  ]);
+  expect(
+    effectFenceForeignKey?.reference().foreignColumns.map(({ name }) => name),
+  ).toEqual([
+    "command_id",
+    "run_id",
+    "node_run_id",
+    "effect_kind",
+    "generation",
+    "request_digest",
+    "fence_token_digest",
+  ]);
+  expect(
+    workflowArtifactConfig.indexes
+      .map(
+        ({ config }) => `${config.unique ? "unique:" : "index:"}${config.name}`,
+      )
+      .sort(),
+  ).toEqual([
+    "index:idx_client_agent_workflow_claim",
+    "index:idx_client_agent_workflow_host",
+    "unique:uk_client_agent_workflow_client_session",
+    "unique:uk_client_agent_workflow_command",
+    "unique:uk_client_agent_workflow_job",
+    "unique:uk_client_agent_workflow_terminal_receipt",
+  ]);
+  expect(workflowArtifactConfig.checks.map(({ name }) => name).sort()).toEqual([
+    "ck_client_agent_workflow_claim_binding",
+    "ck_client_agent_workflow_effect_kind",
+    "ck_client_agent_workflow_generation",
+    "ck_client_agent_workflow_history",
+    "ck_client_agent_workflow_status",
+    "ck_client_agent_workflow_terminal",
+    "ck_client_agent_workflow_version",
+  ]);
 
   const migration = await Bun.file(
     new URL("../drizzle/0040_colossal_baron_strucker.sql", import.meta.url),
@@ -143,6 +214,112 @@ test("Agent Run 固定不可变 Release 并持久化恢复租约", async () => {
   ).text();
   expect(hostBindingMigration).toContain("host_session_digest");
   expect(hostBindingMigration).not.toContain("provider_key");
+  const workflowArtifactMigration = await Bun.file(
+    new URL(
+      "../drizzle/0062_client_agent_workflow_artifact.sql",
+      import.meta.url,
+    ),
+  ).text();
+  expect(workflowArtifactMigration).toContain(
+    'CREATE TABLE "client_agent_workflow_artifacts"',
+  );
+  expect(workflowArtifactMigration).toContain(
+    '"terminal_request_digest" varchar(71)',
+  );
+  expect(workflowArtifactMigration).toContain(
+    'CONSTRAINT "fk_client_agent_workflow_effect_fence"',
+  );
+  expect(workflowArtifactMigration).toContain(
+    'CREATE UNIQUE INDEX "uk_client_agent_workflow_client_session"',
+  );
+  expect(workflowArtifactMigration).not.toContain(
+    'CONSTRAINT "client_agent_workflow_artifacts_command_id_agent_workflow_side_effect_commands_command_id_fk"',
+  );
+  const workflowArtifactSnapshot = (await Bun.file(
+    new URL("../drizzle/meta/0062_snapshot.json", import.meta.url),
+  ).json()) as {
+    prevId: string;
+    tables: Record<
+      string,
+      {
+        columns: Record<
+          string,
+          {
+            name: string;
+            type: string;
+            primaryKey: boolean;
+            notNull: boolean;
+          }
+        >;
+        indexes: Record<string, unknown>;
+        foreignKeys: Record<string, unknown>;
+        checkConstraints: Record<string, unknown>;
+      }
+    >;
+  };
+  const previousWorkflowArtifactSnapshot = (await Bun.file(
+    new URL("../drizzle/meta/0061_snapshot.json", import.meta.url),
+  ).json()) as { id: string };
+  expect(workflowArtifactSnapshot.prevId).toBe(
+    previousWorkflowArtifactSnapshot.id,
+  );
+  expect(
+    workflowArtifactSnapshot.tables["public.client_agent_workflow_artifacts"]
+      ?.columns.terminal_request_digest,
+  ).toEqual({
+    name: "terminal_request_digest",
+    type: "varchar(71)",
+    primaryKey: false,
+    notNull: false,
+  });
+  const workflowArtifactSnapshotTable =
+    workflowArtifactSnapshot.tables["public.client_agent_workflow_artifacts"];
+  expect(
+    Object.keys(workflowArtifactSnapshotTable?.indexes ?? {}).sort(),
+  ).toEqual([
+    "idx_client_agent_workflow_claim",
+    "idx_client_agent_workflow_host",
+    "uk_client_agent_workflow_client_session",
+    "uk_client_agent_workflow_command",
+    "uk_client_agent_workflow_job",
+    "uk_client_agent_workflow_terminal_receipt",
+  ]);
+  expect(
+    Object.keys(workflowArtifactSnapshotTable?.foreignKeys ?? {}).sort(),
+  ).toEqual([
+    "client_agent_workflow_artifacts_client_session_id_client_agent_sessions_session_id_fk",
+    "client_agent_workflow_artifacts_durable_job_id_durable_jobs_id_fk",
+    "fk_client_agent_workflow_effect_fence",
+  ]);
+  expect(
+    Object.keys(workflowArtifactSnapshotTable?.checkConstraints ?? {}).sort(),
+  ).toEqual([
+    "ck_client_agent_workflow_claim_binding",
+    "ck_client_agent_workflow_effect_kind",
+    "ck_client_agent_workflow_generation",
+    "ck_client_agent_workflow_history",
+    "ck_client_agent_workflow_status",
+    "ck_client_agent_workflow_terminal",
+    "ck_client_agent_workflow_version",
+  ]);
+  const migrationJournal = (await Bun.file(
+    new URL("../drizzle/meta/_journal.json", import.meta.url),
+  ).json()) as {
+    entries: readonly {
+      idx: number;
+      version: string;
+      tag: string;
+      breakpoints: boolean;
+    }[];
+  };
+  expect(migrationJournal.entries.at(-1)).toMatchObject({
+    idx: 62,
+    version: "7",
+    tag: "0062_client_agent_workflow_artifact",
+    breakpoints: true,
+  });
+  expect(workflowArtifactMigration).not.toContain("provider_key");
+  expect(workflowArtifactMigration).not.toContain("message_json");
   expect(screenshotMigration).toContain(
     'CREATE UNIQUE INDEX "uk_agent_screenshot_intakes_run"',
   );

package/template/packages/database/src/schema/client-agent-workflow-artifact.ts

@@ -0,0 +1,158 @@
+import { sql } from "drizzle-orm";
+import {
+  check,
+  doublePrecision,
+  foreignKey,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  uniqueIndex,
+  varchar,
+} from "drizzle-orm/pg-core";
+import { durableJobs } from "./durable-jobs.js";
+import { clientAgentSessions } from "./client-agent.js";
+import { agentWorkflowSideEffectCommands } from "./agent-workflow-effects.js";
+
+export type ClientAgentWorkflowArtifactStatus =
+  | "pending"
+  | "claimed"
+  | "cancellation-requested"
+  | "completed"
+  | "cancelled";
+
+/**
+ * Workflow effect 与浏览器 Client Agent Session 之间的唯一桥接事实。
+ * 原始对话和 Provider 配置不在这里持久化；逐次执行历史继续由
+ * client_agent_receipts 承载。
+ */
+export const clientAgentWorkflowArtifacts = pgTable(
+  "client_agent_workflow_artifacts",
+  {
+    workId: varchar("work_id", { length: 80 }).primaryKey(),
+    commandId: varchar("command_id", { length: 96 }).notNull(),
+    durableJobId: varchar("durable_job_id", { length: 64 })
+      .notNull()
+      .references(() => durableJobs.id, { onDelete: "restrict" }),
+    runId: varchar("run_id", { length: 96 }).notNull(),
+    nodeRunId: varchar("node_run_id", { length: 96 }).notNull(),
+    effectKind: varchar("effect_kind", { length: 24 }).$type<"job">().notNull(),
+    taskKey: varchar("task_key", { length: 160 }).notNull(),
+    operationKey: varchar("operation_key", { length: 200 }).notNull(),
+    bindingDigest: varchar("binding_digest", { length: 71 }).notNull(),
+    actorId: varchar("actor_id", { length: 64 }).notNull(),
+    scopeDigest: varchar("scope_digest", { length: 71 }).notNull(),
+    authorizationSnapshotDigest: varchar("authorization_snapshot_digest", {
+      length: 71,
+    }).notNull(),
+    runPolicyDigest: varchar("run_policy_digest", { length: 71 }).notNull(),
+    requestDigest: varchar("request_digest", { length: 71 }).notNull(),
+    inputDigest: varchar("input_digest", { length: 71 }).notNull(),
+    effectGeneration: integer("effect_generation").notNull(),
+    effectFenceTokenDigest: varchar("effect_fence_token_digest", {
+      length: 71,
+    }).notNull(),
+    status: varchar("status", { length: 32 })
+      .$type<ClientAgentWorkflowArtifactStatus>()
+      .notNull(),
+    claimGeneration: integer("claim_generation").notNull().default(0),
+    clientBindingDigest: varchar("client_binding_digest", { length: 71 }),
+    installationId: varchar("installation_id", { length: 160 }),
+    hostSessionDigest: varchar("host_session_digest", { length: 71 }),
+    clientSessionId: varchar("client_session_id", { length: 80 }).references(
+      () => clientAgentSessions.sessionId,
+      { onDelete: "restrict" },
+    ),
+    claimTokenHash: varchar("claim_token_hash", { length: 71 }),
+    claimExpiresAt: doublePrecision("claim_expires_at"),
+    historySequence: integer("history_sequence").notNull().default(0),
+    historyHeadDigest: varchar("history_head_digest", { length: 71 }),
+    terminalReceiptId: varchar("terminal_receipt_id", { length: 96 }),
+    terminalReceiptDigest: varchar("terminal_receipt_digest", { length: 71 }),
+    terminalRequestDigest: varchar("terminal_request_digest", { length: 71 }),
+    terminalResultJson: jsonb("terminal_result_json").$type<
+      Record<string, unknown>
+    >(),
+    artifactRef: varchar("artifact_ref", { length: 37 }),
+    artifactFilename: varchar("artifact_filename", { length: 240 }),
+    artifactContentType: varchar("artifact_content_type", { length: 120 }),
+    artifactByteSize: integer("artifact_byte_size"),
+    artifactSha256: varchar("artifact_sha256", { length: 64 }),
+    cancelRequestedAt: doublePrecision("cancel_requested_at"),
+    finishedAt: doublePrecision("finished_at"),
+    version: integer("version").notNull().default(1),
+    createdAt: doublePrecision("created_at").notNull(),
+    updatedAt: doublePrecision("updated_at").notNull(),
+  },
+  (table) => [
+    uniqueIndex("uk_client_agent_workflow_command").on(table.commandId),
+    uniqueIndex("uk_client_agent_workflow_job").on(table.durableJobId),
+    uniqueIndex("uk_client_agent_workflow_terminal_receipt").on(
+      table.terminalReceiptId,
+    ),
+    uniqueIndex("uk_client_agent_workflow_client_session").on(
+      table.clientSessionId,
+    ),
+    index("idx_client_agent_workflow_claim").on(
+      table.actorId,
+      table.status,
+      table.updatedAt,
+    ),
+    index("idx_client_agent_workflow_host").on(
+      table.hostSessionDigest,
+      table.status,
+    ),
+    foreignKey({
+      columns: [
+        table.commandId,
+        table.runId,
+        table.nodeRunId,
+        table.effectKind,
+        table.effectGeneration,
+        table.requestDigest,
+        table.effectFenceTokenDigest,
+      ],
+      foreignColumns: [
+        agentWorkflowSideEffectCommands.commandId,
+        agentWorkflowSideEffectCommands.runId,
+        agentWorkflowSideEffectCommands.nodeRunId,
+        agentWorkflowSideEffectCommands.effectKind,
+        agentWorkflowSideEffectCommands.generation,
+        agentWorkflowSideEffectCommands.requestDigest,
+        agentWorkflowSideEffectCommands.fenceTokenDigest,
+      ],
+      name: "fk_client_agent_workflow_effect_fence",
+    }).onDelete("restrict"),
+    check(
+      "ck_client_agent_workflow_status",
+      sql`${table.status} in ('pending', 'claimed', 'cancellation-requested', 'completed', 'cancelled')`,
+    ),
+    check(
+      "ck_client_agent_workflow_generation",
+      sql`${table.effectGeneration} > 0 and ${table.claimGeneration} >= 0`,
+    ),
+    check(
+      "ck_client_agent_workflow_effect_kind",
+      sql`${table.effectKind} = 'job'`,
+    ),
+    check(
+      "ck_client_agent_workflow_claim_binding",
+      sql`(${table.claimGeneration} = 0 and ${table.status} in ('pending', 'cancellation-requested', 'cancelled') and ${table.clientBindingDigest} is null and ${table.installationId} is null and ${table.hostSessionDigest} is null and ${table.clientSessionId} is null and ${table.claimTokenHash} is null and ${table.claimExpiresAt} is null)
+        or (${table.claimGeneration} > 0 and ${table.status} <> 'pending' and ${table.clientBindingDigest} is not null and ${table.installationId} is not null and ${table.hostSessionDigest} is not null)`,
+    ),
+    check(
+      "ck_client_agent_workflow_terminal",
+      sql`(${table.status} = 'completed' and ${table.terminalReceiptId} is not null and ${table.terminalReceiptDigest} is not null and ${table.terminalRequestDigest} is not null and ${table.terminalResultJson} is not null and ${table.artifactRef} is not null and ${table.artifactFilename} is not null and ${table.artifactContentType} is not null and ${table.artifactByteSize} is not null and ${table.artifactSha256} is not null and ${table.finishedAt} is not null)
+        or (${table.status} = 'cancelled' and ${table.finishedAt} is not null and ${table.terminalReceiptId} is null and ${table.terminalRequestDigest} is null and ${table.artifactRef} is null)
+        or (${table.status} in ('pending', 'claimed', 'cancellation-requested') and ${table.finishedAt} is null and ${table.terminalReceiptId} is null and ${table.terminalRequestDigest} is null and ${table.artifactRef} is null)`,
+    ),
+    check(
+      "ck_client_agent_workflow_history",
+      sql`${table.historySequence} >= 0 and (${table.historySequence} = 0 or ${table.historyHeadDigest} is not null)`,
+    ),
+    check(
+      "ck_client_agent_workflow_version",
+      sql`${table.version} > 0 and ${table.createdAt} <= ${table.updatedAt}`,
+    ),
+  ],
+);

package/template/packages/database/src/schema/index.ts

@@ -39,6 +39,7 @@ export * from "./agent-context-message.js";
 export * from "./agent-session-receipt.js";
 export * from "./agent-session.js";
 export * from "./client-agent.js";
+export * from "./client-agent-workflow-artifact.js";
 export * from "./embedding-runtime.js";
 export * from "./ai-output-artifacts.js";
 // @windy-module system.agent end

package/template/packages/jobs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/jobs",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

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

@@ -81,5 +81,15 @@ function createContext(): DurableHandlerContext {
     heartbeat: async () => undefined,
     progress: async () => undefined,
     publishArtifact: async () => undefined,
+    publishArtifactOnce: async (publicationKey, artifact) => ({
+      schemaVersion: 1,
+      publicationKey,
+      artifactId: "dap_stable",
+      jobId: "job-1",
+      stageKey: "main",
+      kind: artifact.kind,
+      artifactRef: artifact.artifactRef,
+      sha256: artifact.sha256,
+    }),
   };
 }

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/package.json

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

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

@@ -16,6 +16,12 @@ export function validateClientExecution(
   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,

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

@@ -174,6 +174,8 @@ export interface AiOperationLimits {
  */
 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;

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

@@ -23,4 +23,7 @@ export const agentAuditActionKeys: ReadonlySet<string> = new Set([
   "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

@@ -149,6 +149,21 @@ function workflowBindings(): ApiPermissionBinding[] {
       "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}`,
+      ),
+    ),
   ];
 }
 

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

@@ -209,6 +209,21 @@ export const systemAuditActions: ModuleManifest["auditActions"] = [
     label: "解析 Agent Workflow 产物",
     description: "在对象授权与数据范围内解析 Workflow 产物引用。",
   },
+  {
+    key: "agent.workflow.client-artifact.claim",
+    label: "领取 Client Agent Workflow 任务",
+    description: "按当前宿主身份领取已持久化且受 fence 约束的浏览器任务。",
+  },
+  {
+    key: "agent.workflow.client-artifact.advance",
+    label: "推进 Client Agent Workflow 任务",
+    description: "校验完整 Provider receipt 链并封存 Durable Artifact。",
+  },
+  {
+    key: "agent.workflow.client-artifact.cancel",
+    label: "取消 Client Agent Workflow 任务",
+    description: "取消当前领取代次并拒绝迟到结果写入。",
+  },
   // @windy-module system.agent end
   "security.denied",
   "system.error",

package/template/packages/server-sdk/index.ts

@@ -2,6 +2,7 @@ export type { ModuleActor } from "./src/actor.js";
 export { pageAgentClientRunCapability } from "./src/client-agent-session.js";
 export type {
   ModuleClientAgentHostAuthAdapter,
+  ModuleClientAgentHostAuthPurpose,
   ModuleClientAgentHostPrincipal,
   ModuleClientAgentSessionCreateInput,
   ModuleClientAgentSessionGrant,
@@ -10,6 +11,30 @@ export type {
   ModuleClientAgentSessionStatus,
   ModuleClientAgentSessionView,
 } from "./src/client-agent-session.js";
+// @windy-module system.agent begin
+export {
+  CLIENT_AGENT_WORKFLOW_ARTIFACT_BINDING_LIMITS,
+  CLIENT_AGENT_WORKFLOW_ARTIFACT_TASK_KEY,
+  CLIENT_AGENT_WORKFLOW_ARTIFACT_WORK_ID_PREFIX,
+  CLIENT_AGENT_WORKFLOW_SCOPE_CONTAINMENT_CONTRACT_VERSION,
+} from "./src/client-agent-workflow-artifact.js";
+export type {
+  ModuleClientAgentWorkflowArtifactBeginSpec,
+  ModuleClientAgentWorkflowArtifactCommand,
+  ModuleClientAgentWorkflowArtifactPolicy,
+  ModuleClientAgentWorkflowArtifactPort,
+  ModuleClientAgentWorkflowArtifactProjectBinding,
+  ModuleClientAgentWorkflowArtifactSafeCode,
+  ModuleClientAgentWorkflowArtifactStatus,
+  ModuleClientAgentWorkflowArtifactSummary,
+  ModuleClientAgentWorkflowArtifactTerminalResultAuthority,
+  ModuleClientAgentWorkflowClientTaskAuthority,
+  ModuleClientAgentWorkflowExecutionTask,
+  ModuleClientAgentWorkflowTaskInputArtifact,
+  ModuleClientAgentWorkflowProjectLaunchAuthority,
+  ModuleClientAgentWorkflowArtifactView,
+} from "./src/client-agent-workflow-artifact.js";
+// @windy-module system.agent end
 export type {
   ModuleAiArtifactPort,
   ModuleAiArtifactRef,
@@ -150,6 +175,33 @@ export type {
   ModuleDurableHandlerDefinition,
   ModuleDurableStoragePort,
 } from "./src/durable-handler.js";
+// @windy-module system.agent begin
+export {
+  ModuleWorkflowInputArtifactUnavailableError,
+  ModuleWorkflowInputMaterializationError,
+  requireModuleWorkflowInputArtifactPublicationPortV1,
+  type ModuleWorkflowInputArtifactPublicationPortV1,
+  type ModuleWorkflowInputArtifactPublicationV1,
+  type ModuleWorkflowInputArtifactSourceV1,
+  type ModuleWorkflowInputJsonArtifactV1,
+  type ModuleWorkflowInputResourceArtifactV1,
+  type ModuleWorkflowInputMaterializationHandleV1,
+  type ModuleWorkflowInputMaterializationPortV1,
+  type ModuleWorkflowInputMaterializationSourceV1,
+  type ModuleWorkflowInputMaterializationViewV1,
+  moduleWorkflowInputMaterializationHandlerKey,
+} from "./src/workflow-input-artifact-port.js";
+export {
+  MODULE_WORKFLOW_INPUT_MATERIALIZATION_LIMITS_V1,
+  parseModuleWorkflowInputJsonArtifactV1,
+  parseModuleWorkflowInputJsonValueV1,
+  parseModuleWorkflowInputMaterializationBeginV1,
+  parseModuleWorkflowInputMaterializationPayloadV1,
+  parseModuleWorkflowInputMaterializationSourceV1,
+  parseModuleWorkflowInputResourceArtifactV1,
+} from "./src/workflow-input-artifact-validation.js";
+export { defineModuleWorkflowInputMaterializationHandlerV1 } from "./src/workflow-input-materialization-handler.js";
+// @windy-module system.agent end
 export type {
   GovernedExportRenderedArtifact,
   GovernedExportWatermarkContext,

package/template/packages/server-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/server-sdk",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -32,6 +32,7 @@
     "src/audit-port.ts",
     "src/background-ai-port.ts",
     "src/client-agent-session.ts",
+    "src/client-agent-workflow-artifact.ts",
     "src/data-governance-registration.ts",
     "src/debug-session-provider.ts",
     "src/durable-handler.ts",
@@ -52,6 +53,9 @@
     "src/task-registration.ts",
     "src/tool-registration.ts",
     "src/tool-host-port.ts",
+    "src/workflow-input-artifact-port.ts",
+    "src/workflow-input-artifact-validation.ts",
+    "src/workflow-input-materialization-handler.ts",
     "src/user-directory-port.ts",
     "contracts/**/*.json"
   ],

package/template/packages/server-sdk/src/client-agent-session.ts

@@ -8,11 +8,23 @@ export interface ModuleClientAgentHostPrincipal {
   readonly sessionId: string;
 }
 
+export type ModuleClientAgentHostAuthPurpose = "control" | "completion";
+
 export interface ModuleClientAgentHostAuthAdapter {
   ready(signal?: AbortSignal): Promise<boolean>;
   authenticate(input: {
     readonly token: string;
-    readonly purpose: "control" | "completion";
+    readonly purpose: ModuleClientAgentHostAuthPurpose;
+    readonly signal?: AbortSignal;
+  }): Promise<ModuleClientAgentHostPrincipal | undefined>;
+  /**
+   * Web Cookie 等当前登录会话可选入口。Host 已解析 canonical Actor，Adapter 只确认
+   * installation/session 绑定；返回 principal 仍不得携带权限、Scope 或业务坐标。
+   */
+  authenticateCurrentSession?(input: {
+    readonly request: Request;
+    readonly actorId: string;
+    readonly purpose: ModuleClientAgentHostAuthPurpose;
     readonly signal?: AbortSignal;
   }): Promise<ModuleClientAgentHostPrincipal | undefined>;
   bindRevocations(