create-windy 0.8.2 → 0.8.3

package/dist/cli.js

@@ -325,6 +325,15 @@ var agentOptionalModule = {
     "apps/server/src/module-host/tool-handlers.test.ts",
     "apps/server/src/module-host/module-secret-tool-boundary.test.ts",
     "apps/web/src/pages/system/AiRuntimePage.vue",
+    "apps/web/src/pages/system/AgentToolsPage.vue",
+    "apps/web/src/pages/system/AgentDebugPage.vue",
+    "apps/web/src/pages/system/components/agent-workbench",
+    "apps/web/src/pages/system/composables/useAgentWorkbench.ts",
+    "apps/web/src/pages/system/composables/useAgentWorkbench.webtest.ts",
+    "apps/web/src/pages/system/composables/useSessionReplay.ts",
+    "apps/web/src/services/agent-admin-api.ts",
+    "apps/web/src/services/agent-admin-api.webtest.ts",
+    "apps/web/src/services/agent-workbench-event.ts",
     "apps/web/src/pages/system/AgentSessionPage.vue",
     "apps/web/src/pages/system/AgentSessionPage.webtest.ts",
     "apps/web/src/pages/system/AgentWorkflowPage.vue",
@@ -344,6 +353,9 @@ var agentOptionalModule = {
     "apps/web/src/services/ai-runtime-api.ts",
     "apps/web/src/services/ai-runtime-api.webtest.ts",
     "scripts/provision-speech-readiness.ts",
+    "packages/modules/src/system-agent-admin-registration.test.ts",
+    "packages/modules/src/system-agent-admin-menus.ts",
+    "packages/modules/src/system-agent-admin-bindings.ts",
     "packages/modules/src/system-agent-audit-actions.ts",
     "packages/modules/src/system-agent-tools.ts",
     "packages/modules/src/system-agent-supervisor.ts",
@@ -359,6 +371,8 @@ var agentOptionalModule = {
     "packages/server-sdk/src/workflow-input-materialization-handler.ts",
     "packages/database/src/agent-runtime-schema.test.ts",
     "packages/database/src/ai-output-artifacts.test.ts",
+    "packages/shared/src/agent-admin-catalog.ts",
+    "packages/shared/src/agent-workbench.ts",
     "packages/shared/src/agent-workflow-definition.ts",
     "packages/shared/src/agent-workflow-delegation.ts",
     "packages/shared/src/agent-workflow-evaluation.ts",
@@ -371,6 +385,8 @@ var agentOptionalModule = {
   ],
   documentation: [
     "docs/adr/0003-agent-session-event-source.md",
+    "docs/architecture/agent-admin-workbench-plan.md",
+    "docs/architecture/agent-admin-workbench-implementation.md",
     "docs/architecture/agent-harness.md",
     "docs/architecture/agent-runtime-compatibility.md",
     "docs/architecture/agent-workflow.md",
@@ -8530,7 +8546,8 @@ var recipes = [
     to: "0.8.0"
   },
   { id: "starter-0.8.0-to-0.8.1", from: "0.8.0", to: "0.8.1" },
-  { id: "starter-0.8.1-to-0.8.2", from: "0.8.1", to: "0.8.2" }
+  { id: "starter-0.8.1-to-0.8.2", from: "0.8.1", to: "0.8.2" },
+  { id: "starter-0.8.2-to-0.8.3", from: "0.8.2", to: "0.8.3" }
 ];
 function resolveRecipeChain(sourceVersion, targetVersion) {
   if (compareVersions2(sourceVersion, minimumSupportedUpdateVersion) < 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-windy",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "创建单组织、单租户、私有部署优先的 Windy 企业 Dashboard Starter",
   "type": "module",
   "bin": {

package/template/.windy-template.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "templateCommit": "7c00e145cc8fef9f4c6ec621e8740e3c01f7cc2d",
-  "generatorVersion": "0.8.2",
+  "templateCommit": "c701e845048c839516533e164cb550e3348eb89c",
+  "generatorVersion": "0.8.3",
   "modules": [
     {
       "name": "system",

package/template/apps/server/src/agent/admin-catalog-bootstrap.ts

@@ -0,0 +1,25 @@
+import type { ModuleAiOperationReadinessPortV1 } from "@southwind-ai/server-sdk";
+import type { AgentPlatformRuntimeInput } from "./runtime-bootstrap-input.js";
+import type { composeAgentToolRuntime } from "./runtime-tool-composition.js";
+import { registerAgentAdminCatalogRoutes } from "./tool-catalog-routes.js";
+
+export interface AgentAdminReadinessRef {
+  current?: ModuleAiOperationReadinessPortV1;
+}
+
+export function registerAgentAdminCatalogRuntime(
+  input: AgentPlatformRuntimeInput,
+  tools: ReturnType<typeof composeAgentToolRuntime>,
+  readiness: AgentAdminReadinessRef,
+) {
+  registerAgentAdminCatalogRoutes(input.app, {
+    modules: input.modules,
+    hosts: input.hosts,
+    runtime: input.runtime,
+    registry: tools.toolRegistry,
+    authorizer: tools.routeAuthorizer,
+    runtimeAvailable: () => input.platformConfig.enableAI,
+    operationReadiness: async (operationKey) =>
+      (await readiness.current?.inspect({ operationKey }))?.status === "ready",
+  });
+}

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

@@ -11,13 +11,12 @@ export function registerAgentSessions(input: {
   runtime: ReturnType<typeof createServerRuntime>;
   secret: string;
 }) {
-  if (!input.hosts.agentSessionProviders.length) return;
-  registerAgentSessionRoutesV1(
-    input.app,
-    new AgentSessionFacadeV1(
-      input.hosts,
-      input.runtime,
-      new AgentSessionIdCodecV1(input.secret),
-    ),
+  const facade = new AgentSessionFacadeV1(
+    input.hosts,
+    input.runtime,
+    new AgentSessionIdCodecV1(input.secret),
   );
+  if (!input.hosts.agentSessionProviders.length) return facade;
+  registerAgentSessionRoutesV1(input.app, facade);
+  return facade;
 }

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

@@ -2,6 +2,8 @@ import { randomUUIDv7 } from "bun";
 import {
   MODULE_AGENT_SESSION_SCHEMA_VERSION,
   type ModuleAgentSessionSummaryV1,
+  type ModuleAgentSessionRunReferenceV1,
+  type ModuleAgentSessionWorkflowReferenceV1,
 } from "@southwind-ai/server-sdk";
 import { evaluateAccessGuards } from "../access-guards.js";
 import { auditActor, type RequestGuardContext } from "../guards.js";
@@ -33,12 +35,15 @@ export interface AgentSessionSummaryDtoV1 {
 }
 
 export interface AgentSessionDetailDtoV1 extends AgentSessionSummaryDtoV1 {
+  readonly truncated?: boolean;
   readonly messages: readonly {
     sequence: number;
     role: "user" | "assistant";
     content: string;
     createdAt: string;
   }[];
+  readonly runRefs?: readonly ModuleAgentSessionRunReferenceV1[];
+  readonly workflowRefs?: readonly ModuleAgentSessionWorkflowReferenceV1[];
 }
 
 export class AgentSessionFacadeError extends Error {
@@ -156,6 +161,13 @@ export class AgentSessionFacadeV1 {
             session: {
               ...this.project(entry, actor.id, validated),
               messages: validated.messages,
+              ...(validated.truncated !== undefined
+                ? { truncated: validated.truncated }
+                : {}),
+              ...(validated.runRefs ? { runRefs: validated.runRefs } : {}),
+              ...(validated.workflowRefs
+                ? { workflowRefs: validated.workflowRefs }
+                : {}),
             } satisfies AgentSessionDetailDtoV1,
           };
         } catch (error) {

package/template/apps/server/src/agent/agent-session-validation.ts

@@ -66,6 +66,49 @@ export function validateAgentSessionDetail(
     previousSequence = message.sequence;
   }
   if (totalChars > MAX_TOTAL_MESSAGE_CHARS) invalidProvider();
+  if (value.truncated !== undefined && typeof value.truncated !== "boolean")
+    invalidProvider();
+  const messageSequences = new Set(
+    value.messages.map(({ sequence }) => sequence),
+  );
+  if (value.runRefs !== undefined) {
+    if (!Array.isArray(value.runRefs) || value.runRefs.length > 200)
+      invalidProvider();
+    const ids = new Set<string>();
+    for (const ref of value.runRefs) {
+      if (
+        !ref ||
+        !validText(ref.runId, 200) ||
+        !validText(ref.operationKey, 200) ||
+        !/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/.test(ref.operationKey) ||
+        ids.has(ref.runId) ||
+        (ref.sessionId !== undefined && !validText(ref.sessionId, 200)) ||
+        (ref.turnId !== undefined && !validText(ref.turnId, 200)) ||
+        (ref.workflowRunId !== undefined &&
+          !validText(ref.workflowRunId, 200)) ||
+        (ref.messageSequence !== undefined &&
+          !messageSequences.has(ref.messageSequence))
+      )
+        invalidProvider();
+      ids.add(ref.runId);
+    }
+  }
+  if (value.workflowRefs !== undefined) {
+    if (!Array.isArray(value.workflowRefs) || value.workflowRefs.length > 100)
+      invalidProvider();
+    const ids = new Set<string>();
+    for (const ref of value.workflowRefs) {
+      if (
+        !ref ||
+        !validText(ref.workflowRunId, 200) ||
+        ids.has(ref.workflowRunId) ||
+        (ref.messageSequence !== undefined &&
+          !messageSequences.has(ref.messageSequence))
+      )
+        invalidProvider();
+      ids.add(ref.workflowRunId);
+    }
+  }
   return value;
 }
 

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

@@ -0,0 +1,202 @@
+import { describe, expect, test } from "bun:test";
+import { createServerRuntime } from "../runtime.js";
+import { AgentAdminOperationCatalog } from "./operation-catalog.js";
+import {
+  createRunFacadeFixture,
+  runFacadeManifest,
+} from "./run-facade.test-support.js";
+
+async function fixture(
+  options: { workflowOnly?: boolean; runtimeAvailable?: boolean } = {},
+) {
+  const run = await createRunFacadeFixture(undefined, {
+    workflowOnly: options.workflowOnly,
+  });
+  const module = runFacadeManifest(options.workflowOnly);
+  const catalog = new AgentAdminOperationCatalog({
+    modules: [module],
+    hosts: run.hosts,
+    runtime: run.runtime,
+    runtimeAvailable: () => options.runtimeAvailable ?? true,
+  });
+  return { ...run, catalog, module };
+}
+
+describe("Admin Operation catalogue uses production registration", () => {
+  test("Registered and governed agent exposes real Schema/limits/tools, without preparing or running", async () => {
+    const { catalog, context, prepared, module, remote } = await fixture();
+    const [operation] = await catalog.list(context);
+    expect(operation).toMatchObject({
+      key: "business.answer",
+      module: "business",
+      inputSchemaKey: "business.input.v1",
+      inputSchema: module.jsonSchemas!.find(
+        ({ key }) => key === "business.input.v1",
+      )!.schema,
+      outputSchemaKey: "business.output.v1",
+      allowedToolKeys: ["business.records.list"],
+      limits: module.aiOperations![0]!.limits,
+      selectable: true,
+      availabilityReason: "allowed",
+    });
+    expect(prepared).toHaveLength(0);
+    expect(remote.started).toHaveLength(0);
+  });
+
+  test("Catalog read capability cannot start an unauthorized operation", async () => {
+    const { catalog, context, facade } = await fixture();
+    context.actor.permissionKeys = ["system.agent-debug.read"];
+    const [operation] = await catalog.list(context);
+    expect(operation).toMatchObject({
+      selectable: false,
+      availabilityReason: "permission-denied",
+    });
+    await expect(
+      facade.start(
+        "business.answer",
+        { question: "测试" },
+        "catalog-no-grant",
+        context,
+      ),
+    ).rejects.toMatchObject({ code: "FORBIDDEN" });
+  });
+
+  test("Workflow-only operation and unavailable Runtime are unselectable", async () => {
+    const workflow = await fixture({ workflowOnly: true });
+    expect((await workflow.catalog.list(workflow.context))[0]).toMatchObject({
+      selectable: false,
+      availabilityReason: "workflow-only",
+      launchAuthority: "workflow-artifact",
+    });
+    const unavailable = await fixture({ runtimeAvailable: false });
+    expect(
+      (await unavailable.catalog.list(unavailable.context))[0],
+    ).toMatchObject({
+      selectable: false,
+      availabilityReason: "runtime-unavailable",
+    });
+  });
+
+  test("Declared readiness needs a current successful projection", async () => {
+    const { module, hosts, runtime, context } = await fixture();
+    module.aiOperations![0]!.readiness = {
+      contractVersion: 1,
+      variant: "test",
+      inputModalities: ["text"],
+      outputModalities: ["text"],
+      expectedDeployment: {
+        key: "test",
+        identity: "test",
+        releaseDigest: `sha256:${"a".repeat(64)}`,
+        offersDigest: `sha256:${"b".repeat(64)}`,
+      },
+      minConcurrentRuns: 1,
+      minQueueDepth: 1,
+    };
+    const input = {
+      modules: [module],
+      hosts,
+      runtime,
+      runtimeAvailable: () => true,
+    };
+    expect(
+      (await new AgentAdminOperationCatalog(input).list(context))[0],
+    ).toMatchObject({
+      selectable: false,
+      availabilityReason: "runtime-unavailable",
+    });
+    expect(
+      (
+        await new AgentAdminOperationCatalog({
+          ...input,
+          operationReadiness: async () => false,
+        }).list(context)
+      )[0],
+    ).toMatchObject({
+      selectable: false,
+      availabilityReason: "runtime-unavailable",
+    });
+    expect(
+      (
+        await new AgentAdminOperationCatalog({
+          ...input,
+          operationReadiness: async () => true,
+        }).list(context)
+      )[0],
+    ).toMatchObject({ selectable: true });
+  });
+
+  test("Unregistered handler, unsupported kind, invalid scope fail closed", async () => {
+    const { module, hosts, runtime, context } = await fixture();
+    const catalog = (current = module, currentHosts = hosts) =>
+      new AgentAdminOperationCatalog({
+        modules: [current],
+        hosts: currentHosts,
+        runtime,
+        runtimeAvailable: () => true,
+      });
+    expect(
+      (
+        await catalog(module, { ...hosts, aiOperationHandlers: [] }).list(
+          context,
+        )
+      )[0],
+    ).toMatchObject({
+      selectable: false,
+      availabilityReason: "handler-unavailable",
+    });
+    const speech = structuredClone(module);
+    speech.aiOperations![0]!.kind = "speech";
+    expect((await catalog(speech).list(context))[0]).toMatchObject({
+      selectable: false,
+      availabilityReason: "unsupported-operation",
+    });
+    delete context.actor.scopeContext;
+    expect((await catalog().list(context))[0]).toMatchObject({
+      selectable: false,
+      availabilityReason: "scope-unavailable",
+    });
+  });
+
+  test("Feature closure and missing registered output Schema fail closed", async () => {
+    const { module, hosts, runtime, context } = await fixture();
+    const missingSchema = structuredClone(module);
+    missingSchema.jsonSchemas = missingSchema.jsonSchemas!.filter(
+      ({ key }) => key !== "business.output.v1",
+    );
+    expect(
+      () =>
+        new AgentAdminOperationCatalog({
+          modules: [missingSchema],
+          hosts,
+          runtime,
+          runtimeAvailable: () => true,
+        }),
+    ).toThrow();
+    const disabledModule = structuredClone(module);
+    disabledModule.features = disabledModule.features.map((feature) => ({
+      ...feature,
+      enabled: false,
+    }));
+    const disabledRuntime = createServerRuntime(
+      {},
+      { featureCatalog: disabledModule.features },
+    );
+    const missing = new AgentAdminOperationCatalog({
+      modules: [disabledModule],
+      hosts,
+      runtime: disabledRuntime,
+      runtimeAvailable: () => true,
+    });
+    expect((await missing.list(context))[0]).toMatchObject({
+      selectable: false,
+      availabilityReason: "feature-unavailable",
+    });
+    context.license = { status: "expired", restricted: true };
+    context.licenseEnforced = true;
+    expect((await missing.list(context))[0]).toMatchObject({
+      selectable: false,
+      availabilityReason: "license-unavailable",
+    });
+  });
+});

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

@@ -0,0 +1,135 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type {
+  AgentAdminAvailabilityReason,
+  AgentAdminOperationCatalogItem,
+} from "@southwind-ai/shared";
+import { evaluateAccessGuards } from "../access-guards.js";
+import { isServerScopeContext } from "../data-access/context.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { InitializedModuleHosts } from "../module-host.js";
+import type { createServerRuntime } from "../runtime.js";
+import {
+  buildRegisteredOperations,
+  type RegisteredOperation,
+} from "./run-operation-registry.js";
+import { catalogGuardReason } from "./tool-catalog-availability.js";
+
+export interface AgentAdminOperationCatalogInput {
+  readonly modules: readonly ModuleManifest[];
+  readonly hosts: InitializedModuleHosts;
+  readonly runtime: ReturnType<typeof createServerRuntime>;
+  readonly runtimeAvailable: () => boolean;
+  /** Optional current readiness projection; no Provider execution or grants. */
+  readonly operationReadiness?: (
+    operationKey: string,
+    context: RequestGuardContext,
+  ) => Promise<boolean>;
+}
+
+export class AgentAdminOperationCatalog {
+  readonly #operations: ReadonlyMap<string, RegisteredOperation>;
+  readonly #schemas: ReadonlyMap<
+    string,
+    NonNullable<ModuleManifest["jsonSchemas"]>[number]["schema"]
+  >;
+
+  constructor(private readonly input: AgentAdminOperationCatalogInput) {
+    this.#operations = buildRegisteredOperations(input.modules, input.hosts);
+    this.#schemas = new Map(
+      input.modules.flatMap(({ jsonSchemas }) =>
+        (jsonSchemas ?? []).map(({ key, schema }) => [key, schema] as const),
+      ),
+    );
+  }
+
+  async list(
+    context: RequestGuardContext,
+  ): Promise<readonly AgentAdminOperationCatalogItem[]> {
+    return Promise.all(
+      [...this.#operations.values()].map(async (operation) => {
+        const definition = operation.definition;
+        const module = this.input.modules.find(({ aiOperations }) =>
+          aiOperations?.some(({ key }) => key === definition.key),
+        )!;
+        const inputSchema = this.#schemas.get(definition.inputSchemaKey);
+        const outputSchema = this.#schemas.get(definition.outputSchemaKey);
+        const availabilityReason = await this.availability(operation, context);
+        return {
+          key: definition.key,
+          module: module.name,
+          moduleLabel: module.label,
+          kind: definition.kind,
+          visibility: definition.visibility ?? "public",
+          execution: definition.execution,
+          featureKey: definition.featureKey,
+          permissionKey: definition.permissionKey,
+          auditAction: definition.auditAction,
+          dataClassification: definition.dataClassification,
+          requiredCapabilities: [...definition.requiredCapabilities],
+          inputModalities: [...(definition.inputModalities ?? ["text"])],
+          inputSchemaKey: definition.inputSchemaKey,
+          outputSchemaKey: definition.outputSchemaKey,
+          ...(inputSchema ? { inputSchema: structuredClone(inputSchema) } : {}),
+          ...(outputSchema
+            ? { outputSchema: structuredClone(outputSchema) }
+            : {}),
+          allowedToolKeys: [...definition.allowedToolKeys],
+          limits: { ...definition.limits },
+          launchAuthority:
+            definition.clientExecution?.launchAuthority ?? "direct",
+          selectable: availabilityReason === "allowed",
+          availabilityReason,
+        };
+      }),
+    );
+  }
+
+  private async availability(
+    operation: RegisteredOperation,
+    context: RequestGuardContext,
+  ): Promise<AgentAdminAvailabilityReason> {
+    const { definition } = operation;
+    if (!operation.feature) return "governance-unavailable";
+    const access = await evaluateAccessGuards(
+      this.input.runtime,
+      context,
+      {
+        feature: operation.feature,
+        permission: { permissionKey: definition.permissionKey },
+      },
+      { record: false },
+    );
+    if (!access.decision.allowed)
+      return catalogGuardReason(access.decision.reason);
+    if (definition.visibility === "internal") return "internal-operation";
+    if (definition.kind !== "agent") return "unsupported-operation";
+    if (definition.clientExecution?.launchAuthority === "workflow-artifact")
+      return "workflow-only";
+    if (!operation.registration?.prepare || !operation.moduleName)
+      return "handler-unavailable";
+    if (!isServerScopeContext(context.actor.scopeContext))
+      return "scope-unavailable";
+    if (
+      !this.#schemas.has(definition.inputSchemaKey) ||
+      !this.#schemas.has(definition.outputSchemaKey)
+    )
+      return "governance-unavailable";
+    if (
+      definition.providerEgress?.mode === "configured-endpoint" &&
+      !definition.providerDataPolicy
+    )
+      return "governance-unavailable";
+    if (definition.isolatedExecution || !this.input.runtimeAvailable())
+      return "runtime-unavailable";
+    if (definition.readiness) {
+      if (!this.input.operationReadiness) return "runtime-unavailable";
+      try {
+        if (!(await this.input.operationReadiness(definition.key, context)))
+          return "runtime-unavailable";
+      } catch {
+        return "runtime-unavailable";
+      }
+    }
+    return "allowed";
+  }
+}

package/template/apps/server/src/agent/run-browser-visibility.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, test } from "bun:test";
+import { AgentRunFacade } from "./run-facade.js";
+import { assertBrowserVisibleOperation } from "./run-browser-visibility.js";
+import {
+  createRunFacadeFixture,
+  runFacadeManifest,
+} from "./run-facade.test-support.js";
+import { createTestRunAuthorizationStore } from "./run-authorization.test-support.js";
+import { AgentAdminOperationCatalog } from "./operation-catalog.js";
+
+describe("Internal operations remain private to trusted orchestration", () => {
+  test("Public/default operations remain browser-visible", async () => {
+    const { facade } = await createRunFacadeFixture();
+    expect(facade.operationPolicy("business.answer")?.visibility).toBe(
+      "public",
+    );
+    expect(() =>
+      assertBrowserVisibleOperation(facade, "business.answer"),
+    ).not.toThrow();
+  });
+
+  test("Internal declaration blocks browser access and Admin selection without blocking governed server orchestration", async () => {
+    const { hosts, runtime, remote, context } = await createRunFacadeFixture();
+    const module = runFacadeManifest();
+    module.aiOperations![0]!.visibility = "internal";
+    const facade = new AgentRunFacade(
+      [module],
+      hosts,
+      runtime,
+      remote,
+      createTestRunAuthorizationStore(),
+    );
+    expect(() =>
+      assertBrowserVisibleOperation(facade, "business.answer"),
+    ).toThrow("Agent Run 不存在或不可访问");
+    const catalog = new AgentAdminOperationCatalog({
+      modules: [module],
+      hosts,
+      runtime,
+      runtimeAvailable: () => true,
+    });
+    expect((await catalog.list(context))[0]).toMatchObject({
+      visibility: "internal",
+      selectable: false,
+      availabilityReason: "internal-operation",
+    });
+    await facade.start(
+      "business.answer",
+      { question: "可信服务端编排" },
+      "server-orchestration",
+      context,
+    );
+    expect(remote.started).toHaveLength(1);
+    context.actor.permissionKeys = [];
+    await expect(
+      facade.start("business.answer", { question: "无权" }, "denied", context),
+    ).rejects.toMatchObject({ code: "FORBIDDEN" });
+  });
+});

package/template/apps/server/src/agent/run-browser-visibility.ts

@@ -0,0 +1,11 @@
+import type { AgentRunFacade } from "./run-facade.js";
+import { inaccessibleRun } from "./run-errors.js";
+
+export function assertBrowserVisibleOperation(
+  facade: AgentRunFacade,
+  operationKey: string,
+) {
+  if (facade.operationPolicy(operationKey)?.visibility === "internal") {
+    throw inaccessibleRun();
+  }
+}

package/template/apps/server/src/agent/run-operation-policy.ts

@@ -12,6 +12,7 @@ export function publicAgentOperationPolicy(
     allowedToolKeys: [...operation.definition.allowedToolKeys],
     featureKey: operation.definition.featureKey,
     permissionKey: operation.definition.permissionKey,
+    visibility: operation.definition.visibility ?? "public",
     deploymentKey:
       provider.mode === "configured-endpoint"
         ? provider.deploymentKey

package/template/apps/server/src/agent/run-route-response.ts

@@ -0,0 +1,35 @@
+import { AgentRunFacadeError } from "./run-errors.js";
+
+export function facadeError(error: unknown): Response {
+  if (error instanceof AgentRunFacadeError) {
+    return errorResponse(error.code, error.message, error.status);
+  }
+  return errorResponse(
+    "RUNTIME_UNAVAILABLE",
+    "Agent Runtime 暂不可用",
+    503,
+    true,
+  );
+}
+
+export function errorResponse(
+  code: string,
+  message: string,
+  status: number,
+  retryable = false,
+): Response {
+  return Response.json(
+    { code, message, requestId: crypto.randomUUID(), retryable },
+    { status },
+  );
+}
+
+export function required(value: string | undefined): string {
+  if (!value)
+    throw new AgentRunFacadeError("INVALID_INPUT", "Run ID 无效", 400);
+  return value;
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}