create-windy 0.8.2 → 0.8.3

package/template/packages/modules/src/system-admin-ui-catalog.ts

@@ -33,7 +33,13 @@ const definitions = [
   // @windy-module system.agent begin
   [
     "system.agent",
-    ["system.agent-session", "system.ai-runtime", "system.agent-workflow"],
+    [
+      "system.agent-tools",
+      "system.agent-debug",
+      "system.agent-session",
+      "system.ai-runtime",
+      "system.agent-workflow",
+    ],
   ],
   // @windy-module system.agent end
   // @windy-module system.operations begin

package/template/packages/modules/src/system-agent-admin-bindings.ts

@@ -0,0 +1,42 @@
+import type { ApiPermissionBinding } from "@southwind-ai/shared";
+import { binding } from "./system-api-binding.js";
+
+export function systemAgentAdminBindings(): ApiPermissionBinding[] {
+  return [
+    binding(
+      "GET",
+      "/api/agent/admin/tools",
+      "system.agent-tools.read",
+      "system.agent-tools",
+      "system.agent-tools.read",
+    ),
+    binding(
+      "GET",
+      "/api/agent/admin/operations",
+      "system.agent-debug.read",
+      "system.agent-debug",
+      "system.agent-debug.read",
+    ),
+    binding(
+      "GET",
+      "/api/agent/admin/session-recordings",
+      "system.agent-debug.read",
+      "system.agent-debug",
+      "agent.debug.recording.read",
+    ),
+    binding(
+      "GET",
+      "/api/agent/admin/session-recordings/:sessionId",
+      "system.agent-debug.read",
+      "system.agent-debug",
+      "agent.debug.recording.replay",
+    ),
+    binding(
+      "POST",
+      "/api/agent/admin/test-sessions",
+      "system.agent-debug.manage",
+      "system.agent-debug",
+      "agent.debug.session.create",
+    ),
+  ];
+}

package/template/packages/modules/src/system-agent-admin-menus.ts

@@ -0,0 +1,26 @@
+import type { ModuleManifest } from "./manifest.js";
+
+export const systemAgentAdminMenus: ModuleManifest["menus"] = [
+  {
+    key: "system.agent-tools",
+    title: "Agent 工具目录",
+    type: "menu",
+    order: 12,
+    visible: true,
+    path: "/admin/system/agent-tools",
+    icon: "wrench",
+    permissionKey: "system.agent-tools.read",
+    featureKey: "system.agent-tools",
+  },
+  {
+    key: "system.agent-debug",
+    title: "Agent 调试工作台",
+    type: "menu",
+    order: 13,
+    visible: true,
+    path: "/admin/system/agent-debug",
+    icon: "flask-conical",
+    permissionKey: "system.agent-debug.read",
+    featureKey: "system.agent-debug",
+  },
+];

package/template/packages/modules/src/system-agent-admin-registration.test.ts

@@ -0,0 +1,52 @@
+import { expect, test } from "bun:test";
+import { systemFoundationModule } from "./system-modules.js";
+import { systemModuleManifests } from "./system-module-catalog.js";
+
+// @windy-module system.agent begin
+test("Agent 工作台能力在菜单、路由、API、审计和模块分片一致注册", () => {
+  const manifest = systemFoundationModule();
+  const menus = manifest.menus.flatMap((menu) => menu.children ?? []);
+  for (const key of ["system.agent-tools", "system.agent-debug"]) {
+    expect(manifest.features.some((feature) => feature.key === key)).toBe(true);
+    expect(
+      manifest.permissions.some(
+        ({ key: permission }) => permission === `${key}.read`,
+      ),
+    ).toBe(true);
+    expect(menus.find((menu) => menu.key === key)).toMatchObject({
+      featureKey: key,
+      permissionKey: `${key}.read`,
+    });
+    expect(
+      manifest.adminRoutes.find((route) => route.key === key),
+    ).toMatchObject({ featureKey: key, permissionKey: `${key}.read` });
+  }
+  const bindings = manifest.apiPermissions.filter(({ path }) =>
+    path.startsWith("/api/agent/admin/"),
+  );
+  expect(bindings).toHaveLength(5);
+  const actions = manifest.auditActions.map((action) =>
+    typeof action === "string" ? action : action.key,
+  );
+  expect(
+    bindings.every(
+      ({ auditAction }) => auditAction && actions.includes(auditAction),
+    ),
+  ).toBe(true);
+  expect(bindings.find(({ method }) => method === "POST")).toMatchObject({
+    permissionKey: "system.agent-debug.manage",
+    featureKey: "system.agent-debug",
+  });
+  const agent = systemModuleManifests().find(
+    ({ name }) => name === "system.agent",
+  )!;
+  expect(
+    agent.apiPermissions.filter(({ path }) =>
+      path.startsWith("/api/agent/admin/"),
+    ),
+  ).toHaveLength(5);
+  expect(agent.features.map(({ key }) => key)).toEqual(
+    expect.arrayContaining(["system.agent-tools", "system.agent-debug"]),
+  );
+});
+// @windy-module system.agent end

package/template/packages/modules/src/system-agent-audit-actions.ts

@@ -1,4 +1,9 @@
 export const agentAuditActionKeys: ReadonlySet<string> = new Set([
+  "system.agent-tools.read",
+  "system.agent-debug.read",
+  "agent.debug.recording.read",
+  "agent.debug.recording.replay",
+  "agent.debug.session.create",
   "agent.session.read",
   "agent.session.create",
   "agent.session.checkpoint",

package/template/packages/modules/src/system-ai-api-bindings.ts

@@ -2,6 +2,7 @@ import type { ApiPermissionBinding } from "@southwind-ai/shared";
 import { binding } from "./system-api-binding.js";
 
 // @windy-module system.agent begin
+import { systemAgentAdminBindings } from "./system-agent-admin-bindings.js";
 export function systemAiControlPlaneBindings(): ApiPermissionBinding[] {
   const reports = (
     [
@@ -67,6 +68,7 @@ export function systemAiControlPlaneBindings(): ApiPermissionBinding[] {
     ),
   );
   return [
+    ...systemAgentAdminBindings(),
     ...reports,
     ...read,
     ...execute,

package/template/packages/modules/src/system-audit-actions.ts

@@ -83,6 +83,31 @@ export const systemAuditActions: ModuleManifest["auditActions"] = [
   "file.download",
   // @windy-module system.storage end
   // @windy-module system.agent begin
+  {
+    key: "system.agent-tools.read",
+    label: "查看 Agent 工具目录",
+    description: "按当前授权访问 Agent 工作台受控投影。",
+  },
+  {
+    key: "system.agent-debug.read",
+    label: "查看 Agent 调试 Operation",
+    description: "按当前授权访问 Agent 工作台受控投影。",
+  },
+  {
+    key: "agent.debug.recording.read",
+    label: "查询 Agent 回放会话",
+    description: "按当前授权访问 Agent 工作台受控投影。",
+  },
+  {
+    key: "agent.debug.recording.replay",
+    label: "回放 Agent 会话记录",
+    description: "按当前授权访问 Agent 工作台受控投影。",
+  },
+  {
+    key: "agent.debug.session.create",
+    label: "创建 Agent 测试会话",
+    description: "按当前授权访问 Agent 工作台受控投影。",
+  },
   "agent.mcp.access",
   "agent.tool.execute",
   "agent.operation.execute",

package/template/packages/modules/src/system-features.ts

@@ -129,6 +129,25 @@ export const systemFeatures: ModuleManifest["features"] = [
     dependencies: [shared.featureKey("system.agent")],
     allowedLicenseVersions: [shared.licenseVersionKey("advanced")],
   },
+  {
+    ...feature(
+      "system.agent-tools",
+      "Agent 工具目录",
+      "查看已安装模块工具的契约、治理规则和当前调用条件。",
+    ),
+    dependencies: [shared.featureKey("system.agent")],
+  },
+  {
+    ...feature(
+      "system.agent-debug",
+      "Agent 调试工作台",
+      "创建受治理的测试会话，回放授权业务会话并定位实际调用流程。",
+    ),
+    dependencies: [
+      shared.featureKey("system.agent"),
+      shared.featureKey("system.agent-session"),
+    ],
+  },
   // @windy-module system.agent end
   // @windy-module system.operations begin
   feature(

package/template/packages/modules/src/system-module-catalog.ts

@@ -1,4 +1,8 @@
 import type { ModuleFactory, ModuleManifest } from "./manifest.js";
+import {
+  auditActionKey,
+  permissionResource,
+} from "./system-module-ownership.js";
 import { selectSystemMenus } from "./system-module-menu-selection.js";
 import { systemFoundationModule } from "./system-modules.js";
 import { selectSystemJsonSchemas } from "./system-module-schema-catalog.js";
@@ -138,9 +142,18 @@ export const systemModuleDefinitions = [
       "system.scheduler",
       "system.workflow",
     ],
-    resources: ["agent", "agent-session", "agent-workflow", "ai-runtime"],
+    resources: [
+      "agent",
+      "agent-tools",
+      "agent-debug",
+      "agent-session",
+      "agent-workflow",
+      "ai-runtime",
+    ],
     featureKeys: [
       "system.agent",
+      "system.agent-tools",
+      "system.agent-debug",
       "system.agent-session",
       "system.agent-workflow",
       "system.ai-runtime",
@@ -334,14 +347,3 @@ function createSystemCapabilityModule(
     },
   };
 }
-
-function auditActionKey(
-  action: ModuleManifest["auditActions"][number],
-): string {
-  return typeof action === "string" ? action : action.key;
-}
-
-function permissionResource(permissionKey: string): string {
-  const parts = permissionKey.split(".");
-  return parts.length >= 3 ? parts.slice(1, -1).join(".") : "";
-}

package/template/packages/modules/src/system-module-ownership.ts

@@ -0,0 +1,12 @@
+import type { ModuleManifest } from "./manifest.js";
+
+export function auditActionKey(
+  action: ModuleManifest["auditActions"][number],
+): string {
+  return typeof action === "string" ? action : action.key;
+}
+
+export function permissionResource(permissionKey: string): string {
+  const parts = permissionKey.split(".");
+  return parts.length >= 3 ? parts.slice(1, -1).join(".") : "";
+}

package/template/packages/modules/src/system-modules.ts

@@ -4,6 +4,7 @@ import {
   systemAgentToolSchemas,
   systemAgentTools,
 } from "./system-agent-tools.js";
+import { systemAgentAdminMenus } from "./system-agent-admin-menus.js";
 import { systemAgentSupervisorSchemas } from "./system-agent-supervisor.js";
 // @windy-module system.agent end
 import { systemAdminRoutes } from "./system-admin-routes.js";
@@ -241,6 +242,7 @@ export function systemFoundationModule(): ModuleManifest {
           },
           // @windy-module system.operations end
           // @windy-module system.agent begin
+          ...systemAgentAdminMenus,
           {
             key: "system.agent-session",
             title: "Agent 会话",

package/template/packages/modules/src/system-permissions.ts

@@ -22,6 +22,8 @@ const systemResourceLabels = {
   // @windy-module system.agent begin
   agent: "智能代理",
   "agent-session": "Agent 长期会话",
+  "agent-tools": "Agent 工具目录",
+  "agent-debug": "Agent 调试工作台",
   "agent-workflow": "Agent Workflow",
   "ai-runtime": "AI Runtime 报表",
   // @windy-module system.agent end
@@ -129,6 +131,9 @@ export const systemPermissions: ModuleManifest["permissions"] = [
   // @windy-module system.audit end
   // @windy-module system.agent begin
   permission("agent", "read"),
+  permission("agent-tools", "read"),
+  permission("agent-debug", "read"),
+  permission("agent-debug", "manage"),
   permission("agent-session", "read"),
   permission("agent-session", "manage"),
   permission("agent-workflow", "read", "sensitive-disclosure"),

package/template/packages/server-sdk/index.ts

@@ -78,6 +78,8 @@ export type {
   ModuleAgentSessionGetInputV1,
   ModuleAgentSessionListInputV1,
   ModuleAgentSessionMessageV1,
+  ModuleAgentSessionRunReferenceV1,
+  ModuleAgentSessionWorkflowReferenceV1,
   ModuleAgentSessionPageV1,
   ModuleAgentSessionProviderV1,
   ModuleAgentSessionSummaryV1,

package/template/packages/server-sdk/src/agent-session-provider.ts

@@ -43,6 +43,25 @@ export interface ModuleAgentSessionMessageV1 {
 
 export interface ModuleAgentSessionV1 extends ModuleAgentSessionSummaryV1 {
   readonly messages: readonly ModuleAgentSessionMessageV1[];
+  /** Provider 返回了有界历史窗口；不得把该窗口当作完整会话。 */
+  readonly truncated?: boolean;
+  /** 当前 get() 已按业务来源重授权的关联事实；Host 仍逐 Run/Workflow 重授权。 */
+  readonly runRefs?: readonly ModuleAgentSessionRunReferenceV1[];
+  readonly workflowRefs?: readonly ModuleAgentSessionWorkflowReferenceV1[];
+}
+
+export interface ModuleAgentSessionRunReferenceV1 {
+  readonly runId: string;
+  readonly operationKey: string;
+  readonly messageSequence?: number;
+  readonly sessionId?: string;
+  readonly turnId?: string;
+  readonly workflowRunId?: string;
+}
+
+export interface ModuleAgentSessionWorkflowReferenceV1 {
+  readonly workflowRunId: string;
+  readonly messageSequence?: number;
 }
 
 /**

package/template/packages/shared/index.ts

@@ -2,6 +2,8 @@ export * from "./src/audit.js";
 export * from "./src/ai-operation-readiness.js";
 // @windy-module system.agent begin
 export * from "./src/ai-runtime-report.js";
+export * from "./src/agent-admin-catalog.js";
+export * from "./src/agent-workbench.js";
 export * from "./src/agent-workflow.js";
 export * from "./src/agent-workflow-events.js";
 export * from "./src/agent-workflow-evaluation.js";

package/template/packages/shared/src/agent-admin-catalog.ts

@@ -0,0 +1,73 @@
+import type { JsonObject } from "./json.js";
+import type { CandidateRole } from "./workflow.js";
+
+/** Public, bounded categories; never include raw Guard events or Provider bodies. */
+export type AgentAdminAvailabilityReason =
+  | "allowed"
+  | "permission-denied"
+  | "feature-unavailable"
+  | "license-unavailable"
+  | "scope-unavailable"
+  | "runtime-unavailable"
+  | "workflow-only"
+  | "internal-operation"
+  | "unsupported-operation"
+  | "handler-unavailable"
+  | "governance-unavailable";
+
+export interface AgentAdminToolCatalogItem {
+  readonly key: string;
+  readonly label: string;
+  readonly description: string;
+  readonly module: string;
+  readonly operation: "query" | "command" | "background";
+  readonly featureKey: string;
+  readonly permissionKey: string;
+  readonly auditAction: string;
+  readonly scopeMode: "platform" | "request";
+  readonly executionMode: "host" | "sandbox";
+  readonly dataClassification: "public" | "internal" | "sensitive";
+  readonly approval: "none" | "required";
+  readonly approvalRoles?: readonly CandidateRole[];
+  readonly approvalTimeoutSeconds?: number;
+  readonly idempotency: "none" | "supported" | "required";
+  readonly limits: AgentAdminCatalogLimits;
+  readonly inputSchemaKey: string;
+  readonly outputSchemaKey: string;
+  readonly inputSchema: JsonObject;
+  readonly outputSchema: JsonObject;
+  readonly allowedOperationKeys: readonly string[];
+  /** Current Guard + Scope eligibility, not an execution or approval grant. */
+  readonly allowed: boolean;
+  readonly availabilityReason: AgentAdminAvailabilityReason;
+}
+
+export interface AgentAdminCatalogLimits {
+  readonly maxDurationSeconds: number;
+  readonly maxInputBytes: number;
+  readonly maxOutputBytes: number;
+}
+
+export interface AgentAdminOperationCatalogItem {
+  readonly key: string;
+  readonly module: string;
+  readonly moduleLabel: string;
+  readonly kind: string;
+  readonly visibility: "public" | "internal";
+  readonly execution: string;
+  readonly featureKey: string;
+  readonly permissionKey: string;
+  readonly auditAction: string;
+  readonly dataClassification: "public" | "internal" | "sensitive";
+  readonly requiredCapabilities: readonly string[];
+  readonly inputModalities: readonly string[];
+  readonly inputSchemaKey: string;
+  readonly outputSchemaKey: string;
+  readonly inputSchema?: JsonObject;
+  readonly outputSchema?: JsonObject;
+  readonly allowedToolKeys: readonly string[];
+  readonly limits: AgentAdminCatalogLimits;
+  readonly launchAuthority: "direct" | "workflow-artifact";
+  readonly selectable: boolean;
+  readonly availabilityReason: AgentAdminAvailabilityReason;
+}

package/template/packages/shared/src/agent-workbench.ts

@@ -0,0 +1,100 @@
+import type { JsonValue } from "./json.js";
+
+export type AgentWorkbenchRecordingSourceV1 = "harness" | "business";
+export type AgentWorkbenchCorrelationStatusV1 =
+  | "complete"
+  | "partial"
+  | "missing";
+
+export interface AgentWorkbenchEventV1 {
+  readonly sequence: number;
+  readonly type: string;
+  readonly summary: string;
+  readonly occurredAt?: string;
+  readonly runId?: string;
+  readonly turnId?: string;
+  readonly stepId?: string;
+  readonly modelAttemptId?: string;
+  readonly attemptSequence?: number;
+  readonly toolCallId?: string;
+  readonly toolKey?: string;
+  readonly workItemId?: string;
+  readonly artifactId?: string;
+  readonly workflowRunId?: string;
+  readonly nodeRunId?: string;
+  readonly outcome?: string;
+  readonly usage?: {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly totalTokens?: number;
+    readonly costMicros?: number;
+  };
+}
+
+export interface AgentWorkbenchRunV1 {
+  readonly runId: string;
+  readonly operationKey: string;
+  readonly sessionId?: string;
+  readonly turnId?: string;
+  readonly messageSequence?: number;
+  readonly status: string;
+  readonly events: readonly AgentWorkbenchEventV1[];
+  readonly result?: { readonly output?: JsonValue; readonly status?: string };
+  readonly correlationStatus: AgentWorkbenchCorrelationStatusV1;
+  readonly missing: readonly string[];
+}
+
+export interface AgentWorkbenchWorkflowV1 {
+  readonly workflowRunId: string;
+  readonly sessionId?: string;
+  readonly messageSequence?: number;
+  readonly workflowKey: string;
+  readonly title: string;
+  readonly status: string;
+  readonly parentRunId?: string;
+  readonly parentNodeRunId?: string;
+  readonly nodes: readonly {
+    readonly nodeRunId: string;
+    readonly nodeId: string;
+    readonly type: string;
+    readonly status: string;
+    readonly attempt: number;
+    readonly previousNodeRunId?: string;
+    readonly agentRunId?: string;
+    readonly workItemId?: string;
+    readonly selectedBranch?: string;
+    readonly artifactIds: readonly string[];
+  }[];
+  readonly events: readonly AgentWorkbenchEventV1[];
+}
+
+export interface AgentWorkbenchRecordingSummaryV1 {
+  readonly source: AgentWorkbenchRecordingSourceV1;
+  readonly sessionId: string;
+  readonly title: string;
+  readonly updatedAt: string;
+  readonly operationKey?: string;
+  readonly sessionStatus?: "active" | "archived";
+}
+
+export interface AgentWorkbenchRecordingV1 extends AgentWorkbenchRecordingSummaryV1 {
+  readonly mode: "read-only";
+  readonly sideEffectPolicy: "no-reexecution";
+  readonly correlationStatus: AgentWorkbenchCorrelationStatusV1;
+  readonly messages: readonly {
+    readonly sequence: number;
+    readonly role: "user" | "assistant";
+    readonly content: string;
+    readonly createdAt: string;
+  }[];
+  readonly timeline: readonly AgentWorkbenchEventV1[];
+  /** Parent forks retain separate original ledger sequences, never renumbered. */
+  readonly segments?: readonly {
+    readonly sessionId: string;
+    readonly throughSequence: number;
+    readonly timeline: readonly AgentWorkbenchEventV1[];
+  }[];
+  readonly runs: readonly AgentWorkbenchRunV1[];
+  readonly workflows: readonly AgentWorkbenchWorkflowV1[];
+  readonly missing: readonly string[];
+}