create-windy 0.6.12 → 0.6.14

package/template/apps/server/src/agent/memory-runtime-adapters.ts

@@ -0,0 +1,266 @@
+import { agentMemoryProjections, agentSessions } from "@southwind-ai/database";
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import { and, desc, eq, gt, inArray, isNull, or } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { evaluateAccessGuards } from "../access-guards.js";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import { isServerScopeContext } from "../data-access/context.js";
+import type { createServerRuntime } from "../runtime.js";
+import type {
+  AuthorizationDecision,
+  MemoryCapabilityAuthorizer,
+  MemoryObjectAuthorizationPort,
+  MemoryProjection,
+  MemoryRetrievalRequest,
+  MemorySearchPort,
+} from "./context-memory/contracts.js";
+import type { MemoryProjectionWriteAuthorizationPort } from "./context-memory/memory-projector.js";
+import type { CaseMemoryObjectAuthorizationPort } from "./context-memory/memory-object-registry.js";
+import type { SessionProjectionSourceAuthorizer } from "./session-projection-access.js";
+import type { SessionId } from "./session-log/domain.js";
+import type { DrizzleSessionEventRepository } from "./session-persistence/drizzle-session-repository.js";
+
+type ServerRuntime = Pick<
+  ReturnType<typeof createServerRuntime>,
+  "recordDecisions" | "resolveFeature"
+>;
+
+export class RuntimeMemoryCapabilityAuthorizer implements MemoryCapabilityAuthorizer {
+  constructor(private readonly runtime: ServerRuntime) {}
+
+  async authorize(request: MemoryRetrievalRequest) {
+    const access = await evaluateAccessGuards(
+      this.runtime,
+      request.guardContext,
+      {
+        permission: { permissionKey: request.permissionKey },
+        feature: request.feature,
+      },
+      { record: false },
+    );
+    const actor = decision(
+      request.guardContext.actor.type !== "anonymous",
+      "actor",
+    );
+    const scope = decision(
+      isServerScopeContext(request.guardContext.actor.scopeContext),
+      "scope",
+    );
+    const feature = fromGuard(access.feature, access.decision.allowed);
+    const permission = fromGuard(access.permission, access.decision.allowed);
+    const license = fromGuard(
+      access.licenseVersion ?? access.entitlement ?? access.license,
+      access.decision.allowed,
+    );
+    return {
+      allowed: [actor, scope, feature, permission, license].every(
+        ({ allowed }) => allowed,
+      ),
+      actor,
+      scope,
+      feature,
+      permission,
+      license,
+    };
+  }
+}
+
+export class RuntimeMemoryProjectionWriteAuthorizer implements MemoryProjectionWriteAuthorizationPort {
+  constructor(
+    private readonly runtime: ServerRuntime,
+    private readonly feature: FeatureFlagDefinition,
+    private readonly permissionKey: string,
+  ) {}
+
+  async authorize(
+    _input: Parameters<MemoryProjectionWriteAuthorizationPort["authorize"]>[0],
+    context: Parameters<MemoryProjectionWriteAuthorizationPort["authorize"]>[1],
+  ) {
+    if (
+      context.actor.type === "anonymous" ||
+      !isServerScopeContext(context.actor.scopeContext)
+    ) {
+      return decision(false, "actor-or-scope-denied");
+    }
+    const access = await evaluateAccessGuards(
+      this.runtime,
+      context,
+      {
+        permission: { permissionKey: this.permissionKey },
+        feature: this.feature,
+      },
+      { record: false },
+    );
+    return decision(access.decision.allowed, access.decision.reason);
+  }
+}
+
+/** Candidate retrieval shares the canonical active Memory projection; no shadow index. */
+export class DrizzleGovernedMemorySearch implements MemorySearchPort {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async search(
+    _query: string,
+    limit: number,
+    actor: Parameters<MemorySearchPort["search"]>[2],
+    _requestId: string,
+    _signal: AbortSignal,
+    scope?: Parameters<MemorySearchPort["search"]>[5],
+  ) {
+    if (!scope?.sessionId.trim() || !scope.kinds.length) {
+      throw new Error("Memory Search 缺少受治理 Scope");
+    }
+    const scopeDigest = `sha256:${captureAuthorizationScope(actor.scopeContext).hash}`;
+    const rows = await this.db
+      .select({ memoryId: agentMemoryProjections.memoryId })
+      .from(agentMemoryProjections)
+      .innerJoin(
+        agentSessions,
+        eq(
+          agentMemoryProjections.derivedFromSessionId,
+          agentSessions.sessionId,
+        ),
+      )
+      .where(
+        and(
+          eq(agentMemoryProjections.status, "active"),
+          or(
+            isNull(agentMemoryProjections.expiresAt),
+            gt(agentMemoryProjections.expiresAt, Date.now()),
+          ),
+          eq(agentSessions.status, "active"),
+          eq(agentSessions.actorId, actor.id),
+          eq(agentSessions.scopeDigest, scopeDigest),
+          inArray(agentMemoryProjections.kind, [...scope.kinds]),
+          scope.caseId
+            ? or(
+                isNull(agentMemoryProjections.currentCaseId),
+                eq(agentMemoryProjections.currentCaseId, scope.caseId),
+              )
+            : isNull(agentMemoryProjections.currentCaseId),
+          or(
+            and(
+              eq(agentMemoryProjections.scopeKind, "user"),
+              eq(agentMemoryProjections.scopeId, actor.id),
+            ),
+            and(
+              eq(agentMemoryProjections.scopeKind, "session"),
+              eq(agentMemoryProjections.scopeId, scope.sessionId),
+              eq(agentMemoryProjections.derivedFromSessionId, scope.sessionId),
+            ),
+            scope.caseId
+              ? and(
+                  eq(agentMemoryProjections.scopeKind, "case"),
+                  eq(agentMemoryProjections.scopeId, scope.caseId),
+                )
+              : undefined,
+          ),
+        ),
+      )
+      .orderBy(desc(agentMemoryProjections.updatedAt))
+      .limit(limit);
+    return rows;
+  }
+}
+
+export class GovernedMemoryObjectAuthorization implements MemoryObjectAuthorizationPort {
+  constructor(
+    private readonly sessions: DrizzleSessionEventRepository,
+    private readonly sources: SessionProjectionSourceAuthorizer,
+    private readonly caseObjects?: CaseMemoryObjectAuthorizationPort,
+  ) {}
+
+  async authorize(
+    projection: MemoryProjection,
+    context: Parameters<MemoryObjectAuthorizationPort["authorize"]>[1],
+    signal: Parameters<MemoryObjectAuthorizationPort["authorize"]>[2],
+  ) {
+    if (
+      !(await this.validDerivation(
+        projection,
+        context.actor.id,
+        context.actor.scopeContext,
+      )) ||
+      !(await this.inScope(projection, context.actor.id))
+    ) {
+      return decision(false, "object-forbidden");
+    }
+    try {
+      if (
+        projection.kind === "case-memory-candidate" ||
+        projection.kind === "verified-fact-reference"
+      ) {
+        if (!this.caseObjects)
+          return decision(false, "module-adapter-unavailable");
+        const current = await this.caseObjects.authorizeCurrent({
+          projection,
+          context,
+          signal,
+        });
+        if (!current.allowed) return decision(false, "object-forbidden");
+      }
+      await this.sources.requireAll(
+        projection.sources.map((source) => ({
+          moduleKey: source.moduleKey,
+          kind: source.kind,
+          id: source.id,
+          version: source.version,
+          sequence: source.sequence,
+          digest: source.digest,
+          valid: source.validity.status === "valid",
+        })),
+        context,
+      );
+      return decision(true, "allowed");
+    } catch {
+      return decision(false, "source-unavailable");
+    }
+  }
+
+  private async inScope(projection: MemoryProjection, actorId: string) {
+    if (projection.scope.kind === "user") {
+      return projection.scope.actorId === actorId;
+    }
+    if (projection.scope.kind === "case") {
+      return projection.kind === "verified-fact-reference"
+        ? projection.sources.some(
+            (source) => source.moduleKey === projection.fact.moduleKey,
+          )
+        : projection.sources.some(
+            ({ moduleKey }) => moduleKey !== "system.agent",
+          );
+    }
+    return projection.scope.sessionId === projection.derivation.sessionId;
+  }
+
+  private async validDerivation(
+    projection: MemoryProjection,
+    actorId: string,
+    scopeContext: Parameters<typeof captureAuthorizationScope>[0],
+  ) {
+    const session = await this.sessions.get(
+      projection.derivation.sessionId as SessionId,
+    );
+    return Boolean(
+      session &&
+      session.status === "active" &&
+      session.governance.actorId === actorId &&
+      session.governance.scopeDigest ===
+        `sha256:${captureAuthorizationScope(scopeContext).hash}` &&
+      projection.derivation.throughSequence <= session.headSequence,
+    );
+  }
+}
+
+function fromGuard(
+  value: { allowed: boolean; reason: string } | undefined,
+  fallback: boolean,
+): AuthorizationDecision {
+  return value
+    ? decision(value.allowed, value.reason)
+    : decision(fallback, "guard");
+}
+
+function decision(allowed: boolean, reason: string): AuthorizationDecision {
+  return { allowed, reason };
+}

package/template/apps/server/src/agent/memory-scope-binding.ts

@@ -0,0 +1,14 @@
+export function normalizeMemoryScopeCaseId(scope?: {
+  readonly caseId: string;
+}) {
+  return normalizeCaseId(scope?.caseId);
+}
+
+export function normalizeCaseId(caseId?: string) {
+  if (caseId === undefined) return undefined;
+  const normalized = caseId.trim();
+  if (!normalized || normalized.length > 160) {
+    throw new Error("Case Memory 坐标无效");
+  }
+  return normalized;
+}

package/template/apps/server/src/agent/module-ai-port-factory.ts

@@ -0,0 +1,41 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { createModuleAiOperationReadinessPort } from "../ai-runtime-readiness/operation-port.js";
+import type { AiRuntimeReadinessTrustStoreV1 } from "../ai-runtime-readiness/trust-store.js";
+import { createModuleAiOperationPort } from "../module-host/ai-operation-port.js";
+import type { createServerRuntime } from "../runtime.js";
+
+type OperationRuntime = Parameters<typeof createModuleAiOperationPort>[3];
+type ReadinessInput = Parameters<typeof createModuleAiOperationReadinessPort>[0];
+
+export function createModuleAiPorts(input: {
+  readonly modules: readonly ModuleManifest[];
+  readonly runtime: ReturnType<typeof createServerRuntime>;
+  readonly sources: ReadinessInput["sources"];
+  readonly trustStore: AiRuntimeReadinessTrustStoreV1;
+  readonly operations: OperationRuntime;
+}) {
+  const operations = (
+    moduleName: string,
+    guardContext: Parameters<typeof createModuleAiOperationPort>[1],
+    signal: AbortSignal,
+  ) => createModuleAiOperationPort(
+    moduleName,
+    guardContext,
+    signal,
+    input.operations,
+  );
+  const readiness = (
+    moduleName: string,
+    guardContext: Parameters<typeof createModuleAiOperationPort>[1],
+    signal: AbortSignal,
+  ) => createModuleAiOperationReadinessPort({
+    moduleName,
+    guardContext,
+    signal,
+    modules: input.modules,
+    sources: input.sources,
+    trustStore: input.trustStore,
+    runtime: input.runtime,
+  });
+  return { operations, readiness };
+}

package/template/apps/server/src/agent/provider-input-governance.ts

@@ -1,5 +1,6 @@
 import type {
   AiProviderDataPolicy,
+  AiProviderDataField,
   AiProviderDlpAction,
 } from "@southwind-ai/modules";
 import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
@@ -44,6 +45,24 @@ export function projectProviderInput(
   return selectProviderInput(input, policy, (value) => cloneValue(value));
 }
 
+/** 对 Client Agent 每轮动态 envelope 执行同一 Manifest allowlist 与 DLP。 */
+export function governProviderEnvelope(
+  value: ModuleAiJsonValue,
+  field: AiProviderDataField,
+  policy: AiProviderDataPolicy,
+): ModuleAiJsonValue {
+  const rule = policy.envelopeFields.find(
+    (candidate) => candidate.field === field,
+  );
+  if (!rule) {
+    throw new ProviderInputGovernanceError(
+      "FORBIDDEN",
+      `Provider envelope 字段未获允许：${field}`,
+    );
+  }
+  return governValue(value, rule.dlpAction);
+}
+
 function selectProviderInput(
   input: ModuleAiJsonValue,
   policy: AiProviderDataPolicy,

package/template/apps/server/src/agent/remote-runtime-response.ts

@@ -0,0 +1,162 @@
+import {
+  AgentRuntimeError,
+  type AgentRuntimeRunStatus,
+  type AgentRuntimeStartResponse,
+  type AgentRuntimeStatusResponse,
+  type AgentRuntimeTerminalEvent,
+} from "./run-contracts.js";
+
+export function parseRemoteStart(value: unknown): AgentRuntimeStartResponse {
+  if (!isRecord(value)) throw new Error("Agent Runtime 创建响应无效");
+  const runId = text(value.runId);
+  const status = text(value.status);
+  const eventsUrl = text(value.eventsUrl);
+  if (!runId || !status || !runStatuses.has(status) || !eventsUrl) {
+    throw new Error("Agent Runtime 创建响应字段无效");
+  }
+  return {
+    runId,
+    status: status as AgentRuntimeRunStatus,
+    eventsUrl,
+  };
+}
+
+export function parseRemoteStatus(value: unknown): AgentRuntimeStatusResponse {
+  if (!isRecord(value)) throw new Error("Agent Runtime 状态响应无效");
+  const runId = text(value.runId);
+  const status = text(value.status);
+  const lastSequence = value.lastSequence;
+  if (
+    !runId ||
+    !status ||
+    !runStatuses.has(status) ||
+    !Number.isSafeInteger(lastSequence) ||
+    Number(lastSequence) < 0
+  ) {
+    throw new Error("Agent Runtime 状态字段无效");
+  }
+  const terminalEvent =
+    value.terminalEvent === undefined
+      ? undefined
+      : parseTerminalEvent(value.terminalEvent, runId);
+  const terminalStatus = ["completed", "failed", "cancelled"].includes(status);
+  if (
+    terminalStatus !== Boolean(terminalEvent) ||
+    (terminalEvent && terminalEvent.sequence !== Number(lastSequence)) ||
+    (terminalEvent && terminalEvent.type !== `run.${status}`)
+  ) {
+    throw new Error("Agent Runtime 状态与终态事件不一致");
+  }
+  return {
+    runId,
+    status: status as AgentRuntimeRunStatus,
+    lastSequence: Number(lastSequence),
+    ...(terminalEvent ? { terminalEvent } : {}),
+  };
+}
+
+export async function remoteRuntimeError(
+  response: Response,
+): Promise<AgentRuntimeError> {
+  try {
+    const value = (await response.json()) as {
+      code?: unknown;
+      message?: unknown;
+      retryable?: unknown;
+    };
+    if (
+      typeof value.code === "string" &&
+      typeof value.message === "string" &&
+      typeof value.retryable === "boolean" &&
+      value.message.length <= 200
+    ) {
+      return new AgentRuntimeError(
+        knownRemoteCode(value.code),
+        value.message,
+        value.retryable,
+      );
+    }
+  } catch {
+    // Provider 或代理正文不可透传。
+  }
+  return new AgentRuntimeError(
+    "RUNTIME_UNAVAILABLE",
+    `Agent Runtime 请求失败（HTTP ${response.status}）`,
+    response.status >= 500,
+  );
+}
+
+const runStatuses: ReadonlySet<string> = new Set<AgentRuntimeRunStatus>([
+  "accepted",
+  "running",
+  "awaiting-approval",
+  "completed",
+  "failed",
+  "cancelled",
+]);
+
+function parseTerminalEvent(
+  value: unknown,
+  expectedRunId: string,
+): AgentRuntimeTerminalEvent {
+  if (!isRecord(value)) throw new Error("Agent Runtime 终态事件无效");
+  const type = value.type;
+  const runId = text(value.runId);
+  const sequence = value.sequence;
+  if (
+    !["run.completed", "run.failed", "run.cancelled"].includes(String(type)) ||
+    runId !== expectedRunId ||
+    !Number.isSafeInteger(sequence) ||
+    Number(sequence) <= 0
+  ) {
+    throw new Error("Agent Runtime 终态事件字段无效");
+  }
+  if (type !== "run.failed") {
+    return {
+      type: type as "run.completed" | "run.cancelled",
+      runId,
+      sequence: Number(sequence),
+    };
+  }
+  if (!isRecord(value.error)) throw new Error("Agent Runtime 失败事件无效");
+  const code = text(value.error.code);
+  const message = text(value.error.message);
+  const requestId = text(value.error.requestId);
+  if (
+    !code ||
+    !message ||
+    !requestId ||
+    typeof value.error.retryable !== "boolean"
+  ) {
+    throw new Error("Agent Runtime 失败字段无效");
+  }
+  return {
+    type,
+    runId,
+    sequence: Number(sequence),
+    error: { code, message, requestId, retryable: value.error.retryable },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function knownRemoteCode(
+  code: string,
+): ConstructorParameters<typeof AgentRuntimeError>[0] {
+  return [
+    "CAPABILITY_UNAVAILABLE",
+    "MODEL_ROUTE_UNAVAILABLE",
+    "RUN_CONFLICT",
+    "FORBIDDEN",
+    "BUDGET_EXCEEDED",
+    "INVALID_INPUT",
+  ].includes(code)
+    ? (code as ConstructorParameters<typeof AgentRuntimeError>[0])
+    : "RUNTIME_UNAVAILABLE";
+}