create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/agent-workflow/subagent-node-adapter.ts

@@ -0,0 +1,229 @@
+import type { RequestGuardContext } from "../guards.js";
+import type { AgentWorkflowNodeAdapter } from "./adapter-dispatch.js";
+import type {
+  AgentWorkflowDelegationExecutionPort,
+  AgentWorkflowNodeInputPort,
+} from "./node-execution-ports.js";
+import {
+  committedPlatformResult,
+  failedPlatformResult,
+  platformDigest,
+  reconciledPlatformResult,
+} from "./platform-node-adapter-support.js";
+
+export function subagentNodeAdapter(input: {
+  readonly context: RequestGuardContext;
+  readonly inputs: AgentWorkflowNodeInputPort;
+  readonly delegations: AgentWorkflowDelegationExecutionPort;
+}): AgentWorkflowNodeAdapter {
+  return {
+    nodeType: "subagent",
+    async prepare(nodeContext) {
+      const node = nodeContext.node;
+      if (node.type !== "subagent") {
+        return failedPlatformResult("NODE_TYPE_MISMATCH");
+      }
+      const value = await input.inputs.readJson({
+        context: nodeContext,
+        schemaKey: node.inputSchemaKey,
+      });
+      const reserved = await input.delegations.reserve({
+        parentRunId: nodeContext.run.runId,
+        parentNodeId: node.id,
+        parentNodeRunId: nodeContext.nodeRun.nodeRunId,
+        capabilityKey: node.capabilityKey,
+        operationKey: node.operationKey,
+        allowedToolKeys: node.allowedToolKeys,
+        requiredFeatureKeys: node.requiredFeatureKeys,
+        requiredPermissionKeys: node.requiredPermissionKeys,
+        ...(node.allowedLicenseVersions
+          ? { allowedLicenseVersions: node.allowedLicenseVersions }
+          : {}),
+        budget: node.budget,
+        workspacePolicyKey: node.workspacePolicyKey,
+        scopePolicyKey: node.scopePolicyKey,
+        parentActorId: nodeContext.run.actorId,
+        parentScopeDigest: nodeContext.run.scopeDigest,
+        parentAuthorizationSnapshotDigest:
+          nodeContext.run.authorizationSnapshotDigest,
+        parentToolPolicyDigest: nodeContext.run.toolPolicyDigest,
+        parentWorkspacePolicyDigest: nodeContext.run.workspacePolicyDigest,
+        parentExecutionPolicyDigest: nodeContext.run.executionPolicyDigest,
+        context: input.context,
+        idempotencyKey: nodeContext.nodeRun.idempotencyKey,
+        signal: nodeContext.signal,
+      });
+      return {
+        outcome: "effect",
+        effectKind: "subagent",
+        effectKey: node.id,
+        adapter: {
+          kind: "child-agent",
+          coordinate: reserved.childSessionId,
+        },
+        requestDigest: platformDigest({
+          capabilityKey: node.capabilityKey,
+          operationKey: node.operationKey,
+          allowedToolKeys: node.allowedToolKeys,
+          budget: node.budget,
+          workspacePolicyKey: node.workspacePolicyKey,
+          scopePolicyKey: node.scopePolicyKey,
+          value,
+        }),
+        budgetReservationId: reserved.budgetReservationId,
+        delegationId: reserved.delegationId,
+      };
+    },
+    async dispatch({ context: nodeContext, command, fence }) {
+      const node = nodeContext.node;
+      if (node.type !== "subagent" || !command.delegationId) {
+        return failedPlatformResult("SUBAGENT_COORDINATE_MISSING");
+      }
+      const value = await input.inputs.readJson({
+        context: nodeContext,
+        schemaKey: node.inputSchemaKey,
+      });
+      const started = await input.delegations.start({
+        delegationId: command.delegationId,
+        childSessionId: command.adapter.coordinate,
+        operationKey: node.operationKey,
+        value,
+        effectFence: fence,
+        idempotencyKey: command.idempotencyKey,
+        deadlineAt: nodeContext.run.deadlineAt,
+        signal: nodeContext.signal,
+      });
+      return childResult(
+        input.delegations,
+        nodeContext,
+        command.delegationId,
+        command.adapter.coordinate,
+        fence,
+        started.childAgentRunId,
+      );
+    },
+    async reconcile({
+      context: nodeContext,
+      command,
+      fence,
+      committedReceipt,
+    }) {
+      if (!command.delegationId) {
+        return failedPlatformResult("SUBAGENT_COORDINATE_MISSING");
+      }
+      if (fence && !committedReceipt) {
+        const node = nodeContext.node;
+        if (node.type !== "subagent") {
+          return failedPlatformResult("NODE_TYPE_MISMATCH");
+        }
+        const value = await input.inputs.readJson({
+          context: nodeContext,
+          schemaKey: node.inputSchemaKey,
+        });
+        await input.delegations.start({
+          delegationId: command.delegationId,
+          childSessionId: command.adapter.coordinate,
+          operationKey: node.operationKey,
+          value,
+          effectFence: fence,
+          idempotencyKey: command.idempotencyKey,
+          deadlineAt: nodeContext.run.deadlineAt,
+          signal: nodeContext.signal,
+        });
+      }
+      if (committedReceipt) {
+        const current = await input.delegations.reconcile({
+          delegationId: command.delegationId,
+          signal: nodeContext.signal,
+        });
+        if (current.status === "completed") {
+          if (current.resultDigest !== committedReceipt.resultDigest) {
+            return failedPlatformResult("SUBAGENT_RECEIPT_MISMATCH");
+          }
+          return reconciledPlatformResult(
+            nodeContext,
+            committedReceipt,
+            current.artifacts,
+            current.cumulativeUsage,
+            current.executionEvidence,
+          );
+        }
+        return current.status === "running"
+          ? { outcome: "pending" }
+          : failedPlatformResult(current.safeCode);
+      }
+      if (!fence) return { outcome: "pending" };
+      return childResult(
+        input.delegations,
+        nodeContext,
+        command.delegationId,
+        command.adapter.coordinate,
+        fence,
+      );
+    },
+    async cancel({ context: nodeContext, command }) {
+      if (!command?.delegationId) return { cancelled: true };
+      const cancelled = await input.delegations.cancel(
+        command.delegationId,
+        nodeContext.signal,
+      );
+      const current = await input.delegations.reconcile({
+        delegationId: command.delegationId,
+        signal: nodeContext.signal,
+      });
+      if (
+        current.status === "running" ||
+        current.status === "completed" ||
+        !current.cumulativeUsage
+      ) {
+        return { cancelled: false };
+      }
+      return {
+        cancelled:
+          cancelled || ["failed", "cancelled"].includes(current.status),
+        safeCode: current.safeCode,
+        cumulativeUsage: current.cumulativeUsage,
+      };
+    },
+  };
+}
+
+async function childResult(
+  delegations: AgentWorkflowDelegationExecutionPort,
+  context: Parameters<
+    NonNullable<AgentWorkflowNodeAdapter["dispatch"]>
+  >[0]["context"],
+  delegationId: string,
+  adapterCoordinate: string,
+  fence: Parameters<
+    NonNullable<AgentWorkflowNodeAdapter["dispatch"]>
+  >[0]["fence"],
+  expectedChildRunId?: string,
+) {
+  const result = await delegations.reconcile({
+    delegationId,
+    signal: context.signal,
+  });
+  if (result.status === "running") {
+    return {
+      outcome: "waiting" as const,
+      adapter: { kind: "child-agent" as const, coordinate: adapterCoordinate },
+    };
+  }
+  if (result.status !== "completed") {
+    return failedPlatformResult(result.safeCode, result.cumulativeUsage);
+  }
+  if (expectedChildRunId && result.childAgentRunId !== expectedChildRunId) {
+    return failedPlatformResult("SUBAGENT_RUN_COORDINATE_MISMATCH");
+  }
+  return committedPlatformResult(
+    context,
+    fence,
+    result.resultDigest,
+    result.childAgentRunId,
+    result.artifacts,
+    result.cumulativeUsage,
+    result.executionEvidence,
+    result.smallResult,
+  );
+}

package/template/apps/server/src/agent-workflow/tool-node-adapter.ts

@@ -0,0 +1,259 @@
+import { createHash } from "node:crypto";
+import type { ModuleAgentToolInvocation } from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+import {
+  AgentToolApprovalCoordinator,
+  AgentToolApprovalError,
+  AgentToolApprovalPending,
+} from "../agent/tool-approval.js";
+import type { GovernedToolRegistry } from "../agent/tool-registry.js";
+import type { WorkflowService } from "../workflow/service.js";
+import type { AgentWorkflowNodeAdapter } from "./adapter-dispatch.js";
+import type { AgentWorkflowNodeInputPort } from "./node-execution-ports.js";
+import {
+  committedPlatformResult,
+  directPlatformResult,
+  failedPlatformResult,
+  platformDigest,
+  reconciledPlatformResult,
+} from "./platform-node-adapter-support.js";
+
+export function toolNodeAdapter(input: {
+  readonly context: RequestGuardContext;
+  readonly inputs: AgentWorkflowNodeInputPort;
+  readonly tools: GovernedToolRegistry;
+  readonly workflow: WorkflowService;
+}): AgentWorkflowNodeAdapter {
+  const approvals = new AgentToolApprovalCoordinator(input.workflow);
+  return {
+    nodeType: "tool",
+    async prepare(nodeContext) {
+      const node = nodeContext.node;
+      if (node.type !== "tool")
+        return failedPlatformResult("NODE_TYPE_MISMATCH");
+      const definition = input.tools.definition(node.toolKey);
+      if (
+        !definition ||
+        !(await input.tools.allowed(node.toolKey, input.context))
+      ) {
+        return failedPlatformResult("TOOL_AUTHORIZATION_REVOKED");
+      }
+      if (!validEffect(node.effect, definition.operation)) {
+        return failedPlatformResult("TOOL_EFFECT_MISMATCH");
+      }
+      if (
+        nodeContext.run.usage.toolCalls >= nodeContext.run.budget.maxToolCalls
+      ) {
+        return failedPlatformResult("TOOL_BUDGET_EXCEEDED");
+      }
+      const argumentsValue = await input.inputs.readToolInput({
+        context: nodeContext,
+        schemaKey: node.inputSchemaKey,
+      });
+      if (node.effect === "read") {
+        let result;
+        try {
+          result = await input.tools.execute(
+            node.toolKey,
+            argumentsValue,
+            input.context,
+            nodeContext.nodeRun.idempotencyKey,
+          );
+        } catch {
+          return failedPlatformResult(
+            "TOOL_EXECUTION_FAILED",
+            recordToolCall(nodeContext.run.usage),
+          );
+        }
+        return directPlatformResult({
+          context: nodeContext,
+          result,
+          cumulativeUsage: recordToolCall(nodeContext.run.usage),
+        });
+      }
+      if (definition.idempotency === "none") {
+        return failedPlatformResult("WRITE_TOOL_IDEMPOTENCY_REQUIRED");
+      }
+      if (definition.approval !== "required") {
+        return failedPlatformResult("WRITE_TOOL_APPROVAL_REQUIRED");
+      }
+      return {
+        outcome: "effect",
+        effectKind: "tool",
+        effectKey: node.id,
+        adapter: {
+          kind: "agent-tool",
+          coordinate: `agent-tool:${nodeContext.nodeRun.idempotencyKey}`,
+        },
+        requestDigest: platformDigest({
+          toolKey: node.toolKey,
+          arguments: argumentsValue,
+        }),
+      };
+    },
+    async dispatch({ context: nodeContext, command, fence }) {
+      return executeWrite({
+        ...input,
+        approvals,
+        nodeContext,
+        command,
+        fence,
+      });
+    },
+    async reconcile({
+      context: nodeContext,
+      command,
+      fence,
+      committedReceipt,
+    }) {
+      if (committedReceipt) {
+        return reconciledPlatformResult(
+          nodeContext,
+          committedReceipt,
+          nodeContext.inputArtifacts,
+          recordToolCall(nodeContext.run.usage),
+        );
+      }
+      if (!fence) return { outcome: "pending" };
+      return executeWrite({
+        ...input,
+        approvals,
+        nodeContext,
+        command,
+        fence,
+      });
+    },
+    async cancel({ context: nodeContext, command }) {
+      if (!command || nodeContext.node.type !== "tool") {
+        return { cancelled: true };
+      }
+      const item = await input.workflow.get(
+        approvalWorkItemId(command, nodeContext.node.toolKey),
+        input.context.actor,
+      );
+      if (!item) return { cancelled: true };
+      if (!["pending", "claimed"].includes(item.status)) {
+        return { cancelled: item.status === "cancelled" };
+      }
+      await input.workflow.cancel(
+        item.id,
+        {
+          expectedVersion: item.version,
+          idempotencyKey: `${command.idempotencyKey}:cancel-approval`,
+          reason: "Agent Workflow cancelled",
+        },
+        input.context.actor,
+      );
+      return { cancelled: true };
+    },
+  };
+}
+
+async function executeWrite(input: {
+  readonly context: RequestGuardContext;
+  readonly inputs: AgentWorkflowNodeInputPort;
+  readonly tools: GovernedToolRegistry;
+  readonly approvals: AgentToolApprovalCoordinator;
+  readonly nodeContext: Parameters<
+    NonNullable<AgentWorkflowNodeAdapter["dispatch"]>
+  >[0]["context"];
+  readonly command: Parameters<
+    NonNullable<AgentWorkflowNodeAdapter["dispatch"]>
+  >[0]["command"];
+  readonly fence: Parameters<
+    NonNullable<AgentWorkflowNodeAdapter["dispatch"]>
+  >[0]["fence"];
+}) {
+  const node = input.nodeContext.node;
+  if (node.type !== "tool") return failedPlatformResult("NODE_TYPE_MISMATCH");
+  const definition = input.tools.definition(node.toolKey);
+  if (
+    !definition ||
+    !(await input.tools.allowed(node.toolKey, input.context))
+  ) {
+    return failedPlatformResult("TOOL_AUTHORIZATION_REVOKED");
+  }
+  if (
+    definition.idempotency === "none" ||
+    definition.approval !== "required" ||
+    !validEffect("write", definition.operation)
+  ) {
+    return failedPlatformResult("WRITE_TOOL_POLICY_REVOKED");
+  }
+  const argumentsValue = await input.inputs.readToolInput({
+    context: input.nodeContext,
+    schemaKey: node.inputSchemaKey,
+  });
+  const invocation: ModuleAgentToolInvocation = {
+    runId: input.command.runId,
+    toolCallId: input.command.commandId,
+    toolKey: node.toolKey,
+    arguments: argumentsValue,
+  };
+  try {
+    await input.approvals.requireApproved(
+      definition,
+      invocation,
+      input.context,
+    );
+  } catch (error) {
+    if (error instanceof AgentToolApprovalPending) {
+      return {
+        outcome: "waiting" as const,
+        adapter: input.command.adapter,
+      };
+    }
+    if (error instanceof AgentToolApprovalError) {
+      return failedPlatformResult(error.code);
+    }
+    throw error;
+  }
+  let execution;
+  try {
+    execution = await input.tools.executeWithAuditReceipt(
+      node.toolKey,
+      argumentsValue,
+      input.context,
+      input.command.commandId,
+    );
+  } catch {
+    return failedPlatformResult(
+      "TOOL_EXECUTION_FAILED",
+      recordToolCall(input.nodeContext.run.usage),
+    );
+  }
+  return committedPlatformResult(
+    input.nodeContext,
+    input.fence,
+    platformDigest(execution.result),
+    execution.auditReceipt.auditEventId,
+    input.nodeContext.inputArtifacts,
+    recordToolCall(input.nodeContext.run.usage),
+    undefined,
+    execution.result,
+  );
+}
+
+function recordToolCall(
+  current: import("@southwind-ai/shared").AgentWorkflowUsage,
+) {
+  return { ...current, toolCalls: current.toolCalls + 1 };
+}
+
+function validEffect(effect: "read" | "write", operation: string) {
+  return effect === "read"
+    ? operation === "query"
+    : operation === "command" || operation === "background";
+}
+
+function approvalWorkItemId(
+  command: Parameters<
+    NonNullable<AgentWorkflowNodeAdapter["dispatch"]>
+  >[0]["command"],
+  toolKey: string,
+) {
+  const idempotencyKey = `agent-tool:${createHash("sha256")
+    .update(`${command.runId}\u0000${command.commandId}\u0000${toolKey}`)
+    .digest("hex")}`;
+  return `agent-tool-${idempotencyKey.slice("agent-tool:".length, 56)}`;
+}

package/template/apps/server/src/agent-workflow/usage.ts

@@ -0,0 +1,149 @@
+import {
+  isAgentWorkflowTerminal,
+  type AgentWorkflowRun,
+  type AgentWorkflowUsage,
+} from "@southwind-ai/shared";
+import { AgentWorkflowStateError } from "./state-machine.js";
+
+export const EMPTY_AGENT_WORKFLOW_USAGE = Object.freeze({
+  durationMs: 0,
+  modelAttempts: 0,
+  toolCalls: 0,
+  subagents: 0,
+  inputTokens: { status: "measured", value: 0, source: "host-measured" },
+  outputTokens: { status: "measured", value: 0, source: "host-measured" },
+  cost: {
+    status: "measured",
+    amountMicros: 0,
+    currency: "USD",
+    source: "host-measured",
+  },
+} satisfies AgentWorkflowUsage);
+
+export function recordAgentWorkflowUsage(
+  run: AgentWorkflowRun,
+  usage: AgentWorkflowUsage,
+  expectedVersion: number,
+  at: string,
+  allowUnknownForTerminalFailure = false,
+  allowBudgetOverrunForTerminalFailure = false,
+): AgentWorkflowRun {
+  if (run.version !== expectedVersion)
+    stateError("VERSION_CONFLICT", "Workflow version 已变化");
+  if (
+    !Number.isFinite(Date.parse(at)) ||
+    Date.parse(at) < Date.parse(run.updatedAt)
+  ) {
+    stateError("INVALID_TRANSITION", "Workflow Usage 时间无效");
+  }
+  if (isAgentWorkflowTerminal(run.status)) {
+    stateError("TERMINAL_RUN", "Workflow Run 终态不能增加 Usage");
+  }
+  assertUsageProgression(run.usage, usage);
+  assertKnownUsageWithinBudget(
+    run,
+    usage,
+    allowUnknownForTerminalFailure,
+    allowBudgetOverrunForTerminalFailure,
+  );
+  return {
+    ...run,
+    usage: structuredClone(usage),
+    updatedAt: at,
+    version: run.version + 1,
+  };
+}
+
+export function assertKnownUsageWithinBudget(
+  run: AgentWorkflowRun,
+  usage: AgentWorkflowUsage = run.usage,
+  allowUnknown = false,
+  allowOverrun = false,
+) {
+  for (const [value, maximum, label] of [
+    [usage.durationMs, run.budget.maxDurationSeconds * 1_000, "durationMs"],
+    [usage.modelAttempts, run.budget.maxModelAttempts, "modelAttempts"],
+    [usage.toolCalls, run.budget.maxToolCalls, "toolCalls"],
+    [usage.subagents, run.budget.maxSubagents, "subagents"],
+  ] as const) {
+    if (
+      !Number.isSafeInteger(value) ||
+      value < 0 ||
+      (!allowOverrun && value > maximum)
+    ) {
+      stateError("BUDGET_EXCEEDED", `Workflow Budget 已超出：${label}`);
+    }
+  }
+  for (const [measurement, maximum, label] of [
+    [usage.inputTokens, run.budget.maxInputTokens, "inputTokens"],
+    [usage.outputTokens, run.budget.maxOutputTokens, "outputTokens"],
+  ] as const) {
+    if (
+      (measurement.status === "measured" &&
+        (!Number.isSafeInteger(measurement.value) ||
+          measurement.value < 0 ||
+          (!allowOverrun && measurement.value > maximum))) ||
+      (measurement.status === "unknown" && !allowUnknown)
+    ) {
+      stateError("BUDGET_EXCEEDED", `Workflow Usage 无效或已超出：${label}`);
+    }
+  }
+  if (
+    (usage.cost.status === "measured" &&
+      (!Number.isSafeInteger(usage.cost.amountMicros) ||
+        usage.cost.amountMicros < 0 ||
+        (!allowOverrun && usage.cost.amountMicros > run.budget.maxCostMicros) ||
+        !usage.cost.currency.trim())) ||
+    (usage.cost.status === "unknown" && !allowUnknown)
+  ) {
+    stateError("BUDGET_EXCEEDED", "Workflow Cost Usage 无效或已超出");
+  }
+}
+
+function assertUsageProgression(
+  previous: AgentWorkflowUsage,
+  current: AgentWorkflowUsage,
+) {
+  for (const key of [
+    "durationMs",
+    "modelAttempts",
+    "toolCalls",
+    "subagents",
+  ] as const) {
+    if (!Number.isSafeInteger(current[key]) || current[key] < previous[key]) {
+      stateError("BUDGET_EXCEEDED", `Workflow Usage 不能回退：${key}`);
+    }
+  }
+  for (const key of ["inputTokens", "outputTokens"] as const) {
+    const before = previous[key];
+    const after = current[key];
+    if (
+      (before.status === "measured" &&
+        after.status !== "measured" &&
+        current.modelAttempts === previous.modelAttempts) ||
+      (before.status === "measured" &&
+        after.status === "measured" &&
+        after.value < before.value)
+    ) {
+      stateError("BUDGET_EXCEEDED", `Workflow Usage 不能回退：${key}`);
+    }
+  }
+  if (
+    (previous.cost.status === "measured" &&
+      current.cost.status !== "measured" &&
+      current.modelAttempts === previous.modelAttempts) ||
+    (previous.cost.status === "measured" &&
+      current.cost.status === "measured" &&
+      (current.cost.currency !== previous.cost.currency ||
+        current.cost.amountMicros < previous.cost.amountMicros))
+  ) {
+    stateError("BUDGET_EXCEEDED", "Workflow Cost Usage 不能回退或变更币种");
+  }
+}
+
+function stateError(
+  code: ConstructorParameters<typeof AgentWorkflowStateError>[0],
+  message: string,
+): never {
+  throw new AgentWorkflowStateError(code, message);
+}