@southwind-ai/shared 0.3.0 → 0.3.2

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";
@@ -17,6 +19,7 @@ export * from "./src/migration-bundle-validation.js";
 export * from "./src/mcp.js";
 export * from "./src/module-configuration.js";
 export * from "./src/correlation.js";
+export * from "./src/structured-log.js";
 export * from "./src/notification.js";
 export * from "./src/password.js";
 export * from "./src/platform-settings.js";
@@ -32,3 +35,15 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/shared",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {
@@ -15,7 +15,8 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "exports": {
-    ".": "./index.ts"
+    ".": "./index.ts",
+    "./structured-log": "./src/structured-log.ts"
   },
   "publishConfig": {
     "access": "public"

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/rbac.ts

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

package/src/structured-log.ts

@@ -0,0 +1,215 @@
+/** 运行日志只承载排障线索；业务审计和 Agent Run 事实使用各自的持久化入口。 */
+export const STRUCTURED_LOG_MAX_BYTES = 2048;
+
+export type StructuredLogLevel = "info" | "warn" | "error";
+export type StructuredLogOutcome = "success" | "failure" | "denied";
+
+export interface StructuredLogInput {
+  event: string;
+  requestId?: string;
+  runId?: string;
+  jobId?: string;
+  traceId?: string;
+  diagnosticId?: string;
+  outcome?: StructuredLogOutcome;
+  errorCode?: string;
+  stageKey?: string;
+  handlerKey?: string;
+  queue?: string;
+  attemptNumber?: number;
+  method?: string;
+  /** 只接受框架登记的路由模板，不能传请求 URL 或实际对象路径。 */
+  route?: string;
+  statusCode?: number;
+  durationMs?: number;
+  actorType?: string;
+  authority?: string;
+  port?: number;
+  created?: number;
+  metadataUpdated?: number;
+  archived?: number;
+  unchanged?: number;
+  queued?: number;
+  dropped?: number;
+  completedUnits?: number;
+  totalUnits?: number;
+  count?: number;
+  /** 兼容现有 Logger 接口；未知字段在序列化时一律丢弃。 */
+  [key: string]: unknown;
+}
+
+export interface StructuredLogSink {
+  info(record: Record<string, unknown>): void;
+  warn(record: Record<string, unknown>): void;
+  error(record: Record<string, unknown>): void;
+}
+
+export interface StructuredLogger {
+  info(input: StructuredLogInput, message?: string): void;
+  warn(input: StructuredLogInput, message?: string): void;
+  error(input: StructuredLogInput, message?: string): void;
+}
+
+const stableKey = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+const correlationKey = /^[A-Za-z0-9._-]{1,128}$/;
+const errorKey = /^[A-Z][A-Z0-9_]{0,95}$/;
+const methodKey = /^[A-Z]{1,12}$/;
+const routeTemplate =
+  /^\/(?:[A-Za-z][A-Za-z0-9_-]*|:[A-Za-z][A-Za-z0-9_]*|\*)(?:\/(?:[A-Za-z][A-Za-z0-9_-]*|:[A-Za-z][A-Za-z0-9_]*|\*))*$/;
+
+/** Adapter 可接 Pino、stdout 或测试 Sink；自由文本 message 不进入日志。 */
+export function createStructuredLogger(
+  sink: StructuredLogSink,
+  component: string,
+  now: () => Date = () => new Date(),
+): StructuredLogger {
+  if (!stableKey.test(component) || component.length > 64) {
+    throw new Error("运行日志 component 必须是有界稳定 Key");
+  }
+  const emit = (level: StructuredLogLevel, input: StructuredLogInput) => {
+    const record = structuredLogRecord(level, component, input, now());
+    try {
+      sink[level](record);
+    } catch {
+      // 排障日志是旁路输出；审计和业务结果由各自的可靠存储决定。
+    }
+  };
+  return {
+    info: (input) => emit("info", input),
+    warn: (input) => emit("warn", input),
+    error: (input) => emit("error", input),
+  };
+}
+
+export function structuredLogRecord(
+  level: StructuredLogLevel,
+  component: string,
+  input: StructuredLogInput,
+  at: Date,
+): Record<string, unknown> {
+  const record: Record<string, unknown> = {
+    timestamp: at.toISOString(),
+    level,
+    component,
+    event:
+      stableKey.test(input.event) && input.event.length <= 96
+        ? input.event
+        : "logging.event.invalid",
+    retentionClass: "operational",
+  };
+  for (const key of [
+    "requestId",
+    "runId",
+    "jobId",
+    "traceId",
+    "diagnosticId",
+  ] as const) {
+    const value = input[key];
+    if (typeof value === "string" && correlationKey.test(value)) {
+      record[key] = value;
+    }
+  }
+  if (
+    input.outcome === "success" ||
+    input.outcome === "failure" ||
+    input.outcome === "denied"
+  )
+    record.outcome = input.outcome;
+  if (typeof input.errorCode === "string" && errorKey.test(input.errorCode)) {
+    record.errorCode = input.errorCode;
+  }
+  for (const key of [
+    "stageKey",
+    "handlerKey",
+    "queue",
+    "actorType",
+    "authority",
+  ] as const) {
+    const value = input[key];
+    if (
+      typeof value === "string" &&
+      value.length <= 64 &&
+      stableKey.test(value)
+    ) {
+      record[key] = value;
+    }
+  }
+  if (typeof input.method === "string" && methodKey.test(input.method)) {
+    record.method = input.method;
+  }
+  if (
+    typeof input.route === "string" &&
+    input.route.length <= 160 &&
+    (input.route === "/" || routeTemplate.test(input.route))
+  )
+    record.route = input.route;
+  if (validNumber(input.statusCode, 100, 599, true))
+    record.statusCode = input.statusCode;
+  if (validNumber(input.durationMs, 0, 3_600_000))
+    record.durationMs = input.durationMs;
+  if (validNumber(input.port, 1, 65535, true)) record.port = input.port;
+  if (validNumber(input.attemptNumber, 1, 1_000_000_000, true))
+    record.attemptNumber = input.attemptNumber;
+  for (const key of [
+    "created",
+    "metadataUpdated",
+    "archived",
+    "unchanged",
+    "queued",
+    "dropped",
+    "completedUnits",
+    "totalUnits",
+    "count",
+  ] as const) {
+    const value = input[key];
+    if (validNumber(value, 0, 1_000_000_000, true)) record[key] = value;
+  }
+  for (const key of [
+    "dropped",
+    "completedUnits",
+    "totalUnits",
+    "count",
+    "route",
+    "queued",
+    "unchanged",
+    "archived",
+    "metadataUpdated",
+    "created",
+    "port",
+    "attemptNumber",
+    "queue",
+    "handlerKey",
+    "authority",
+    "actorType",
+    "stageKey",
+    "diagnosticId",
+    "traceId",
+    "jobId",
+    "runId",
+    "requestId",
+  ] as const) {
+    if (
+      new TextEncoder().encode(JSON.stringify(record)).length <=
+      STRUCTURED_LOG_MAX_BYTES
+    )
+      break;
+    delete record[key];
+    record.truncated = true;
+  }
+  return record;
+}
+
+function validNumber(
+  value: unknown,
+  min: number,
+  max: number,
+  integer = false,
+): value is number {
+  return (
+    typeof value === "number" &&
+    Number.isFinite(value) &&
+    value >= min &&
+    value <= max &&
+    (!integer || Number.isInteger(value))
+  );
+}