create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/agent/context-memory/search-provider-port.test.ts

@@ -0,0 +1,62 @@
+// @windy-module system.search begin
+import { describe, expect, test } from "bun:test";
+import { buildScopeContext } from "../../data-access/context.js";
+import type { RequestActor } from "../../guards.js";
+import type { SearchProvider } from "../../search/contracts.js";
+import { SearchProviderMemorySearchPort } from "./search-provider-port.js";
+
+describe("SearchProvider Memory adapter", () => {
+  test("复用现有 Provider 并传入当前 Actor 与服务端 Scope", async () => {
+    let actorId = "";
+    const provider: SearchProvider = {
+      key: "system.agent-session.memory.search",
+      providerVersion: "1",
+      search: async (_query, context) => {
+        actorId = context.actor.id;
+        return {
+          hits: [
+            {
+              id: "memory-1",
+              resourceType: "agent-memory",
+              maskedTitle: "受治理 Memory",
+              score: 0.9,
+            },
+          ],
+        };
+      },
+      health: async () => ({
+        status: "healthy",
+        checkedAt: "2026-08-27T00:00:00.000Z",
+      }),
+    };
+    const actor = scopedActor();
+    const result = await new SearchProviderMemorySearchPort(provider).search(
+      "偏好",
+      5,
+      actor,
+      "request-1",
+      new AbortController().signal,
+    );
+    expect(actorId).toBe("actor-1");
+    expect(result).toEqual([{ memoryId: "memory-1", score: 0.9 }]);
+  });
+});
+
+function scopedActor(): RequestActor {
+  return {
+    id: "actor-1",
+    type: "user",
+    name: "办案人员",
+    roleCodes: ["operator"],
+    permissionKeys: ["system.agent-session.read"],
+    scopeContext: buildScopeContext("actor-1", "department-1", [
+      {
+        id: "role-1",
+        code: "operator",
+        dataScope: "self",
+        departmentIds: [],
+      },
+    ]),
+  };
+}
+// @windy-module system.search end

package/template/apps/server/src/agent/context-memory/search-provider-port.ts

@@ -0,0 +1,75 @@
+// @windy-module system.search begin
+import { isServerScopeContext } from "../../data-access/context.js";
+import type {
+  SearchExecutionContext,
+  SearchProvider,
+} from "../../search/contracts.js";
+import {
+  ContextMemoryError,
+  type MemorySearchHit,
+  type MemorySearchPort,
+} from "./contracts.js";
+
+/**
+ * Reuses the existing governed SearchProvider seam. The injected provider may
+ * use the platform Embedding adapter internally; this module owns no index.
+ */
+export class SearchProviderMemorySearchPort implements MemorySearchPort {
+  constructor(
+    private readonly provider: SearchProvider,
+    private readonly resourceType = "agent-memory",
+  ) {}
+
+  async search(
+    query: string,
+    limit: number,
+    actor: Parameters<MemorySearchPort["search"]>[2],
+    requestId: string,
+    signal: AbortSignal,
+  ): Promise<readonly MemorySearchHit[]> {
+    if (!isServerScopeContext(actor.scopeContext)) {
+      throw new ContextMemoryError(
+        "AUTHORIZATION_DENIED",
+        "Memory Search 缺少服务端 ScopeContext",
+      );
+    }
+    const context: SearchExecutionContext = {
+      actor: { ...actor, scopeContext: actor.scopeContext },
+      userId: actor.id,
+      roleCodes: actor.roleCodes,
+      organizationId: actor.scopeContext.departmentId,
+      requestId,
+    };
+    const page = await this.provider.search(
+      { text: query, limit, signal },
+      context,
+    );
+    if (page.hits.length > limit) {
+      throw invalidProvider();
+    }
+    const ids = new Set<string>();
+    return page.hits.map((hit) => {
+      if (
+        hit.resourceType !== this.resourceType ||
+        !hit.id.trim() ||
+        ids.has(hit.id) ||
+        (hit.score !== undefined && !Number.isFinite(hit.score))
+      ) {
+        throw invalidProvider();
+      }
+      ids.add(hit.id);
+      return Object.freeze({
+        memoryId: hit.id,
+        ...(hit.score !== undefined ? { score: hit.score } : {}),
+      });
+    });
+  }
+}
+
+function invalidProvider(): ContextMemoryError {
+  return new ContextMemoryError(
+    "INVALID_PROJECTION",
+    "Memory SearchProvider 返回了无效投影",
+  );
+}
+// @windy-module system.search end

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

@@ -0,0 +1,95 @@
+import { agentMemoryProjections } from "@southwind-ai/database";
+import { and, asc, eq, lte } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ModuleAuthoritativeSourceAccessRegistry } from "./authoritative-source-registry.js";
+import type { MemoryProjection } from "./contracts.js";
+import type { DrizzleSessionInvalidationOutbox } from "../session-persistence/drizzle-invalidation-outbox.js";
+import type { AgentSessionPayloadCodec } from "../session-persistence/payload-codec.js";
+
+export class WorkingContextExpiryScheduler {
+  readonly #timer: ReturnType<typeof setInterval>;
+  #running = false;
+
+  constructor(
+    private readonly db: NodePgDatabase,
+    private readonly codec: AgentSessionPayloadCodec,
+    private readonly sources: ModuleAuthoritativeSourceAccessRegistry,
+    private readonly outbox: DrizzleSessionInvalidationOutbox,
+    intervalMs = 60_000,
+  ) {
+    const run = async () => {
+      if (this.#running) return;
+      this.#running = true;
+      try {
+        await this.expireBatch(Date.now());
+      } catch {
+        // Transaction rollback keeps the row active for the next bounded sweep.
+      } finally {
+        this.#running = false;
+      }
+    };
+    this.#timer = setInterval(() => void run(), intervalMs);
+    this.#timer.unref?.();
+    queueMicrotask(() => void run());
+  }
+
+  dispose() {
+    clearInterval(this.#timer);
+  }
+
+  private async expireBatch(now: number) {
+    const candidates = await this.db
+      .select()
+      .from(agentMemoryProjections)
+      .where(
+        and(
+          eq(agentMemoryProjections.kind, "working-context"),
+          eq(agentMemoryProjections.status, "active"),
+          lte(agentMemoryProjections.expiresAt, now),
+        ),
+      )
+      .orderBy(asc(agentMemoryProjections.expiresAt))
+      .limit(100);
+    for (const candidate of candidates) {
+      await this.db.transaction(async (transaction) => {
+        const db = transaction as unknown as NodePgDatabase;
+        const [expired] = await db
+          .update(agentMemoryProjections)
+          .set({ status: "invalidated", updatedAt: now })
+          .where(
+            and(
+              eq(agentMemoryProjections.memoryId, candidate.memoryId),
+              eq(agentMemoryProjections.status, "active"),
+              lte(agentMemoryProjections.expiresAt, now),
+            ),
+          )
+          .returning();
+        if (!expired || expired.expiresAt === null) return;
+        const projection = this.codec.decode<MemoryProjection>(
+          expired.payloadCipher,
+          expired.payloadDigest,
+        );
+        const producer = this.sources.bindInvalidationProducer({
+          moduleKey: "system.agent",
+          append: {
+            append: (envelope) => this.outbox.appendInTransaction(db, envelope),
+          },
+        });
+        const result = await producer.sourceExpired({
+          source: {
+            sourceKind: "working-context",
+            sourceId: projection.memoryId,
+            version: projection.version,
+            sequence: projection.derivation.throughSequence,
+          },
+          event: {
+            eventId: `working-context-expired:${projection.memoryId}:${expired.expiresAt}`,
+            eventSequence: projection.derivation.throughSequence,
+            occurredAt: new Date(expired.expiresAt).toISOString(),
+          },
+        });
+        if (result === "stale") throw new Error("Working Context 过期传播序列冲突");
+      });
+    }
+  }
+}

package/template/apps/server/src/agent/context-message-recovery.ts

@@ -0,0 +1,23 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import { stableDigest } from "./context-memory/digest.js";
+
+export type RecoverableContextRole = "system" | "user" | "assistant" | "tool";
+
+/** Converts encrypted provider history into the text-only recovery contract. */
+export function recoverContextMessage(
+  role: RecoverableContextRole,
+  content: ModuleAiJsonValue,
+) {
+  const recovered = typeof content === "string"
+    ? content
+    : JSON.stringify({ type: "recovered-message", content });
+  const projectedRole = role === "tool" ? "system" : role;
+  const projectedContent = role === "tool"
+    ? JSON.stringify({ type: "tool-receipt", content: recovered })
+    : recovered;
+  return {
+    role: projectedRole,
+    content: projectedContent,
+    digest: stableDigest({ role: projectedRole, content: projectedContent }),
+  };
+}

package/template/apps/server/src/agent/context-version-routes.ts

@@ -0,0 +1,241 @@
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+import type { RouteApp } from "../system/routes.js";
+import type {
+  ContextMessageOrigin,
+  GovernedContextMessage,
+  ProviderContextEnvelope,
+} from "./context-memory/attempt-context-contracts.js";
+import type {
+  ContextSourceReference,
+  ContextSourceRequest,
+} from "./context-memory/contracts.js";
+import type {
+  AgentContextVersionRuntime,
+  AttemptContextBaseInput,
+  CommitAttemptContextInput,
+} from "./context-version-runtime.js";
+import { assertNoPrivateReasoning } from "./session-log/events.js";
+import { validInternalToken } from "./run-routes.js";
+
+const MAX_TEXT = 512;
+const PATH = "/internal/agent/context-versions";
+
+interface RouteContext {
+  readonly body?: unknown;
+  readonly request: Request;
+  readonly guardContext: RequestGuardContext;
+}
+
+export function registerAgentContextVersionRoutes(
+  app: RouteApp,
+  runtime: AgentContextVersionRuntime,
+  internalToken: string,
+) {
+  app.post(PATH, async (raw) => {
+    const route = raw as RouteContext;
+    if (!validInternalToken(route.request, internalToken)) {
+      return errorResponse("FORBIDDEN", "内部调用认证失败", 403);
+    }
+    try {
+      const parsed = parseInput(route.body, route.guardContext.requestId);
+      if (parsed.phase === "prepare") {
+        return await runtime.prepare(parsed.input, route.request.signal);
+      }
+      if (parsed.phase === "abort") {
+        const status = await runtime.abort(parsed.input);
+        return { status };
+      }
+      const version = await runtime.commit(parsed.input, route.request.signal);
+      return {
+        contextVersionId: version.contextVersionId,
+        digest: version.digest,
+        status: "active",
+        providerRequestDigest: version.provider.requestDigest,
+      };
+    } catch {
+      return errorResponse(
+        "CONTEXT_VERSION_UNAVAILABLE",
+        "Context Version 暂不可用",
+        503,
+      );
+    }
+  });
+}
+
+export function registerUnavailableAgentContextVersionRoute(
+  app: RouteApp,
+  internalToken: string,
+) {
+  app.post(PATH, (raw) => {
+    const route = raw as RouteContext;
+    if (!validInternalToken(route.request, internalToken)) {
+      return errorResponse("FORBIDDEN", "内部调用认证失败", 403);
+    }
+    return errorResponse(
+      "CONTEXT_VERSION_UNAVAILABLE",
+      "Context Version 暂不可用",
+      503,
+    );
+  });
+}
+
+function parseInput(value: unknown, requestId: string):
+  | { phase: "prepare"; input: AttemptContextBaseInput }
+  | { phase: "abort"; input: AttemptContextBaseInput & { preparationId: string } }
+  | { phase: "commit"; input: CommitAttemptContextInput } {
+  if (!isRecord(value) || value.contractVersion !== 2) throw invalid();
+  const base = parseBase(value, requestId);
+  if (value.phase === "prepare") return { phase: "prepare", input: base };
+  const preparationId = text(value.preparationId);
+  if (value.phase === "abort") {
+    return { phase: "abort", input: { ...base, preparationId } };
+  }
+  if (value.phase !== "commit" || !isRecord(value.governedEnvelope)) throw invalid();
+  const provider = parseProvider(value.governedEnvelope.provider);
+  if (!Array.isArray(value.governedEnvelope.messages)) throw invalid();
+  const messages = value.governedEnvelope.messages.map(parseMessage);
+  return {
+    phase: "commit",
+    input: { ...base, preparationId, provider, messages },
+  };
+}
+
+function parseBase(
+  value: Record<string, unknown>,
+  requestId: string,
+): AttemptContextBaseInput {
+  if (!Array.isArray(value.sources) || value.sources.length !== 1) throw invalid();
+  return {
+    sessionId: text(value.sessionId),
+    turnId: text(value.turnId),
+    runId: text(value.runId),
+    modelAttemptId: text(value.modelAttemptId),
+    authorizationGrant: text(value.authorizationGrant, 1024),
+    sources: value.sources.map(parseSourceRequest),
+    requestId,
+    ...(value.caseId === undefined ? {} : { caseId: text(value.caseId, 160) }),
+  };
+}
+
+function parseProvider(value: unknown): ProviderContextEnvelope {
+  if (!isRecord(value)) throw invalid();
+  return {
+    deploymentKey: text(value.deploymentKey),
+    model: text(value.model),
+    requestDigest: digest(value.requestDigest),
+    toolsDigest: digest(value.toolsDigest),
+    outputSchemaDigest: digest(value.outputSchemaDigest),
+  };
+}
+
+function parseMessage(value: unknown): GovernedContextMessage {
+  if (!isRecord(value) || !Array.isArray(value.origins)) throw invalid();
+  const role = value.role;
+  if (!["system", "user", "assistant", "tool"].includes(String(role))) {
+    throw invalid();
+  }
+  const content = jsonValue(value.content);
+  assertNoPrivateReasoning(content as object);
+  return {
+    ordinal: integer(value.ordinal),
+    role: role as GovernedContextMessage["role"],
+    content,
+    digest: digest(value.digest),
+    recoveryDigest: digest(value.recoveryDigest),
+    origins: value.origins.map(parseOrigin),
+  };
+}
+
+function parseOrigin(value: unknown): ContextMessageOrigin {
+  if (!isRecord(value)) throw invalid();
+  const type = value.type;
+  if (![
+    "instructions", "user-prompt", "artifact", "context-source",
+    "provider-output", "tool-receipt",
+  ].includes(String(type))) throw invalid();
+  return {
+    type: type as ContextMessageOrigin["type"],
+    sourceId: text(value.sourceId),
+    sourceVersion: text(value.sourceVersion),
+    digest: digest(value.digest),
+    ...(value.source === undefined ? {} : { source: parseReference(value.source) }),
+  };
+}
+
+function parseSourceRequest(value: unknown): ContextSourceRequest {
+  if (!isRecord(value)) throw invalid();
+  const moduleKey = text(value.moduleKey);
+  const kind = text(value.kind);
+  if (moduleKey !== "system.agent" || kind !== "recent-event") throw invalid();
+  return { moduleKey, kind, id: text(value.id) };
+}
+
+function parseReference(value: unknown): ContextSourceReference {
+  if (!isRecord(value) || !isRecord(value.validity)) throw invalid();
+  const status = value.validity.status;
+  if (status !== "valid" && status !== "invalid") throw invalid();
+  return {
+    moduleKey: text(value.moduleKey),
+    kind: text(value.kind) as ContextSourceReference["kind"],
+    id: text(value.id),
+    version: text(value.version),
+    sequence: positiveInteger(value.sequence),
+    digest: digest(value.digest),
+    validity: {
+      status,
+      checkedAt: timestamp(value.validity.checkedAt),
+      ...(value.validity.expiresAt === undefined
+        ? {}
+        : { expiresAt: timestamp(value.validity.expiresAt) }),
+      ...(value.validity.reason === undefined
+        ? {}
+        : { reason: text(value.validity.reason) as ContextSourceReference["validity"]["reason"] }),
+    },
+  };
+}
+
+function jsonValue(value: unknown): ModuleAiJsonValue {
+  const encoded = JSON.stringify(value);
+  if (encoded === undefined || encoded.length > 1_000_000) throw invalid();
+  return JSON.parse(encoded) as ModuleAiJsonValue;
+}
+
+function integer(value: unknown) {
+  if (!Number.isSafeInteger(value) || Number(value) < 0) throw invalid();
+  return Number(value);
+}
+
+function positiveInteger(value: unknown) {
+  const result = integer(value);
+  if (result < 1) throw invalid();
+  return result;
+}
+
+function digest(value: unknown) {
+  if (typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)) throw invalid();
+  return value;
+}
+
+function timestamp(value: unknown) {
+  const result = text(value);
+  if (!Number.isFinite(Date.parse(result))) throw invalid();
+  return result;
+}
+
+function text(value: unknown, limit = MAX_TEXT) {
+  if (typeof value !== "string" || !value.trim() || value.length > limit) {
+    throw invalid();
+  }
+  return value;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function invalid() { return new Error("Context Version 请求无效"); }
+
+function errorResponse(code: string, message: string, status: number) {
+  return Response.json({ code, message, retryable: status >= 500 }, { status });
+}