create-windy 0.8.2 → 0.9.1

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

@@ -0,0 +1,339 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  AgentWorkbenchRecordingSourceV1,
+  AgentWorkbenchRecordingSummaryV1,
+  AgentWorkbenchRecordingV1,
+  AgentWorkbenchWorkflowV1,
+} from "@southwind-ai/shared";
+import { evaluateAccessGuards } from "../access-guards.js";
+import { auditActor, type RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { AgentWorkflowQueryService } from "../agent-workflow/query-service.js";
+import type { AgentSessionFacadeV1 } from "./agent-session-facade.js";
+import type { AgentSessionProjectionFacade } from "./session-projection-facade.js";
+import type { AgentWorkbenchRunReader } from "./workbench-run-reader.js";
+
+export interface AgentWorkbenchDependencies {
+  readonly modules: readonly ModuleManifest[];
+  readonly runtime: Pick<
+    ReturnType<typeof createServerRuntime>,
+    "resolveFeature" | "recordDecisions" | "auditSink"
+  >;
+  readonly sessions?: Pick<
+    AgentSessionProjectionFacade,
+    "create" | "list" | "recording"
+  >;
+  readonly business?: Pick<AgentSessionFacadeV1, "get" | "list">;
+  readonly runs?: AgentWorkbenchRunReader;
+  readonly workflows?: Pick<
+    AgentWorkflowQueryService,
+    "recording" | "recordingsForSession"
+  >;
+}
+
+export class AgentWorkbenchFacade {
+  constructor(private readonly ports: AgentWorkbenchDependencies) {}
+
+  async createTestSession(context: RequestGuardContext) {
+    await this.requireCapability("system.agent-debug", "manage", context);
+    await this.requireCapability("system.agent-session", "manage", context);
+    if (!this.ports.sessions || !this.ports.runs) throw unavailable();
+    const created = await this.ports.sessions.create(context);
+    this.audit(context, created.session.sessionId, "create", "success");
+    return { sessionId: created.session.sessionId };
+  }
+
+  async list(
+    source: AgentWorkbenchRecordingSourceV1,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<{ items: readonly AgentWorkbenchRecordingSummaryV1[] }> {
+    await this.requireCapability("system.agent-debug", "read", context);
+    if (source === "business") {
+      if (!this.ports.business) return { items: [] };
+      const result = await this.ports.business.list(context, signal);
+      this.audit(context, source, "list", "success");
+      return {
+        items: result.sessions.map((session) => ({
+          source,
+          sessionId: session.id,
+          title: session.title,
+          updatedAt: session.updatedAt,
+          operationKey: session.operationKey,
+        })),
+      };
+    }
+    await this.requireCapability("system.agent-session", "read", context);
+    if (!this.ports.sessions) throw unavailable();
+    const result = await this.ports.sessions.list(context);
+    this.audit(context, source, "list", "success");
+    return {
+      items: result.items.map((session) => ({
+        source,
+        sessionId: session.sessionId,
+        title: `调试会话 ${session.sessionId.slice(-8)}`,
+        updatedAt: session.updatedAt,
+        sessionStatus: session.status,
+      })),
+    };
+  }
+
+  async recording(
+    source: AgentWorkbenchRecordingSourceV1,
+    sessionId: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<AgentWorkbenchRecordingV1> {
+    await this.requireCapability("system.agent-debug", "read", context);
+    const bounded = AbortSignal.any([signal, AbortSignal.timeout(15_000)]);
+    try {
+      const recording =
+        source === "business"
+          ? await this.business(sessionId, context, bounded)
+          : await this.harness(sessionId, context, bounded);
+      this.audit(context, sessionId, "replay", "success");
+      return recording;
+    } catch (error) {
+      this.audit(context, sessionId, "replay", "failure");
+      throw error;
+    }
+  }
+
+  private async harness(
+    sessionId: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<AgentWorkbenchRecordingV1> {
+    await this.requireCapability("system.agent-session", "read", context);
+    if (!this.ports.sessions) throw unavailable();
+    const history = await this.ports.sessions.recording(sessionId, context);
+    const missing = history.truncated ? ["SESSION_EVENTS_PARTIAL"] : [];
+    const runs = await this.readRuns(history.runRefs, context, signal);
+    const workflows = (
+      await Promise.all(
+        history.segments.map((segment) =>
+          this.sessionWorkflows(segment.sessionId, context, missing),
+        ),
+      )
+    ).flat();
+    if (history.runRefs.length > 200) missing.push("RUN_CORRELATION_PARTIAL");
+    if (history.runRefs.length && !runs.length)
+      missing.push("RUN_RUNTIME_UNAVAILABLE");
+    if (!history.runRefs.length && !workflows.length)
+      missing.push("NO_RUN_CORRELATION");
+    if (runs.some((run) => run.correlationStatus !== "complete"))
+      missing.push("RUN_CORRELATION_PARTIAL");
+    return {
+      source: "harness",
+      sessionId,
+      title: `调试会话 ${sessionId.slice(-8)}`,
+      updatedAt: history.session.updatedAt,
+      sessionStatus: history.session.status,
+      mode: "read-only",
+      sideEffectPolicy: "no-reexecution",
+      messages: [],
+      timeline: history.timeline,
+      segments: history.segments,
+      runs,
+      workflows,
+      missing,
+      correlationStatus: missing.length
+        ? runs.length || workflows.length
+          ? "partial"
+          : "missing"
+        : "complete",
+    };
+  }
+
+  private async business(
+    sessionId: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<AgentWorkbenchRecordingV1> {
+    if (!this.ports.business) throw unavailable();
+    // Provider get() re-authorizes source data for this actor on every historical read.
+    const { session } = await this.ports.business.get(
+      sessionId,
+      context,
+      signal,
+    );
+    const missing: string[] = [];
+    if (session.truncated) missing.push("BUSINESS_MESSAGES_PARTIAL");
+    const refs = session.runRefs ?? [];
+    const runs = await this.readRuns(refs, context, signal);
+    const workflowRefs = [
+      ...new Map([
+        ...(session.workflowRefs ?? []).map(
+          (ref) => [ref.workflowRunId, ref] as const,
+        ),
+        ...refs.flatMap((ref) =>
+          ref.workflowRunId
+            ? [
+                [
+                  ref.workflowRunId,
+                  {
+                    workflowRunId: ref.workflowRunId,
+                    messageSequence: ref.messageSequence,
+                  },
+                ] as const,
+              ]
+            : [],
+        ),
+      ]).values(),
+    ];
+    const workflows: AgentWorkbenchWorkflowV1[] = [];
+    if (workflowRefs.length) {
+      if (
+        !this.ports.workflows ||
+        !(await this.allowed("system.agent-workflow", "read", context))
+      )
+        missing.push("WORKFLOW_NOT_ACCESSIBLE");
+      else
+        for (const ref of workflowRefs) {
+          try {
+            const detail = await this.ports.workflows.recording(
+              ref.workflowRunId,
+              context,
+            );
+            workflows.push({
+              ...detail.recording,
+              ...(ref.messageSequence !== undefined
+                ? { messageSequence: ref.messageSequence }
+                : {}),
+            });
+            if (detail.truncated) missing.push("WORKFLOW_EVENTS_PARTIAL");
+          } catch {
+            missing.push("WORKFLOW_NOT_ACCESSIBLE");
+          }
+        }
+    }
+    if (!refs.length && !workflowRefs.length)
+      missing.push("BUSINESS_PROVIDER_CORRELATION_MISSING");
+    if (refs.length && !runs.length) missing.push("RUN_RUNTIME_UNAVAILABLE");
+    if (runs.some((run) => run.correlationStatus !== "complete"))
+      missing.push("RUN_CORRELATION_PARTIAL");
+    return {
+      source: "business",
+      sessionId,
+      title: session.title,
+      operationKey: session.operationKey,
+      updatedAt: session.updatedAt,
+      mode: "read-only",
+      sideEffectPolicy: "no-reexecution",
+      messages: session.messages,
+      // Message order is the source ledger order; Run/Workflow each retain their own sequence domains.
+      timeline: session.messages.map((message) => ({
+        sequence: message.sequence,
+        type: `message.${message.role}`,
+        summary: message.role === "user" ? "用户消息" : "业务回答",
+        occurredAt: message.createdAt,
+      })),
+      runs,
+      workflows,
+      missing: [...new Set(missing)],
+      correlationStatus: missing.length
+        ? runs.length || workflows.length
+          ? "partial"
+          : "missing"
+        : "complete",
+    };
+  }
+
+  private async readRuns(
+    refs: readonly import("@southwind-ai/server-sdk").ModuleAgentSessionRunReferenceV1[],
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    if (!this.ports.runs) return [];
+    // Bound fanout; sequential reads prevent large business sessions from overwhelming Runtime.
+    const runs = [];
+    for (const ref of refs.slice(0, 200)) {
+      signal.throwIfAborted();
+      runs.push(await this.ports.runs.read(ref, context, signal));
+    }
+    return runs;
+  }
+
+  private async sessionWorkflows(
+    sessionId: string,
+    context: RequestGuardContext,
+    missing: string[],
+  ) {
+    if (!this.ports.workflows) {
+      return [];
+    }
+    if (!(await this.allowed("system.agent-workflow", "read", context))) {
+      missing.push("WORKFLOW_NOT_ACCESSIBLE");
+      return [];
+    }
+    const records = await this.ports.workflows.recordingsForSession(
+      sessionId,
+      context,
+    );
+    if (records.truncated) missing.push("WORKFLOW_DISCOVERY_PARTIAL");
+    return records.items;
+  }
+
+  private async allowed(
+    featureKey: string,
+    action: string,
+    context: RequestGuardContext,
+  ) {
+    const feature = this.ports.modules
+      .flatMap(({ features }) => features)
+      .find(({ key }) => key === featureKey);
+    if (!feature) return false;
+    return (
+      await evaluateAccessGuards(this.ports.runtime, context, {
+        feature,
+        permission: { permissionKey: `${featureKey}.${action}` },
+      })
+    ).decision.allowed;
+  }
+  private async requireCapability(
+    featureKey: string,
+    action: string,
+    context: RequestGuardContext,
+  ) {
+    if (!(await this.allowed(featureKey, action, context)))
+      throw new AgentWorkbenchError("FORBIDDEN", 403);
+  }
+  private audit(
+    context: RequestGuardContext,
+    id: string,
+    mode: string,
+    outcome: "success" | "failure",
+  ) {
+    this.ports.runtime.auditSink.recordEvent({
+      id: crypto.randomUUID(),
+      action:
+        mode === "create"
+          ? "agent.debug.session.create"
+          : mode === "replay"
+            ? "agent.debug.recording.replay"
+            : "agent.debug.recording.read",
+      outcome,
+      actor: auditActor(context),
+      target: { type: "agent-session", id },
+      module: "system.agent",
+      requestId: context.requestId,
+      metadata: {
+        mode,
+        sideEffectPolicy: mode === "create" ? "new-session" : "no-reexecution",
+      },
+      occurredAt: new Date().toISOString(),
+    });
+  }
+}
+
+export class AgentWorkbenchError extends Error {
+  constructor(
+    readonly code: "FORBIDDEN" | "WORKBENCH_UNAVAILABLE",
+    readonly status: 403 | 503,
+  ) {
+    super(code);
+  }
+}
+function unavailable() {
+  return new AgentWorkbenchError("WORKBENCH_UNAVAILABLE", 503);
+}

package/template/apps/server/src/agent/workbench-recording.contract.test.ts

@@ -0,0 +1,328 @@
+import { describe, expect, test } from "bun:test";
+import type { AgentRuntimePort } from "./run-contracts.js";
+import {
+  createRunFacadeFixture,
+  guardContext,
+} from "./run-facade.test-support.js";
+import {
+  AgentWorkbenchRunReader,
+  readRecordedRunEvents,
+} from "./workbench-run-reader.js";
+import { projectPublicRunEvents } from "./workbench-sse.js";
+import { projectWorkbenchResult } from "./workbench-safe-result.js";
+import { validateAgentSessionDetail } from "./agent-session-validation.js";
+
+const records = [
+  { sequence: 1, type: "run.started", runId: "run_1", rawBody: "SECRET" },
+  {
+    sequence: 2,
+    type: "tool.requested",
+    toolCallId: "call_1",
+    toolKey: "business.records.read",
+    arguments: { password: "SECRET" },
+  },
+  {
+    sequence: 3,
+    type: "approval.required",
+    toolCallId: "call_1",
+    workItemId: "item_1",
+  },
+  {
+    sequence: 4,
+    type: "approval.resolved",
+    toolCallId: "call_1",
+    workItemId: "item_1",
+    outcome: "approved",
+  },
+  {
+    sequence: 5,
+    type: "tool.completed",
+    toolCallId: "call_1",
+    result: "SECRET",
+  },
+  {
+    sequence: 6,
+    type: "usage.reported",
+    attemptSequence: 2,
+    usage: {
+      inputTokens: 15,
+      outputTokens: 6,
+      totalTokens: 21,
+      providerBody: "SECRET",
+    },
+  },
+  { sequence: 7, type: "output.delta", text: "受控回答" },
+  { sequence: 8, type: "run.completed" },
+];
+const encoder = new TextEncoder();
+function frames(events: readonly object[], crlf = false) {
+  const content = events
+    .map((event) => `data: ${JSON.stringify(event)}\n\n`)
+    .join("");
+  return crlf ? content.replaceAll("\n", "\r\n") : content;
+}
+function remote(content = frames(records)): AgentRuntimePort {
+  return {
+    start: async () => {
+      throw new Error("must never start");
+    },
+    cancel: async () => {
+      throw new Error("must never cancel");
+    },
+    health: async () => new Response(),
+    events: async () => new Response(content),
+    status: async (runId) => ({
+      runId,
+      status: "completed",
+      lastSequence: records.length,
+    }),
+    result: async () =>
+      Response.json({
+        status: "completed",
+        output: {
+          answer: "业务结果",
+          secret: "SECRET",
+          nested: { reasoning: "SECRET", total: 12 },
+        },
+      }),
+  };
+}
+
+describe("Workbench immutable recorded Run read port", () => {
+  test("current actor authorization precedes read, no start/cancel/Memory writes; Tool/Approval/Attempt order survives", async () => {
+    const fixture = await createRunFacadeFixture();
+    await fixture.facade.start(
+      "business.answer",
+      { question: "测试" },
+      "unique",
+      fixture.context,
+    );
+    const reader = new AgentWorkbenchRunReader(fixture.facade, remote());
+    const result = await reader.read(
+      { runId: "run_1", operationKey: "business.answer" },
+      fixture.context,
+      new AbortController().signal,
+    );
+    expect(result.correlationStatus).toBe("complete");
+    expect(result.events.map(({ sequence }) => sequence)).toEqual([
+      1, 2, 3, 4, 5, 6, 7, 8,
+    ]);
+    expect(result.events[2]?.workItemId).toBe("item_1");
+    expect(result.events[5]?.attemptSequence).toBe(2);
+    expect(result.events[5]?.usage?.totalTokens).toBe(21);
+    expect(result.result?.output).toEqual({
+      answer: "业务结果",
+      nested: { total: 12 },
+    });
+    expect(JSON.stringify(result)).not.toContain("SECRET");
+    expect(fixture.remote.started).toHaveLength(1);
+    const denied = await reader.read(
+      { runId: "run_1", operationKey: "business.answer" },
+      guardContext([]),
+      new AbortController().signal,
+    );
+    expect(denied.missing).toEqual(["RUN_NOT_ACCESSIBLE"]);
+    const wrongSession = await reader.read(
+      {
+        runId: "run_1",
+        operationKey: "business.answer",
+        sessionId: "session_other",
+      },
+      fixture.context,
+      new AbortController().signal,
+    );
+    expect(wrongSession.missing).toEqual(["RUN_NOT_ACCESSIBLE"]);
+  });
+  test("internal Operations never expose answers and partial/empty recordings are explicit", async () => {
+    const fixture = await createRunFacadeFixture();
+    const internal = new AgentWorkbenchRunReader(
+      {
+        authorizeRun: fixture.facade.authorizeRun.bind(fixture.facade),
+        operationPolicy: (key) => {
+          const policy = fixture.facade.operationPolicy(key);
+          return policy
+            ? { ...policy, visibility: "internal" as const }
+            : undefined;
+        },
+      },
+      remote(),
+    );
+    expect(
+      (
+        await internal.read(
+          { runId: "run_1", operationKey: "business.answer" },
+          fixture.context,
+          new AbortController().signal,
+        )
+      ).missing,
+    ).toEqual(["RUN_NOT_ACCESSIBLE"]);
+    await fixture.facade.start(
+      "business.answer",
+      { question: "测试" },
+      "unique",
+      fixture.context,
+    );
+    const port = remote();
+    const empty = new AgentWorkbenchRunReader(fixture.facade, {
+      ...port,
+      status: async (runId) => ({
+        runId,
+        status: "completed",
+        lastSequence: 0,
+      }),
+    });
+    expect(
+      (
+        await empty.read(
+          { runId: "run_1", operationKey: "business.answer" },
+          fixture.context,
+          new AbortController().signal,
+        )
+      ).missing,
+    ).toEqual(["RUN_EVENTS_MISSING"]);
+    expect(
+      (
+        await readRecordedRunEvents(
+          remote(frames([records[0]!, records[2]!])),
+          "run_1",
+          3,
+          new AbortController().signal,
+        )
+      ).missing,
+    ).toEqual(["RUN_EVENTS_PARTIAL"]);
+  });
+  test("many complete frames within one large chunk and split CRLF remain exact ordered facts", async () => {
+    const events = Array.from({ length: 1500 }, (_, index) => ({
+      sequence: index + 1,
+      type: "tool.requested",
+      toolCallId: `call_${index}`,
+      toolKey: "business.records.read",
+      rawBody: "x".repeat(160),
+    }));
+    const content = frames(events, true);
+    const parts = [
+      content.slice(0, content.indexOf("\r\n") + 1),
+      content.slice(content.indexOf("\r\n") + 1),
+    ];
+    const port = {
+      ...remote(),
+      events: async () =>
+        new Response(
+          new ReadableStream({
+            start(controller) {
+              for (const part of parts)
+                controller.enqueue(encoder.encode(part));
+              controller.close();
+            },
+          }),
+        ),
+    };
+    const read = await readRecordedRunEvents(
+      port,
+      "run_1",
+      1500,
+      new AbortController().signal,
+    );
+    expect(read.events).toHaveLength(1500);
+    expect(read.missing).toEqual([]);
+    const stream = projectPublicRunEvents(await port.events());
+    const data = await stream.text();
+    expect(data.match(/^id:/gm)).toHaveLength(1500);
+    expect(data).not.toContain("rawBody");
+  });
+  test("public SSE keeps normal answer, usage and approval fields but strips arbitrary sensitive payloads", async () => {
+    const publicStream = projectPublicRunEvents(new Response(frames(records)));
+    const events = (await publicStream.text())
+      .split("\n\n")
+      .filter(Boolean)
+      .map(
+        (frame) =>
+          JSON.parse(
+            frame
+              .split("\n")
+              .find((line) => line.startsWith("data:"))!
+              .slice(6),
+          ) as Record<string, unknown>,
+      );
+    expect(events[6]?.text).toBe("受控回答");
+    expect(events[2]?.workItemId).toBe("item_1");
+    expect(events[3]?.outcome).toBe("approved");
+    expect(events[5]?.usage).toEqual({
+      inputTokens: 15,
+      outputTokens: 6,
+      totalTokens: 21,
+    });
+    expect(JSON.stringify(events)).not.toContain("SECRET");
+  });
+  test("safe result recursively removes private state while keeping legitimate business JSON", () => {
+    expect(
+      projectWorkbenchResult({
+        output: {
+          currency: "CNY",
+          total: 12,
+          chain_of_thought: "hidden",
+          details: [{ arguments: { secret: "hidden" }, amount: 5 }],
+        },
+        providerBody: "hidden",
+      }),
+    ).toEqual({
+      output: { currency: "CNY", total: 12, details: [{ amount: 5 }] },
+    });
+  });
+  test("provider references are bounded, unique and point to messages actually returned", () => {
+    const base = {
+      sourceId: "1",
+      title: "业务会话",
+      updatedAt: "2026-10-07T01:00:00Z",
+      revision: "1",
+      messages: [
+        {
+          sequence: 2,
+          role: "assistant" as const,
+          content: "回答",
+          createdAt: "2026-10-07T01:00:00Z",
+        },
+      ],
+    };
+    expect(
+      validateAgentSessionDetail(
+        {
+          ...base,
+          truncated: true,
+          runRefs: [
+            {
+              runId: "run_1",
+              operationKey: "business.answer",
+              messageSequence: 2,
+            },
+          ],
+        },
+        "1",
+      ).truncated,
+    ).toBe(true);
+    expect(() =>
+      validateAgentSessionDetail(
+        {
+          ...base,
+          runRefs: [
+            {
+              runId: "run_1",
+              operationKey: "business.answer",
+              messageSequence: 9,
+            },
+          ],
+        },
+        "1",
+      ),
+    ).toThrow();
+    expect(() =>
+      validateAgentSessionDetail(
+        {
+          ...base,
+          workflowRefs: [{ workflowRunId: "wf_1" }, { workflowRunId: "wf_1" }],
+        },
+        "1",
+      ),
+    ).toThrow();
+  });
+});