create-windy 0.8.2 → 0.9.1

package/template/apps/server/src/agent/tool-registry.ts

@@ -7,13 +7,17 @@ import type {
   ModuleToolInput,
   ModuleToolResult,
 } from "@southwind-ai/server-sdk";
-import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import type {
+  AgentAdminAvailabilityReason,
+  FeatureFlagDefinition,
+} from "@southwind-ai/shared";
 import Ajv, { type ValidateFunction } from "ajv";
 import { evaluateAccessGuards } from "../access-guards.js";
 import { isServerScopeContext } from "../data-access/context.js";
 import type { RequestGuardContext } from "../guards.js";
 import type { createServerRuntime } from "../runtime.js";
 import { sandboxFailureEvent, toolEvent, toolJsonBytes } from "./tool-audit.js";
+import { catalogGuardReason } from "./tool-catalog-availability.js";
 import type { GovernedToolExecutionWithAuditReceipt } from "./tool-execution-receipt.js";
 import {
   collectRegisteredTools,
@@ -108,20 +112,47 @@ export class GovernedToolRegistry {
     return this.#tools.get(key)?.definition;
   }
 
-  async allowed(key: string, context: RequestGuardContext): Promise<boolean> {
+  executionMode(key: string): "host" | "sandbox" | undefined {
     const tool = this.#tools.get(key);
-    if (!tool) return false;
-    return (
-      await evaluateAccessGuards(
-        this.runtime,
-        context,
-        {
-          permission: { permissionKey: tool.definition.permissionKey },
-          feature: tool.definition.feature,
-        },
-        { record: false },
-      )
-    ).decision.allowed;
+    return tool ? (tool.handler.executionMode ?? "host") : undefined;
+  }
+
+  async availability(
+    key: string,
+    context: RequestGuardContext,
+  ): Promise<{
+    readonly allowed: boolean;
+    readonly availabilityReason: AgentAdminAvailabilityReason;
+  }> {
+    const tool = this.#tools.get(key);
+    if (!tool)
+      return { allowed: false, availabilityReason: "handler-unavailable" };
+    const access = await evaluateAccessGuards(
+      this.runtime,
+      context,
+      {
+        permission: { permissionKey: tool.definition.permissionKey },
+        feature: tool.definition.feature,
+      },
+      { record: false },
+    );
+    if (!access.decision.allowed) {
+      return {
+        allowed: false,
+        availabilityReason: catalogGuardReason(access.decision.reason),
+      };
+    }
+    if (
+      tool.handler.scopeMode === "request" &&
+      !isServerScopeContext(context.actor.scopeContext)
+    ) {
+      return { allowed: false, availabilityReason: "scope-unavailable" };
+    }
+    return { allowed: true, availabilityReason: "allowed" };
+  }
+
+  async allowed(key: string, context: RequestGuardContext): Promise<boolean> {
+    return (await this.availability(key, context)).allowed;
   }
 
   async execute(

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

@@ -0,0 +1,39 @@
+import type { AgentPlatformRuntimeInput } from "./runtime-bootstrap-input.js";
+import { AgentWorkbenchFacade } from "./workbench-facade.js";
+import { registerAgentWorkbenchRoutes } from "./workbench-routes.js";
+import { AgentWorkbenchRunReader } from "./workbench-run-reader.js";
+import type { RouteApp } from "../system/routes.js";
+import type { AgentRunFacade } from "./run-facade.js";
+import type { AgentRuntimePort } from "./run-contracts.js";
+import type { AgentSessionFacadeV1 } from "./agent-session-facade.js";
+import type { AgentSessionProjectionFacade } from "./session-projection-facade.js";
+import type { AgentWorkflowQueryService } from "../agent-workflow/query-service.js";
+
+export function registerAgentWorkbenchRuntime(
+  input: AgentPlatformRuntimeInput,
+  app: RouteApp,
+  ports: {
+    readonly agentFacade?: AgentRunFacade;
+    readonly remote?: AgentRuntimePort;
+    readonly business?: AgentSessionFacadeV1;
+    readonly sessions?: AgentSessionProjectionFacade;
+    readonly workflows?: AgentWorkflowQueryService;
+  } = {},
+) {
+  registerAgentWorkbenchRoutes(
+    app,
+    new AgentWorkbenchFacade({
+      modules: input.modules,
+      runtime: input.runtime,
+      sessions: ports.sessions,
+      business: input.hosts.agentSessionProviders.length
+        ? ports.business
+        : undefined,
+      workflows: ports.workflows,
+      runs:
+        ports.agentFacade && ports.remote
+          ? new AgentWorkbenchRunReader(ports.agentFacade, ports.remote)
+          : undefined,
+    }),
+  );
+}

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