create-windy 0.8.1 → 0.8.3

package/template/apps/server/src/agent/workbench-event-projection.ts

@@ -0,0 +1,115 @@
+import type { AgentWorkbenchEventV1, JsonValue } from "@southwind-ai/shared";
+
+const labels: Readonly<Record<string, string>> = {
+  "run.started": "运行开始",
+  "run.resumed": "运行恢复",
+  "input.prepared": "输入已准备",
+  "output.delta": "模型生成回答",
+  "tool.requested": "请求调用工具",
+  "tool.completed": "工具调用完成",
+  "approval.required": "等待审批",
+  "approval.resolved": "审批已处理",
+  "usage.reported": "模型用量已记录",
+  "run.completed": "运行完成",
+  "run.failed": "运行失败",
+  "run.cancelled": "运行已取消",
+};
+
+export function projectWorkbenchRunEvent(
+  value: unknown,
+): AgentWorkbenchEventV1 | undefined {
+  if (
+    !isRecord(value) ||
+    !Number.isSafeInteger(value.sequence) ||
+    Number(value.sequence) < 1
+  )
+    return;
+  const type = safeCoordinate(value.type);
+  if (!type || !Object.hasOwn(labels, type)) return;
+  const projected: Record<string, JsonValue> = {
+    sequence: Number(value.sequence),
+    type,
+    summary: labels[type]!,
+  };
+  for (const key of [
+    "runId",
+    "turnId",
+    "stepId",
+    "modelAttemptId",
+    "toolCallId",
+    "toolKey",
+    "workItemId",
+    "artifactId",
+    "outcome",
+  ] as const) {
+    const text = safeCoordinate(value[key]);
+    if (text) projected[key] = text;
+  }
+  if (
+    typeof value.occurredAt === "string" &&
+    Number.isFinite(Date.parse(value.occurredAt))
+  )
+    projected.occurredAt = value.occurredAt;
+  if (
+    Number.isSafeInteger(value.attemptSequence) &&
+    Number(value.attemptSequence) > 0
+  )
+    projected.attemptSequence = Number(value.attemptSequence);
+  if (isRecord(value.usage)) {
+    const usage: Record<string, number> = {};
+    for (const key of [
+      "inputTokens",
+      "outputTokens",
+      "totalTokens",
+      "costMicros",
+    ] as const) {
+      const count = value.usage[key];
+      if (Number.isSafeInteger(count) && Number(count) >= 0)
+        usage[key] = Number(count);
+    }
+    projected.usage = usage;
+  }
+  return projected as unknown as AgentWorkbenchEventV1;
+}
+
+/** SSE keeps canonical answer deltas, but never forwards arbitrary Provider/Tool fields. */
+export function projectPublicRunEvent(
+  value: unknown,
+): Record<string, JsonValue> | undefined {
+  const projected = projectWorkbenchRunEvent(value);
+  if (!projected || !isRecord(value)) return;
+  const result = { ...projected } as Record<string, JsonValue>;
+  if (value.type === "output.delta" && typeof value.text === "string")
+    result.text = value.text.slice(0, 64_000);
+  if (value.type === "input.prepared") {
+    if (
+      Number.isSafeInteger(value.artifactCount) &&
+      Number(value.artifactCount) >= 0
+    )
+      result.artifactCount = Number(value.artifactCount);
+    if (Array.isArray(value.inputModalities))
+      result.inputModalities = value.inputModalities.filter(
+        (item): item is string =>
+          typeof item === "string" && /^[a-z-]{1,32}$/.test(item),
+      );
+  }
+  if (value.type === "run.failed" && isRecord(value.error)) {
+    result.error = {
+      code: safeCoordinate(value.error.code) ?? "RUN_FAILED",
+      message: "运行失败，请查看受控错误代码",
+      retryable: value.error.retryable === true,
+      requestId: safeCoordinate(value.error.requestId) ?? "unavailable",
+    };
+  }
+  return result;
+}
+
+export function safeCoordinate(value: unknown): string | undefined {
+  return typeof value === "string" && /^[A-Za-z0-9_.:/-]{1,200}$/.test(value)
+    ? value
+    : undefined;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}

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

@@ -0,0 +1,189 @@
+import { expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { AgentWorkbenchDependencies } from "./workbench-facade.js";
+import { AgentWorkbenchFacade } from "./workbench-facade.js";
+import { featureKey } from "@southwind-ai/shared";
+import { guardContext } from "./run-facade.test-support.js";
+import { createServerRuntime } from "../runtime.js";
+import { manifest } from "../module-host/test-fixtures.js";
+import { AgentWorkbenchRunReader } from "./workbench-run-reader.js";
+import { createRunFacadeFixture } from "./run-facade.test-support.js";
+
+function base(enabled = true) {
+  const keys = [
+    "system.agent-debug",
+    "system.agent-session",
+    "system.agent-workflow",
+  ];
+  const module: ModuleManifest = manifest("system", {
+    features: keys.map((key) => ({
+      key: featureKey(key),
+      label: key,
+      module: "system",
+      enabled,
+      visible: "visible",
+      stage: "stable",
+    })),
+  });
+  const runtime = createServerRuntime(
+    {},
+    {
+      featureCatalog: module.features,
+      licenseResolver: { resolve: () => ({ status: "valid" }) },
+    },
+  );
+  return { modules: [module], runtime };
+}
+const permissions = [
+  "system.agent-debug.read",
+  "system.agent-debug.manage",
+  "system.agent-session.read",
+  "system.agent-session.manage",
+  "system.agent-workflow.read",
+];
+const signal = () => new AbortController().signal;
+
+test("test Session requires debug.manage AND canonical session.manage and persistent runtime", async () => {
+  let created = 0;
+  const fixture = await createRunFacadeFixture();
+  const ports: AgentWorkbenchDependencies = {
+    ...base(),
+    runs: new AgentWorkbenchRunReader(fixture.facade, fixture.remote),
+    sessions: {
+      create: async () => {
+        created += 1;
+        return {
+          session: {
+            sessionId: "session_test" as const,
+            governance: {
+              actorId: "actor-1",
+              scopeDigest: `sha256:${"a".repeat(64)}` as const,
+            },
+            status: "active",
+            createdAt: "2026-10-07T00:00:00Z",
+            updatedAt: "2026-10-07T00:00:00Z",
+            headSequence: 1,
+          },
+          events: [],
+          replayed: false,
+        };
+      },
+      list: async () => ({ items: [] }),
+      recording: async () => {
+        throw new Error("not used");
+      },
+    },
+  };
+  const facade = new AgentWorkbenchFacade(ports);
+  await expect(
+    facade.createTestSession(guardContext(["system.agent-debug.manage"])),
+  ).rejects.toMatchObject({ code: "FORBIDDEN" });
+  expect(created).toBe(0);
+  expect(await facade.createTestSession(guardContext(permissions))).toEqual({
+    sessionId: "session_test",
+  });
+  expect(created).toBe(1);
+  await expect(
+    new AgentWorkbenchFacade(base()).createTestSession(
+      guardContext(permissions),
+    ),
+  ).rejects.toMatchObject({ code: "WORKBENCH_UNAVAILABLE" });
+  await expect(
+    new AgentWorkbenchFacade({ ...ports, ...base(false) }).createTestSession(
+      guardContext(permissions),
+    ),
+  ).rejects.toMatchObject({ code: "FORBIDDEN" });
+});
+
+test("business replay re-reads authoritative Provider on every read and never calls mutations or metrics", async () => {
+  let gets = 0;
+  const fixture = await createRunFacadeFixture();
+  const facade = new AgentWorkbenchFacade({
+    ...base(),
+    business: {
+      list: async () => ({ schemaVersion: 1, sessions: [], truncated: false }),
+      get: async () => {
+        gets += 1;
+        return {
+          schemaVersion: 1,
+          session: {
+            id: "opaque",
+            operationKey: "business.answer",
+            title: "业务会话",
+            revision: "2",
+            updatedAt: "2026-10-07T01:00:00Z",
+            truncated: true,
+            messages: [
+              {
+                sequence: 2,
+                role: "assistant",
+                content: "来源回答",
+                createdAt: "2026-10-07T01:00:00Z",
+              },
+            ],
+            runRefs: [
+              {
+                runId: "missing",
+                operationKey: "business.answer",
+                messageSequence: 2,
+              },
+            ],
+            workflowRefs: [
+              { workflowRunId: "missing-workflow", messageSequence: 2 },
+            ],
+          },
+        };
+      },
+    },
+    runs: new AgentWorkbenchRunReader(fixture.facade, fixture.remote),
+    workflows: {
+      recording: async () => {
+        throw new Error("wrong scope");
+      },
+      recordingsForSession: async () => ({ items: [], truncated: false }),
+    },
+  });
+  const context = guardContext(permissions);
+  const first = await facade.recording("business", "opaque", context, signal());
+  const second = await facade.recording(
+    "business",
+    "opaque",
+    context,
+    signal(),
+  );
+  expect(gets).toBe(2);
+  expect(first.timeline.map(({ sequence }) => sequence)).toEqual([2]);
+  expect(first.runs[0]?.missing).toEqual(["RUN_NOT_ACCESSIBLE"]);
+  expect(first.missing).toContain("BUSINESS_MESSAGES_PARTIAL");
+  expect(first.missing).toContain("WORKFLOW_NOT_ACCESSIBLE");
+  expect(first.sideEffectPolicy).toBe("no-reexecution");
+  expect(second.correlationStatus).toBe("partial");
+  expect(fixture.remote.started).toHaveLength(0);
+});
+
+test("missing business correlations are explicit, read permission cannot create a test", async () => {
+  const facade = new AgentWorkbenchFacade({
+    ...base(),
+    business: {
+      list: async () => ({ schemaVersion: 1, sessions: [], truncated: false }),
+      get: async () => ({
+        schemaVersion: 1,
+        session: {
+          id: "opaque",
+          operationKey: "business.answer",
+          title: "业务会话",
+          revision: "2",
+          updatedAt: "2026-10-07T01:00:00Z",
+          messages: [],
+        },
+      }),
+    },
+  });
+  const context = guardContext(["system.agent-debug.read"]);
+  expect(
+    (await facade.recording("business", "opaque", context, signal())).missing,
+  ).toEqual(["BUSINESS_PROVIDER_CORRELATION_MISSING"]);
+  await expect(facade.createTestSession(context)).rejects.toMatchObject({
+    code: "FORBIDDEN",
+  });
+});

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);
+}