@southwind-ai/shared 0.3.1 → 0.3.3

package/index.ts

@@ -2,6 +2,8 @@ export * from "./src/audit.js";
 export * from "./src/ai-operation-readiness.js";
 // @windy-module system.agent begin
 export * from "./src/ai-runtime-report.js";
+export * from "./src/agent-admin-catalog.js";
+export * from "./src/agent-workbench.js";
 export * from "./src/agent-workflow.js";
 export * from "./src/agent-workflow-events.js";
 export * from "./src/agent-workflow-evaluation.js";
@@ -33,3 +35,18 @@ export * from "./src/stable-key.js";
 export * from "./src/workflow.js";
 
 export * from "./src/license-console-capabilities.js";
+
+// @windy-module system.agent begin
+export * from "./src/agent-skills.js";
+// @windy-module system.agent end
+
+// @windy-module system.audit begin
+export * from "./src/diagnostics.js";
+// @windy-module system.audit end
+
+// @windy-module system.agent begin
+export * from "./src/agent-workflow-presets.js";
+// @windy-module system.agent end
+
+export * from "./src/environment-assessment.js";
+export * from "./src/environment-policy.js";

package/package.json

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

package/src/agent-admin-catalog.ts

@@ -0,0 +1,73 @@
+import type { JsonObject } from "./json.js";
+import type { CandidateRole } from "./workflow.js";
+
+/** Public, bounded categories; never include raw Guard events or Provider bodies. */
+export type AgentAdminAvailabilityReason =
+  | "allowed"
+  | "permission-denied"
+  | "feature-unavailable"
+  | "license-unavailable"
+  | "scope-unavailable"
+  | "runtime-unavailable"
+  | "workflow-only"
+  | "internal-operation"
+  | "unsupported-operation"
+  | "handler-unavailable"
+  | "governance-unavailable";
+
+export interface AgentAdminToolCatalogItem {
+  readonly key: string;
+  readonly label: string;
+  readonly description: string;
+  readonly module: string;
+  readonly operation: "query" | "command" | "background";
+  readonly featureKey: string;
+  readonly permissionKey: string;
+  readonly auditAction: string;
+  readonly scopeMode: "platform" | "request";
+  readonly executionMode: "host" | "sandbox";
+  readonly dataClassification: "public" | "internal" | "sensitive";
+  readonly approval: "none" | "required";
+  readonly approvalRoles?: readonly CandidateRole[];
+  readonly approvalTimeoutSeconds?: number;
+  readonly idempotency: "none" | "supported" | "required";
+  readonly limits: AgentAdminCatalogLimits;
+  readonly inputSchemaKey: string;
+  readonly outputSchemaKey: string;
+  readonly inputSchema: JsonObject;
+  readonly outputSchema: JsonObject;
+  readonly allowedOperationKeys: readonly string[];
+  /** Current Guard + Scope eligibility, not an execution or approval grant. */
+  readonly allowed: boolean;
+  readonly availabilityReason: AgentAdminAvailabilityReason;
+}
+
+export interface AgentAdminCatalogLimits {
+  readonly maxDurationSeconds: number;
+  readonly maxInputBytes: number;
+  readonly maxOutputBytes: number;
+}
+
+export interface AgentAdminOperationCatalogItem {
+  readonly key: string;
+  readonly module: string;
+  readonly moduleLabel: string;
+  readonly kind: string;
+  readonly visibility: "public" | "internal";
+  readonly execution: string;
+  readonly featureKey: string;
+  readonly permissionKey: string;
+  readonly auditAction: string;
+  readonly dataClassification: "public" | "internal" | "sensitive";
+  readonly requiredCapabilities: readonly string[];
+  readonly inputModalities: readonly string[];
+  readonly inputSchemaKey: string;
+  readonly outputSchemaKey: string;
+  readonly inputSchema?: JsonObject;
+  readonly outputSchema?: JsonObject;
+  readonly allowedToolKeys: readonly string[];
+  readonly limits: AgentAdminCatalogLimits;
+  readonly launchAuthority: "direct" | "workflow-artifact";
+  readonly selectable: boolean;
+  readonly availabilityReason: AgentAdminAvailabilityReason;
+}

package/src/agent-skills.ts

@@ -0,0 +1,68 @@
+/** DSH 技能是工作方法与文件包，不能授予业务权限或承载可执行授权。 */
+export type AgentSkillScope = "personal" | "department" | "tenant";
+export type AgentSkillOrigin = "builtin" | "shared";
+export type AgentSkillStatus = "published" | "disabled";
+export interface AgentSkillRequirement {
+  readonly toolKey: string;
+  readonly featureKey: string;
+  readonly permissionKey: string;
+}
+export interface AgentSkillFile {
+  readonly path: string;
+  readonly contentBase64: string;
+}
+export interface AgentSkillBundle {
+  readonly name: string;
+  readonly displayName: string;
+  readonly description: string;
+  readonly digest: string;
+  readonly files: readonly AgentSkillFile[];
+}
+export interface AgentSkillVersion {
+  readonly key: string;
+  readonly version: number;
+  readonly tenantId: string;
+  readonly ownerActorId: string;
+  readonly departmentId?: string;
+  readonly scope: AgentSkillScope;
+  readonly origin: AgentSkillOrigin;
+  readonly status: AgentSkillStatus;
+  readonly name: string;
+  readonly description: string;
+  readonly digest: string;
+  readonly requirements: readonly AgentSkillRequirement[];
+  readonly safetyConstraints: readonly string[];
+  readonly createdAt: string;
+  readonly createdBy: string;
+  readonly restoredFromVersion?: number;
+  readonly source: string;
+}
+export interface AgentSkillGovernanceItem {
+  readonly skill: AgentSkillVersion;
+  readonly available: boolean;
+  readonly governable: boolean;
+}
+export interface ImportAgentSkillRequest {
+  readonly format: "markdown" | "zip";
+  /** SKILL.md 正文，或 ZIP 的标准 base64。 */
+  readonly content: string;
+  readonly scope: AgentSkillScope;
+  readonly expectedVersion: number;
+  readonly requirements?: readonly AgentSkillRequirement[];
+  readonly safetyConstraints?: readonly string[];
+}
+export interface AgentSkillCommandRequest {
+  readonly expectedVersion: number;
+  readonly version?: number;
+}
+export interface PublishedAgentSkillBundle {
+  readonly skill: AgentSkillVersion;
+  readonly bundle: AgentSkillBundle;
+}
+
+export interface AgentSkillRuntimeBundle {
+  readonly key: string;
+  readonly version: number;
+  readonly digest: string;
+  readonly files: readonly AgentSkillFile[];
+}

package/src/agent-workbench.ts

@@ -0,0 +1,100 @@
+import type { JsonValue } from "./json.js";
+
+export type AgentWorkbenchRecordingSourceV1 = "harness" | "business";
+export type AgentWorkbenchCorrelationStatusV1 =
+  | "complete"
+  | "partial"
+  | "missing";
+
+export interface AgentWorkbenchEventV1 {
+  readonly sequence: number;
+  readonly type: string;
+  readonly summary: string;
+  readonly occurredAt?: string;
+  readonly runId?: string;
+  readonly turnId?: string;
+  readonly stepId?: string;
+  readonly modelAttemptId?: string;
+  readonly attemptSequence?: number;
+  readonly toolCallId?: string;
+  readonly toolKey?: string;
+  readonly workItemId?: string;
+  readonly artifactId?: string;
+  readonly workflowRunId?: string;
+  readonly nodeRunId?: string;
+  readonly outcome?: string;
+  readonly usage?: {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly totalTokens?: number;
+    readonly costMicros?: number;
+  };
+}
+
+export interface AgentWorkbenchRunV1 {
+  readonly runId: string;
+  readonly operationKey: string;
+  readonly sessionId?: string;
+  readonly turnId?: string;
+  readonly messageSequence?: number;
+  readonly status: string;
+  readonly events: readonly AgentWorkbenchEventV1[];
+  readonly result?: { readonly output?: JsonValue; readonly status?: string };
+  readonly correlationStatus: AgentWorkbenchCorrelationStatusV1;
+  readonly missing: readonly string[];
+}
+
+export interface AgentWorkbenchWorkflowV1 {
+  readonly workflowRunId: string;
+  readonly sessionId?: string;
+  readonly messageSequence?: number;
+  readonly workflowKey: string;
+  readonly title: string;
+  readonly status: string;
+  readonly parentRunId?: string;
+  readonly parentNodeRunId?: string;
+  readonly nodes: readonly {
+    readonly nodeRunId: string;
+    readonly nodeId: string;
+    readonly type: string;
+    readonly status: string;
+    readonly attempt: number;
+    readonly previousNodeRunId?: string;
+    readonly agentRunId?: string;
+    readonly workItemId?: string;
+    readonly selectedBranch?: string;
+    readonly artifactIds: readonly string[];
+  }[];
+  readonly events: readonly AgentWorkbenchEventV1[];
+}
+
+export interface AgentWorkbenchRecordingSummaryV1 {
+  readonly source: AgentWorkbenchRecordingSourceV1;
+  readonly sessionId: string;
+  readonly title: string;
+  readonly updatedAt: string;
+  readonly operationKey?: string;
+  readonly sessionStatus?: "active" | "archived";
+}
+
+export interface AgentWorkbenchRecordingV1 extends AgentWorkbenchRecordingSummaryV1 {
+  readonly mode: "read-only";
+  readonly sideEffectPolicy: "no-reexecution";
+  readonly correlationStatus: AgentWorkbenchCorrelationStatusV1;
+  readonly messages: readonly {
+    readonly sequence: number;
+    readonly role: "user" | "assistant";
+    readonly content: string;
+    readonly createdAt: string;
+  }[];
+  readonly timeline: readonly AgentWorkbenchEventV1[];
+  /** Parent forks retain separate original ledger sequences, never renumbered. */
+  readonly segments?: readonly {
+    readonly sessionId: string;
+    readonly throughSequence: number;
+    readonly timeline: readonly AgentWorkbenchEventV1[];
+  }[];
+  readonly runs: readonly AgentWorkbenchRunV1[];
+  readonly workflows: readonly AgentWorkbenchWorkflowV1[];
+  readonly missing: readonly string[];
+}

package/src/agent-workflow-presets.ts

@@ -0,0 +1,26 @@
+import type { AgentWorkflowBudget } from "./agent-workflow-run.js";
+import type { AgentWorkflowNodeType } from "./agent-workflow-definition.js";
+
+export interface AgentWorkflowPresetSummary {
+  readonly key: string;
+  readonly moduleKey: string;
+  readonly label: string;
+  readonly description: string;
+  readonly workflowKey: string;
+  readonly version: string;
+  readonly budget: AgentWorkflowBudget;
+  readonly nodes: readonly {
+    readonly id: string;
+    readonly label: string;
+    readonly type: AgentWorkflowNodeType;
+  }[];
+  readonly availability: "available" | "unavailable";
+  readonly safeCode?: string;
+  readonly blockedReason?: string;
+  /** 由所属模块注册的业务入口；目录本身不发布或启动 Workflow。 */
+  readonly entry?: { readonly path: string; readonly label: string };
+}
+
+export interface AgentWorkflowPresetListResponse {
+  readonly items: readonly AgentWorkflowPresetSummary[];
+}

package/src/diagnostics.ts

@@ -0,0 +1,13 @@
+/** 可向授权运维人员公开的失败索引，不包含业务正文、异常堆栈或身份凭据。 */
+export interface DiagnosticRecord {
+  readonly diagnosticId: string;
+  readonly requestId: string;
+  readonly occurredAt: string;
+  readonly expiresAt: string;
+  readonly service: "server";
+  readonly stage: "http";
+  readonly method: string;
+  readonly route: string;
+  readonly statusCode: number;
+  readonly errorCode: string;
+}

package/src/environment-assessment.ts

@@ -0,0 +1,68 @@
+/** Host evidence is supplied by an explicitly mounted collector report, never inferred from a container. */
+export const HOST_PROBE_KEYS = [
+  "cpu",
+  "memory",
+  "blockDevices",
+  "disks",
+  "mounts",
+  "network",
+  "systemd",
+  "docker",
+  "compose",
+  "containers",
+  "gpu",
+] as const;
+export type HostProbeKey = (typeof HOST_PROBE_KEYS)[number];
+export interface HostDiagnosticProbe {
+  status:
+    | "ok"
+    | "missing"
+    | "permission-denied"
+    | "timeout"
+    | "failed"
+    | "unsupported";
+  exitCode: number | null;
+  output: string;
+  truncated: boolean;
+}
+export interface HostDiagnosticsReport {
+  schemaVersion: 1;
+  scope: "host";
+  collector: "windy-host-diagnostics-v1";
+  collectedAt: string;
+  facts: {
+    os: string;
+    distribution?: string;
+    kernel: string;
+    architecture: string;
+    cpuLogicalCount: number;
+    memoryTotalBytes: number | null;
+    /** Present only when a successful GPU query establishes the count. */
+    gpuCount?: number;
+  };
+  probes: Record<HostProbeKey, HostDiagnosticProbe>;
+  deployment?: {
+    status: "available" | "invalid" | "unreadable";
+    releaseId?: string;
+    gitSha?: string;
+    platform?: string;
+  };
+}
+export interface EnvironmentSnapshot {
+  generatedAt: string;
+  process: {
+    scope: "process";
+    platform: string;
+    architecture: string;
+    nodeVersion: string;
+    bunVersion?: string;
+    containerized: boolean;
+    logicalCpuCount: number;
+    memoryTotalBytes: number;
+  };
+  host: {
+    status: "available" | "not-configured" | "invalid" | "stale" | "unreadable";
+    message: string;
+    report?: HostDiagnosticsReport;
+  };
+}

package/src/environment-policy.ts

@@ -0,0 +1,205 @@
+/** Deployment requirements are recommendations, not authorization or probe results. */
+export interface FeatureEnvironmentPolicy {
+  key: string;
+  title: string;
+  execution: "none" | "cpu" | "local-gpu" | "remote";
+  recommendedEnabled?: boolean;
+  supportedPlatforms?: string[];
+  supportedArchitectures?: string[];
+  minMemoryGiB?: number;
+  requiredEnvironmentKeys?: string[];
+}
+export const AI_RUNTIME_KINDS = [
+  "agent",
+  "document",
+  "speech",
+  "embedding",
+] as const;
+export type AiRuntimeKind = (typeof AI_RUNTIME_KINDS)[number];
+export type AiRuntimeSwitches = Partial<Record<AiRuntimeKind, boolean>>;
+
+export interface AntivirusEnvironmentPolicy {
+  packaged: boolean;
+  enabled: boolean;
+}
+
+export interface EnvironmentPolicy {
+  schemaVersion: 1;
+  build: { modules: string[]; runtimes?: AiRuntimeSwitches };
+  runtime?: AiRuntimeSwitches;
+  antivirus?: AntivirusEnvironmentPolicy;
+  features: FeatureEnvironmentPolicy[];
+}
+export interface FeatureEnvironmentAssessment {
+  key: string;
+  title: string;
+  status:
+    | "hardware"
+    | "software"
+    | "not-packaged"
+    | "configuration"
+    | "unknown"
+    | "available"
+    | "disabled";
+  message: string;
+  evidence: string[];
+  recommendedEnabled?: boolean;
+}
+export interface EnvironmentAssessmentSnapshot {
+  status: "available" | "not-configured" | "invalid";
+  message: string;
+  features: FeatureEnvironmentAssessment[];
+}
+
+function object(
+  value: unknown,
+  required: string[],
+  optional: string[] = [],
+): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("环境预设必须为对象");
+  const record = value as Record<string, unknown>;
+  if (
+    required.some((key) => !Object.hasOwn(record, key)) ||
+    Object.keys(record).some((key) => ![...required, ...optional].includes(key))
+  )
+    throw new Error("环境预设缺少必需字段或包含未知字段");
+  return record;
+}
+function strings(value: unknown, pattern: RegExp, max = 128): string[] {
+  if (
+    !Array.isArray(value) ||
+    value.length > max ||
+    value.some(
+      (item) =>
+        typeof item !== "string" || item.length > 128 || !pattern.test(item),
+    ) ||
+    new Set(value).size !== value.length
+  )
+    throw new Error("环境预设列表无效或重复");
+  return value as string[];
+}
+export function parseEnvironmentPolicy(value: unknown): EnvironmentPolicy {
+  const root = object(
+    value,
+    ["schemaVersion", "build", "features"],
+    ["runtime", "antivirus"],
+  );
+  if (root.schemaVersion !== 1) throw new Error("不支持的环境预设版本");
+  const build = object(root.build, ["modules"], ["runtimes"]);
+  const modules = strings(build.modules, /^[a-z][a-z0-9.-]*$/);
+  if (!Array.isArray(root.features) || root.features.length > 128)
+    throw new Error("功能评估配置超出上限");
+  const features = root.features.map((value): FeatureEnvironmentPolicy => {
+    const row = object(
+      value,
+      ["key", "title", "execution"],
+      [
+        "recommendedEnabled",
+        "supportedPlatforms",
+        "supportedArchitectures",
+        "minMemoryGiB",
+        "requiredEnvironmentKeys",
+      ],
+    );
+    const [key] = strings([row.key], /^[a-z][a-z0-9.-]*$/);
+    if (
+      typeof row.title !== "string" ||
+      !row.title.trim() ||
+      row.title.length > 120
+    )
+      throw new Error("功能评估标题无效");
+    if (!["none", "cpu", "local-gpu", "remote"].includes(String(row.execution)))
+      throw new Error("功能执行方式无效");
+    if (
+      row.recommendedEnabled !== undefined &&
+      typeof row.recommendedEnabled !== "boolean"
+    )
+      throw new Error("推荐开关必须为布尔值");
+    if (
+      row.minMemoryGiB !== undefined &&
+      (typeof row.minMemoryGiB !== "number" ||
+        !Number.isFinite(row.minMemoryGiB) ||
+        row.minMemoryGiB <= 0 ||
+        row.minMemoryGiB > 65536)
+    )
+      throw new Error("最低内存要求无效");
+    return {
+      key: key!,
+      title: row.title,
+      execution: row.execution as FeatureEnvironmentPolicy["execution"],
+      ...(row.recommendedEnabled === undefined
+        ? {}
+        : { recommendedEnabled: row.recommendedEnabled as boolean }),
+      ...(row.minMemoryGiB === undefined
+        ? {}
+        : { minMemoryGiB: row.minMemoryGiB as number }),
+      ...(row.supportedPlatforms === undefined
+        ? {}
+        : {
+            supportedPlatforms: strings(
+              row.supportedPlatforms,
+              /^(linux|darwin|win32)$/,
+            ),
+          }),
+      ...(row.supportedArchitectures === undefined
+        ? {}
+        : {
+            supportedArchitectures: strings(
+              row.supportedArchitectures,
+              /^(x64|arm64|arm|ia32|ppc64|s390x|riscv64|loong64)$/,
+            ),
+          }),
+      ...(row.requiredEnvironmentKeys === undefined
+        ? {}
+        : {
+            requiredEnvironmentKeys: strings(
+              row.requiredEnvironmentKeys,
+              /^[A-Z][A-Z0-9_]*$/,
+            ),
+          }),
+    };
+  });
+  if (new Set(features.map(({ key }) => key)).size !== features.length)
+    throw new Error("功能评估 Key 重复");
+  const runtime = Object.hasOwn(root, "runtime")
+    ? parseRuntimeSwitches(root.runtime)
+    : undefined;
+  const runtimes = Object.hasOwn(build, "runtimes")
+    ? parseRuntimeSwitches(build.runtimes)
+    : undefined;
+  for (const kind of AI_RUNTIME_KINDS) {
+    if (runtimes?.[kind] === false && runtime?.[kind] === true)
+      throw new Error(`运行时未随包交付：${kind}`);
+  }
+  const antivirus = Object.hasOwn(root, "antivirus")
+    ? parseAntivirusPolicy(root.antivirus)
+    : undefined;
+  return {
+    schemaVersion: 1,
+    build: { modules, ...(runtimes ? { runtimes } : {}) },
+    features,
+    ...(runtime ? { runtime } : {}),
+    ...(antivirus ? { antivirus } : {}),
+  };
+}
+
+function parseRuntimeSwitches(value: unknown): AiRuntimeSwitches {
+  const switches = object(value, [], [...AI_RUNTIME_KINDS]);
+  const runtime: AiRuntimeSwitches = {};
+  for (const kind of AI_RUNTIME_KINDS) {
+    if (!Object.hasOwn(switches, kind)) continue;
+    const enabled = switches[kind];
+    if (typeof enabled !== "boolean") throw new Error("运行时开关必须为布尔值");
+    runtime[kind] = enabled;
+  }
+  return runtime;
+}
+
+function parseAntivirusPolicy(value: unknown): AntivirusEnvironmentPolicy {
+  const { packaged, enabled } = object(value, ["packaged", "enabled"]);
+  if (typeof packaged !== "boolean" || typeof enabled !== "boolean")
+    throw new Error("病毒扫描交付和启用设置必须为布尔值");
+  if (enabled && !packaged) throw new Error("病毒扫描未随项目交付，不能启用");
+  return { packaged, enabled };
+}

package/src/license-console-capabilities.ts

@@ -101,6 +101,13 @@ export const LICENSE_CONSOLE_CAPABILITIES = {
     apis: ["POST /api/auth/sessions/:id/revoke"],
     auditActions: ["auth.session.revoke"],
   },
+  profile: {
+    feature: "license.profile",
+    permission: "license.profile.update",
+    entry: "profile",
+    apis: ["PATCH /api/auth/me"],
+    auditActions: ["license.operator.updated"],
+  },
   audit: {
     feature: "license.audit",
     permission: "license.audit.read",

package/src/license.ts

@@ -205,6 +205,7 @@ export type LicenseOperatorRole =
 export type LicenseOperatorPermission =
   | "license.record.read"
   | "license.audit.read"
+  | "license.profile.update"
   | "license.issue"
   | "license.project.manage"
   | "license.key.rotate"

package/src/module-configuration.ts

@@ -20,7 +20,8 @@ export interface ModuleConfigFieldDescriptor {
   path: string;
   label: string;
   description: string;
-  input: "boolean" | "integer" | "text";
+  input: "boolean" | "integer" | "text" | "time-zone";
+  unit?: "bytes";
   applyMode?: ModuleConfigApplyMode;
   minimum?: number;
   maximum?: number;

package/src/rbac.ts

@@ -24,6 +24,7 @@ export type PermissionAction =
   | "reveal"
   | "approve"
   | "execute"
+  | "use"
   | "retry"
   | "manage";