create-windy 0.8.2 → 0.8.3

package/template/apps/server/src/agent/tool-catalog-routes.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, test } from "bun:test";
+import { featureKey } from "@southwind-ai/shared";
+import { Elysia } from "elysia";
+import { createStaticRouteAuthorizer } from "../module-host/static-route-authorization.js";
+import type { RouteApp } from "../system/routes.js";
+import {
+  createRunFacadeFixture,
+  runFacadeManifest,
+} from "./run-facade.test-support.js";
+import { registerAgentAdminCatalogRoutes } from "./tool-catalog-routes.js";
+import { GovernedToolRegistry } from "./tool-registry.js";
+
+async function fixture() {
+  const run = await createRunFacadeFixture();
+  const module = runFacadeManifest();
+  module.features.push(
+    ...["system.agent-tools", "system.agent-debug"].map((key) => ({
+      ...module.features[0]!,
+      key: featureKey(key),
+    })),
+  );
+  module.apiPermissions.push(
+    ...["tools", "operations"].map((kind) => ({
+      method: "GET" as const,
+      path: `/api/agent/admin/${kind}`,
+      permissionKey:
+        kind === "tools"
+          ? "system.agent-tools.read"
+          : "system.agent-debug.read",
+      featureKey: featureKey(
+        kind === "tools" ? "system.agent-tools" : "system.agent-debug",
+      ),
+    })),
+  );
+  const registry = new GovernedToolRegistry(
+    [module],
+    new Map([
+      [
+        "business.records.list",
+        {
+          scopeMode: "request" as const,
+          execute: () => ({ items: [] }),
+        },
+      ],
+    ]),
+    run.runtime,
+  );
+  const app = new Elysia().derive(() => ({ guardContext: run.context }));
+  app.group("/api", (group) => {
+    registerAgentAdminCatalogRoutes(group as unknown as RouteApp, {
+      modules: [module],
+      hosts: run.hosts,
+      runtime: run.runtime,
+      registry,
+      authorizer: createStaticRouteAuthorizer(run.runtime, [module]),
+      runtimeAvailable: () => true,
+    });
+    return group;
+  });
+  return { ...run, app };
+}
+
+describe("Manifest-authorized Admin catalog endpoints", () => {
+  test("Read permission is required and is independent from execution permission", async () => {
+    const { app, context, runtime } = await fixture();
+    const request = () =>
+      app.handle(new Request("http://localhost/api/agent/admin/tools"));
+    expect((await request()).status).toBe(403);
+    context.actor.permissionKeys = ["system.agent-tools.read"];
+    const response = await request();
+    expect(response.status).toBe(200);
+    const items = await response.json();
+    expect(items[0]).toMatchObject({
+      key: "business.records.list",
+      allowed: false,
+      availabilityReason: "permission-denied",
+    });
+    expect(runtime.auditSink.list().at(-1)).toMatchObject({
+      action: "system.agent-tools.read",
+      metadata: { itemCount: 1 },
+    });
+  });
+
+  test("Operation metadata access cannot start runs and successful reads are audited", async () => {
+    const { app, context, remote, prepared, runtime } = await fixture();
+    context.actor.permissionKeys = ["system.agent-debug.read"];
+    const response = await app.handle(
+      new Request("http://localhost/api/agent/admin/operations"),
+    );
+    expect(response.status).toBe(200);
+    const items = await response.json();
+    expect(items[0]).toMatchObject({
+      key: "business.answer",
+      selectable: false,
+    });
+    expect(remote.started).toHaveLength(0);
+    expect(prepared).toHaveLength(0);
+    expect(runtime.auditSink.list().at(-1)).toMatchObject({
+      action: "system.agent-debug.read",
+      metadata: { itemCount: 1 },
+    });
+  });
+});

package/template/apps/server/src/agent/tool-catalog-routes.ts

@@ -0,0 +1,62 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { RequestGuardContext } from "../guards.js";
+import type { StaticRouteAuthorizer } from "../module-host/static-route-authorization.js";
+import type { RouteApp } from "../system/routes.js";
+import {
+  AgentAdminOperationCatalog,
+  type AgentAdminOperationCatalogInput,
+} from "./operation-catalog.js";
+import type { GovernedToolRegistry } from "./tool-registry.js";
+import { projectAdminToolCatalog } from "./tool-catalog.js";
+import { auditAgentAdminCatalogRead } from "./tool-catalog-audit.js";
+
+export interface AgentAdminCatalogRouteInput extends AgentAdminOperationCatalogInput {
+  readonly modules: readonly ModuleManifest[];
+  readonly registry: GovernedToolRegistry;
+  readonly authorizer: StaticRouteAuthorizer;
+}
+
+export function registerAgentAdminCatalogRoutes(
+  app: RouteApp,
+  input: AgentAdminCatalogRouteInput,
+): void {
+  const operations = new AgentAdminOperationCatalog(input);
+  app.get("/agent/admin/tools", async (raw) => {
+    const { guardContext } = raw as { guardContext: RequestGuardContext };
+    const denied = await input.authorizer.authorize(
+      guardContext,
+      "GET",
+      "/api/agent/admin/tools",
+    );
+    if (denied) return denied;
+    const items = await projectAdminToolCatalog(
+      input.registry,
+      input.modules,
+      guardContext,
+    );
+    auditAgentAdminCatalogRead(
+      input.runtime,
+      guardContext,
+      "tools",
+      items.length,
+    );
+    return items;
+  });
+  app.get("/agent/admin/operations", async (raw) => {
+    const { guardContext } = raw as { guardContext: RequestGuardContext };
+    const denied = await input.authorizer.authorize(
+      guardContext,
+      "GET",
+      "/api/agent/admin/operations",
+    );
+    if (denied) return denied;
+    const items = await operations.list(guardContext);
+    auditAgentAdminCatalogRead(
+      input.runtime,
+      guardContext,
+      "operations",
+      items.length,
+    );
+    return items;
+  });
+}

package/template/apps/server/src/agent/tool-catalog.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from "bun:test";
+import { createServerRuntime } from "../runtime.js";
+import { guardContext, runFacadeManifest } from "./run-facade.test-support.js";
+import { projectAdminToolCatalog } from "./tool-catalog.js";
+import {
+  GovernedToolRegistry,
+  type ModuleToolHandlers,
+} from "./tool-registry.js";
+
+function fixture(options: { enabled?: boolean; sandbox?: boolean } = {}) {
+  const module = runFacadeManifest();
+  module.features = module.features.map((feature) => ({
+    ...feature,
+    enabled: options.enabled ?? true,
+  }));
+  const runtime = createServerRuntime({}, { featureCatalog: module.features });
+  const handlers: ModuleToolHandlers = new Map([
+    [
+      "business.records.list",
+      {
+        scopeMode: "request",
+        executionMode: options.sandbox ? "sandbox" : "host",
+        execute: () => ({ items: [] }),
+      },
+    ],
+  ]);
+  return {
+    module,
+    registry: new GovernedToolRegistry([module], handlers, runtime),
+  };
+}
+
+describe("Admin dynamic Tool catalogue", () => {
+  test("Business-owned declaration, Schema and installed execution mode match actual registry", async () => {
+    const { module, registry } = fixture({ sandbox: true });
+    const [tool] = await projectAdminToolCatalog(
+      registry,
+      [module],
+      guardContext(["business.records.read"]),
+    );
+    const definition = registry.definition("business.records.list")!;
+    expect(tool).toMatchObject({
+      key: definition.key,
+      module: "business",
+      label: definition.label,
+      description: definition.description,
+      featureKey: definition.featureKey,
+      permissionKey: definition.permissionKey,
+      scopeMode: definition.scopeMode,
+      executionMode: "sandbox",
+      approval: definition.approval,
+      idempotency: definition.idempotency,
+      limits: definition.limits,
+      inputSchemaKey: definition.inputSchemaKey,
+      outputSchemaKey: definition.outputSchemaKey,
+      inputSchema: definition.inputSchema,
+      outputSchema: definition.outputSchema,
+      allowedOperationKeys: ["business.answer"],
+      allowed: true,
+      availabilityReason: "allowed",
+    });
+    expect(tool.inputSchema).not.toBe(definition.inputSchema);
+  });
+
+  test("Catalogued but unauthorized tools do not gain execution rights", async () => {
+    const { module, registry } = fixture();
+    const context = guardContext(["system.agent-tools.read"]);
+    const tools = await projectAdminToolCatalog(registry, [module], context);
+    expect(tools).toHaveLength(1);
+    expect(tools[0]).toMatchObject({
+      allowed: false,
+      availabilityReason: "permission-denied",
+    });
+    await expect(
+      registry.execute("business.records.list", {}, context),
+    ).rejects.toMatchObject({ code: "TOOL_FORBIDDEN" });
+  });
+
+  test("Current runtime feature and server-created scope determine callability", async () => {
+    const disabled = fixture({ enabled: false });
+    const context = guardContext(["business.records.read"]);
+    const [off] = await projectAdminToolCatalog(
+      disabled.registry,
+      [disabled.module],
+      context,
+    );
+    expect(off).toMatchObject({
+      allowed: false,
+      availabilityReason: "feature-unavailable",
+    });
+    const { registry, module } = fixture();
+    delete context.actor.scopeContext;
+    const [noScope] = await projectAdminToolCatalog(
+      registry,
+      [module],
+      context,
+    );
+    expect(noScope).toMatchObject({
+      allowed: false,
+      availabilityReason: "scope-unavailable",
+    });
+    expect(await registry.allowed("business.records.list", context)).toBe(
+      false,
+    );
+    await expect(
+      registry.execute("business.records.list", {}, context),
+    ).rejects.toMatchObject({ code: "TOOL_FORBIDDEN" });
+  });
+
+  test("License refusal is bounded and contains no raw guard event", async () => {
+    const { registry, module } = fixture();
+    const context = guardContext(["business.records.read"]);
+    context.license = { status: "expired", restricted: true };
+    context.licenseEnforced = true;
+    const [tool] = await projectAdminToolCatalog(registry, [module], context);
+    expect(tool).toMatchObject({
+      allowed: false,
+      availabilityReason: "license-unavailable",
+    });
+    expect(tool).not.toHaveProperty("auditEvent");
+  });
+});

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

@@ -0,0 +1,44 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { AgentAdminToolCatalogItem } from "@southwind-ai/shared";
+import type { RequestGuardContext } from "../guards.js";
+import type { GovernedToolRegistry } from "./tool-registry.js";
+
+export async function projectAdminToolCatalog(
+  registry: GovernedToolRegistry,
+  modules: readonly ModuleManifest[],
+  context: RequestGuardContext,
+): Promise<readonly AgentAdminToolCatalogItem[]> {
+  const operations = modules.flatMap(({ aiOperations }) => aiOperations ?? []);
+  return Promise.all(
+    registry.definitions().map(async (tool) => ({
+      key: tool.key,
+      label: tool.label,
+      description: tool.description,
+      module: tool.module,
+      operation: tool.operation,
+      featureKey: tool.featureKey,
+      permissionKey: tool.permissionKey,
+      auditAction: tool.auditAction,
+      scopeMode: tool.scopeMode,
+      executionMode: registry.executionMode(tool.key)!,
+      dataClassification: tool.dataClassification,
+      approval: tool.approval,
+      ...(tool.approvalRoles
+        ? { approvalRoles: structuredClone(tool.approvalRoles) }
+        : {}),
+      ...(tool.approvalTimeoutSeconds
+        ? { approvalTimeoutSeconds: tool.approvalTimeoutSeconds }
+        : {}),
+      idempotency: tool.idempotency,
+      limits: { ...tool.limits },
+      inputSchemaKey: tool.inputSchemaKey,
+      outputSchemaKey: tool.outputSchemaKey,
+      inputSchema: structuredClone(tool.inputSchema),
+      outputSchema: structuredClone(tool.outputSchema),
+      allowedOperationKeys: operations
+        .filter(({ allowedToolKeys }) => allowedToolKeys.includes(tool.key))
+        .map(({ key }) => key),
+      ...(await registry.availability(tool.key, context)),
+    })),
+  );
+}

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