create-windy 0.8.0 → 0.8.1

package/template/apps/agent-server/tests/test_run_operational_logging.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import asyncio
+import io
+import json
+import logging
+from collections.abc import Iterator
+from typing import TextIO, cast
+
+import httpx
+import pytest
+
+from southwind_agent_server.app import create_app
+from southwind_agent_server.deterministic import DeterministicEngineAdapter
+from southwind_agent_server.runtime_logging import AgentOperationalAttempt, logger
+from southwind_agent_server.service import AgentRunService
+from southwind_agent_server.store import RunRecord
+from southwind_agent_server.structured_logging import AgentStructuredLogHandler
+
+
+@pytest.fixture(autouse=True)
+def operational_log_level() -> Iterator[None]:
+    previous = logger.level
+    logger.setLevel(logging.INFO)
+    try:
+        yield
+    finally:
+        logger.setLevel(previous)
+
+
+@pytest.mark.parametrize("broken_sink", [False, True])
+async def test_real_run_completion_and_replay_with_operational_logs(
+    monkeypatch: pytest.MonkeyPatch,
+    broken_sink: bool,
+) -> None:
+    class Stream(io.StringIO):
+        def write(self, value: str) -> int:
+            written = super().write(value)
+            if broken_sink:
+                raise OSError("sink-secret")
+            return written
+
+    stream = Stream()
+    monkeypatch.setattr(logger, "handlers", [AgentStructuredLogHandler(stream)])
+    monkeypatch.setattr(logger, "propagate", False)
+    app = create_app(DeterministicEngineAdapter(), heartbeat_seconds=0.01)
+    service = cast(AgentRunService, app.state.run_service)
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app),
+        base_url="http://agent.test",
+    ) as client:
+
+        async def start() -> httpx.Response:
+            return await client.post(
+                "/api/agent/runs",
+                headers={"Idempotency-Key": "operational-replay"},
+                json={
+                    "operationKey": "test.echo",
+                    "input": {"text": "input-secret"},
+                    "traceId": "1" * 32,
+                },
+            )
+
+        response = await start()
+        assert response.status_code == 200
+        run_id = str(response.json()["runId"])
+        await asyncio.gather(*service._tasks)
+        replay = await start()
+        assert replay.json()["runId"] == run_id
+        events = await client.get(f"/api/agent/runs/{run_id}/events")
+        result = await client.get(f"/api/agent/runs/{run_id}/result")
+    assert result.json()["status"] == "completed"
+    assert result.json()["output"] == {"text": "input-secret"}
+    assert "run.failed" not in events.text
+    records = [json.loads(line) for line in stream.getvalue().splitlines()]
+    assert [record["event"] for record in records] == [
+        "agent.run.attempt.started",
+        "agent.run.attempt.completed",
+    ]
+    assert all(record["runId"] == run_id for record in records)
+    assert all(record["traceId"] == "1" * 32 for record in records)
+    assert records[-1]["outcome"] == "success"
+    assert records[-1]["durationMs"] >= 0
+    assert "input-secret" not in stream.getvalue()
+    assert "sink-secret" not in stream.getvalue()
+
+
+@pytest.mark.parametrize("status", ["failed", "cancelled", "running"])
+def test_attempt_terminal_mapping_and_duplicate_finish_are_safe(
+    monkeypatch: pytest.MonkeyPatch,
+    status: str,
+) -> None:
+    stream = io.StringIO()
+    monkeypatch.setattr(logger, "handlers", [AgentStructuredLogHandler(stream)])
+    monkeypatch.setattr(logger, "propagate", False)
+    record = RunRecord("run-1", "test.echo", {"secret": "input"}, "key", "digest")
+    attempt = AgentOperationalAttempt(record)
+    attempt.start()
+    attempt.start()
+    attempt.finish(status)
+    attempt.finish(status)
+    records = [json.loads(line) for line in stream.getvalue().splitlines()]
+    assert len(records) == 2
+    assert records[-1]["outcome"] == "failure"
+    expected = status if status in {"failed", "cancelled"} else "interrupted"
+    assert records[-1]["errorCode"] == f"AGENT_RUN_{expected.upper()}"
+    assert "secret" not in stream.getvalue()
+
+
+def test_unknown_info_message_does_not_expand_log_content() -> None:
+    stream = io.StringIO()
+    handler = AgentStructuredLogHandler(cast(TextIO, stream))
+    handler.emit(logging.makeLogRecord({"levelno": logging.INFO, "msg": "secret"}))
+    assert stream.getvalue() == ""

package/template/apps/agent-server/tests/test_structured_logging.py

@@ -0,0 +1,105 @@
+import io
+import json
+import logging
+from importlib import import_module
+from typing import TextIO, cast
+
+from southwind_agent_server.structured_logging import (
+    MAX_LOG_BYTES,
+    AgentStructuredLogHandler,
+    agent_log_record,
+    configure_agent_logging,
+)
+
+
+def test_agent_report_failure_keeps_only_safe_correlation() -> None:
+    stream = io.StringIO()
+    handler = AgentStructuredLogHandler(stream)
+    logger = logging.getLogger("southwind_agent_server.test_structured_logging")
+    logger.addHandler(handler)
+    logger.setLevel(logging.WARNING)
+    logger.propagate = False
+    try:
+        try:
+            raise ValueError("secret-error")
+        except ValueError:
+            logger.exception(
+                "Agent Runtime 报表写入失败",
+                extra={
+                    "run_id": "run-1",
+                    "report_stage": "run_terminal",
+                    "request_id": "bad\nrequest-secret",
+                    "body": "secret-body",
+                    "authorization": "Bearer secret-token",
+                },
+            )
+    finally:
+        logger.removeHandler(handler)
+    line = stream.getvalue().strip()
+    parsed = json.loads(line)
+    assert parsed["event"] == "agent.report.write.failed"
+    assert parsed["errorCode"] == "AGENT_REPORT_WRITE_FAILED"
+    assert parsed["runId"] == "run-1"
+    assert parsed["stageKey"] == "run_terminal"
+    assert parsed["retentionClass"] == "operational"
+    assert len(line.encode("utf-8")) <= MAX_LOG_BYTES
+    assert all(
+        secret not in line
+        for secret in (
+            "request-secret",
+            "secret-body",
+            "secret-token",
+            "secret-error",
+        )
+    )
+
+
+def test_unknown_message_and_long_fields_are_bounded() -> None:
+    record = logging.makeLogRecord(
+        {
+            "name": "southwind_agent_server.service",
+            "levelno": logging.ERROR,
+            "msg": "secret-message",
+            "run_id": "x" * 500,
+            "report_stage": "payload secret",
+        }
+    )
+    safe = agent_log_record(record)
+    assert safe["event"] == "agent.runtime.failed"
+    assert "runId" not in safe
+    assert "stageKey" not in safe
+    assert "secret-message" not in json.dumps(safe)
+    assert len(json.dumps(safe).encode("utf-8")) <= MAX_LOG_BYTES
+
+
+def test_asgi_entrypoint_installs_handler_without_changing_app() -> None:
+    from southwind_agent_server.app import app
+
+    asgi = import_module("southwind_agent_server.asgi")
+    configure_agent_logging()
+    handlers = [
+        handler
+        for handler in logging.getLogger("southwind_agent_server").handlers
+        if isinstance(handler, AgentStructuredLogHandler)
+    ]
+    assert asgi.app is app
+    assert len(handlers) == 1
+
+
+def test_stdout_failure_does_not_interrupt_runtime() -> None:
+    class BrokenStream:
+        def write(self, _value: str) -> None:
+            raise OSError("stdout unavailable")
+
+        def flush(self) -> None:
+            raise OSError("stdout unavailable")
+
+    handler = AgentStructuredLogHandler(cast(TextIO, BrokenStream()))
+    record = logging.makeLogRecord(
+        {
+            "name": "southwind_agent_server.service",
+            "levelno": logging.ERROR,
+            "msg": "Agent Run 恢复轮询失败，将继续重试",
+        }
+    )
+    handler.emit(record)

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

@@ -0,0 +1,194 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { buildScopeContext } from "../data-access/context.js";
+import { createRequestGuardContext } from "../guards.js";
+import type { InitializedModuleHosts } from "../module-host.js";
+import { createServerRuntime } from "../runtime.js";
+import { IsolatedExecutionGuard } from "./isolated-execution-guard.js";
+import { createTestRunAuthorizationStore } from "./run-authorization.test-support.js";
+import { buildAgentRuntimeRelease } from "./run-release.js";
+
+const definition: NonNullable<ModuleManifest["aiOperations"]>[number] = {
+  key: "business.answer",
+  kind: "agent",
+  featureKey: "business.ai",
+  permissionKey: "business.ai.execute",
+  auditAction: "business.ai.execute",
+  inputSchemaKey: "business.input.v1",
+  outputSchemaKey: "business.output.v1",
+  requiredCapabilities: ["text-generation"],
+  allowedToolKeys: [],
+  dataClassification: "internal",
+  execution: "streaming",
+  toolNetworkPolicy: { mode: "forbidden" },
+  limits: { maxDurationSeconds: 60, maxInputBytes: 4096, maxOutputBytes: 4096 },
+  isolatedExecution: {
+    version: 1,
+    mode: "isolated",
+    languages: ["python"],
+    inputArtifactTypes: ["text/plain"],
+    network: "forbidden",
+    limits: {
+      maxWorkspaceBytes: 4096,
+      maxFileBytes: 2048,
+      maxOutputBytes: 1024,
+      maxDurationSeconds: 30,
+      maxCpuMillis: 30_000,
+      maxMemoryBytes: 134_217_728,
+      maxPids: 4,
+      maxConcurrentProcesses: 1,
+      maxToolCalls: 3,
+      maxToolRounds: 2,
+    },
+  },
+};
+
+const module = {
+  name: "business",
+  version: "0.1.0",
+  features: [
+    {
+      key: "business.ai",
+      enabled: true,
+      module: "business",
+      label: "AI",
+      visible: "visible",
+      stage: "stable",
+    },
+  ],
+  jsonSchemas: [
+    { key: "business.input.v1", schema: { type: "object" } },
+    { key: "business.output.v1", schema: { type: "object" } },
+  ],
+  tools: [],
+  aiOperations: [definition],
+} as unknown as ModuleManifest;
+const hosts = { aiOperationHandlers: [] } as unknown as InitializedModuleHosts;
+
+describe("隔离执行逐次准入", () => {
+  test("运行时或持久预算端口缺失时拒绝，绝不执行宿主脚本", async () => {
+    const fixture = await setup();
+    await expect(
+      fixture.guard().admit(fixture.invocation),
+    ).rejects.toMatchObject({
+      code: "RUNTIME_UNAVAILABLE",
+    });
+  });
+
+  test("当前授权、Run 状态及预算每次复核", async () => {
+    const fixture = await setup();
+    const calls: unknown[] = [];
+    const guard = fixture.guard({
+      state: { status: async () => "running" },
+      budget: {
+        reserve: async (input) => {
+          calls.push(input);
+          return true;
+        },
+      },
+      available: true,
+    });
+    await expect(guard.admit(fixture.invocation)).resolves.toEqual(
+      definition.isolatedExecution!,
+    );
+    expect(calls).toEqual([
+      {
+        runId: "run_1",
+        callId: "call_1",
+        maxToolCalls: 3,
+        maxToolRounds: 2,
+        maxConcurrentProcesses: 1,
+      },
+    ]);
+    await expect(
+      guard.admit({ ...fixture.invocation, language: "node" }),
+    ).rejects.toMatchObject({ code: "EXECUTION_DENIED" });
+
+    const denied = fixture.guard({
+      state: { status: async () => "terminal" },
+      budget: {
+        reserve: async () => {
+          throw new Error("terminal Run must not reserve");
+        },
+      },
+      available: true,
+    });
+    await expect(denied.admit(fixture.invocation)).rejects.toMatchObject({
+      code: "EXECUTION_DENIED",
+    });
+    fixture.actor.permissionKeys = [];
+    await expect(guard.admit(fixture.invocation)).rejects.toMatchObject({
+      code: "EXECUTION_DENIED",
+    });
+    expect(calls).toHaveLength(1);
+  });
+});
+
+async function setup() {
+  const actor = {
+    id: "actor-1",
+    type: "user" as const,
+    name: "测试用户",
+    roleCodes: ["user"],
+    permissionKeys: ["business.ai.execute"],
+    scopeContext: buildScopeContext("actor-1", undefined, [
+      { id: "role-user", code: "user", dataScope: "self", departmentIds: [] },
+    ]),
+  };
+  const runtime = createServerRuntime(
+    {},
+    {
+      featureCatalog: module.features,
+      licenseResolver: { resolve: () => ({ status: "valid" }) },
+    },
+  );
+  const context = createRequestGuardContext(
+    new Request("http://localhost/api/agent/runs"),
+    {
+      resolveActor: () => actor,
+      resolveLicense: () => ({ status: "valid" }),
+    },
+  );
+  const authorizations = createTestRunAuthorizationStore();
+  const grant = await authorizations.issue({
+    operationKey: definition.key,
+    releaseId: buildAgentRuntimeRelease([module], module, definition, undefined)
+      .releaseId,
+    idempotencyKey: "isolated-execution-test",
+    input: { question: "analyze" },
+    authorizationSnapshot: {
+      permissionKey: definition.permissionKey,
+      featureKey: definition.featureKey,
+      allowedToolKeys: [],
+      toolNetworkMode: "forbidden",
+    },
+    context,
+  });
+  await authorizations.bind(grant, "run_1");
+  return {
+    actor,
+    invocation: {
+      executionGrant: grant.token,
+      runId: "run_1",
+      callId: "call_1",
+      language: "python" as const,
+    },
+    guard: (
+      ports: {
+        state?: ConstructorParameters<typeof IsolatedExecutionGuard>[5];
+        budget?: ConstructorParameters<typeof IsolatedExecutionGuard>[6];
+        available?: boolean;
+      } = {},
+    ) =>
+      new IsolatedExecutionGuard(
+        [module],
+        hosts,
+        runtime,
+        authorizations,
+        async () => actor,
+        ports.state,
+        ports.budget,
+        ports.available,
+      ),
+  };
+}

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(