create-windy 0.8.0 → 0.8.2

package/template/apps/server/src/agent/isolated-execution-guard.ts

@@ -0,0 +1,202 @@
+import type {
+  AiIsolatedExecutionPolicyV1,
+  ModuleManifest,
+} from "@southwind-ai/modules";
+import { evaluateAccessGuards } from "../access-guards.js";
+import type { RequestActor } from "../guards.js";
+import { findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { InitializedModuleHosts } from "../module-host.js";
+import type { AgentRunAuthorizationStore } from "./run-authorization.js";
+import { buildAgentRuntimeRelease } from "./run-release.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+/** Must reserve atomically and durably by Run and call ID; absent storage denies admission. */
+export interface IsolatedExecutionBudgetPort {
+  reserve(input: {
+    readonly runId: string;
+    readonly callId: string;
+    readonly maxToolCalls: number;
+    readonly maxToolRounds: number;
+    readonly maxConcurrentProcesses: number;
+  }): Promise<boolean>;
+}
+
+export interface IsolatedExecutionRunStatePort {
+  status(runId: string): Promise<"accepted" | "running" | "terminal">;
+}
+
+export class IsolatedExecutionAdmissionError extends Error {
+  constructor(
+    readonly code:
+      | "EXECUTION_DENIED"
+      | "BUDGET_EXCEEDED"
+      | "RUNTIME_UNAVAILABLE",
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** Revalidates the authoritative Run and current governance facts for every process call. */
+export class IsolatedExecutionGuard {
+  readonly #operations: Map<
+    string,
+    {
+      definition: NonNullable<ModuleManifest["aiOperations"]>[number];
+      releaseId: string;
+    }
+  >;
+  readonly #features: ModuleManifest["features"];
+
+  constructor(
+    modules: readonly ModuleManifest[],
+    hosts: InitializedModuleHosts,
+    private readonly runtime: ServerRuntime,
+    private readonly authorizations: AgentRunAuthorizationStore,
+    private readonly resolveActor: (
+      actorId: string,
+    ) => Promise<RequestActor | undefined>,
+    private readonly state?: IsolatedExecutionRunStatePort,
+    private readonly budget?: IsolatedExecutionBudgetPort,
+    private readonly executionRuntimeAvailable = false,
+  ) {
+    this.#features = modules.flatMap((module) => module.features);
+    const handlers = new Map(
+      hosts.aiOperationHandlers.map(({ registration }) => [
+        registration.operationKey,
+        registration,
+      ]),
+    );
+    this.#operations = new Map(
+      modules.flatMap((module) =>
+        (module.aiOperations ?? [])
+          .filter((definition) => definition.kind === "agent")
+          .map(
+            (definition) =>
+              [
+                definition.key,
+                {
+                  definition,
+                  releaseId: buildAgentRuntimeRelease(
+                    modules,
+                    module,
+                    definition,
+                    handlers.get(definition.key),
+                  ).releaseId,
+                },
+              ] as const,
+          ),
+      ),
+    );
+  }
+
+  async admit(input: {
+    readonly executionGrant: string;
+    readonly runId: string;
+    readonly callId: string;
+    readonly language: "python" | "node";
+  }): Promise<AiIsolatedExecutionPolicyV1> {
+    if (!input.callId || !input.runId) throw denied("执行调用坐标缺失");
+    let binding;
+    try {
+      binding = await this.authorizations.authorizeTool(
+        input.executionGrant,
+        input.runId,
+      );
+    } catch {
+      throw denied("Agent Run 执行授权无效");
+    }
+    const current = this.#operations.get(binding.operationKey);
+    const policy = current?.definition.isolatedExecution;
+    if (
+      !current ||
+      !policy ||
+      current.releaseId !== binding.releaseId ||
+      !policy.languages.includes(input.language) ||
+      binding.authorizationSnapshot.toolNetworkMode !== "forbidden" ||
+      binding.authorizationSnapshot.delegation !== undefined ||
+      binding.authorizationSnapshot.runtimeBudgetDigest !== undefined ||
+      current.definition.featureKey !==
+        binding.authorizationSnapshot.featureKey ||
+      current.definition.permissionKey !==
+        binding.authorizationSnapshot.permissionKey
+    ) {
+      throw denied("Operation 未授权隔离执行或版本已变化");
+    }
+    let actor: RequestActor | undefined;
+    try {
+      actor = await this.resolveActor(binding.actorId);
+    } catch {
+      throw denied("Agent Run Actor 当前不可用");
+    }
+    if (!actor || actor.id !== binding.actorId || actor.type === "anonymous") {
+      throw denied("Agent Run Actor 当前不可用");
+    }
+    let context: Awaited<
+      ReturnType<ServerRuntime["createGuardContextForActor"]>
+    >;
+    try {
+      context = await this.runtime.createGuardContextForActor(
+        new Request("http://agent-execution.internal"),
+        actor,
+      );
+    } catch {
+      throw denied("Agent Run 当前授权无法复核");
+    }
+    try {
+      this.authorizations.assertCurrentScope(binding, context);
+    } catch {
+      throw denied("Agent Run 当前数据范围已变化");
+    }
+    let access: Awaited<ReturnType<typeof evaluateAccessGuards>>;
+    try {
+      access = await evaluateAccessGuards(this.runtime, context, {
+        permission: { permissionKey: current.definition.permissionKey },
+        feature: findFeature(this.#features, current.definition.featureKey),
+      });
+    } catch {
+      throw denied("Agent Operation 当前授权无法复核");
+    }
+    if (!access.decision.allowed) throw denied("Agent Operation 当前无权执行");
+    if (!this.executionRuntimeAvailable || !this.state || !this.budget) {
+      throw new IsolatedExecutionAdmissionError(
+        "RUNTIME_UNAVAILABLE",
+        "隔离执行 Runtime 或预算存储未装配",
+      );
+    }
+    let status: "accepted" | "running" | "terminal";
+    try {
+      status = await this.state.status(input.runId);
+    } catch {
+      throw denied("Agent Run 状态无法复核");
+    }
+    if (status !== "running") throw denied("Agent Run 当前不可执行");
+    let reserved: boolean;
+    try {
+      reserved = await this.budget.reserve({
+        runId: input.runId,
+        callId: input.callId,
+        maxToolCalls: policy.limits.maxToolCalls,
+        maxToolRounds: policy.limits.maxToolRounds,
+        maxConcurrentProcesses: policy.limits.maxConcurrentProcesses,
+      });
+    } catch {
+      throw new IsolatedExecutionAdmissionError(
+        "RUNTIME_UNAVAILABLE",
+        "执行预算无法原子预留",
+      );
+    }
+    if (!reserved)
+      throw new IsolatedExecutionAdmissionError(
+        "BUDGET_EXCEEDED",
+        "隔离执行预算已耗尽",
+      );
+    return policy;
+  }
+}
+
+function denied(message: string): IsolatedExecutionAdmissionError {
+  return new IsolatedExecutionAdmissionError("EXECUTION_DENIED", message);
+}

package/template/apps/server/src/agent/run-definition-support.ts

@@ -1,6 +1,6 @@
 import type { ModuleManifest } from "@southwind-ai/modules";
 import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
-import type { AgentRuntimeError } from "./run-contracts.js";
+import { AgentRuntimeError } from "./run-contracts.js";
 import { AgentRunFacadeError } from "./run-errors.js";
 
 export function toolDefinitions(
@@ -56,3 +56,13 @@ export function publicRunPath(
 ) {
   return `/api/agent/runs/${encodeURIComponent(runId)}/${resource}?operationKey=${encodeURIComponent(operationKey)}`;
 }
+
+export function mapAgentRuntimeError(error: unknown) {
+  return error instanceof AgentRuntimeError
+    ? new AgentRunFacadeError(
+        error.code,
+        error.message,
+        runtimeErrorStatus(error.code),
+      )
+    : error;
+}

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

@@ -17,7 +17,6 @@ import type {
   AgentRuntimePort,
   AgentRuntimeStartResponse,
 } from "./run-contracts.js";
-import { AgentRuntimeError } from "./run-contracts.js";
 import {
   rotateVisionArtifacts,
   validateVisionArtifacts,
@@ -33,7 +32,7 @@ import { attachAgentRun } from "./run-attach.js";
 import {
   digest,
   publicRunPath,
-  runtimeErrorStatus,
+  mapAgentRuntimeError,
 } from "./run-definition-support.js";
 import { AgentRunFacadeError } from "./run-errors.js";
 import { scopedRuntimeIdempotencyKey } from "./idempotency-key.js";
@@ -63,7 +62,10 @@ import {
   resolveAgentRunExecutionPolicy,
   type AgentRunDelegationPolicy,
 } from "./agent-run-delegation-policy.js";
-import { publicAgentOperationPolicy } from "./run-operation-policy.js";
+import {
+  assertAgentRuntimeAssembled,
+  publicAgentOperationPolicy,
+} from "./run-operation-policy.js";
 export { AgentRunFacadeError } from "./run-errors.js";
 type ServerRuntime = ReturnType<typeof createServerRuntime>;
 export class AgentRunFacade {
@@ -124,6 +126,7 @@ export class AgentRunFacade {
         ? { sessionBinding: this.#sessionBindingAuthorization }
         : {}),
     });
+    assertAgentRuntimeAssembled(operation);
     const executionPolicy = resolveAgentRunExecutionPolicy(
       operation,
       context,
@@ -265,14 +268,7 @@ export class AgentRunFacade {
         sessionTurn,
         sessionLinked,
       });
-      if (error instanceof AgentRuntimeError) {
-        throw new AgentRunFacadeError(
-          error.code,
-          error.message,
-          runtimeErrorStatus(error.code),
-        );
-      }
-      throw error;
+      throw mapAgentRuntimeError(error);
     }
   }
   async authorizeRun(

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

@@ -1,3 +1,4 @@
+import { AgentRunFacadeError } from "./run-errors.js";
 import { resolveProviderEgress } from "@southwind-ai/modules";
 import type { RegisteredOperation } from "./run-operation-registry.js";
 
@@ -18,3 +19,13 @@ export function publicAgentOperationPolicy(
     release: structuredClone(operation.release),
   };
 }
+
+export function assertAgentRuntimeAssembled(operation: RegisteredOperation) {
+  if (operation.definition.isolatedExecution) {
+    throw new AgentRunFacadeError(
+      "RUNTIME_UNAVAILABLE",
+      "隔离执行 Runtime 尚未装配",
+      503,
+    );
+  }
+}

package/template/apps/server/src/agent/workflow-durable-runtime-input.ts

@@ -1,3 +1,4 @@
+import type { StructuredLogger } from "@southwind-ai/shared";
 import type { DurableHandlerRegistry } from "@southwind-ai/jobs";
 import { DurableArtifactService } from "../jobs/artifact-service.js";
 import type { DurableJobService } from "../jobs/service.js";
@@ -14,18 +15,20 @@ export function workflowDurableInput([durable, storage, logger]: readonly [
   {
     readonly blobStore: ConstructorParameters<typeof DurableArtifactService>[1];
   },
-  {
-    error(fields: Record<string, unknown>, message: string): void;
-  },
+  Pick<StructuredLogger, "error">,
 ]) {
   return {
     jobs: durable.service,
     jobWorker: durable.worker,
     jobRegistry: durable.registry,
     jobArtifacts: new DurableArtifactService(durable.facts, storage.blobStore),
-    onWorkflowContinuationError: (error: unknown) =>
+    onWorkflowContinuationError: (_error: unknown) =>
       logger.error(
-        { event: "agent.workflow.continuation.failed", error },
+        {
+          event: "agent.workflow.continuation.failed",
+          outcome: "failure",
+          errorCode: "AGENT_WORKFLOW_CONTINUATION_FAILED",
+        },
         "Agent Workflow continuation 派发失败",
       ),
   };

package/template/apps/server/src/jobs/legacy-service-runtime.ts

@@ -10,6 +10,8 @@ import type { BulkDataRepository } from "../bulk-data/repository.js";
 import type { BulkResourceHandler } from "../bulk-data/resource-handler.js";
 // @windy-module system.bulk-data end
 import type { createServerRuntime } from "../runtime.js";
+import type { StructuredLogger } from "@southwind-ai/shared";
+import { createServerLogger } from "../observability/structured-logger.js";
 import type { RequestActor } from "../guards.js";
 // @windy-module system.bulk-data begin
 import { evaluateAccessGuards } from "../access-guards.js";
@@ -48,6 +50,7 @@ interface LegacyServiceRuntimeInput {
   // @windy-module system.workflow end
   installModuleDurableHandlers?: (registry: DurableHandlerRegistry) => void;
   durableContextualize?: DurableWorkerOptions["contextualize"];
+  logger?: StructuredLogger;
 }
 
 export function createLegacyServiceRuntime(input: LegacyServiceRuntimeInput) {
@@ -61,6 +64,7 @@ export function createLegacyServiceRuntime(input: LegacyServiceRuntimeInput) {
   input.installModuleDurableHandlers?.(registry);
   const worker = new DurableJobWorker(execution, registry, {
     contextualize: input.durableContextualize,
+    logger: input.logger ?? createServerLogger(),
   });
   // @windy-module system.workflow begin
   const workflowTimeout = new WorkflowTimeoutRuntime(

package/template/apps/server/src/jobs/runtime-logging.test.ts

@@ -0,0 +1,212 @@
+import { describe, expect, test } from "bun:test";
+import { DurableHandlerRegistry } from "@southwind-ai/jobs";
+import {
+  createStructuredLogger,
+  type StructuredLogger,
+} from "@southwind-ai/shared";
+import { InMemoryDurableExecutionRepository } from "./in-memory-execution.js";
+import { DurableJobService } from "./service.js";
+import { DurableJobWorker } from "./worker.js";
+
+const base = new Date("2026-09-30T00:00:00.000Z");
+
+function capture() {
+  const records: Record<string, unknown>[] = [];
+  const write = (record: Record<string, unknown>) => records.push(record);
+  const logger = createStructuredLogger(
+    { info: write, warn: write, error: write },
+    "windy-server",
+  );
+  return { logger, records };
+}
+
+async function fixture(
+  handler?: () => void | Promise<void>,
+  logger?: StructuredLogger,
+) {
+  const repository = new InMemoryDurableExecutionRepository();
+  const service = new DurableJobService(repository, () => base);
+  const registry = new DurableHandlerRegistry();
+  if (handler)
+    registry.register({
+      key: "test.handler",
+      payload: { parse: (value) => value },
+      execute: handler,
+    });
+  const worker = new DurableJobWorker(repository, registry, {
+    logger,
+    now: () => base,
+    leaseDurationMs: 60_000,
+  });
+  return { service, worker };
+}
+
+describe("Durable Job runtime logging", () => {
+  test("idle 无日志；每个实际 attempt 仅一条开始和一条完成", async () => {
+    const { logger, records } = capture();
+    const { service, worker } = await fixture(() => undefined, logger);
+    expect(await worker.runNext("default", "worker-a")).toEqual({
+      status: "idle",
+    });
+    expect(records).toEqual([]);
+    const submitted = await service.submit({
+      handlerKey: "test.handler",
+      idempotencyKey: "job-log-success",
+      payload: { secret: "secret-payload" },
+      requestedBy: "user-secret",
+      stageKeys: ["prepare", "apply"],
+    });
+    expect(await worker.runNext("default", "worker-a")).toEqual({
+      status: "succeeded",
+      jobId: submitted.job.id,
+    });
+    expect(await worker.runNext("default", "worker-a")).toEqual({
+      status: "succeeded",
+      jobId: submitted.job.id,
+    });
+    expect(records.map((record) => record.event)).toEqual([
+      "job.attempt.started",
+      "job.attempt.completed",
+      "job.attempt.started",
+      "job.attempt.completed",
+    ]);
+    expect(records.map((record) => record.stageKey)).toEqual([
+      "prepare",
+      "prepare",
+      "apply",
+      "apply",
+    ]);
+    for (const record of records) {
+      expect(record).toMatchObject({
+        jobId: submitted.job.id,
+        attemptNumber: 1,
+        handlerKey: "test.handler",
+        queue: "default",
+      });
+    }
+    const serialized = JSON.stringify(records);
+    expect(serialized).not.toContain("secret-payload");
+    expect(serialized).not.toContain("user-secret");
+    expect(serialized).not.toContain("leaseToken");
+  });
+
+  test("未注册 handler 与执行失败都配对，且只记录稳定错误码", async () => {
+    const missing = capture();
+    const missingFixture = await fixture(undefined, missing.logger);
+    await missingFixture.service.submit({
+      handlerKey: "test.handler",
+      idempotencyKey: "job-missing",
+      payload: { secret: "secret-payload" },
+      requestedBy: "user-1",
+    });
+    expect(
+      (await missingFixture.worker.runNext("default", "worker-a")).status,
+    ).toBe("failed");
+    expect(missing.records.map((record) => record.event)).toEqual([
+      "job.attempt.started",
+      "job.attempt.completed",
+    ]);
+    expect(missing.records[1]?.errorCode).toBe("HANDLER_NOT_REGISTERED");
+
+    const failed = capture();
+    const failedFixture = await fixture(() => {
+      throw new Error("secret-error");
+    }, failed.logger);
+    await failedFixture.service.submit({
+      handlerKey: "test.handler",
+      idempotencyKey: "job-failed",
+      payload: { secret: "secret-payload" },
+      requestedBy: "user-1",
+    });
+    expect(
+      (await failedFixture.worker.runNext("default", "worker-a")).status,
+    ).toBe("failed");
+    expect(failed.records.map((record) => record.event)).toEqual([
+      "job.attempt.started",
+      "job.attempt.completed",
+    ]);
+    expect(failed.records[1]?.errorCode).toBe("JOB_ATTEMPT_FAILED");
+    expect(JSON.stringify(failed.records)).not.toContain("secret-error");
+  });
+
+  test("取消与租约失效各写一次安全终态", async () => {
+    const cancelled = capture();
+    let entered: () => void = () => undefined;
+    let release: () => void = () => undefined;
+    const enteredPromise = new Promise<void>((resolve) => {
+      entered = resolve;
+    });
+    const releasePromise = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const cancelledFixture = await fixture(async () => {
+      entered();
+      await releasePromise;
+    }, cancelled.logger);
+    const cancelledJob = await cancelledFixture.service.submit({
+      handlerKey: "test.handler",
+      idempotencyKey: "job-cancelled",
+      payload: {},
+      requestedBy: "user-1",
+    });
+    const run = cancelledFixture.worker.runNext("default", "worker-a");
+    await enteredPromise;
+    await cancelledFixture.worker.cancel(cancelledJob.job.id);
+    release();
+    expect((await run).status).toBe("cancelled");
+    expect(cancelled.records.map((record) => record.event)).toEqual([
+      "job.attempt.started",
+      "job.attempt.completed",
+    ]);
+    expect(cancelled.records[1]?.errorCode).toBe("JOB_CANCELLED");
+
+    const lost = capture();
+    const repository = new InMemoryDurableExecutionRepository();
+    const service = new DurableJobService(repository, () => base);
+    await service.submit({
+      handlerKey: "test.handler",
+      idempotencyKey: "job-lease-lost",
+      payload: {},
+      requestedBy: "user-1",
+    });
+    let now = base;
+    const registry = new DurableHandlerRegistry().register({
+      key: "test.handler",
+      payload: { parse: (value) => value },
+      execute: async (_payload, context) => {
+        now = new Date(base.getTime() + 100);
+        await context.heartbeat();
+      },
+    });
+    const worker = new DurableJobWorker(repository, registry, {
+      logger: lost.logger,
+      now: () => now,
+      leaseDurationMs: 10,
+    });
+    expect((await worker.runNext("default", "worker-a")).status).toBe(
+      "lease-lost",
+    );
+    expect(lost.records.map((record) => record.event)).toEqual([
+      "job.attempt.started",
+      "job.attempt.completed",
+    ]);
+    expect(lost.records[1]?.errorCode).toBe("JOB_LEASE_LOST");
+  });
+
+  test("logger 抛错不改变 Job 结果", async () => {
+    const fail = () => {
+      throw new Error("sink down");
+    };
+    const logger: StructuredLogger = { info: fail, warn: fail, error: fail };
+    const { service, worker } = await fixture(() => undefined, logger);
+    await service.submit({
+      handlerKey: "test.handler",
+      idempotencyKey: "sink-failure",
+      payload: {},
+      requestedBy: "user-1",
+    });
+    expect((await worker.runNext("default", "worker-a")).status).toBe(
+      "succeeded",
+    );
+  });
+});

package/template/apps/server/src/jobs/runtime-logging.ts

@@ -0,0 +1,58 @@
+import type { ClaimedDurableJob } from "@southwind-ai/jobs";
+import type { StructuredLogger } from "@southwind-ai/shared";
+
+export type JobAttemptResult =
+  | "succeeded"
+  | "failed"
+  | "cancelled"
+  | "lease-lost";
+
+/** Only canonical claim coordinates enter operational logs. */
+export function logJobAttemptStarted(
+  logger: StructuredLogger | undefined,
+  claim: ClaimedDurableJob,
+): void {
+  safeLog(() =>
+    logger?.info({
+      event: "job.attempt.started",
+      jobId: claim.jobId,
+      stageKey: claim.stage.key,
+      attemptNumber: claim.stage.currentAttempt,
+      handlerKey: claim.job.handlerKey,
+      queue: claim.job.queue,
+    }),
+  );
+}
+
+export function logJobAttemptCompleted(
+  logger: StructuredLogger | undefined,
+  claim: ClaimedDurableJob,
+  status: JobAttemptResult,
+  durationMs: number,
+  errorCode?: string,
+): void {
+  const fields = {
+    event: "job.attempt.completed",
+    jobId: claim.jobId,
+    stageKey: claim.stage.key,
+    attemptNumber: claim.stage.currentAttempt,
+    handlerKey: claim.job.handlerKey,
+    queue: claim.job.queue,
+    durationMs: Number(durationMs.toFixed(3)),
+    outcome:
+      status === "succeeded" ? ("success" as const) : ("failure" as const),
+    ...(errorCode ? { errorCode } : {}),
+  };
+  safeLog(() => {
+    if (status === "failed" || status === "lease-lost") logger?.error(fields);
+    else logger?.info(fields);
+  });
+}
+
+function safeLog(write: () => void): void {
+  try {
+    write();
+  } catch {
+    // Runtime logging is best effort; Job fact writes retain their own contract.
+  }
+}