create-windy 0.6.12 → 0.6.15

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

@@ -0,0 +1,87 @@
+import type { RequestGuardContext } from "../../guards.js";
+import type {
+  AuthorizationDecision,
+  CaseMemoryCandidate,
+  VerifiedFactReferenceMemory,
+} from "./contracts.js";
+
+export type CaseMemoryProjection =
+  | CaseMemoryCandidate
+  | VerifiedFactReferenceMemory;
+
+export interface ModuleMemoryObjectAuthorizationAdapter {
+  /** Re-reads the module object and verifies its relationship to projection.caseId. */
+  authorizeCurrent(input: {
+    readonly projection: CaseMemoryProjection;
+    readonly context: RequestGuardContext;
+    readonly signal: AbortSignal;
+  }): Promise<AuthorizationDecision>;
+}
+
+export interface ModuleMemoryObjectAdapterRegistration {
+  readonly moduleKey: string;
+  readonly authorization: ModuleMemoryObjectAuthorizationAdapter;
+}
+
+export interface CaseMemoryObjectAuthorizationPort {
+  authorizeCurrent(input: {
+    readonly projection: CaseMemoryProjection;
+    readonly context: RequestGuardContext;
+    readonly signal: AbortSignal;
+  }): Promise<AuthorizationDecision>;
+}
+
+/** Dispatches case Memory to owning modules; every involved module must allow. */
+export class ModuleMemoryObjectAuthorizationRegistry
+  implements CaseMemoryObjectAuthorizationPort
+{
+  readonly #adapters: ReadonlyMap<string, ModuleMemoryObjectAuthorizationAdapter>;
+
+  constructor(registrations: readonly ModuleMemoryObjectAdapterRegistration[]) {
+    const adapters = new Map<string, ModuleMemoryObjectAuthorizationAdapter>();
+    for (const registration of registrations) {
+      const moduleKey = registration.moduleKey.trim();
+      if (!moduleKey || adapters.has(moduleKey)) {
+        throw new Error("Memory 对象授权 Adapter 注册无效或重复");
+      }
+      adapters.set(moduleKey, registration.authorization);
+    }
+    this.#adapters = adapters;
+  }
+
+  async authorizeCurrent(
+    input: Parameters<CaseMemoryObjectAuthorizationPort["authorizeCurrent"]>[0],
+  ): Promise<AuthorizationDecision> {
+    const moduleKeys = projectionModuleKeys(input.projection);
+    if (!moduleKeys.length) return denied();
+    for (const moduleKey of moduleKeys) {
+      const adapter = this.#adapters.get(moduleKey);
+      if (!adapter) return denied();
+      let decision: AuthorizationDecision;
+      try {
+        decision = await adapter.authorizeCurrent(input);
+      } catch {
+        return denied();
+      }
+      if (!decision.allowed || !decision.reason.trim()) return denied();
+    }
+    return { allowed: true, reason: "module-authoritative" };
+  }
+}
+
+function projectionModuleKeys(projection: CaseMemoryProjection): string[] {
+  if (projection.kind === "verified-fact-reference") {
+    return projection.fact.moduleKey.trim() ? [projection.fact.moduleKey] : [];
+  }
+  return [
+    ...new Set(
+      projection.sources
+        .map(({ moduleKey }) => moduleKey)
+        .filter((moduleKey) => moduleKey !== "system.agent"),
+    ),
+  ];
+}
+
+function denied(): AuthorizationDecision {
+  return { allowed: false, reason: "module-adapter-unavailable" };
+}

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

@@ -0,0 +1,121 @@
+import type { RequestGuardContext } from "../../guards.js";
+import type {
+  AuthorizationDecision,
+  ContextSourceReference,
+  MemoryProjection,
+} from "./contracts.js";
+
+interface MemoryProjectionTriggerBase {
+  readonly triggerId: string;
+  readonly derivation: {
+    readonly sessionId: string;
+    readonly throughSequence: number;
+  };
+  readonly sources: readonly ContextSourceReference[];
+  readonly expiresAt?: string;
+  readonly currentCaseId?: string;
+}
+
+export type WorkingContextItem =
+  | { readonly type: "user-message"; readonly content: string }
+  | { readonly type: "assistant-summary"; readonly summary: string }
+  | {
+      readonly type: "artifact-ref";
+      readonly moduleKey: string;
+      readonly artifactId: string;
+      readonly version: string;
+      readonly digest: string;
+    }
+  | {
+      readonly type: "tool-receipt";
+      readonly toolKey: string;
+      readonly receiptId: string;
+      readonly resultDigest: string;
+    };
+
+export type MemoryProjectionTrigger =
+  | (MemoryProjectionTriggerBase & {
+      readonly kind: "working-context";
+      readonly sessionId: string;
+      readonly items: readonly WorkingContextItem[];
+    })
+  | (MemoryProjectionTriggerBase & {
+      readonly kind: "session-summary";
+      readonly sessionId: string;
+      readonly summary: string;
+      readonly coveredThroughSequence: number;
+    })
+  | (MemoryProjectionTriggerBase & {
+      readonly kind: "user-preference";
+      readonly actorId: string;
+      readonly preferenceKey: string;
+      readonly value: string;
+    })
+  | (MemoryProjectionTriggerBase & {
+      readonly kind: "case-memory-candidate";
+      readonly caseId: string;
+      readonly claim: string;
+      readonly confidence?: number;
+    })
+  | (MemoryProjectionTriggerBase & {
+      readonly kind: "verified-fact-reference";
+      readonly caseId: string;
+      readonly fact: {
+        readonly moduleKey: string;
+        readonly resourceType: string;
+        readonly resourceId: string;
+        readonly version: string;
+        readonly digest: string;
+      };
+    });
+
+export interface MemoryProjectionWriteAuthorizationPort {
+  authorize(
+    input: {
+      readonly kind: MemoryProjectionTrigger["kind"];
+      readonly scope: MemoryProjection["scope"];
+      readonly sourceModuleKeys: readonly string[];
+    },
+    context: RequestGuardContext,
+  ): Promise<AuthorizationDecision>;
+}
+
+export interface GovernedMemoryProjectorOptions {
+  readonly now?: () => Date;
+  /** Hard upper bound for temporary Working Context retention. */
+  readonly workingContextTtlMs?: number;
+}
+
+export interface MemoryProjectionTriggerPort {
+  projectWorkingContext(
+    trigger: Extract<MemoryProjectionTrigger, { kind: "working-context" }>,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<MemoryProjection>;
+  projectSessionSummary(
+    trigger: Extract<MemoryProjectionTrigger, { kind: "session-summary" }>,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<MemoryProjection>;
+  projectUserPreference(
+    trigger: Extract<MemoryProjectionTrigger, { kind: "user-preference" }>,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<MemoryProjection>;
+  projectCaseMemoryCandidate(
+    trigger: Extract<
+      MemoryProjectionTrigger,
+      { kind: "case-memory-candidate" }
+    >,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<MemoryProjection>;
+  projectVerifiedFactReference(
+    trigger: Extract<
+      MemoryProjectionTrigger,
+      { kind: "verified-fact-reference" }
+    >,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<MemoryProjection>;
+}

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

@@ -0,0 +1,155 @@
+import type { RequestGuardContext } from "../../guards.js";
+import {
+  ContextMemoryError,
+  type ContextSourceReference,
+} from "./contracts.js";
+import type {
+  MemoryProjectionTrigger,
+  WorkingContextItem,
+} from "./memory-projector-contracts.js";
+
+export function validateMemoryProjectionTrigger(
+  trigger: MemoryProjectionTrigger,
+  context: RequestGuardContext,
+  now: Date,
+): void {
+  if (
+    !trigger.triggerId.trim() ||
+    !context.actor.id.trim() ||
+    !trigger.derivation.sessionId.trim() ||
+    !Number.isSafeInteger(trigger.derivation.throughSequence) ||
+    trigger.derivation.throughSequence < 1 ||
+    (trigger.currentCaseId !== undefined &&
+      (!trigger.currentCaseId.trim() || trigger.currentCaseId.length > 160)) ||
+    !trigger.sources.length
+  ) {
+    throw invalid();
+  }
+  if (
+    trigger.expiresAt &&
+    (!Number.isFinite(Date.parse(trigger.expiresAt)) ||
+      Date.parse(trigger.expiresAt) <= now.getTime())
+  ) {
+    throw invalid();
+  }
+  for (const source of trigger.sources) validateSource(source, now);
+  switch (trigger.kind) {
+    case "working-context":
+      if (!trigger.sessionId.trim() || !trigger.items.length) throw invalid();
+      trigger.items.forEach(validateWorkingContextItem);
+      return;
+    case "session-summary":
+      if (
+        !trigger.sessionId.trim() ||
+        !trigger.summary.trim() ||
+        !Number.isSafeInteger(trigger.coveredThroughSequence) ||
+        trigger.coveredThroughSequence < 1
+      )
+        throw invalid();
+      return;
+    case "user-preference":
+      if (
+        trigger.actorId !== context.actor.id ||
+        !trigger.preferenceKey.trim() ||
+        !trigger.value.trim()
+      )
+        throw invalid();
+      return;
+    case "case-memory-candidate":
+      if (
+        !trigger.caseId.trim() ||
+        (trigger.currentCaseId !== undefined &&
+          trigger.currentCaseId !== trigger.caseId) ||
+        !trigger.claim.trim() ||
+        !hasBusinessSource(trigger.sources) ||
+        (trigger.confidence !== undefined &&
+          (!Number.isFinite(trigger.confidence) ||
+            trigger.confidence < 0 ||
+            trigger.confidence > 1))
+      )
+        throw invalid();
+      return;
+    case "verified-fact-reference":
+      if (!validFactTrigger(trigger)) throw invalid();
+  }
+}
+
+function validateSource(source: ContextSourceReference, now: Date): void {
+  const expiresAt = source.validity.expiresAt
+    ? Date.parse(source.validity.expiresAt)
+    : undefined;
+  if (
+    !source.moduleKey.trim() ||
+    !source.id.trim() ||
+    !source.version.trim() ||
+    !Number.isSafeInteger(source.sequence) ||
+    source.sequence < 1 ||
+    !/^[a-f0-9]{64}$/.test(source.digest) ||
+    source.validity.status !== "valid" ||
+    !Number.isFinite(Date.parse(source.validity.checkedAt)) ||
+    (expiresAt !== undefined &&
+      (!Number.isFinite(expiresAt) || expiresAt <= now.getTime()))
+  )
+    throw invalid();
+}
+
+function validateWorkingContextItem(item: WorkingContextItem): void {
+  switch (item.type) {
+    case "user-message":
+      if (!item.content.trim()) throw invalid();
+      return;
+    case "assistant-summary":
+      if (!item.summary.trim()) throw invalid();
+      return;
+    case "artifact-ref":
+      if (
+        !item.moduleKey.trim() ||
+        !item.artifactId.trim() ||
+        !item.version.trim() ||
+        !/^[a-f0-9]{64}$/.test(item.digest)
+      )
+        throw invalid();
+      return;
+    case "tool-receipt":
+      if (
+        !item.toolKey.trim() ||
+        !item.receiptId.trim() ||
+        !/^sha256:[a-f0-9]{64}$/.test(item.resultDigest)
+      )
+        throw invalid();
+  }
+}
+
+function validFactTrigger(
+  trigger: Extract<
+    MemoryProjectionTrigger,
+    { kind: "verified-fact-reference" }
+  >,
+): boolean {
+  const fact = trigger.fact;
+  return (
+    Boolean(trigger.caseId.trim()) &&
+    (trigger.currentCaseId === undefined ||
+      trigger.currentCaseId === trigger.caseId) &&
+    Boolean(fact.moduleKey.trim()) &&
+    Boolean(fact.resourceType.trim()) &&
+    Boolean(fact.resourceId.trim()) &&
+    Boolean(fact.version.trim()) &&
+    /^[a-f0-9]{64}$/.test(fact.digest) &&
+    trigger.sources.some(
+      (source) =>
+        source.moduleKey === fact.moduleKey &&
+        source.id === fact.resourceId &&
+        source.version === fact.version &&
+        source.digest === fact.digest,
+    )
+  );
+}
+
+function hasBusinessSource(sources: readonly ContextSourceReference[]) {
+  return sources.some(({ moduleKey }) => moduleKey !== "system.agent");
+}
+
+function invalid() {
+  return new ContextMemoryError("INVALID_PROJECTION", "Memory 投影触发无效");
+}

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

@@ -0,0 +1,19 @@
+import { describe, expect, test } from "bun:test";
+import {
+  DEFAULT_WORKING_CONTEXT_TTL_MS,
+  GovernedMemoryProjector,
+} from "./memory-projector.js";
+
+describe("Governed Memory Projector 配置", () => {
+  test("Host 拒绝超过 24 小时的 Working Context TTL", () => {
+    expect(
+      () =>
+        new GovernedMemoryProjector(
+          { append: async () => undefined },
+          { authorize: async () => ({ allowed: true, reason: "allowed" }) },
+          { authorize: async () => ({ allowed: true, reason: "allowed" }) },
+          { workingContextTtlMs: DEFAULT_WORKING_CONTEXT_TTL_MS + 1 },
+        ),
+    ).toThrow("Working Context TTL 配置无效");
+  });
+});

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

@@ -0,0 +1,259 @@
+import type { RequestGuardContext } from "../../guards.js";
+import {
+  ContextMemoryError,
+  type AuthorizationDecision,
+  type MemoryObjectAuthorizationPort,
+  type MemoryProjection,
+  type MemoryProjectionRecorder,
+} from "./contracts.js";
+import { sha256, stableDigest } from "./digest.js";
+import { memoryProjectionContent } from "./memory-content.js";
+import type {
+  GovernedMemoryProjectorOptions,
+  MemoryProjectionTrigger,
+  MemoryProjectionTriggerPort,
+  MemoryProjectionWriteAuthorizationPort,
+} from "./memory-projector-contracts.js";
+export type {
+  GovernedMemoryProjectorOptions,
+  MemoryProjectionTrigger,
+  MemoryProjectionTriggerPort,
+  MemoryProjectionWriteAuthorizationPort,
+  WorkingContextItem,
+} from "./memory-projector-contracts.js";
+import { validateMemoryProjectionTrigger } from "./memory-projector-validation.js";
+
+export const DEFAULT_WORKING_CONTEXT_TTL_MS = 24 * 60 * 60 * 1_000;
+
+/** Builds all five Memory kinds from explicit internal triggers and appends once. */
+export class GovernedMemoryProjector implements MemoryProjectionTriggerPort {
+  readonly #now: () => Date;
+  readonly #workingContextTtlMs: number;
+
+  constructor(
+    private readonly recorder: MemoryProjectionRecorder,
+    private readonly writes: MemoryProjectionWriteAuthorizationPort,
+    private readonly objects: MemoryObjectAuthorizationPort,
+    options: GovernedMemoryProjectorOptions = {},
+  ) {
+    this.#now = options.now ?? (() => new Date());
+    this.#workingContextTtlMs =
+      options.workingContextTtlMs ?? DEFAULT_WORKING_CONTEXT_TTL_MS;
+    if (
+      !Number.isSafeInteger(this.#workingContextTtlMs) ||
+      this.#workingContextTtlMs < 1 ||
+      this.#workingContextTtlMs > DEFAULT_WORKING_CONTEXT_TTL_MS
+    )
+      throw new Error("Working Context TTL 配置无效");
+  }
+
+  projectWorkingContext(
+    trigger: Extract<MemoryProjectionTrigger, { kind: "working-context" }>,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    return this.project(trigger, context, signal);
+  }
+
+  projectSessionSummary(
+    trigger: Extract<MemoryProjectionTrigger, { kind: "session-summary" }>,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    return this.project(trigger, context, signal);
+  }
+
+  projectUserPreference(
+    trigger: Extract<MemoryProjectionTrigger, { kind: "user-preference" }>,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    return this.project(trigger, context, signal);
+  }
+
+  projectCaseMemoryCandidate(
+    trigger: Extract<
+      MemoryProjectionTrigger,
+      { kind: "case-memory-candidate" }
+    >,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    return this.project(trigger, context, signal);
+  }
+
+  projectVerifiedFactReference(
+    trigger: Extract<
+      MemoryProjectionTrigger,
+      { kind: "verified-fact-reference" }
+    >,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    return this.project(trigger, context, signal);
+  }
+
+  async project(
+    trigger: MemoryProjectionTrigger,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<MemoryProjection> {
+    const now = this.#now();
+    validateMemoryProjectionTrigger(trigger, context, now);
+    if (signal.aborted) throw sourceUnavailable("Memory 投影已取消");
+    const projection = buildProjection(trigger, now, this.#workingContextTtlMs);
+    const writeDecision = await safeAuthorize(() =>
+      this.writes.authorize(
+        {
+          kind: projection.kind,
+          scope: projection.scope,
+          sourceModuleKeys: [
+            ...new Set(projection.sources.map(({ moduleKey }) => moduleKey)),
+          ],
+        },
+        context,
+      ),
+    );
+    if (!writeDecision.allowed) throw denied();
+    const objectDecision = await safeAuthorize(() =>
+      this.objects.authorize(projection, context, signal),
+    );
+    if (!objectDecision.allowed) throw denied();
+    if (signal.aborted) throw sourceUnavailable("Memory 投影已取消");
+    try {
+      await this.recorder.append(projection);
+    } catch {
+      throw sourceUnavailable("Memory 投影无法写入");
+    }
+    return structuredClone(projection);
+  }
+}
+
+function buildProjection(
+  trigger: MemoryProjectionTrigger,
+  now: Date,
+  workingContextTtlMs: number,
+): MemoryProjection {
+  const expiresAt = effectiveExpiry(trigger, now, workingContextTtlMs);
+  const currentCaseId =
+    trigger.kind === "case-memory-candidate" ||
+    trigger.kind === "verified-fact-reference"
+      ? trigger.caseId
+      : trigger.currentCaseId;
+  const common = {
+    memoryId: memoryId(trigger),
+    version: trigger.triggerId,
+    digest: "",
+    sources: structuredClone(trigger.sources),
+    validity: {
+      status: "valid" as const,
+      checkedAt: now.toISOString(),
+      ...(expiresAt ? { expiresAt } : {}),
+    },
+    createdAt: now.toISOString(),
+    derivation: structuredClone(trigger.derivation),
+    ...(currentCaseId ? { currentCaseId } : {}),
+    ...(expiresAt ? { expiresAt } : {}),
+  };
+  let projection: MemoryProjection;
+  switch (trigger.kind) {
+    case "working-context":
+      projection = {
+        ...common,
+        kind: trigger.kind,
+        scope: { kind: "session", sessionId: trigger.sessionId },
+        content: JSON.stringify({ items: trigger.items }),
+        expiresAt: expiresAt!,
+      };
+      break;
+    case "session-summary":
+      projection = {
+        ...common,
+        kind: trigger.kind,
+        scope: { kind: "session", sessionId: trigger.sessionId },
+        summary: trigger.summary,
+        coveredThroughSequence: trigger.coveredThroughSequence,
+      };
+      break;
+    case "user-preference":
+      projection = {
+        ...common,
+        kind: trigger.kind,
+        scope: { kind: "user", actorId: trigger.actorId },
+        preferenceKey: trigger.preferenceKey,
+        value: trigger.value,
+      };
+      break;
+    case "case-memory-candidate":
+      projection = {
+        ...common,
+        kind: trigger.kind,
+        scope: { kind: "case", caseId: trigger.caseId },
+        claim: trigger.claim,
+        reviewStatus: "pending",
+        ...(trigger.confidence !== undefined
+          ? { confidence: trigger.confidence }
+          : {}),
+      };
+      break;
+    case "verified-fact-reference":
+      projection = {
+        ...common,
+        kind: trigger.kind,
+        scope: { kind: "case", caseId: trigger.caseId },
+        fact: structuredClone(trigger.fact),
+      };
+  }
+  return {
+    ...projection,
+    digest: sha256(memoryProjectionContent(projection)),
+  };
+}
+
+function effectiveExpiry(
+  trigger: MemoryProjectionTrigger,
+  now: Date,
+  workingContextTtlMs: number,
+): string | undefined {
+  if (trigger.kind !== "working-context") return trigger.expiresAt;
+  const automaticExpiry = now.getTime() + workingContextTtlMs;
+  const requestedExpiry = trigger.expiresAt
+    ? Date.parse(trigger.expiresAt)
+    : automaticExpiry;
+  return new Date(Math.min(automaticExpiry, requestedExpiry)).toISOString();
+}
+
+function memoryId(trigger: MemoryProjectionTrigger): string {
+  return `memory_${stableDigest({
+    kind: trigger.kind,
+    triggerId: trigger.triggerId,
+  }).slice(0, 48)}`;
+}
+
+async function safeAuthorize(
+  authorize: () => Promise<AuthorizationDecision>,
+): Promise<AuthorizationDecision> {
+  try {
+    const decision = await authorize();
+    if (typeof decision.allowed !== "boolean" || !decision.reason.trim())
+      throw new Error("invalid decision");
+    return decision;
+  } catch {
+    throw authorizationUnavailable();
+  }
+}
+
+function denied() {
+  return new ContextMemoryError("AUTHORIZATION_DENIED", "Memory 投影未获授权");
+}
+
+function authorizationUnavailable() {
+  return new ContextMemoryError(
+    "AUTHORIZATION_UNAVAILABLE",
+    "Memory 授权暂不可用",
+  );
+}
+
+function sourceUnavailable(message: string) {
+  return new ContextMemoryError("SOURCE_UNAVAILABLE", message);
+}