create-windy 0.8.2 → 0.9.1

package/template/apps/server/src/agent/workbench-routes.ts

@@ -0,0 +1,97 @@
+import type { RequestGuardContext } from "../guards.js";
+import type { RouteApp } from "../system/routes.js";
+import { AgentSessionFacadeError } from "./agent-session-facade.js";
+import { AgentSessionProjectionError } from "./session-projection-facade.js";
+import {
+  AgentWorkbenchError,
+  type AgentWorkbenchFacade,
+} from "./workbench-facade.js";
+
+interface Context {
+  request: Request;
+  params: Record<string, string | undefined>;
+  guardContext: RequestGuardContext;
+}
+
+export function registerAgentWorkbenchRoutes(
+  app: RouteApp,
+  facade: AgentWorkbenchFacade,
+) {
+  app.get("/agent/admin/session-recordings", (raw) =>
+    handle(raw, (context) =>
+      facade.list(
+        source(context.request),
+        context.guardContext,
+        context.request.signal,
+      ),
+    ),
+  );
+  app.get("/agent/admin/session-recordings/:sessionId", (raw) =>
+    handle(raw, (context) => {
+      const id = context.params.sessionId;
+      if (!id || !/^[A-Za-z0-9_.:-]{1,250}$/.test(id)) throw new InputError();
+      return facade.recording(
+        source(context.request),
+        id,
+        context.guardContext,
+        context.request.signal,
+      );
+    }),
+  );
+  app.post("/agent/admin/test-sessions", (raw) =>
+    handle(raw, (context) => facade.createTestSession(context.guardContext)),
+  );
+}
+
+async function handle(
+  raw: unknown,
+  action: (context: Context) => Promise<unknown>,
+) {
+  const context = raw as Context;
+  try {
+    return json(await action(context));
+  } catch (error) {
+    if (
+      error instanceof AgentWorkbenchError ||
+      error instanceof AgentSessionFacadeError ||
+      error instanceof AgentSessionProjectionError
+    )
+      return json(
+        {
+          code: error.code,
+          requestId: context.guardContext.requestId,
+          retryable: error.status >= 500,
+        },
+        error.status,
+      );
+    if (error instanceof InputError)
+      return json(
+        {
+          code: "INVALID_INPUT",
+          requestId: context.guardContext.requestId,
+          retryable: false,
+        },
+        400,
+      );
+    return json(
+      {
+        code: "WORKBENCH_UNAVAILABLE",
+        requestId: context.guardContext.requestId,
+        retryable: true,
+      },
+      503,
+    );
+  }
+}
+function source(request: Request): "business" | "harness" {
+  const value = new URL(request.url).searchParams.get("source") ?? "harness";
+  if (value !== "harness" && value !== "business") throw new InputError();
+  return value;
+}
+function json(value: unknown, status = 200) {
+  return Response.json(value, {
+    status,
+    headers: { "cache-control": "no-store" },
+  });
+}
+class InputError extends Error {}

package/template/apps/server/src/agent/workbench-run-integration.test.ts

@@ -0,0 +1,231 @@
+import type { AgentWorkbenchRecordingV1 } from "@southwind-ai/shared";
+import type { SessionId } from "./session-log/domain.js";
+import { expect, test } from "bun:test";
+import { Elysia } from "elysia";
+import { systemModuleManifest } from "@southwind-ai/modules";
+import { createServerRuntime } from "../runtime.js";
+import { AgentRunFacade } from "./run-facade.js";
+import {
+  createRunFacadeFixture,
+  guardContext,
+  runFacadeManifest,
+} from "./run-facade.test-support.js";
+import { createTestRunAuthorizationStore } from "./run-authorization.test-support.js";
+import { registerAgentRunRoutes } from "./run-routes.js";
+import type { AgentRuntimePort } from "./run-contracts.js";
+import type { RestrictedAgentToolHost } from "./tool-host.js";
+import { InMemorySessionEventRepository } from "./session-log/in-memory-repository.js";
+import { SessionEventLogService } from "./session-log/service.js";
+import { AgentSessionProjectionFacade } from "./session-projection-facade.js";
+import type { DrizzleSessionEventRepository } from "./session-persistence/drizzle-session-repository.js";
+import type {
+  DrizzleContextProjectionReader,
+  DrizzleMemoryProjectionStore,
+} from "./session-persistence/drizzle-context-memory.js";
+import type { DrizzleSessionMutationCoordinator } from "./session-persistence/drizzle-session-mutations.js";
+import { PersistentAgentRunSessionLink } from "./session-run-link.js";
+import type {
+  SessionRunProjectionReceipt,
+  SessionRunResultMemoryPort,
+} from "./session-result-memory.js";
+import { AgentWorkbenchFacade } from "./workbench-facade.js";
+import { AgentWorkbenchRunReader } from "./workbench-run-reader.js";
+import { registerAgentWorkbenchRoutes } from "./workbench-routes.js";
+
+test("Admin Session → normal governed Run → terminal settlement → read-only replay preserves ledger", async () => {
+  const fixture = await createRunFacadeFixture();
+  const modules = [systemModuleManifest("system.agent"), runFacadeManifest()];
+  const runtime = createServerRuntime(
+    {},
+    {
+      featureCatalog: modules.flatMap(({ features }) => features),
+      licenseResolver: { resolve: () => ({ status: "valid" }) },
+    },
+  );
+  const context = guardContext([
+    "system.agent-debug.read",
+    "system.agent-debug.manage",
+    "system.agent-session.manage",
+    "system.agent-session.read",
+    "business.ai.execute",
+    "business.records.read",
+  ]);
+  // Exercise the production Session service and Run link with an in-memory persistence adapter.
+  const repository = new InMemorySessionEventRepository();
+  const dbRepository = repository as unknown as DrizzleSessionEventRepository;
+  const service = new SessionEventLogService(repository);
+  const sessions = new AgentSessionProjectionFacade(
+    dbRepository,
+    service,
+    {} as DrizzleContextProjectionReader,
+    {} as DrizzleMemoryProjectionStore,
+    {} as DrizzleSessionMutationCoordinator,
+  );
+  const receipts = new Map<string, SessionRunProjectionReceipt>();
+  const links = new PersistentAgentRunSessionLink(dbRepository, service, {
+    read: async (sessionId, runId) => receipts.get(`${sessionId}:${runId}`),
+    append: async (receipt) => {
+      receipts.set(`${receipt.sessionId}:${receipt.runId}`, receipt);
+    },
+  });
+  let resultsRead = 0;
+  let cancelled = false;
+  const eventData = [
+    { sequence: 1, type: "run.started" },
+    {
+      sequence: 2,
+      type: "tool.requested",
+      toolCallId: "call-1",
+      toolKey: "business.records.list",
+      arguments: { password: "private-canary" },
+    },
+    { sequence: 3, type: "tool.completed", toolCallId: "call-1" },
+    {
+      sequence: 4,
+      type: "usage.reported",
+      attemptSequence: 1,
+      usage: { totalTokens: 12 },
+    },
+    { sequence: 5, type: "run.completed" },
+  ];
+  const remote: AgentRuntimePort = {
+    start: (...args) => fixture.remote.start(...args),
+    health: async () => new Response(),
+    status: async (runId) => ({
+      runId,
+      status: cancelled ? "cancelled" : "completed",
+      lastSequence: 5,
+    }),
+    events: async () =>
+      new Response(
+        eventData.map((event) => `data: ${JSON.stringify(event)}\n\n`).join(""),
+      ),
+    result: async () => {
+      resultsRead++;
+      return Response.json({
+        status: "completed",
+        output: { answer: "受控测试回答" },
+      });
+    },
+    cancel: async () => {
+      cancelled = true;
+      return Response.json({ status: "cancelled" });
+    },
+  };
+  const resultMemory: SessionRunResultMemoryPort = {
+    hasProjection: async ({ sessionId, runId }) =>
+      receipts.has(`${sessionId}:${runId}`),
+    project: async ({ sessionId, runId, terminalSequence }) => {
+      const receipt: SessionRunProjectionReceipt = {
+        sessionId,
+        runId,
+        terminalSequence,
+        resultDigest: `sha256:${"a".repeat(64)}`,
+        memoryIds: ["memory-1", "memory-2"],
+        projectedAt: new Date().toISOString(),
+      };
+      receipts.set(`${sessionId}:${runId}`, receipt);
+      return receipt;
+    },
+  };
+  const facade = new AgentRunFacade(
+    modules,
+    fixture.hosts,
+    runtime,
+    remote,
+    createTestRunAuthorizationStore(),
+    undefined,
+    undefined,
+    links,
+  );
+  const workbench = new AgentWorkbenchFacade({
+    modules,
+    runtime,
+    sessions,
+    runs: new AgentWorkbenchRunReader(facade, remote),
+  });
+  const app = new Elysia().derive(() => ({ guardContext: context }));
+  registerAgentWorkbenchRoutes(app, workbench);
+  registerAgentRunRoutes(
+    app,
+    facade,
+    remote,
+    {} as RestrictedAgentToolHost,
+    "test-internal",
+    links,
+    resultMemory,
+  );
+  const create = await app.handle(
+    new Request("http://localhost/agent/admin/test-sessions", {
+      method: "POST",
+    }),
+  );
+  expect(create.status).toBe(200);
+  const { sessionId } = (await create.json()) as { sessionId: SessionId };
+  const start = await app.handle(
+    new Request("http://localhost/agent/runs", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "idempotency-key": "test-request",
+      },
+      body: JSON.stringify({
+        operationKey: "business.answer",
+        input: { question: "测试" },
+        sessionId,
+      }),
+    }),
+  );
+  expect(start.status).toBe(200);
+  expect(await start.json()).toMatchObject({ runId: "run_1" });
+  expect(
+    (await repository.read({ sessionId, afterSequence: 0, limit: 100 })).some(
+      ({ data }) => data.type === "run.linked" && data.runId === "run_1",
+    ),
+  ).toBe(true);
+  expect(fixture.remote.started[0]?.executionGrant).toMatch(/^grant_/);
+  const query = new URLSearchParams({
+    operationKey: "business.answer",
+    sessionId,
+  });
+  const events = await app.handle(
+    new Request(`http://localhost/agent/runs/run_1/events?${query}`),
+  );
+  expect(events.status).toBe(200);
+  const text = await events.text();
+  expect(text).toContain("business.records.list");
+  expect(text).not.toContain("private-canary");
+  const result = await app.handle(
+    new Request(`http://localhost/agent/runs/run_1/result?${query}`),
+  );
+  expect(result.status).toBe(200);
+  expect(await result.json()).toMatchObject({
+    output: { answer: "受控测试回答" },
+  });
+  const before = (await repository.get(sessionId))!.headSequence;
+  const detail = await app.handle(
+    new Request(
+      `http://localhost/agent/admin/session-recordings/${sessionId}?source=harness`,
+    ),
+  );
+  expect(detail.status).toBe(200);
+  const recording = (await detail.json()) as AgentWorkbenchRecordingV1;
+  expect(recording).toMatchObject({
+    mode: "read-only",
+    sideEffectPolicy: "no-reexecution",
+  });
+  expect(recording.runs[0]).toMatchObject({
+    runId: "run_1",
+    operationKey: "business.answer",
+    status: "completed",
+  });
+  expect(
+    recording.runs[0].events.map(
+      (event: { sequence: number }) => event.sequence,
+    ),
+  ).toEqual([1, 2, 3, 4, 5]);
+  expect(JSON.stringify(recording)).not.toContain("private-canary");
+  expect((await repository.get(sessionId))!.headSequence).toBe(before);
+  expect(fixture.remote.started).toHaveLength(1);
+  expect(resultsRead).toBe(2);
+});

package/template/apps/server/src/agent/workbench-run-reader.ts

@@ -0,0 +1,187 @@
+import type { ModuleAgentSessionRunReferenceV1 } from "@southwind-ai/server-sdk";
+import type {
+  AgentWorkbenchEventV1,
+  AgentWorkbenchRunV1,
+} from "@southwind-ai/shared";
+import type { RequestGuardContext } from "../guards.js";
+import type { AgentRunFacade } from "./run-facade.js";
+import type { AgentRuntimePort } from "./run-contracts.js";
+import {
+  isRecord,
+  projectWorkbenchRunEvent,
+} from "./workbench-event-projection.js";
+import { projectWorkbenchResult } from "./workbench-safe-result.js";
+
+export class AgentWorkbenchRunReader {
+  constructor(
+    private readonly facade: Pick<
+      AgentRunFacade,
+      "authorizeRun" | "operationPolicy"
+    >,
+    private readonly remote: AgentRuntimePort,
+  ) {}
+
+  async read(
+    ref: ModuleAgentSessionRunReferenceV1,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<AgentWorkbenchRunV1> {
+    const identity = {
+      runId: ref.runId,
+      operationKey: ref.operationKey,
+      ...(ref.sessionId ? { sessionId: ref.sessionId } : {}),
+      ...(ref.turnId ? { turnId: ref.turnId } : {}),
+      ...(ref.messageSequence !== undefined
+        ? { messageSequence: ref.messageSequence }
+        : {}),
+    };
+    try {
+      if (
+        this.facade.operationPolicy(ref.operationKey)?.visibility === "internal"
+      )
+        throw new Error("Internal operation");
+      const current = await this.facade.authorizeRun(
+        ref.operationKey,
+        ref.runId,
+        context,
+      );
+      if (ref.sessionId && current.sessionId !== ref.sessionId)
+        throw new Error("Run association mismatch");
+    } catch {
+      return {
+        ...identity,
+        status: "unavailable",
+        events: [],
+        correlationStatus: "missing",
+        missing: ["RUN_NOT_ACCESSIBLE"],
+      };
+    }
+    try {
+      const bounded = AbortSignal.any([signal, AbortSignal.timeout(10_000)]);
+      const status = await this.remote.status(ref.runId, bounded);
+      const history = await readRecordedRunEvents(
+        this.remote,
+        ref.runId,
+        status.lastSequence,
+        bounded,
+      );
+      let result;
+      const missing = [...history.missing];
+      if (
+        !status.lastSequence &&
+        ["completed", "failed", "cancelled"].includes(status.status)
+      )
+        missing.push("RUN_EVENTS_MISSING");
+      if (status.status === "completed") {
+        const response = await this.remote.result(ref.runId, bounded);
+        if (response.ok)
+          result = projectWorkbenchResult(await readBoundedJson(response));
+        else missing.push("RUN_RESULT_UNAVAILABLE");
+      }
+      return {
+        ...identity,
+        status: status.status,
+        events: history.events,
+        ...(result ? { result } : {}),
+        correlationStatus: missing.length ? "partial" : "complete",
+        missing,
+      };
+    } catch {
+      return {
+        ...identity,
+        status: "unavailable",
+        events: [],
+        correlationStatus: "missing",
+        missing: ["RUN_RECORDING_UNAVAILABLE"],
+      };
+    }
+  }
+}
+
+export async function readRecordedRunEvents(
+  remote: AgentRuntimePort,
+  runId: string,
+  through: number,
+  signal: AbortSignal,
+) {
+  const events: AgentWorkbenchEventV1[] = [];
+  if (!through) return { events, missing: [] as string[] };
+  const response = await remote.events(runId, 0, signal);
+  if (!response.ok || !response.body)
+    throw new Error("Run recording unavailable");
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let bytes = 0;
+  let lastSequence = 0;
+  let count = 0;
+  let missingOrder = false;
+  try {
+    while (
+      lastSequence < through &&
+      count < 10_000 &&
+      bytes < 2 * 1_024 * 1_024
+    ) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      bytes += chunk.value.byteLength;
+      buffer += decoder.decode(chunk.value, { stream: true });
+      let separator: RegExpExecArray | null;
+      while (
+        (separator = /\r?\n\r?\n/.exec(buffer)) &&
+        lastSequence < through &&
+        count < 10_000
+      ) {
+        const frame = buffer.slice(0, separator.index);
+        if (frame.length > 256_000) throw new Error("Run frame exceeds bound");
+        buffer = buffer.slice(separator.index + separator[0].length);
+        const data = frame
+          .split(/\r?\n/)
+          .filter((line) => line.startsWith("data:"))
+          .map((line) => line.slice(5).trimStart())
+          .join("\n");
+        if (!data) continue;
+        const value: unknown = JSON.parse(data);
+        if (
+          !isRecord(value) ||
+          !Number.isSafeInteger(value.sequence) ||
+          Number(value.sequence) <= lastSequence
+        )
+          throw new Error("Invalid Run event order");
+        if (Number(value.sequence) !== lastSequence + 1) missingOrder = true;
+        lastSequence = Number(value.sequence);
+        count += 1;
+        const projected = projectWorkbenchRunEvent(value);
+        if (projected) events.push({ ...projected, runId });
+        else missingOrder = true;
+      }
+      if (buffer.length > 256_000 && lastSequence < through)
+        throw new Error("Run frame exceeds bound");
+    }
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+  const missing =
+    lastSequence < through || missingOrder ? ["RUN_EVENTS_PARTIAL"] : [];
+  return { events, missing };
+}
+
+async function readBoundedJson(response: Response): Promise<unknown> {
+  if (!response.body) throw new Error("Missing result body");
+  const reader = response.body.getReader();
+  let content = "";
+  let bytes = 0;
+  const decoder = new TextDecoder();
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      bytes += chunk.value.byteLength;
+      if (bytes > 2 * 1_024 * 1_024) throw new Error("Result bound exceeded");
+      content += decoder.decode(chunk.value, { stream: true });
+    }
+    return JSON.parse(content + decoder.decode()) as unknown;
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+}

package/template/apps/server/src/agent/workbench-safe-result.ts

@@ -0,0 +1,61 @@
+import type { JsonValue } from "@southwind-ai/shared";
+import { isRecord } from "./workbench-event-projection.js";
+
+const privateKeys = new Set([
+  "secret",
+  "password",
+  "token",
+  "apikey",
+  "authorization",
+  "executiongrant",
+  "chainofthought",
+  "reasoning",
+  "rawreasoning",
+  "thoughts",
+  "rawbody",
+  "providerbody",
+  "arguments",
+  "toolarguments",
+]);
+
+/** Controlled answer projection. Tool parameters and private provider state are not answers. */
+export function projectWorkbenchResult(value: unknown): {
+  output?: JsonValue;
+  status?: string;
+} {
+  if (!isRecord(value)) return {};
+  const result: { output?: JsonValue; status?: string } = {};
+  if (typeof value.status === "string" && /^[a-z-]{1,32}$/.test(value.status))
+    result.status = value.status;
+  if (value.output !== undefined)
+    result.output = safeJson(value.output, 0, { remaining: 64_000 });
+  return result;
+}
+
+function safeJson(
+  value: unknown,
+  depth: number,
+  budget: { remaining: number },
+): JsonValue {
+  if (depth > 12 || budget.remaining <= 0) return "[受控摘要已截断]";
+  if (typeof value === "string") {
+    const size = Math.min(value.length, 16_000, budget.remaining);
+    budget.remaining -= size;
+    return value.slice(0, size);
+  }
+  if (value === null || typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (Array.isArray(value))
+    return value.slice(0, 200).map((item) => safeJson(item, depth + 1, budget));
+  if (isRecord(value)) {
+    const projected: Record<string, JsonValue> = {};
+    for (const [key, child] of Object.entries(value).slice(0, 200)) {
+      if (privateKeys.has(key.replace(/[-_\s]/g, "").toLowerCase())) continue;
+      if (key.length > 200) continue;
+      budget.remaining -= key.length;
+      projected[key] = safeJson(child, depth + 1, budget);
+    }
+    return projected;
+  }
+  return null;
+}

package/template/apps/server/src/agent/workbench-sse.ts

@@ -0,0 +1,50 @@
+import { projectPublicRunEvent } from "./workbench-event-projection.js";
+
+export function projectPublicRunEvents(response: Response): Response {
+  if (!response.ok || !response.body) return response;
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  return new Response(
+    response.body.pipeThrough(
+      new TransformStream<Uint8Array, Uint8Array>({
+        transform(chunk, controller) {
+          buffer += decoder.decode(chunk, { stream: true });
+          let separator: RegExpExecArray | null;
+          while ((separator = /\r?\n\r?\n/.exec(buffer))) {
+            const frame = buffer.slice(0, separator.index);
+            if (frame.length > 256_000)
+              throw new Error("Run event frame exceeds limit");
+            buffer = buffer.slice(separator.index + separator[0].length);
+            const data = frame
+              .split(/\r?\n/)
+              .filter((line) => line.startsWith("data:"))
+              .map((line) => line.slice(5).trimStart())
+              .join("\n");
+            if (!data) continue;
+            const event = projectPublicRunEvent(JSON.parse(data) as unknown);
+            if (event)
+              controller.enqueue(
+                encoder.encode(
+                  `id: ${event.sequence}\nevent: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`,
+                ),
+              );
+          }
+          if (buffer.length > 256_000)
+            throw new Error("Run event frame exceeds limit");
+        },
+        flush() {
+          if (buffer.trim()) throw new Error("Incomplete Run event frame");
+        },
+      }),
+    ),
+    {
+      status: response.status,
+      headers: {
+        "content-type": "text/event-stream",
+        "cache-control": "no-store",
+        "x-accel-buffering": "no",
+      },
+    },
+  );
+}

package/template/apps/server/src/agent/workflow-runtime-bootstrap.ts

@@ -1,3 +1,6 @@
+import { AgentWorkflowPresetRegistry } from "../agent-workflow/preset-registry.js";
+import { registerAgentWorkflowPresetRoutes } from "../agent-workflow/preset-routes.js";
+import { projectAgentWorkflowPresets } from "../app/agent-workflow-presets.js";
 import type { RouteApp } from "../system/routes.js";
 import { composeProductionAgentWorkflowRuntime } from "../agent-workflow/runtime-composition.js";
 import { registerAgentWorkflowRoutes } from "../agent-workflow/routes.js";
@@ -57,5 +60,11 @@ export function registerProductionAgentWorkflowRuntime(
       : {}),
   });
   registerAgentWorkflowRoutes(app, runtime);
+  registerAgentWorkflowPresetRoutes(
+    app,
+    new AgentWorkflowPresetRegistry(input.modules, projectAgentWorkflowPresets),
+    input.runtime,
+    () => !!runtime,
+  );
   return runtime;
 }