create-windy 0.6.12 → 0.6.14

package/template/apps/server/src/agent/context-memory/context-builder.ts

@@ -0,0 +1,184 @@
+import { randomUUIDv7 } from "bun";
+import {
+  ContextMemoryError,
+  type BuiltContext,
+  type ContextBuildRequest,
+  type ContextSourcePort,
+  type ContextSourceReference,
+  type ContextVersion,
+  type ContextVersionRecorder,
+  type ResolvedContextSource,
+} from "./contracts.js";
+import { stableDigest } from "./digest.js";
+
+export interface ContextBuilderOptions {
+  readonly now?: () => Date;
+  readonly idFactory?: () => string;
+}
+
+export class ContextBuilder {
+  readonly #now: () => Date;
+  readonly #idFactory: () => string;
+
+  constructor(
+    private readonly source: ContextSourcePort,
+    private readonly recorder: ContextVersionRecorder,
+    options: ContextBuilderOptions = {},
+  ) {
+    this.#now = options.now ?? (() => new Date());
+    this.#idFactory = options.idFactory ?? (() => `context_${randomUUIDv7()}`);
+  }
+
+  async build(
+    request: ContextBuildRequest,
+    signal: AbortSignal,
+  ): Promise<BuiltContext> {
+    const resolved = await this.resolve(request, signal);
+    const references = resolved.map(({ reference }) => reference);
+    const version = immutableClone<ContextVersion>({
+      contextVersionId: this.#idFactory(),
+      sessionId: request.sessionId,
+      turnId: request.turnId,
+      runId: request.runId,
+      modelAttemptId: request.modelAttemptId,
+      sources: references,
+      digest: contextDigest(request, references),
+      createdAt: this.#now().toISOString(),
+    });
+    try {
+      await this.recorder.record(version);
+    } catch {
+      throw unavailable("Context Version 无法写入 Session 事实源");
+    }
+    return immutableClone({ version, sources: resolved });
+  }
+
+  /** Resolve and validate sources without claiming a Provider attempt was sent. */
+  async resolve(
+    request: ContextBuildRequest,
+    signal: AbortSignal,
+  ): Promise<readonly ResolvedContextSource[]> {
+    validateRequest(request);
+    if (signal.aborted) throw unavailable("Context 构建已取消");
+    const resolved: ResolvedContextSource[] = [];
+    for (const sourceRequest of request.sources) {
+      let source: ResolvedContextSource;
+      try {
+        source = await this.source.resolve(
+          sourceRequest,
+          request.guardContext,
+          signal,
+        );
+      } catch (error) {
+        if (error instanceof ContextMemoryError) throw error;
+        throw unavailable("Context 来源暂不可用");
+      }
+      validateResolvedSource(sourceRequest, source, this.#now());
+      resolved.push(immutableClone(source));
+    }
+
+    return immutableClone(resolved);
+  }
+}
+
+export function contextDigest(
+  request: Pick<
+    ContextBuildRequest,
+    "sessionId" | "turnId" | "runId" | "modelAttemptId"
+  >,
+  sources: readonly ContextSourceReference[],
+): string {
+  return stableDigest({
+    contractVersion: 1,
+    sessionId: request.sessionId,
+    turnId: request.turnId,
+    runId: request.runId,
+    modelAttemptId: request.modelAttemptId,
+    sources,
+  });
+}
+
+function validateRequest(request: ContextBuildRequest): void {
+  for (const value of [
+    request.sessionId,
+    request.turnId,
+    request.runId,
+    request.modelAttemptId,
+  ]) {
+    if (!value?.trim()) throw invalid("Context 坐标不完整");
+  }
+  if (!request.sources.length) throw invalid("Context 来源不能为空");
+  if (!request.guardContext?.actor?.id?.trim()) {
+    throw invalid("Context 缺少当前 Actor");
+  }
+  const keys = new Set<string>();
+  for (const source of request.sources) {
+    if (!source.moduleKey?.trim() || !source.id?.trim() || !source.kind) {
+      throw invalid("Context 来源坐标无效");
+    }
+    const key = `${source.moduleKey}\u0000${source.kind}\u0000${source.id}`;
+    if (keys.has(key)) throw invalid("Context 来源不能重复");
+    keys.add(key);
+  }
+}
+
+function validateResolvedSource(
+  requested: ContextBuildRequest["sources"][number],
+  source: ResolvedContextSource,
+  now: Date,
+): void {
+  const { reference } = source;
+  if (
+    reference.moduleKey !== requested.moduleKey ||
+    reference.kind !== requested.kind ||
+    reference.id !== requested.id ||
+    !reference.version?.trim() ||
+    !Number.isSafeInteger(reference.sequence) ||
+    reference.sequence < 1 ||
+    !source.content?.trim() ||
+    !/^[a-f0-9]{64}$/.test(reference.digest) ||
+    !["system", "user", "assistant", "tool"].includes(source.role) ||
+    reference.digest !== stableDigest({ role: source.role, content: source.content }) ||
+    !Number.isFinite(Date.parse(reference.validity.checkedAt))
+  ) {
+    throw new ContextMemoryError(
+      "SOURCE_INVALID",
+      "Context 来源投影与声明不一致",
+    );
+  }
+  const expiresAt = reference.validity.expiresAt
+    ? Date.parse(reference.validity.expiresAt)
+    : undefined;
+  if (
+    reference.validity.status !== "valid" ||
+    (expiresAt !== undefined &&
+      (!Number.isFinite(expiresAt) || expiresAt <= now.getTime()))
+  ) {
+    throw new ContextMemoryError(
+      "SOURCE_INVALID",
+      "Context 来源已失效或过期",
+    );
+  }
+}
+
+function immutableClone<T>(value: T): T {
+  return deepFreeze(structuredClone(value));
+}
+
+function deepFreeze<T>(value: T): T {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) {
+    return value;
+  }
+  for (const child of Object.values(value as Record<string, unknown>)) {
+    deepFreeze(child);
+  }
+  return Object.freeze(value);
+}
+
+function invalid(message: string): ContextMemoryError {
+  return new ContextMemoryError("INVALID_REQUEST", message);
+}
+
+function unavailable(message: string): ContextMemoryError {
+  return new ContextMemoryError("SOURCE_UNAVAILABLE", message);
+}

package/template/apps/server/src/agent/context-memory/contracts.ts

@@ -0,0 +1,284 @@
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import type { RequestActor, RequestGuardContext } from "../../guards.js";
+
+export const MEMORY_KINDS = [
+  "working-context",
+  "session-summary",
+  "user-preference",
+  "case-memory-candidate",
+  "verified-fact-reference",
+] as const;
+
+export type MemoryKind = (typeof MEMORY_KINDS)[number];
+
+export type ContextSourceKind =
+  | "system-instruction"
+  | "operation-instruction"
+  | "recent-event"
+  | "run-result"
+  | "skill"
+  | "artifact-summary"
+  | MemoryKind;
+
+export interface ContextSourceValidity {
+  readonly status: "valid" | "invalid";
+  readonly checkedAt: string;
+  readonly expiresAt?: string;
+  readonly reason?:
+    | "revoked"
+    | "deleted"
+    | "archived"
+    | "expired"
+    | "superseded"
+    | "authorization-denied"
+    | "unavailable";
+}
+
+export interface ContextSourceReference {
+  readonly moduleKey: string;
+  readonly kind: ContextSourceKind;
+  readonly id: string;
+  readonly version: string;
+  readonly sequence: number;
+  /** SHA-256 of the exact model-visible projection, never of hidden source data. */
+  readonly digest: string;
+  readonly validity: ContextSourceValidity;
+}
+
+export interface ResolvedContextSource {
+  readonly reference: ContextSourceReference;
+  readonly role: "system" | "user" | "assistant" | "tool";
+  /** Authorized, redacted model input. It must not contain raw reasoning traces. */
+  readonly content: string;
+}
+
+export interface ContextSourceRequest {
+  readonly moduleKey: string;
+  readonly kind: ContextSourceKind;
+  readonly id: string;
+}
+
+export interface ContextBuildRequest {
+  readonly sessionId: string;
+  readonly turnId: string;
+  readonly runId: string;
+  readonly modelAttemptId: string;
+  readonly guardContext: RequestGuardContext;
+  readonly sources: readonly ContextSourceRequest[];
+}
+
+export interface ContextVersion {
+  readonly contextVersionId: string;
+  readonly sessionId: string;
+  readonly turnId: string;
+  readonly runId: string;
+  readonly modelAttemptId: string;
+  /** Exact business Case coordinate for this attempt; absent means no Case context. */
+  readonly currentCaseId?: string;
+  readonly sources: readonly ContextSourceReference[];
+  readonly digest: string;
+  readonly createdAt: string;
+}
+
+export interface BuiltContext {
+  readonly version: ContextVersion;
+  readonly sources: readonly ResolvedContextSource[];
+}
+
+export interface ContextSourcePort {
+  resolve(
+    request: ContextSourceRequest,
+    guardContext: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<ResolvedContextSource>;
+}
+
+/** Append-only Session Event Store adapter; implementations reject duplicate attempts. */
+export interface ContextVersionRecorder {
+  record(version: ContextVersion): Promise<void>;
+}
+
+export type MemoryScope =
+  | { readonly kind: "session"; readonly sessionId: string }
+  | { readonly kind: "user"; readonly actorId: string }
+  | { readonly kind: "case"; readonly caseId: string };
+
+interface MemoryProjectionBase {
+  readonly memoryId: string;
+  readonly version: string;
+  /** SHA-256 of memoryProjectionContent(projection). */
+  readonly digest: string;
+  readonly sources: readonly ContextSourceReference[];
+  readonly validity: ContextSourceValidity;
+  readonly createdAt: string;
+  readonly expiresAt?: string;
+  /** Case affinity of the derived content, independent of its retrieval scope. */
+  readonly currentCaseId?: string;
+  /** Session lineage which produced this projection, independent of retrieval scope. */
+  readonly derivation: {
+    readonly sessionId: string;
+    readonly throughSequence: number;
+  };
+}
+
+export interface WorkingContextMemory extends MemoryProjectionBase {
+  readonly kind: "working-context";
+  readonly scope: Extract<MemoryScope, { kind: "session" }>;
+  readonly content: string;
+  /** Working Context is temporary even when a producer omits an explicit TTL. */
+  readonly expiresAt: string;
+}
+
+export interface SessionSummaryMemory extends MemoryProjectionBase {
+  readonly kind: "session-summary";
+  readonly scope: Extract<MemoryScope, { kind: "session" }>;
+  readonly summary: string;
+  readonly coveredThroughSequence: number;
+}
+
+export interface UserPreferenceMemory extends MemoryProjectionBase {
+  readonly kind: "user-preference";
+  readonly scope: Extract<MemoryScope, { kind: "user" }>;
+  readonly preferenceKey: string;
+  readonly value: string;
+}
+
+export interface CaseMemoryCandidate extends MemoryProjectionBase {
+  readonly kind: "case-memory-candidate";
+  readonly scope: Extract<MemoryScope, { kind: "case" }>;
+  readonly claim: string;
+  /** A candidate can be rejected, but never mutates itself into a verified fact. */
+  readonly reviewStatus: "pending" | "rejected";
+  readonly confidence?: number;
+}
+
+export interface VerifiedFactReferenceMemory extends MemoryProjectionBase {
+  readonly kind: "verified-fact-reference";
+  readonly scope: Extract<MemoryScope, { kind: "case" }>;
+  /** Reference only: the authoritative domain fact remains in its owning module. */
+  readonly fact: {
+    readonly moduleKey: string;
+    readonly resourceType: string;
+    readonly resourceId: string;
+    readonly version: string;
+    readonly digest: string;
+  };
+}
+
+export type MemoryProjection =
+  | WorkingContextMemory
+  | SessionSummaryMemory
+  | UserPreferenceMemory
+  | CaseMemoryCandidate
+  | VerifiedFactReferenceMemory;
+
+export interface MemoryRetrievalRequest {
+  readonly query: string;
+  readonly sessionId: string;
+  /** Required to return Case Memory; the owning module still reauthorizes this coordinate. */
+  readonly caseId?: string;
+  readonly kinds: readonly MemoryKind[];
+  readonly limit: number;
+  readonly feature: FeatureFlagDefinition;
+  readonly permissionKey: string;
+  readonly guardContext: RequestGuardContext;
+}
+
+export interface AuthorizationDecision {
+  readonly allowed: boolean;
+  readonly reason: string;
+}
+
+export interface MemoryCapabilityDecision {
+  readonly allowed: boolean;
+  readonly actor: AuthorizationDecision;
+  readonly scope: AuthorizationDecision;
+  readonly feature: AuthorizationDecision;
+  readonly permission: AuthorizationDecision;
+  readonly license: AuthorizationDecision;
+}
+
+export interface MemoryCapabilityAuthorizer {
+  authorize(request: MemoryRetrievalRequest): Promise<MemoryCapabilityDecision>;
+}
+
+export interface MemorySearchHit {
+  readonly memoryId: string;
+  readonly score?: number;
+}
+
+export interface MemorySearchPort {
+  search(
+    query: string,
+    limit: number,
+    actor: RequestActor,
+    requestId: string,
+    signal: AbortSignal,
+    scope?: MemorySearchScope,
+  ): Promise<readonly MemorySearchHit[]>;
+}
+
+export interface MemorySearchScope {
+  readonly sessionId: string;
+  /** Case Memory is excluded without an explicit coordinate; lineage is not a substitute. */
+  readonly caseId?: string;
+  readonly kinds: readonly MemoryKind[];
+}
+
+export interface MemoryProjectionPort {
+  read(
+    memoryId: string,
+    guardContext: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<MemoryProjection | undefined>;
+}
+
+/** Projectors append new versions; they never update a candidate into a fact. */
+export interface MemoryProjectionRecorder {
+  append(projection: MemoryProjection): Promise<void>;
+}
+
+export interface MemoryObjectAuthorizationPort {
+  authorize(
+    projection: MemoryProjection,
+    guardContext: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<AuthorizationDecision>;
+}
+
+export interface GovernedMemoryResult {
+  readonly projection: MemoryProjection;
+  readonly score?: number;
+  readonly authorization: {
+    readonly capability: MemoryCapabilityDecision;
+    readonly object: AuthorizationDecision;
+    readonly ttl: AuthorizationDecision;
+  };
+}
+
+export interface MemoryRetrievalResult {
+  readonly items: readonly GovernedMemoryResult[];
+  readonly excluded: {
+    readonly missing: number;
+    readonly objectDenied: number;
+    readonly expired: number;
+    readonly outOfScope: number;
+    readonly invalid: number;
+  };
+}
+
+export class ContextMemoryError extends Error {
+  constructor(
+    readonly code:
+      | "INVALID_REQUEST"
+      | "SOURCE_UNAVAILABLE"
+      | "SOURCE_INVALID"
+      | "AUTHORIZATION_DENIED"
+      | "AUTHORIZATION_UNAVAILABLE"
+      | "INVALID_PROJECTION",
+    message: string,
+  ) {
+    super(message);
+    this.name = "ContextMemoryError";
+  }
+}

package/template/apps/server/src/agent/context-memory/digest.ts

@@ -0,0 +1,22 @@
+import { createHash } from "node:crypto";
+
+export function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function stableDigest(value: unknown): string {
+  return sha256(stableJson(value));
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, item]) => item !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right));
+    return `{${entries
+      .map(([key, item]) => `${JSON.stringify(key)}:${stableJson(item)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}

package/template/apps/server/src/agent/context-memory/memory-authorization.ts

@@ -0,0 +1,82 @@
+import { evaluateAccessGuards } from "../../access-guards.js";
+import { isServerScopeContext } from "../../data-access/context.js";
+import type { GuardDecision } from "../../guards.js";
+import type { createServerRuntime } from "../../runtime.js";
+import type {
+  AuthorizationDecision,
+  MemoryCapabilityAuthorizer,
+  MemoryCapabilityDecision,
+  MemoryRetrievalRequest,
+} from "./contracts.js";
+
+type GuardRuntime = Pick<
+  ReturnType<typeof createServerRuntime>,
+  "recordDecisions" | "resolveFeature"
+>;
+
+export class AccessGuardMemoryCapabilityAuthorizer
+  implements MemoryCapabilityAuthorizer
+{
+  constructor(private readonly runtime: GuardRuntime) {}
+
+  async authorize(
+    request: MemoryRetrievalRequest,
+  ): Promise<MemoryCapabilityDecision> {
+    const actor = request.guardContext.actor;
+    const actorDecision = decision(
+      actor.type !== "anonymous" && actor.id.trim().length > 0,
+      actor.type === "anonymous" ? "anonymous" : "allowed",
+    );
+    const scopeDecision = decision(
+      isServerScopeContext(actor.scopeContext),
+      isServerScopeContext(actor.scopeContext)
+        ? "allowed"
+        : "missing-server-scope",
+    );
+    const guards = await evaluateAccessGuards(
+      this.runtime,
+      request.guardContext,
+      {
+        permission: { permissionKey: request.permissionKey },
+        feature: request.feature,
+      },
+    );
+    const featureDecision = fromGuard(guards.feature);
+    const permissionDecision = fromGuard(guards.permission);
+    const licenseParts = [
+      guards.license,
+      guards.licenseVersion,
+      guards.entitlement,
+    ];
+    const deniedLicense = licenseParts.find((item) => item && !item.allowed);
+    const licenseDecision = deniedLicense
+      ? fromGuard(deniedLicense)
+      : decision(
+          licenseParts.every((item) => item?.allowed === true),
+          licenseParts.every((item) => item?.allowed === true)
+            ? "allowed"
+            : "not-evaluated",
+        );
+    const decisions = {
+      actor: actorDecision,
+      scope: scopeDecision,
+      feature: featureDecision,
+      permission: permissionDecision,
+      license: licenseDecision,
+    };
+    return {
+      allowed: Object.values(decisions).every(({ allowed }) => allowed),
+      ...decisions,
+    };
+  }
+}
+
+function fromGuard(value: GuardDecision | undefined): AuthorizationDecision {
+  return value
+    ? { allowed: value.allowed, reason: value.reason }
+    : { allowed: false, reason: "not-evaluated" };
+}
+
+function decision(allowed: boolean, reason: string): AuthorizationDecision {
+  return { allowed, reason };
+}

package/template/apps/server/src/agent/context-memory/memory-content.ts

@@ -0,0 +1,69 @@
+import type { MemoryProjection } from "./contracts.js";
+
+export function memoryProjectionContent(projection: MemoryProjection): string {
+  switch (projection.kind) {
+    case "working-context":
+      return JSON.stringify({
+        kind: projection.kind,
+        content: projection.content,
+      });
+    case "session-summary":
+      return JSON.stringify({
+        kind: projection.kind,
+        summary: projection.summary,
+        coveredThroughSequence: projection.coveredThroughSequence,
+      });
+    case "user-preference":
+      return JSON.stringify({
+        kind: projection.kind,
+        preferenceKey: projection.preferenceKey,
+        value: projection.value,
+      });
+    case "case-memory-candidate":
+      return JSON.stringify({
+        kind: projection.kind,
+        claim: projection.claim,
+        reviewStatus: projection.reviewStatus,
+        ...(projection.confidence !== undefined
+          ? { confidence: projection.confidence }
+          : {}),
+      });
+    case "verified-fact-reference":
+      return JSON.stringify({ kind: projection.kind, fact: projection.fact });
+  }
+}
+
+export function memoryProjectionScopeId(projection: MemoryProjection) {
+  switch (projection.scope.kind) {
+    case "session":
+      return projection.scope.sessionId;
+    case "user":
+      return projection.scope.actorId;
+    case "case":
+      return projection.scope.caseId;
+  }
+}
+
+export function sameMemoryProjectionCoordinates(
+  left: MemoryProjection,
+  right: MemoryProjection,
+) {
+  return (
+    left.kind === right.kind &&
+    memoryProjectionScopeId(left) === memoryProjectionScopeId(right) &&
+    left.currentCaseId === right.currentCaseId &&
+    left.sources.length === right.sources.length &&
+    left.sources.every((source, index) => {
+      const candidate = right.sources[index];
+      return (
+        candidate !== undefined &&
+        source.moduleKey === candidate.moduleKey &&
+        source.kind === candidate.kind &&
+        source.id === candidate.id &&
+        source.version === candidate.version &&
+        source.sequence === candidate.sequence &&
+        source.digest === candidate.digest
+      );
+    })
+  );
+}