create-windy 0.8.1 → 0.8.3

package/template/apps/server/src/agent/session-recording-reader.contract.test.ts

@@ -0,0 +1,131 @@
+import { expect, test } from "bun:test";
+import { SessionEventLogService } from "./session-log/service.js";
+import { InMemorySessionEventRepository } from "./session-log/in-memory-repository.js";
+import { projectSessionRecording } from "./session-recording-reader.js";
+
+test("fork replay reuses AH1 recorded-only segments and original parent/child sequences", async () => {
+  const repository = new InMemorySessionEventRepository();
+  const service = new SessionEventLogService(repository);
+  const governance = {
+    actorId: "actor-1",
+    scopeDigest: `sha256:${"a".repeat(64)}` as const,
+  };
+  await service.create({
+    sessionId: "session_parent",
+    createdEventId: "session_event_parent",
+    governance,
+  });
+  await service.append({
+    sessionId: "session_parent",
+    expectedSequence: 1,
+    events: [
+      service.newEvent({
+        type: "turn.started",
+        turnId: "session_turn_parent",
+        cause: "user-input",
+        input: {
+          sourceType: "agent-run-input",
+          sourceId: "binding_1",
+          sourceVersion: "business.answer",
+          contentDigest: `sha256:${"b".repeat(64)}`,
+        },
+      }),
+      service.newEvent({
+        type: "run.linked",
+        turnId: "session_turn_parent",
+        runId: "run_parent",
+      }),
+      service.newEvent({
+        type: "turn.completed",
+        turnId: "session_turn_parent",
+        outcome: "completed",
+      }),
+    ],
+  });
+  await service.checkpoint({
+    sessionId: "session_parent",
+    expectedSequence: 4,
+    checkpointId: "session_checkpoint_parent",
+    eventId: "session_event_checkpoint",
+  });
+  await service.fork({
+    parentSessionId: "session_parent",
+    expectedParentSequence: 5,
+    checkpointId: "session_checkpoint_parent",
+    childSessionId: "session_child",
+    parentEventId: "session_event_fork",
+    childCreatedEventId: "session_event_child",
+    governance,
+  });
+  await service.append({
+    sessionId: "session_child",
+    expectedSequence: 1,
+    events: [
+      service.newEvent({
+        type: "turn.started",
+        turnId: "session_turn_child",
+        cause: "user-input",
+        input: {
+          sourceType: "agent-run-input",
+          sourceId: "binding_2",
+          sourceVersion: "business.answer",
+          contentDigest: `sha256:${"c".repeat(64)}`,
+        },
+      }),
+      service.newEvent({
+        type: "run.linked",
+        turnId: "session_turn_child",
+        runId: "run_child",
+      }),
+      service.newEvent({
+        type: "turn.completed",
+        turnId: "session_turn_child",
+        outcome: "completed",
+      }),
+    ],
+  });
+  const replay = await service.replay({ sessionId: "session_child" });
+  const projected = projectSessionRecording({
+    ...replay,
+    segments: await Promise.all(
+      replay.segments.map(async (segment) => ({
+        ...segment,
+        session: (await repository.get(segment.sessionId))!,
+      })),
+    ),
+  });
+  expect(replay.sideEffectPolicy).toBe("recorded-only");
+  expect(projected.segments.map(({ sessionId }) => sessionId)).toEqual([
+    "session_parent",
+    "session_child",
+  ]);
+  expect(
+    projected.segments.map(({ timeline }) =>
+      timeline.map(({ sequence }) => sequence),
+    ),
+  ).toEqual([
+    [1, 2, 3, 4],
+    [1, 2, 3, 4],
+  ]);
+  expect(
+    projected.runRefs.map(({ runId, sessionId, operationKey }) => ({
+      runId,
+      sessionId,
+      operationKey,
+    })),
+  ).toEqual([
+    {
+      runId: "run_parent",
+      sessionId: "session_parent",
+      operationKey: "business.answer",
+    },
+    {
+      runId: "run_child",
+      sessionId: "session_child",
+      operationKey: "business.answer",
+    },
+  ]);
+  expect(projected.truncated).toBe(false);
+  expect((await repository.get("session_parent"))?.headSequence).toBe(6);
+  expect((await repository.get("session_child"))?.headSequence).toBe(4);
+});

package/template/apps/server/src/agent/session-recording-reader.ts

@@ -0,0 +1,62 @@
+import type { SessionRecord } from "./session-log/domain.js";
+import type { ReadOnlySessionReplay } from "./session-log/replay-policy.js";
+import {
+  projectAgentSession,
+  projectAgentSessionTimelineEvent,
+} from "./session-projection-view.js";
+
+/** Already-authorized replay segments preserve parent/child sequence domains. */
+export function projectSessionRecording(
+  replay: Omit<ReadOnlySessionReplay, "segments"> & {
+    segments: readonly {
+      sessionId: string;
+      throughSequence: number;
+      events: ReadOnlySessionReplay["segments"][number]["events"];
+      session: SessionRecord;
+    }[];
+  },
+) {
+  const current = replay.segments.find(
+    ({ sessionId }) => sessionId === replay.sessionId,
+  );
+  if (!current) throw new Error("Current replay segment missing");
+  const segments = replay.segments.map((segment) => ({
+    ...segment,
+    events: segment.events.slice(0, 10_000),
+  }));
+  const runRefs = segments.flatMap(({ sessionId, events }) => {
+    const operations = new Map(
+      events.flatMap(({ data }) =>
+        data.type === "turn.started" &&
+        data.input.sourceType === "agent-run-input"
+          ? [[data.turnId, data.input.sourceVersion] as const]
+          : [],
+      ),
+    );
+    return events.flatMap(({ data }) =>
+      data.type === "run.linked"
+        ? [
+            {
+              runId: data.runId,
+              sessionId,
+              turnId: data.turnId,
+              operationKey: operations.get(data.turnId) ?? "",
+            },
+          ]
+        : [],
+    );
+  });
+  return {
+    session: projectAgentSession(current.session),
+    truncated: replay.segments.some(({ events }) => events.length > 10_000),
+    segments: segments.map(({ sessionId, throughSequence, events }) => ({
+      sessionId,
+      throughSequence,
+      timeline: events.map(projectAgentSessionTimelineEvent),
+    })),
+    timeline: segments
+      .find(({ sessionId }) => sessionId === replay.sessionId)!
+      .events.map(projectAgentSessionTimelineEvent),
+    runRefs,
+  };
+}

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

@@ -0,0 +1,22 @@
+import { randomUUIDv7 } from "bun";
+import { auditActor, type RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+
+export function auditAgentAdminCatalogRead(
+  runtime: ReturnType<typeof createServerRuntime>,
+  context: RequestGuardContext,
+  kind: "tools" | "operations",
+  itemCount: number,
+): void {
+  runtime.auditSink.recordEvent({
+    id: randomUUIDv7(),
+    action:
+      kind === "tools" ? "system.agent-tools.read" : "system.agent-debug.read",
+    actor: auditActor(context),
+    outcome: "success",
+    target: { type: "agent-admin-catalog", id: kind },
+    requestId: context.requestId,
+    metadata: { itemCount },
+    occurredAt: new Date().toISOString(),
+  });
+}

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

@@ -0,0 +1,21 @@
+import type { AgentAdminAvailabilityReason } from "@southwind-ai/shared";
+import type { GuardDecisionReason } from "../guards.js";
+
+export function catalogGuardReason(
+  reason: GuardDecisionReason,
+): AgentAdminAvailabilityReason {
+  switch (reason) {
+    case "allowed":
+    case "anonymous":
+      return "allowed";
+    case "feature-disabled":
+    case "dependency-missing":
+      return "feature-unavailable";
+    case "license-restricted":
+    case "license-version-not-allowed":
+    case "entitlement-not-granted":
+      return "license-unavailable";
+    default:
+      return "permission-denied";
+  }
+}

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