create-windy 0.3.2 → 0.3.5

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

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/server-sdk",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -9,14 +9,20 @@
   "files": [
     "index.ts",
     "src/actor.ts",
+    "src/ai-artifact-port.ts",
+    "src/ai-operation-port.ts",
     "src/ai-operation-registration.ts",
     "src/audit-port.ts",
+    "src/background-ai-port.ts",
+    "src/data-governance-registration.ts",
+    "src/durable-handler.ts",
     "src/jobs-port.ts",
     "src/module-host.ts",
     "src/namespace.ts",
     "src/request-context.ts",
     "src/role-preset.ts",
     "src/route-definition.ts",
+    "src/sandbox-tool.ts",
     "src/search-provider-port.ts",
     "src/storage-port.ts",
     "src/task-registration.ts",
@@ -29,9 +35,9 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "dependencies": {
-    "@southwind-ai/jobs": "workspace:*",
-    "@southwind-ai/shared": "workspace:*",
-    "@southwind-ai/storage": "workspace:*"
+    "@southwind-ai/jobs": "workspace:^",
+    "@southwind-ai/shared": "workspace:^",
+    "@southwind-ai/storage": "workspace:^"
   },
   "exports": {
     ".": "./index.ts"

package/template/packages/server-sdk/src/ai-artifact-port.ts

@@ -0,0 +1,34 @@
+import type { ModuleResourceFileRequest } from "./storage-port.js";
+
+export interface ModuleAiArtifactRef {
+  /** 平台签发的不透明短时引用；业务不得解析或拼接底层地址。 */
+  readonly value: string;
+  readonly mediaType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+  readonly expiresAt: string;
+}
+
+export interface ModuleAiArtifactPort {
+  /**
+   * 将已经过业务对象绑定和当前 Actor 授权的资源文件换成短时 ArtifactRef。
+   * Port 不暴露 Blob Key、宿主路径、平台 Repository 或 Provider 凭据。
+   */
+  issue(
+    source: ModuleResourceFileRequest,
+    options?: { ttlSeconds?: number },
+  ): Promise<ModuleAiArtifactRef>;
+}
+
+export class ModuleAiArtifactError extends Error {
+  constructor(
+    readonly code:
+      | "AI_ARTIFACT_UNAVAILABLE"
+      | "AI_ARTIFACT_FORBIDDEN"
+      | "AI_ARTIFACT_INVALID",
+    message: string,
+  ) {
+    super(message);
+    this.name = "ModuleAiArtifactError";
+  }
+}

package/template/packages/server-sdk/src/ai-operation-port.ts

@@ -0,0 +1,65 @@
+import type { ModuleAiArtifactRef } from "./ai-artifact-port.js";
+import type { ModuleAiJsonValue } from "./ai-operation-registration.js";
+
+export interface ModuleAiRunReceipt {
+  readonly runId: string;
+  readonly status: string;
+  readonly eventsUrl: string;
+}
+
+export type ModuleEmbeddingItem =
+  | { readonly id: string; readonly text: string }
+  | { readonly id: string; readonly source: ModuleAiArtifactRef };
+
+export interface ModuleAiOperationPort {
+  startAgent(input: {
+    operationKey: string;
+    input: ModuleAiJsonValue;
+    artifacts?: readonly ModuleAiArtifactRef[];
+    idempotencyKey: string;
+  }): Promise<ModuleAiRunReceipt>;
+  startDocument(input: {
+    operationKey: string;
+    sources: readonly ModuleAiArtifactRef[];
+    options: ModuleAiJsonValue;
+    idempotencyKey: string;
+  }): Promise<ModuleAiRunReceipt>;
+  startSpeech(input: {
+    operationKey: string;
+    source: ModuleAiArtifactRef;
+    options: ModuleAiJsonValue;
+    idempotencyKey: string;
+  }): Promise<ModuleAiRunReceipt>;
+  embed(input: {
+    operationKey: string;
+    items: readonly ModuleEmbeddingItem[];
+    options: ModuleAiJsonValue;
+    idempotencyKey: string;
+  }): Promise<ModuleAiJsonValue>;
+  result(input: {
+    kind: "agent" | "document" | "speech";
+    operationKey: string;
+    runId: string;
+  }): Promise<ModuleAiJsonValue>;
+  cancel(input: {
+    kind: "agent" | "document" | "speech";
+    operationKey: string;
+    runId: string;
+    reason?: string;
+  }): Promise<void>;
+}
+
+export class ModuleAiOperationError extends Error {
+  constructor(
+    readonly code:
+      | "AI_OPERATION_UNAVAILABLE"
+      | "AI_OPERATION_FORBIDDEN"
+      | "AI_OPERATION_INVALID"
+      | "AI_OPERATION_PENDING"
+      | "AI_OPERATION_FAILED",
+    message: string,
+  ) {
+    super(message);
+    this.name = "ModuleAiOperationError";
+  }
+}

package/template/packages/server-sdk/src/ai-operation-registration.ts

@@ -16,12 +16,53 @@ export interface ModuleAiOperationContext {
 export interface ModuleAiOperationPlan {
   readonly instructions: string;
   readonly userPrompt: string;
+  /**
+   * 可选 JSON Schema。宿主只把它交给受控 Runtime，并以 Manifest outputSchemaKey
+   * 关联审计；业务不能在此选择模型、Provider 或 Endpoint。
+   */
+  readonly outputSchema?: ModuleAiJsonValue;
+}
+
+export interface ModuleDocumentOperationPlan {
+  /** 已由业务校验并经 Provider input allowlist/DLP 收窄的模型无关选项。 */
+  readonly options?: ModuleAiJsonValue;
+}
+
+export interface ModuleSpeechOperationPlan {
+  /** 领域校验后的批量转写选项；不包含 Provider、Endpoint、模型或 Secret。 */
+  readonly options?: ModuleAiJsonValue;
+}
+
+export interface ModuleEmbeddingOperationPlan {
+  /** 领域校验后的批量向量选项，不包含模型、维度、Provider 或向量库。 */
+  readonly options?: ModuleAiJsonValue;
 }
 
 export interface ModuleAiOperationHandlerRegistration {
   readonly operationKey: string;
-  prepare(
+  /**
+   * 不可变发布坐标。修改 Workflow、Prompt 或 Route 时必须提升对应版本；
+   * 宿主以这些坐标和 Manifest/Tool Schema 摘要固定每个 Run。
+   */
+  readonly release?: {
+    readonly workflowVersion: string;
+    readonly promptVersion: string;
+    readonly routeVersion: string;
+  };
+  prepare?(
     input: ModuleAiJsonValue,
     context: ModuleAiOperationContext,
   ): Promise<ModuleAiOperationPlan> | ModuleAiOperationPlan;
+  prepareDocument?(
+    input: ModuleAiJsonValue,
+    context: ModuleAiOperationContext,
+  ): Promise<ModuleDocumentOperationPlan> | ModuleDocumentOperationPlan;
+  prepareSpeech?(
+    input: ModuleAiJsonValue,
+    context: ModuleAiOperationContext,
+  ): Promise<ModuleSpeechOperationPlan> | ModuleSpeechOperationPlan;
+  prepareEmbedding?(
+    input: ModuleAiJsonValue,
+    context: ModuleAiOperationContext,
+  ): Promise<ModuleEmbeddingOperationPlan> | ModuleEmbeddingOperationPlan;
 }

package/template/packages/server-sdk/src/background-ai-port.ts

@@ -0,0 +1,43 @@
+import type { ModuleAiJsonValue } from "./ai-operation-registration.js";
+
+export interface ModuleBackgroundAiOperationInput {
+  readonly operationKey: string;
+  readonly input: ModuleAiJsonValue;
+  readonly idempotencyKey: string;
+  readonly timeoutSeconds?: number;
+}
+
+export interface ModuleBackgroundAiOperationResult {
+  readonly runId: string;
+  readonly output: ModuleAiJsonValue;
+}
+
+/**
+ * Durable Handler 内的 Actor-aware AI Operation 窄接口。
+ *
+ * Actor、模块命名空间、Guard、Provider 和 Execution Grant 均由宿主持有。
+ */
+export interface ModuleBackgroundAiPort {
+  enqueueOperation(
+    input: ModuleBackgroundAiOperationInput,
+  ): Promise<ModuleBackgroundAiOperationResult>;
+}
+
+export type ModuleBackgroundAiErrorCode =
+  | "AI_OPERATION_UNAVAILABLE"
+  | "AI_OPERATION_DENIED"
+  | "AI_OPERATION_INVALID"
+  | "AI_OPERATION_FAILED"
+  | "AI_OPERATION_CANCELLED"
+  | "AI_OPERATION_TIMEOUT";
+
+export class ModuleBackgroundAiError extends Error {
+  constructor(
+    readonly code: ModuleBackgroundAiErrorCode,
+    message: string,
+    readonly retryable: boolean,
+  ) {
+    super(message);
+    this.name = "ModuleBackgroundAiError";
+  }
+}

package/template/packages/server-sdk/src/data-governance-registration.ts

@@ -0,0 +1,116 @@
+import type { ModuleActor } from "./actor.js";
+import type { JsonValue } from "@southwind-ai/shared";
+
+export interface ModuleGovernedResourceContext {
+  readonly actor: ModuleActor;
+  readonly requestId: string;
+  readonly signal: AbortSignal;
+}
+
+export interface ModuleGovernedRecord {
+  readonly id: string;
+  /** 已排除治理字段的普通业务投影。 */
+  readonly publicFields: Readonly<Record<string, unknown>>;
+  /** Key 必须全部来自 Manifest 对应 Data Policy。 */
+  readonly governedFields: Readonly<Record<string, unknown>>;
+}
+
+export type ModuleGovernedExportQuery = Readonly<
+  Record<string, JsonValue | undefined>
+>;
+
+export interface ModuleGovernedExportPageInput {
+  readonly query: ModuleGovernedExportQuery;
+  readonly cursor?: string;
+  readonly limit: number;
+}
+
+export interface ModuleGovernedExportPage {
+  readonly records: readonly Readonly<Record<string, JsonValue>>[];
+  readonly nextCursor?: string;
+}
+
+export interface GovernedExportWatermarkContext {
+  readonly actorId: string;
+  readonly generatedAt: string;
+  readonly scopeHash: string;
+  readonly jobId: string;
+  readonly requestId: string;
+}
+
+export interface GovernedExportRenderedArtifact {
+  readonly body: ReadableStream<Uint8Array>;
+  /** 不得包含记录原文或敏感字段，仅用于受控 artifact 元数据与审计。 */
+  readonly contentMetadata?: Readonly<Record<string, JsonValue>>;
+}
+
+export interface ModuleGovernedExportRendererRegistration {
+  readonly formatKey: string;
+  readonly templateKey: string;
+  readonly templateVersion: string;
+  readonly inputSchemaKey: string;
+  readonly contentType: string;
+  /** 不含点号，例如 pdf、docx、xlsx。 */
+  readonly filenameExtension: string;
+  readonly limits: {
+    readonly maxRecords: number;
+    readonly maxOutputBytes: number;
+    readonly timeoutSeconds: number;
+  };
+  render(
+    input: {
+      readonly records: AsyncIterable<Readonly<Record<string, JsonValue>>>;
+      readonly watermark: GovernedExportWatermarkContext;
+    },
+    context: {
+      readonly signal: AbortSignal;
+      readonly heartbeat: () => Promise<void>;
+    },
+  ):
+    | Promise<GovernedExportRenderedArtifact>
+    | GovernedExportRenderedArtifact;
+}
+
+export interface ModuleGovernedExportRegistration {
+  /** 四个导出端点的基路径，例如 /api/people/persons/exports。 */
+  readonly basePath: string;
+  /** 默认要求审批；只能显式关闭，不由客户端决定。 */
+  readonly approvalRequired?: boolean;
+  /** 产物保留时间；宿主还会施加平台上限。 */
+  readonly retentionSeconds?: number;
+  /**
+   * 服务端受治理 Renderer。声明后请求必须显式选择已注册 formatKey；
+   * 未声明时保持既有 NDJSON 行为。
+   */
+  readonly renderers?: readonly ModuleGovernedExportRendererRegistration[];
+  validateQuery(query: unknown): ModuleGovernedExportQuery;
+  readPage(
+    input: ModuleGovernedExportPageInput,
+    context: ModuleGovernedResourceContext,
+  ): Promise<ModuleGovernedExportPage> | ModuleGovernedExportPage;
+}
+
+/**
+ * 业务资源治理注册。
+ *
+ * authorize 与 read 分离，避免“能按 ID 查到”被误当作对象级授权。宿主在调用 read 前先
+ * 执行当前 Feature、Permission、Scope 与 authorize；未授权和不存在使用同形结果。
+ */
+export interface ModuleGovernedResourceRegistration {
+  readonly policyKey: string;
+  readonly readPath: string;
+  readonly revealPath: string;
+  readonly revealAuditAction: string;
+  readonly export?: ModuleGovernedExportRegistration;
+  authorize(
+    resourceId: string,
+    context: ModuleGovernedResourceContext,
+  ): Promise<boolean> | boolean;
+  read(
+    resourceId: string,
+    context: ModuleGovernedResourceContext,
+  ):
+    | Promise<ModuleGovernedRecord | undefined>
+    | ModuleGovernedRecord
+    | undefined;
+}

package/template/packages/server-sdk/src/durable-handler.ts

@@ -0,0 +1,29 @@
+import type { DurableHandlerContext, PayloadParser } from "@southwind-ai/jobs";
+import type { ModuleActor } from "./actor.js";
+import type { ModuleBackgroundAiPort } from "./background-ai-port.js";
+import type {
+  ModuleOpenedResourceFile,
+  ModuleResourceFileRequest,
+} from "./storage-port.js";
+
+export interface ModuleDurableStoragePort {
+  openResourceFile(
+    input: ModuleResourceFileRequest,
+  ): Promise<ModuleOpenedResourceFile>;
+}
+
+export interface ModuleDurableHandlerContext extends DurableHandlerContext {
+  readonly actor: ModuleActor;
+  readonly requestId: string;
+  readonly storage: ModuleDurableStoragePort;
+  readonly ai: ModuleBackgroundAiPort;
+}
+
+export interface ModuleDurableHandlerDefinition<T> {
+  readonly key: string;
+  readonly payload: PayloadParser<T>;
+  execute(
+    payload: T,
+    context: ModuleDurableHandlerContext,
+  ): Promise<void> | void;
+}

package/template/packages/server-sdk/src/jobs-port.ts

@@ -22,3 +22,72 @@ export interface ModuleJobSubmitResult {
 export interface ModuleJobSubmitter {
   submit(input: ModuleJobSubmitInput): Promise<ModuleJobSubmitResult>;
 }
+
+export type ModuleJobStatus =
+  | "queued"
+  | "running"
+  | "succeeded"
+  | "failed"
+  | "cancelled";
+
+export interface ModuleJobProgressView {
+  readonly completedUnits: number;
+  readonly totalUnits?: number;
+}
+
+export interface ModuleJobView {
+  readonly jobId: string;
+  readonly handlerKey: string;
+  readonly status: ModuleJobStatus;
+  readonly progress?: ModuleJobProgressView;
+  readonly attempt: number;
+  readonly maxAttempts: number;
+  readonly createdAt: string;
+  readonly startedAt?: string;
+  readonly finishedAt?: string;
+  readonly failureCode?: string;
+  readonly canCancel: boolean;
+  readonly canRecover: boolean;
+  /** 当前持久化版本；控制操作必须回传该值以执行 CAS。 */
+  readonly version: string;
+}
+
+export interface ModuleJobCancelInput {
+  readonly jobId: string;
+  readonly reason: string;
+  readonly expectedStatus?: ModuleJobStatus;
+  readonly expectedVersion?: string;
+}
+
+export interface ModuleJobRecoverInput {
+  readonly jobId: string;
+  readonly reason: string;
+  readonly expectedAttempt: number;
+  readonly expectedStatus: ModuleJobStatus;
+  readonly expectedVersion: string;
+}
+
+export type ModuleJobControlErrorCode =
+  | "JOB_NOT_AVAILABLE"
+  | "JOB_STATE_CONFLICT"
+  | "JOB_CONTROL_UNAVAILABLE"
+  | "JOB_REASON_INVALID";
+
+export class ModuleJobControlError extends Error {
+  constructor(
+    readonly code: ModuleJobControlErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ModuleJobControlError";
+  }
+}
+
+/**
+ * 宿主绑定 Module、Queue、Actor 与授权范围的 Durable Job 受限控制 Port。
+ */
+export interface ModuleJobPort extends ModuleJobSubmitter {
+  get(jobId: string): Promise<ModuleJobView | undefined>;
+  cancel(input: ModuleJobCancelInput): Promise<ModuleJobView>;
+  recover(input: ModuleJobRecoverInput): Promise<ModuleJobView>;
+}

package/template/packages/server-sdk/src/module-host.ts

@@ -1,8 +1,10 @@
-import type { DurableHandlerDefinition } from "@southwind-ai/jobs";
 import type { ModuleAiOperationHandlerRegistration } from "./ai-operation-registration.js";
+import type { ModuleDurableHandlerDefinition } from "./durable-handler.js";
+import type { ModuleGovernedResourceRegistration } from "./data-governance-registration.js";
 import type { ModuleRolePreset } from "./role-preset.js";
 import type { ModuleRouteDefinition } from "./route-definition.js";
 import type { ModuleSearchProvider } from "./search-provider-port.js";
+import type { ModuleSandboxToolHost } from "./sandbox-tool.js";
 import type { ModuleResourceFileAccessPolicy } from "./storage-port.js";
 import type { ModuleTaskHandlerRegistration } from "./task-registration.js";
 import type { ModuleToolHandlerRegistration } from "./tool-registration.js";
@@ -33,7 +35,13 @@ export interface ModuleHost {
   registerResourceFileAccessPolicies(
     policies: readonly ModuleResourceFileAccessPolicy[],
   ): void;
-  registerDurableHandler<T>(definition: DurableHandlerDefinition<T>): void;
+  registerDurableHandler<T>(
+    definition: ModuleDurableHandlerDefinition<T>,
+  ): void;
+  /** 注册 Manifest Data Policy 对应的对象授权、脱敏读取与明文揭示入口。 */
+  registerGovernedResources(
+    registrations: readonly ModuleGovernedResourceRegistration[],
+  ): void;
   /** 注册 Guarded API 路由；须与 Manifest `apiPermissions` 声明一致。 */
   registerRoutes(routes: readonly ModuleRouteDefinition[]): void;
   /** 注册 Manifest `tasks` 已声明定时任务的执行体。 */
@@ -74,4 +82,10 @@ export interface ModuleInitializer {
 export interface InstallableServerModule<TManifest> {
   readonly manifest: TManifest;
   setup(host: ModuleHost): Promise<void> | void;
+  /**
+   * 注册只能在无网络 Tool Worker 中执行的纯业务 Handler。
+   * 该入口不得闭包捕获 Repository、Secret、文件系统或平台运行时。
+   * 注册必须同步完成，避免 Worker 在定义尚未稳定时开始接收请求。
+   */
+  setupSandbox?(host: ModuleSandboxToolHost): void;
 }

package/template/packages/server-sdk/src/request-context.ts

@@ -1,6 +1,8 @@
 import type { ModuleActor } from "./actor.js";
 import type { ModuleAuditEmitter } from "./audit-port.js";
-import type { ModuleJobSubmitter } from "./jobs-port.js";
+import type { ModuleAiArtifactPort } from "./ai-artifact-port.js";
+import type { ModuleAiOperationPort } from "./ai-operation-port.js";
+import type { ModuleJobPort } from "./jobs-port.js";
 import type { ModuleStoragePort } from "./storage-port.js";
 import type { ModuleUserDirectoryPort } from "./user-directory-port.js";
 
@@ -17,7 +19,9 @@ export interface ModuleRequestContext {
   readonly query: Record<string, string | undefined>;
   readonly body?: unknown;
   readonly audit: ModuleAuditEmitter;
-  readonly jobs: ModuleJobSubmitter;
+  readonly aiArtifacts: ModuleAiArtifactPort;
+  readonly aiOperations: ModuleAiOperationPort;
+  readonly jobs: ModuleJobPort;
   readonly storage: ModuleStoragePort;
   readonly userDirectory: ModuleUserDirectoryPort;
 }

package/template/packages/server-sdk/src/sandbox-tool.ts

@@ -0,0 +1,21 @@
+import type { ModuleToolInput, ModuleToolResult } from "./tool-registration.js";
+
+export interface ModuleSandboxToolContext {
+  readonly idempotencyKey: string;
+  readonly signal: AbortSignal;
+}
+
+export interface ModuleSandboxToolHandlerRegistration {
+  readonly toolKey: string;
+  execute(
+    input: ModuleToolInput,
+    context: ModuleSandboxToolContext,
+  ): Promise<ModuleToolResult> | ModuleToolResult;
+}
+
+export interface ModuleSandboxToolHost {
+  readonly moduleName: string;
+  registerToolHandlers(
+    registrations: readonly ModuleSandboxToolHandlerRegistration[],
+  ): void;
+}

package/template/packages/server-sdk/src/tool-registration.ts

@@ -5,6 +5,8 @@ import type { ModuleStoragePort } from "./storage-port.js";
 export interface ModuleToolContext {
   readonly actor: ModuleActor;
   readonly requestId: string;
+  /** 当前 Run 内稳定 Tool Call 标识；写 Tool 必须作为业务幂等键使用。 */
+  readonly idempotencyKey: string;
   readonly signal: AbortSignal;
   /**
    * 与当前 Tool Actor、请求范围和模块命名空间绑定的受限存储 Port。

package/template/packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/shared",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/shared/src/rbac.ts

@@ -23,6 +23,7 @@ export type PermissionAction =
   | "reveal"
   | "approve"
   | "execute"
+  | "retry"
   | "manage";
 
 export type PermissionAccessRisk =
@@ -40,6 +41,35 @@ export type DataScope =
   | "self"
   | "custom";
 
+export type PersistedScopeGrant =
+  | { scope: "all" | "tenant" | "self" }
+  | {
+      scope: "department" | "department-and-children";
+      departmentId?: string;
+    }
+  | { scope: "custom"; dimension: string; values: string[] };
+
+/**
+ * 后台任务可持久化的最小授权范围快照。
+ *
+ * 不包含 Permission、凭据、Secret 或业务字段值；恢复执行时仍须重新解析当前 Actor
+ * 并重新执行 Feature、Permission、License 与对象绑定检查。
+ */
+export interface AuthorizationScopeSnapshot {
+  tenantId: "single-tenant";
+  actorId: string;
+  departmentId?: string;
+  grants: PersistedScopeGrant[];
+  roleIds: string[];
+}
+
+export interface AgentRunAuthorizationSnapshot {
+  permissionKey: string;
+  featureKey: string;
+  allowedToolKeys: string[];
+  toolNetworkMode: "forbidden";
+}
+
 export type CredentialState = "active" | "must-change-password";
 
 export interface PermissionDefinition {