botmux-workflow-core 3.16.0 → 3.17.0

package/dist/esm/runtime.js

@@ -233,6 +233,104 @@ function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+// src/workflows/v3/artifact-contract.ts
+var MANIFEST_FILE_KINDS = [
+  "markdown",
+  "json",
+  "text",
+  "code",
+  "log",
+  "binary",
+  "directory"
+];
+var MANIFEST_SUMMARY_MAX_BYTES = 4 * 1024;
+var MANIFEST_PREVIEW_MAX_BYTES = 4 * 1024;
+var MANIFEST_STATUSES = ["ok", "fail"];
+var MANIFEST_SCHEMA_VERSION = 1;
+
+// src/workflows/v3/artifact-contract-declarations.ts
+var V3_ARTIFACT_OUTPUT_KEY_RE = /^[A-Za-z0-9._-]+$/;
+var V3_ARTIFACT_OUTPUT_MAX_COUNT = 32;
+var V3_ARTIFACT_OUTPUT_MAX_BYTES = 4 * 1024;
+function normalizeArtifactOutputs(value, where, problems) {
+  if (value === void 0) return void 0;
+  if (!isRecord2(value) || Object.keys(value).length === 0) {
+    problems.push(`${where}.outputs must be a non-empty object when present`);
+    return void 0;
+  }
+  const entries = Object.entries(value);
+  if (entries.length > V3_ARTIFACT_OUTPUT_MAX_COUNT) {
+    problems.push(`${where}.outputs has ${entries.length} entries (max ${V3_ARTIFACT_OUTPUT_MAX_COUNT})`);
+  }
+  if (Buffer.byteLength(JSON.stringify(value), "utf-8") > V3_ARTIFACT_OUTPUT_MAX_BYTES) {
+    problems.push(`${where}.outputs exceeds ${V3_ARTIFACT_OUTPUT_MAX_BYTES} serialized bytes`);
+  }
+  const out = /* @__PURE__ */ Object.create(null);
+  const paths = /* @__PURE__ */ new Set();
+  for (const [key, raw] of entries) {
+    const itemWhere = `${where}.outputs.${JSON.stringify(key)}`;
+    if (!V3_ARTIFACT_OUTPUT_KEY_RE.test(key)) {
+      problems.push(`${itemWhere} key must match ${V3_ARTIFACT_OUTPUT_KEY_RE}`);
+      continue;
+    }
+    if (!isRecord2(raw)) {
+      problems.push(`${itemWhere} must be { path, kind }`);
+      continue;
+    }
+    const extra = Object.keys(raw).filter((field) => field !== "path" && field !== "kind");
+    if (extra.length > 0) {
+      problems.push(`${itemWhere} has unsupported key(s): ${extra.join(", ")} (allowed: path, kind)`);
+      continue;
+    }
+    if (!isPortableRelativeArtifactPath(raw.path)) {
+      problems.push(`${itemWhere}.path must be a portable relative path without '.', '..', or empty segments`);
+      continue;
+    }
+    if (typeof raw.kind !== "string" || !MANIFEST_FILE_KINDS.includes(raw.kind)) {
+      problems.push(`${itemWhere}.kind must be one of ${MANIFEST_FILE_KINDS.join(" | ")}`);
+      continue;
+    }
+    if (paths.has(raw.path)) {
+      problems.push(`${where}.outputs contains duplicate path ${JSON.stringify(raw.path)}`);
+      continue;
+    }
+    paths.add(raw.path);
+    out[key] = { path: raw.path, kind: raw.kind };
+  }
+  return out;
+}
+function validateManifestArtifactContract(outputs, manifest) {
+  if (!outputs) return { ok: true, problems: [] };
+  const problems = [];
+  for (const [key, declaration] of Object.entries(outputs)) {
+    const matches = manifest.files.filter((file) => file.path === declaration.path);
+    if (matches.length === 0) {
+      problems.push(
+        `output ${JSON.stringify(key)} requires path ${JSON.stringify(declaration.path)} (available: ${manifest.files.map((file) => `${file.path}:${file.kind}`).join(", ") || "none"})`
+      );
+      continue;
+    }
+    if (matches.length > 1) {
+      problems.push(`output ${JSON.stringify(key)} path ${JSON.stringify(declaration.path)} appears more than once`);
+      continue;
+    }
+    if (matches[0].kind !== declaration.kind) {
+      problems.push(
+        `output ${JSON.stringify(key)} path ${JSON.stringify(declaration.path)} has kind ${JSON.stringify(matches[0].kind)}, expected ${JSON.stringify(declaration.kind)}`
+      );
+    }
+  }
+  return { ok: problems.length === 0, problems };
+}
+function isPortableRelativeArtifactPath(value) {
+  if (typeof value !== "string" || value.length === 0 || value.startsWith("/") || value.includes("\\") || value.includes("\0") || /^[A-Za-z]:/.test(value)) return false;
+  const segments = value.split("/");
+  return segments.every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/workflows/v3/dag.ts
 var NODE_KINDS = ["goal", "host", "loop"];
 var V3_HOST_EXECUTORS = ["feishu-send", "feishu-reply", "botmux-schedule"];
@@ -283,6 +381,10 @@ function validateDag(raw) {
   if (!isObject(raw)) {
     throw new DagValidationError(["root must be a JSON object"]);
   }
+  const schemaVersion = raw.schemaVersion === void 0 ? 1 : raw.schemaVersion;
+  if (schemaVersion !== 1 && schemaVersion !== 2) {
+    problems.push(`schemaVersion must be 1 or 2 (got ${JSON.stringify(raw.schemaVersion)})`);
+  }
   if (typeof raw.runId !== "string" || !SEGMENT_RE.test(raw.runId)) {
     problems.push(`runId must be a path-safe string matching ${SEGMENT_RE} (got ${JSON.stringify(raw.runId)})`);
   }
@@ -319,9 +421,9 @@ function validateDag(raw) {
     if (fromList.includes(id)) problems.push(`node "${id}" depends on itself`);
     if (new Set(fromList).size !== fromList.length) problems.push(`node "${id}".depends has duplicates`);
     const triggerRule = normTriggerRule(n.triggerRule, depends.length, `node "${id}"`, problems);
-    const inputs = normInputs(n.inputs, id, problems);
+    const inputs = normInputs(n.inputs, id, problems, schemaVersion === 2 ? 2 : 1);
     if (type === "loop") {
-      const loopFields = normLoopFields(n, id, problems);
+      const loopFields = normLoopFields(n, id, problems, schemaVersion === 2 ? 2 : 1);
       if (loopFields) {
         nodes.push({
           id,
@@ -338,6 +440,7 @@ function validateDag(raw) {
       continue;
     }
     if (type === "host") {
+      if (n.outputs !== void 0) problems.push(`host node "${id}".outputs is not supported`);
       if (n.goal !== void 0) problems.push(`host node "${id}".goal is not supported`);
       if (n.bot !== void 0) problems.push(`host node "${id}".bot is not supported \u2014 host nodes do not spawn a CLI`);
       if (n.override !== void 0) problems.push(`host node "${id}".override is not supported`);
@@ -413,6 +516,10 @@ function validateDag(raw) {
     const humanGate = normHumanGate(n.humanGate, `node "${id}"`, problems);
     const override = normOverride(n.override, `node "${id}"`, problems);
     const revisitTo = normRevisitTo(n.revisitTo, id, problems);
+    if (schemaVersion !== 2 && n.outputs !== void 0) {
+      problems.push(`goal node "${id}".outputs requires schemaVersion 2`);
+    }
+    const outputs = schemaVersion === 2 ? normalizeArtifactOutputs(n.outputs, `goal node "${id}"`, problems) : void 0;
     nodes.push({
       id,
       type,
@@ -422,6 +529,7 @@ function validateDag(raw) {
       triggerRule,
       override,
       inputs,
+      outputs,
       timeoutSec,
       humanGate,
       resultSchema,
@@ -437,6 +545,14 @@ function validateDag(raw) {
         problems.push(`node "${node.id}".inputs references unknown node "${inp.from}"`);
       } else if (!node.depends.some((d) => d.from === inp.from)) {
         problems.push(`node "${node.id}".inputs.from "${inp.from}" must also be in depends`);
+      } else if (inp.output !== void 0) {
+        const source = nodes.find((candidate) => candidate.id === inp.from);
+        const outputs = source?.type === "loop" ? source.body?.nodes.find((bodyNode) => bodyNode.id === source.output?.from)?.outputs : source?.outputs;
+        if (!outputs || !Object.prototype.hasOwnProperty.call(outputs, inp.output)) {
+          problems.push(
+            `node "${node.id}".inputs output ${JSON.stringify(inp.output)} is not declared by source "${inp.from}"`
+          );
+        }
       }
     }
     if (node.type === "host") {
@@ -515,7 +631,11 @@ function validateDag(raw) {
     }
   }
   if (problems.length > 0) throw new DagValidationError(problems);
-  const dag = { runId: raw.runId, nodes };
+  const dag = {
+    ...raw.schemaVersion !== void 0 ? { schemaVersion } : {},
+    runId: raw.runId,
+    nodes
+  };
   topologicalOrder(dag);
   return dag;
 }
@@ -829,7 +949,7 @@ function downstreamCone(nodeId, nodes) {
 function nodeByIdUnsafe(nodes, nodeId) {
   return nodes.find((node) => node.id === nodeId);
 }
-function normLoopFields(n, id, problems) {
+function normLoopFields(n, id, problems, schemaVersion) {
   const where = `loop node "${id}"`;
   const before = problems.length;
   if (n.timeoutSec !== void 0) {
@@ -900,10 +1020,14 @@ function normLoopFields(n, id, problems) {
     const bFromList = bdepends.map((d) => d.from);
     if (bFromList.includes(bid)) problems.push(`${where}.body node "${bid}" depends on itself`);
     if (new Set(bFromList).size !== bFromList.length) problems.push(`${where}.body node "${bid}".depends has duplicates`);
-    const binputs = normInputs(b.inputs, `${id}.body.${bid}`, problems);
+    const binputs = normInputs(b.inputs, `${id}.body.${bid}`, problems, schemaVersion);
     const btimeout = normTimeoutSec(b.timeoutSec, `${where}.body node "${bid}"`, problems);
     const bschema = normResultSchema(b.resultSchema, `${id}.body.${bid}`, problems);
     const boverride = normOverride(b.override, `${where}.body node "${bid}"`, problems);
+    if (schemaVersion !== 2 && b.outputs !== void 0) {
+      problems.push(`${where}.body node "${bid}".outputs requires schemaVersion 2`);
+    }
+    const boutputs = schemaVersion === 2 ? normalizeArtifactOutputs(b.outputs, `${where}.body node "${bid}"`, problems) : void 0;
     bodyNodes.push({
       id: bid,
       type: "goal",
@@ -912,6 +1036,7 @@ function normLoopFields(n, id, problems) {
       depends: bdepends,
       override: boverride,
       inputs: binputs,
+      outputs: boutputs,
       timeoutSec: btimeout,
       humanGate: null,
       resultSchema: bschema
@@ -926,6 +1051,13 @@ function normLoopFields(n, id, problems) {
         problems.push(`${where}.body node "${bn.id}".inputs references unknown body node "${inp.from}"`);
       } else if (!bn.depends.some((d) => d.from === inp.from)) {
         problems.push(`${where}.body node "${bn.id}".inputs.from "${inp.from}" must also be in depends`);
+      } else if (inp.output !== void 0) {
+        const source = bodyNodes.find((candidate) => candidate.id === inp.from);
+        if (!source?.outputs || !Object.prototype.hasOwnProperty.call(source.outputs, inp.output)) {
+          problems.push(
+            `${where}.body node "${bn.id}".inputs output ${JSON.stringify(inp.output)} is not declared by source "${inp.from}"`
+          );
+        }
       }
     }
   }
@@ -1151,7 +1283,7 @@ function normResultSchema(v, id, problems) {
   }
   return schema;
 }
-function normInputs(v, id, problems) {
+function normInputs(v, id, problems, schemaVersion) {
   if (v === void 0) return [];
   if (!Array.isArray(v)) {
     problems.push(`node "${id}".inputs must be an array`);
@@ -1164,9 +1296,29 @@ function normInputs(v, id, problems) {
       problems.push(`node "${id}".inputs[${j}] must be { from: <nodeId>, select? }`);
       continue;
     }
-    const extra = Object.keys(inp).filter((k) => k !== "from" && k !== "select");
+    const extra = Object.keys(inp).filter((k) => k !== "from" && k !== "select" && k !== "output");
     if (extra.length > 0) {
-      problems.push(`node "${id}".inputs[${j}] has unsupported key(s): ${extra.join(", ")} (allowed: from, select)`);
+      problems.push(`node "${id}".inputs[${j}] has unsupported key(s): ${extra.join(", ")} (allowed: from, select/output)`);
+      continue;
+    }
+    if (schemaVersion === 2) {
+      if (inp.select !== void 0) {
+        problems.push(`node "${id}".inputs[${j}].select is legacy-only; schemaVersion 2 must use output`);
+        continue;
+      }
+      if (inp.output === void 0) {
+        out.push({ from: inp.from });
+        continue;
+      }
+      if (typeof inp.output !== "string" || !SEGMENT_RE.test(inp.output)) {
+        problems.push(`node "${id}".inputs[${j}].output must be a stable key matching ${SEGMENT_RE}`);
+        continue;
+      }
+      out.push({ from: inp.from, output: inp.output });
+      continue;
+    }
+    if (inp.output !== void 0) {
+      problems.push(`node "${id}".inputs[${j}].output requires schemaVersion 2`);
       continue;
     }
     if (inp.select === void 0) {
@@ -3235,21 +3387,6 @@ function writePendingWait(runDir, input) {
   return wait;
 }
 
-// src/workflows/v3/artifact-contract.ts
-var MANIFEST_FILE_KINDS = [
-  "markdown",
-  "json",
-  "text",
-  "code",
-  "log",
-  "binary",
-  "directory"
-];
-var MANIFEST_SUMMARY_MAX_BYTES = 4 * 1024;
-var MANIFEST_PREVIEW_MAX_BYTES = 4 * 1024;
-var MANIFEST_STATUSES = ["ok", "fail"];
-var MANIFEST_SCHEMA_VERSION = 1;
-
 // src/workflows/v3/contract.ts
 var GOAL_ENV = {
   /** Path to the single-sentence goal text file. */
@@ -3730,7 +3867,7 @@ function readAndVerifyV3HostSuccessResult(input) {
       `v3 host success result is invalid JSON: ${err instanceof Error ? err.message : String(err)}`
     );
   }
-  if (!isRecord2(raw)) throw new Error("v3 host success result must be an object");
+  if (!isRecord3(raw)) throw new Error("v3 host success result must be an object");
   const allowed = /* @__PURE__ */ new Set([
     "schemaVersion",
     "runId",
@@ -3763,13 +3900,13 @@ function readAndVerifyV3HostSuccessResult(input) {
   ]) {
     if (raw[key] !== input[key]) throw new Error(`v3 host success result ${key} mismatch`);
   }
-  if (!isRecord2(raw.externalRefs)) throw new Error("v3 host success result externalRefs must be an object");
+  if (!isRecord3(raw.externalRefs)) throw new Error("v3 host success result externalRefs must be an object");
   canonicalJson(raw.output);
   canonicalJson(raw.externalRefs);
   return raw;
 }
 function parsePreparedHostInput(raw) {
-  if (!isRecord2(raw)) throw new Error("v3 host input sidecar must be an object");
+  if (!isRecord3(raw)) throw new Error("v3 host input sidecar must be an object");
   const allowed = /* @__PURE__ */ new Set([
     "schemaVersion",
     "runId",
@@ -3890,12 +4027,12 @@ function assertDirectory(path, label) {
 function sha256(value) {
   return createHash5("sha256").update(value).digest("hex");
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 // src/workflows/v3/shared-node-runtime.ts
-function renderGoalFile(goal, resultSchema, loopCtx, nodeInstructions, hasWorkflowParams = false) {
+function renderGoalFile(goal, resultSchema, loopCtx, nodeInstructions, hasWorkflowParams = false, outputs) {
   const E = GOAL_ENV;
   const kinds = MANIFEST_FILE_KINDS.join(" | ");
   const [okStatus, failStatus] = MANIFEST_STATUSES;
@@ -3913,6 +4050,16 @@ function renderGoalFile(goal, resultSchema, loopCtx, nodeInstructions, hasWorkfl
     `List \`result.json\` in the manifest \`files\` array like any other product (its \`path\` is exactly "result.json"). A missing or schema-violating result.json blocks this node.`,
     ""
   ] : [];
+  const artifactSection = outputs ? [
+    "## Public artifact outputs (REQUIRED for this node)",
+    "These stable output keys are part of the Workflow interface. Write every declared path under the output directory and list it in the success Manifest with the exact kind:",
+    "",
+    "  " + JSON.stringify(outputs),
+    "",
+    "Manifest `name` is presentation-only and may be human-readable; downstream nodes resolve these products by output key \u2192 declared path.",
+    "A missing path or mismatched kind blocks the run and requires a Workflow revision; ordinary retry is disabled.",
+    ""
+  ] : [];
   const loopSection = loopCtx ? [
     "## Loop context",
     `This node runs inside loop "${loopCtx.loopId}", iteration ${loopCtx.iteration} of at most ${loopCtx.maxIterations}.`,
@@ -3937,6 +4084,7 @@ function renderGoalFile(goal, resultSchema, loopCtx, nodeInstructions, hasWorkfl
     ...instructionsSection,
     ...paramsSection,
     ...loopSection,
+    ...artifactSection,
     "## How to complete this node",
     "You are an autonomous agent completing exactly ONE botmux v3 workflow node.",
     "Work toward the goal above until it is done, then stop. Do NOT ask the user with interactive tools (they are disabled in this mode). If you genuinely need a human DECISION to proceed, use the human-ask escape hatch described below (also available as the `botmux-goal-ask` skill).",
@@ -3978,6 +4126,8 @@ function classifyTerminal(errorClass, opts) {
   switch (errorClass) {
     case "manifestInvalid":
     // agent wrote a bad manifest — a retry may fix it
+    case "artifactContractInvalid":
+    // definition/manifest public product mismatch
     case "resultInvalid":
       return "blocked";
     case "workerError":
@@ -5482,7 +5632,8 @@ async function runWorkflow(dag, deps, opts) {
         node.resultSchema,
         loopCtx,
         node.override?.systemPromptAppend,
-        !!workflowDataPath
+        !!workflowDataPath,
+        node.outputs
       )
     );
     const effSnap = mergeNodeCapability(botSnap, node.override);
@@ -5720,6 +5871,20 @@ async function runWorkflow(dag, deps, opts) {
             return;
           }
         }
+        const artifactContract = validateManifestArtifactContract(node.outputs, verdict.manifest);
+        if (!artifactContract.ok) {
+          appendWorkerOutcome({
+            type: "nodeBlocked",
+            nodeId: node.id,
+            ...instanceId ? { instanceId } : {},
+            attemptId,
+            errorClass: "artifactContractInvalid",
+            errorCode: "OUTPUT_CONTRACT_VIOLATION",
+            recovery: "reviseWorkflow",
+            message: artifactContract.problems.join("; ")
+          });
+          return;
+        }
         appendWorkerOutcome({
           type: "nodeSucceeded",
           nodeId: node.id,
@@ -5975,8 +6140,9 @@ ${request.reason}
       depends: bodyDef.depends.map((d) => ({ from: loopInstanceId(ref.loopId, ref.iteration, d.from) })),
       inputs: bodyDef.inputs.map((r) => ({
         from: loopInstanceId(ref.loopId, ref.iteration, r.from),
-        ...r.select ? { select: r.select } : {}
+        ...r.select ? { select: r.select } : {},
         // P3: 实例化时保留 selector
+        ...r.output !== void 0 ? { output: r.output } : {}
       }))
     };
   }
@@ -6176,7 +6342,7 @@ ${request.reason}
       });
     }
     const latestSuccess = (key) => [...events].reverse().find((e) => e.type === "nodeSucceeded" && (e.instanceId ?? e.nodeId) === key);
-    const pushFrom = (label, nodeId, filter) => {
+    const pushFrom = (label, nodeId, filter, output) => {
       const key = snap.nodes.get(nodeId)?.effectiveInstanceId ?? nodeId;
       const succ = latestSuccess(key);
       if (!succ) return;
@@ -6186,6 +6352,7 @@ ${request.reason}
         if (filter && !filter(f)) continue;
         inputs.push({
           from: label,
+          ...output ? { output } : {},
           ...succ.instanceId ? { instanceId: succ.instanceId } : {},
           name: f.name,
           path: join6(upstreamOutputDir, f.path),
@@ -6218,9 +6385,14 @@ ${request.reason}
     };
     const selectorMisses = [];
     const pushRef = (ref) => {
-      const filter = ref.select ? (f) => ref.select.name !== void 0 ? f.name === ref.select.name : f.path === ref.select.path : void 0;
+      const source = nodesById.get(ref.from) ?? (loopRef ? nodesById.get(loopRef.loopId).body.nodes.find(
+        (bodyNode) => loopInstanceId(loopRef.loopId, loopRef.iteration, bodyNode.id) === ref.from
+      ) : void 0);
+      const declaredOutputs = source?.type === "loop" ? source.body?.nodes.find((bodyNode) => bodyNode.id === source.output?.from)?.outputs : source?.outputs;
+      const declared = ref.output ? declaredOutputs?.[ref.output] : void 0;
+      const filter = declared ? (f) => f.path === declared.path : ref.select ? (f) => ref.select.name !== void 0 ? f.name === ref.select.name : f.path === ref.select.path : void 0;
       const before = inputs.length;
-      pushFrom(ref.from, ref.from, filter);
+      pushFrom(ref.from, ref.from, filter, ref.output);
       if (ref.select && inputs.length === before) {
         selectorMisses.push({ from: ref.from, reason: "selectorMiss" });
       }