create-windy 0.8.2 → 0.8.3

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/query-service.ts

@@ -9,6 +9,7 @@ import type {
   AgentWorkflowRepository,
   AgentWorkflowRunSnapshot,
 } from "./repository.js";
+import { projectWorkflowRecording } from "./recording-projection.js";
 
 export class AgentWorkflowQueryService {
   constructor(private readonly repository: AgentWorkflowRepository) {}
@@ -80,6 +81,41 @@ export class AgentWorkflowQueryService {
     return this.requireRelease(releaseId);
   }
 
+  /** Explicit read port: all retry attempts remain facts; no scheduler or result writes. */
+  async recording(runId: string, context: RequestGuardContext) {
+    const snapshot = await this.requireAuthorizedSnapshot(runId, context);
+    const release = await this.requireRelease(snapshot.run.releaseId);
+    const events = await this.repository.readEvents({
+      runId,
+      afterSequence: 0,
+      limit: 1_000,
+    });
+    return {
+      recording: projectWorkflowRecording(snapshot, release.definition, events),
+      truncated: (events.at(-1)?.sequence ?? 0) < snapshot.headSequence,
+    };
+  }
+
+  async recordingsForSession(sessionId: string, context: RequestGuardContext) {
+    const access = currentAccess(context);
+    const candidates = await this.repository.listRunsForActor(
+      access.tenantId,
+      access.actorId,
+      access.scopeDigest,
+      200,
+    );
+    const matched = candidates.filter(({ run }) => run.sessionId === sessionId);
+    const recordings = await Promise.all(
+      matched.map(({ run }) => this.recording(run.runId, context)),
+    );
+    return {
+      items: recordings.map(({ recording }) => recording),
+      truncated:
+        candidates.length === 200 ||
+        recordings.some(({ truncated }) => truncated),
+    };
+  }
+
   async requireAuthorizedSnapshot(
     runId: string,
     context: RequestGuardContext,

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

@@ -0,0 +1,196 @@
+import { expect, test } from "bun:test";
+import type {
+  AgentWorkflowEventEnvelope,
+  AgentWorkflowNodeRun,
+  AgentWorkflowRun,
+} from "@southwind-ai/shared";
+import { projectWorkflowRecording } from "./recording-projection.js";
+
+test("Workflow recording preserves retry attempts, model Run correlation, branch, artifacts and cancellation order", () => {
+  const at = "2026-10-07T00:00:00Z";
+  const run: AgentWorkflowRun = {
+    runId: "workflow_1",
+    releaseId: "release_1",
+    tenantId: "tenant",
+    actorId: "actor-1",
+    routeKey: "workflow.read",
+    inputDigest: "digest",
+    inputReceipt: {
+      schemaKey: "input.v1",
+      value: null,
+      valueDigest: "digest",
+      recordedAt: at,
+    },
+    scopeDigest: "scope",
+    authorizationSnapshotDigest: "auth",
+    toolPolicyDigest: "tools",
+    workspacePolicyDigest: "workspace",
+    executionPolicyDigest: "execution",
+    status: "cancelled",
+    sessionId: "session_1",
+    parentRunId: "workflow_parent",
+    parentNodeRunId: "node_parent",
+    deadlineAt: at,
+    createdAt: at,
+    updatedAt: at,
+    version: 1,
+    budget: {
+      maxDurationSeconds: 60,
+      maxModelAttempts: 3,
+      maxToolCalls: 3,
+      maxSubagents: 1,
+      maxParallelism: 1,
+      maxInputTokens: 100,
+      maxOutputTokens: 100,
+      maxCostMicros: 100,
+    },
+    usage: {
+      durationMs: 2,
+      modelAttempts: 2,
+      toolCalls: 1,
+      subagents: 0,
+      inputTokens: { status: "unknown", reasonCode: "pending" },
+      outputTokens: { status: "unknown", reasonCode: "pending" },
+      cost: { status: "unknown", reasonCode: "pending" },
+    },
+  };
+  const node: AgentWorkflowNodeRun = {
+    nodeRunId: "node_1",
+    runId: "workflow_1",
+    nodeId: "model",
+    nodeType: "model",
+    status: "failed",
+    attempt: 1,
+    maxAttempts: 3,
+    idempotencyKey: "idempotency_1",
+    inputArtifacts: [],
+    outputArtifacts: [],
+    createdAt: at,
+    updatedAt: at,
+    version: 1,
+  };
+  const retried: AgentWorkflowNodeRun = {
+    ...node,
+    nodeRunId: "node_2",
+    previousNodeRunId: "node_1",
+    status: "completed",
+    attempt: 2,
+    resultReceipt: {
+      receiptId: "receipt_2",
+      nodeRunId: "node_2",
+      resultDigest: "digest",
+      selectedBranch: "has-records",
+      artifactIds: ["artifact_1"],
+      recordedAt: at,
+      smallResult: { secret: "not disclosed" },
+      executionEvidence: {
+        source: "agent-runtime-report",
+        agentRunId: "agent_run_2",
+        modelRouteKey: "route",
+        model: "model",
+        modelDeploymentDigest: "deployment",
+        modelConfigurationDigest: "config",
+      },
+    },
+  };
+  const events: AgentWorkflowEventEnvelope[] = [
+    {
+      schemaVersion: 1,
+      eventId: "event_1",
+      workflowRunId: "workflow_1",
+      sequence: 1,
+      occurredAt: at,
+      data: {
+        type: "workflow.node-retry-scheduled",
+        nodeRunId: "node_1",
+        nodeId: "model",
+      },
+    },
+    {
+      schemaVersion: 1,
+      eventId: "event_2",
+      workflowRunId: "workflow_1",
+      sequence: 2,
+      occurredAt: at,
+      data: {
+        type: "workflow.node-completed",
+        nodeRunId: "node_2",
+        nodeId: "model",
+      },
+    },
+    {
+      schemaVersion: 1,
+      eventId: "event_3",
+      workflowRunId: "workflow_1",
+      sequence: 3,
+      occurredAt: at,
+      data: {
+        type: "workflow.node-waiting",
+        nodeRunId: "node_approval",
+        nodeId: "approval",
+      },
+    },
+    {
+      schemaVersion: 1,
+      eventId: "event_4",
+      workflowRunId: "workflow_1",
+      sequence: 4,
+      occurredAt: at,
+      data: { type: "workflow.run-cancelled" },
+    },
+  ];
+  const projected = projectWorkflowRecording(
+    {
+      run,
+      idempotencyKey: "unique",
+      headSequence: 4,
+      recoveryCount: 0,
+      nodeRuns: [
+        node,
+        retried,
+        {
+          ...node,
+          nodeRunId: "node_approval",
+          nodeId: "approval",
+          nodeType: "approval",
+          status: "waiting",
+          adapter: {
+            kind: "approval-work-item",
+            coordinate: "work_item_approved_1",
+          },
+        },
+        {
+          ...node,
+          nodeRunId: "node_unsafe",
+          nodeId: "approval",
+          nodeType: "approval",
+          status: "waiting",
+          adapter: {
+            kind: "approval-work-item",
+            coordinate: "not a safe coordinate",
+          },
+        },
+      ],
+      sideEffects: [],
+    },
+    { workflowKey: "business.review", label: "业务复核" },
+    events,
+  );
+  expect(projected.nodes.slice(0, 2).map(({ attempt }) => attempt)).toEqual([
+    1, 2,
+  ]);
+  expect(projected.nodes[2]?.workItemId).toBe("work_item_approved_1");
+  expect(projected.events[2]?.workItemId).toBe("work_item_approved_1");
+  expect(projected.nodes[3]?.workItemId).toBeUndefined();
+  expect(projected.nodes[1]).toMatchObject({
+    previousNodeRunId: "node_1",
+    agentRunId: "agent_run_2",
+    selectedBranch: "has-records",
+    artifactIds: ["artifact_1"],
+  });
+  expect(projected.events.map(({ sequence }) => sequence)).toEqual([
+    1, 2, 3, 4,
+  ]);
+  expect(projected.parentRunId).toBe("workflow_parent");
+  expect(JSON.stringify(projected)).not.toContain("not disclosed");
+});

package/template/apps/server/src/agent-workflow/recording-projection.ts

@@ -0,0 +1,86 @@
+import type {
+  AgentWorkbenchEventV1,
+  AgentWorkbenchWorkflowV1,
+  AgentWorkflowEventEnvelope,
+} from "@southwind-ai/shared";
+import type { AgentWorkflowRunSnapshot } from "./repository.js";
+
+export function projectWorkflowRecording(
+  snapshot: AgentWorkflowRunSnapshot,
+  label: { workflowKey: string; label: string },
+  events: readonly AgentWorkflowEventEnvelope[],
+): AgentWorkbenchWorkflowV1 {
+  const run = snapshot.run;
+  const workItems = new Map(
+    snapshot.nodeRuns.flatMap((node) =>
+      node.adapter?.kind === "approval-work-item" &&
+      /^[A-Za-z0-9_.:-]{1,200}$/.test(node.adapter.coordinate)
+        ? [[node.nodeRunId, node.adapter.coordinate] as const]
+        : [],
+    ),
+  );
+  return {
+    workflowRunId: run.runId,
+    workflowKey: label.workflowKey,
+    title: label.label,
+    status: run.status,
+    ...(run.sessionId ? { sessionId: run.sessionId } : {}),
+    ...(run.parentRunId ? { parentRunId: run.parentRunId } : {}),
+    ...(run.parentNodeRunId ? { parentNodeRunId: run.parentNodeRunId } : {}),
+    nodes: snapshot.nodeRuns.map((node) => ({
+      nodeRunId: node.nodeRunId,
+      nodeId: node.nodeId,
+      type: node.nodeType,
+      status: node.status,
+      attempt: node.attempt,
+      ...(workItems.has(node.nodeRunId)
+        ? { workItemId: workItems.get(node.nodeRunId)! }
+        : {}),
+      ...(node.previousNodeRunId
+        ? { previousNodeRunId: node.previousNodeRunId }
+        : {}),
+      ...(node.resultReceipt?.executionEvidence
+        ? { agentRunId: node.resultReceipt.executionEvidence.agentRunId }
+        : {}),
+      ...(node.resultReceipt?.selectedBranch
+        ? { selectedBranch: node.resultReceipt.selectedBranch }
+        : {}),
+      artifactIds: [
+        ...new Set([
+          ...node.outputArtifacts.map(({ artifactId }) => artifactId),
+          ...(node.resultReceipt?.artifactIds ?? []),
+        ]),
+      ],
+    })),
+    events: events.map(
+      (event): AgentWorkbenchEventV1 => ({
+        sequence: event.sequence,
+        type: event.data.type,
+        summary: workflowEventLabel(event.data.type),
+        occurredAt: event.occurredAt,
+        workflowRunId: event.workflowRunId,
+        ...("nodeRunId" in event.data
+          ? { nodeRunId: event.data.nodeRunId }
+          : {}),
+        ...("nodeRunId" in event.data && workItems.has(event.data.nodeRunId)
+          ? { workItemId: workItems.get(event.data.nodeRunId)! }
+          : {}),
+        ...("childAgentRunId" in event.data && event.data.childAgentRunId
+          ? { runId: event.data.childAgentRunId }
+          : {}),
+        ...(event.data.type === "workflow.artifact-linked"
+          ? { artifactId: event.data.artifact.artifactId }
+          : {}),
+      }),
+    ),
+  };
+}
+
+function workflowEventLabel(type: string) {
+  if (type.includes("retry")) return "节点重试已记录";
+  if (type.includes("cancel")) return "取消事实已记录";
+  if (type.includes("recover")) return "恢复事实已记录";
+  if (type.includes("artifact")) return "交付件已关联";
+  if (type.includes("delegation")) return "子运行事实已记录";
+  return "工作流事实已记录";
+}

package/template/apps/web/src/pages/system/AgentDebugPage.vue

@@ -0,0 +1,14 @@
+<script setup lang="ts">
+import AgentWorkbench from "./components/agent-workbench/AgentWorkbench.vue";
+</script>
+<template>
+  <div class="space-y-5">
+    <header>
+      <h1 class="text-2xl font-semibold">Agent 调试与会话回放</h1>
+      <p class="mt-2 text-sm text-muted-foreground">
+        在同一视图查看业务会话的多轮调用、工具、审批、产物与工作流，或创建真实受治理测试。
+      </p>
+    </header>
+    <AgentWorkbench />
+  </div>
+</template>