@agentproto/workflow-runtime 0.13.0 → 0.13.1

package/README.md

@@ -301,9 +301,13 @@ try {
 
 This is a manual retry, not a resumable run object — `runWorkflow` has no
 notion of "the run that failed"; the cacheKey is just a namespace the caller
-re-supplies. A first-class `run.retry`/`run.replay` verb that resumes a named
-run without the caller re-threading `workflow`/`input`/`cacheKey` by hand is
-AIP-58 P5, not implemented here.
+re-supplies. A first-class `run.retry` verb that resumes a named run without
+the caller re-threading `workflow`/`input`/`cacheKey` by hand — AIP-58 P5 —
+is a HOST concern, not something this transport-agnostic package implements
+itself: see `@agentproto/runtime`'s `WorkflowRunner.retry()` / the
+`workflow_retry` MCP tool, which owns runId allocation and an always-on
+internal journal (so it works even when the original run never passed a
+`cacheKey` at all — every step it runs is journaled internally either way).
 
 ### Run workspace (AIP-58 §4)
 
@@ -347,12 +351,18 @@ steps:
 
 `path` is read relative to `$run.workspace` (absolute paths, and any path
 that would resolve OUTSIDE the workspace, throw). The step hashes
-(`sha256`) and sizes the file, copies it to `artifactsDir/<sanitized key>`,
-and binds/report an `ArtifactEntry` — `{ key, path: "artifacts/<key>", sha256,
-size, stepId, contentType? }` (`path` here is relative to the RUN WORKSPACE
-ROOT, the parent of `$run.workspace` itself — not the source location).
-Pass `onArtifact` to `runWorkflow` to observe every one recorded, cache hit
-or fresh.
+(`sha256`) and sizes the file, copies it to `artifactsDir/<basename of path,
+sanitized>` — `path: "briefs/latest.md"` above lands at
+`artifacts/latest.md`, keeping the extension, NOT the bare key
+(`artifacts/brief`) — and binds/reports an `ArtifactEntry` — `{ key, path:
+"artifacts/<basename>", sha256, size, stepId, contentType? }` (`path` here is
+relative to the RUN WORKSPACE ROOT, the parent of `$run.workspace` itself —
+not the source location; always read it back rather than assuming a name).
+If two keys' files share a basename, the second one claimed is prefixed with
+its own sanitized key (`artifacts/<key>-<basename>`) instead of silently
+overwriting the first — deterministic, same result run to run. Pass
+`onArtifact` to `runWorkflow` to observe every one recorded, cache hit or
+fresh.
 
 A declarative WORKFLOW.md manifest may instead declare **`outputsFiles`**
 (AIP-16, amended by AIP-58 §4 with `required`) at the top level — checked
@@ -400,11 +410,38 @@ relocates (copies) the file from the ORIGINAL run's `artifactsDir` into the
 CURRENT run's own before returning — the two runs' workspaces stay fully
 disjoint on disk; only the *bytes* are reused, exactly the same way
 `run.replay`'s journal-sourced step reuse is specified to work (AIP-58 §6).
-This is a deliberate, narrower scope than "any cacheable step's output might
-reference a workspace file" — a plain cacheable `tool`/`agent` step whose
-output happens to name a path is NOT relocated automatically; route a
-step's file-shaped output through `kind: "artifact"` (or `outputsFiles`) to
-get cache/replay continuity for it.
+
+A plain cacheable `tool`/`agent` step gets the same treatment, not a narrower
+one (this used to be a documented gap — see "Cache key vs. the run
+workspace" below for why it had to stop being one):
+
+- **Hashing ignores the workspace's identity.** `hashResolvedInputs`
+  replaces every occurrence of `ctx.workspace` inside the serialized
+  resolved input/prompt (including trailing subpaths, e.g.
+  `<workspace>/cleaned/out.txt`) with a stable placeholder before hashing.
+  Two runs of the same logical step under the same `cacheKey` hash
+  identically even though AIP-58 §4 gives each one a fresh, disjoint
+  workspace directory — without this, ANY step whose input/prompt names
+  `$run.workspace` / `{{run.workspace}}` / `_workflowFsRoot` could never hit
+  the journal at all.
+- **A hit relocates forward.** On a hit, every workspace-relative file/
+  directory the entry recorded (`StepCacheEntry.workspaceFiles` — collected,
+  best-effort, from every string in the step's output that resolved to a
+  real path under the ORIGINAL run's workspace) is copied into the matching
+  path under the CURRENT run's own; the recorded output's path strings are
+  then rewritten from the original workspace onto the current one. A
+  downstream step whose input reads one of those paths (`$steps.<id>.path`)
+  finds the bytes there, not just the (by-then-gone) original run's.
+  Best-effort, same posture as the `artifact` step's own relocation: a
+  source already swept by a host's `scratch/` retention policy is not this
+  run's problem to recover.
+- **Still no cross-step content hashing.** This closes the *workspace-path*
+  gap only — the journal still hashes each step's own resolved inputs, not
+  a transitive hash of everything upstream. A step whose resolved input is
+  an opaque reference that stays textually identical across runs (a fixed
+  relative filename, an id) replays from cache on that basis alone,
+  regardless of whether the value behind that reference changed upstream —
+  same limitation any resolved-input-hash cache has, workspace or not.
 
 ### Step lifecycle callbacks
 

package/dist/index.d.ts

@@ -431,7 +431,11 @@ interface AgentStep {
 interface ArtifactStep {
     kind: "artifact";
     id: string;
-    /** Artifact key — also becomes its filename under `artifactsDir` (sanitized). */
+    /** Artifact key — identifies this artifact for `workflow_artifact_get`/
+     *  `workflow_publish`. Its on-disk filename under `artifactsDir` is
+     *  `path`'s own basename (sanitized), not the key — see {@link
+     *  ArtifactEntry.path} — unless another key's file shares the same
+     *  basename, in which case the key disambiguates it (F42). */
     key: Selector<string> | string;
     /** Path to the source file. Relative to `$run.workspace`; MUST resolve
      *  inside it (an absolute path or a `..`-escaping relative one throws). */
@@ -440,10 +444,15 @@ interface ArtifactStep {
 }
 /**
  * AIP-58 §4/§1 `ArtifactEntry` — one run-scoped copy of a declared output
- * file. `path` is always `"artifacts/<sanitized key>"`, relative to the RUN
- * WORKSPACE ROOT (`<runsRoot>/<runId>/`, the parent of `$run.workspace`
- * itself) — never the original in-workspace location the file was read
- * from.
+ * file. `path` is `"artifacts/<basename>"` (F42: the declared source file's
+ * OWN basename, sanitized — e.g. `outputsFiles.pdf: {path: transcript.pdf}`
+ * ⇒ `artifacts/transcript.pdf` — keeping the extension, unlike the bare key),
+ * relative to the RUN WORKSPACE ROOT (`<runsRoot>/<runId>/`, the parent of
+ * `$run.workspace` itself) — never the original in-workspace location the
+ * file was read from. Two keys whose files share a basename get the SECOND
+ * one's name prefixed with its own sanitized key instead (deterministic,
+ * never a silent overwrite) — always read `path` back rather than assuming
+ * `artifacts/<key>` or `artifacts/<basename(path)>`.
  */
 interface ArtifactEntry {
     key: string;
@@ -691,6 +700,20 @@ interface StepCacheEntry {
      *  §4 forbids two runs sharing a workspace) copies the file forward from
      *  here into the new run's own `artifactsDir` instead of re-declaring it. */
     artifactsDirAtCache?: string;
+    /** Set only for a cacheable `tool`/`agent` step (see `hashResolvedInputs`/
+     *  `buildCacheEntry` in `run-workflow.ts`) whenever the host wires a run
+     *  workspace: the absolute `$run.workspace` / `_workflowFsRoot` path this
+     *  entry was cached under. A hit in a LATER run (a different workspace —
+     *  AIP-58 §4 forbids two runs sharing one) rewrites `output`'s path
+     *  strings from here onto the new run's own, and relocates
+     *  {@link workspaceFiles} the same way. */
+    workspaceAtCache?: string;
+    /** Workspace-relative files/directories (under {@link workspaceAtCache})
+     *  this entry's `output` pointed at and that existed on disk when the
+     *  entry was written — copied forward into a later cache-hit run's own
+     *  workspace so a downstream step reading one of these paths finds the
+     *  bytes there too, not just in the original (by-then-gone) run's. */
+    workspaceFiles?: readonly string[];
 }
 /** Opt-in journal for cacheable steps. Host-injected; file-backed in the runtime. */
 interface StepCache {

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { runTool } from '@agentproto/driver';
 import { createHash } from 'crypto';
 import { execFile } from 'child_process';
-import { stat, readFile, mkdir, writeFile, appendFile, readdir, copyFile } from 'fs/promises';
+import { stat, readFile, mkdir, writeFile, appendFile, readdir, copyFile, cp } from 'fs/promises';
 import { join, dirname, isAbsolute, basename, resolve, relative } from 'path';
 import { z } from 'zod';
 import { assertKnownStepRefs } from '@agentproto/workflow';
@@ -1131,8 +1131,74 @@ function spentUsd(state) {
   for (const c of state.costBySession.values()) total += c;
   return total;
 }
-function hashResolvedInputs(kind, resolved) {
-  return createHash("sha256").update(`${kind}\0${JSON.stringify(resolved) ?? "undefined"}`).digest("hex");
+var WORKSPACE_HASH_PLACEHOLDER = "\0$run.workspace\0";
+function hashResolvedInputs(kind, resolved, workspace) {
+  const serialized = `${kind}\0${JSON.stringify(resolved) ?? "undefined"}`;
+  const normalized = workspace ? serialized.split(workspace).join(WORKSPACE_HASH_PLACEHOLDER) : serialized;
+  return createHash("sha256").update(normalized).digest("hex");
+}
+function rewriteWorkspacePaths(value, from, to) {
+  if (typeof value === "string") return value.split(from).join(to);
+  if (Array.isArray(value)) return value.map((v) => rewriteWorkspacePaths(v, from, to));
+  if (value !== null && typeof value === "object" && value.constructor === Object) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = rewriteWorkspacePaths(v, from, to);
+    return out;
+  }
+  return value;
+}
+function collectWorkspaceCandidates(value, workspace, out) {
+  if (typeof value === "string") {
+    if (value === workspace || value.startsWith(`${workspace}/`)) {
+      const rel = relative(workspace, value);
+      if (rel !== "" && !rel.startsWith("..") && !isAbsolute(rel)) out.add(rel);
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const v of value) collectWorkspaceCandidates(v, workspace, out);
+    return;
+  }
+  if (value !== null && typeof value === "object" && value.constructor === Object) {
+    for (const v of Object.values(value)) collectWorkspaceCandidates(v, workspace, out);
+  }
+}
+async function collectWorkspaceFiles(out, workspace) {
+  const candidates = /* @__PURE__ */ new Set();
+  collectWorkspaceCandidates(out, workspace, candidates);
+  const files = [];
+  for (const rel of candidates) {
+    try {
+      await stat(join(workspace, rel));
+      files.push(rel);
+    } catch {
+    }
+  }
+  return files;
+}
+async function buildCacheEntry(ctx, out, hash) {
+  if (ctx.workspace === void 0) return { output: out, resolvedInputHash: hash };
+  const workspaceFiles = await collectWorkspaceFiles(out, ctx.workspace);
+  return {
+    output: out,
+    resolvedInputHash: hash,
+    workspaceAtCache: ctx.workspace,
+    ...workspaceFiles.length > 0 ? { workspaceFiles } : {}
+  };
+}
+async function relocateCachedOutput(ctx, entry) {
+  const from = entry.workspaceAtCache;
+  const to = ctx.workspace;
+  if (from === void 0 || to === void 0 || from === to) return entry.output;
+  for (const rel of entry.workspaceFiles ?? []) {
+    const dest = join(to, rel);
+    try {
+      await mkdir(dirname(dest), { recursive: true });
+      await cp(join(from, rel), dest, { recursive: true });
+    } catch {
+    }
+  }
+  return rewriteWorkspacePaths(entry.output, from, to);
 }
 function stepJournalKey(ctx, step) {
   return `${ctx.cacheKey}\0${step.id}\0${step.kind}${ctx.cacheKeySuffix ?? ""}`;
@@ -1149,10 +1215,10 @@ function completeStep(ctx, stepId, out) {
 }
 async function readStepCache(ctx, step, resolvedInputs) {
   const key = stepJournalKey(ctx, step);
-  const hash = hashResolvedInputs(step.kind, resolvedInputs);
+  const hash = hashResolvedInputs(step.kind, resolvedInputs, ctx.workspace);
   const entry = await ctx.cache.get(key);
   if (entry !== void 0 && entry.resolvedInputHash === hash) {
-    return { hit: true, output: entry.output };
+    return { hit: true, output: await relocateCachedOutput(ctx, entry) };
   }
   return { hit: false, key, hash };
 }
@@ -1509,7 +1575,7 @@ async function execStepBody(step, ctx, item, index) {
       if (c.hit) return cacheHit(ctx, step, c.output);
       ctx.onStepStart?.(step.id);
       const out = await runIt();
-      await ctx.cache.set(c.key, { output: out, resolvedInputHash: c.hash });
+      await ctx.cache.set(c.key, await buildCacheEntry(ctx, out, c.hash));
       return out;
     }
     case "transform":
@@ -1681,7 +1747,8 @@ async function execStepBody(step, ctx, item, index) {
         cacheKey: ctx.cacheKey,
         runGateCommand: ctx.runGateCommand,
         onGateReport: ctx.onGateReport,
-        spawned: ctx.spawned
+        spawned: ctx.spawned,
+        usedArtifactNames: ctx.usedArtifactNames
       });
       return child.output;
     }
@@ -1697,7 +1764,7 @@ async function execStepBody(step, ctx, item, index) {
       const c = await readStepCache(ctx, step, resolved);
       if (c.hit) return cacheHit(ctx, step, c.output);
       const out = await execAgentStep(step, ctx, b);
-      await ctx.cache.set(c.key, { output: out, resolvedInputHash: c.hash });
+      await ctx.cache.set(c.key, await buildCacheEntry(ctx, out, c.hash));
       return out;
     }
     case "gate":
@@ -1706,11 +1773,24 @@ async function execStepBody(step, ctx, item, index) {
       return execArtifactStep(step, ctx, b);
   }
 }
-function sanitizeArtifactKey(key) {
-  const cleaned = key.replace(/[^a-zA-Z0-9._-]/g, "_");
+function sanitizeArtifactFilename(name) {
+  const cleaned = name.replace(/[^a-zA-Z0-9._-]/g, "_");
   return cleaned.length > 0 ? cleaned : "artifact";
 }
-async function copyIntoArtifacts(stepId, key, rawPath, workspace, artifactsDir, contentType) {
+function reserveArtifactDestName(rawPath, key, usedNames) {
+  const base = sanitizeArtifactFilename(basename(rawPath));
+  let candidate = base;
+  if (usedNames.has(candidate)) {
+    const keyPart = sanitizeArtifactFilename(key);
+    candidate = `${keyPart}-${base}`;
+    for (let n = 2; usedNames.has(candidate); n++) {
+      candidate = `${keyPart}-${n}-${base}`;
+    }
+  }
+  usedNames.add(candidate);
+  return candidate;
+}
+async function copyIntoArtifacts(stepId, key, rawPath, workspace, artifactsDir, contentType, usedNames) {
   const abs = isAbsolute(rawPath) ? resolve(rawPath) : resolve(workspace, rawPath);
   const rel = relative(workspace, abs);
   if (rel.startsWith("..") || isAbsolute(rel)) {
@@ -1718,7 +1798,7 @@ async function copyIntoArtifacts(stepId, key, rawPath, workspace, artifactsDir,
   }
   const buf = await readFile(abs);
   const sha256 = createHash("sha256").update(buf).digest("hex");
-  const destName = sanitizeArtifactKey(key);
+  const destName = reserveArtifactDestName(rawPath, key, usedNames);
   await mkdir(artifactsDir, { recursive: true });
   await writeFile(join(artifactsDir, destName), buf);
   return {
@@ -1742,12 +1822,13 @@ async function execArtifactStep(step, ctx, b) {
   const resolvedInputs = { key, path: rawPath };
   const cacheOn = ctx.cache !== void 0 && ctx.cacheKey !== void 0;
   const journalKey = cacheOn ? stepJournalKey(ctx, step) : void 0;
-  const hash = cacheOn ? hashResolvedInputs(step.kind, resolvedInputs) : void 0;
+  const hash = cacheOn ? hashResolvedInputs(step.kind, resolvedInputs, ctx.workspace) : void 0;
   if (cacheOn) {
     const entry = await ctx.cache.get(journalKey);
     if (entry !== void 0 && entry.resolvedInputHash === hash) {
       const out2 = entry.output;
-      const destName = sanitizeArtifactKey(key);
+      const destName = out2.path.slice("artifacts/".length);
+      ctx.usedArtifactNames?.add(destName);
       const destAbs = join(artifactsDir, destName);
       const srcAbs = join(entry.artifactsDirAtCache ?? artifactsDir, destName);
       if (srcAbs !== destAbs) {
@@ -1762,7 +1843,7 @@ async function execArtifactStep(step, ctx, b) {
     }
   }
   ctx.onStepStart?.(step.id);
-  const out = await copyIntoArtifacts(step.id, key, rawPath, workspace, artifactsDir, contentType);
+  const out = await copyIntoArtifacts(step.id, key, rawPath, workspace, artifactsDir, contentType, ctx.usedArtifactNames);
   if (cacheOn) {
     await ctx.cache.set(journalKey, { output: out, resolvedInputHash: hash, artifactsDirAtCache: artifactsDir });
   }
@@ -1780,7 +1861,7 @@ async function checkOutputsFiles(outputsFiles, ctx, workflowId, lastStepId) {
     const abs = isAbsolute(rawPath) ? rawPath : resolve(ctx.workspace, rawPath);
     let out;
     try {
-      out = await copyIntoArtifacts(lastStepId ?? workflowId, key, abs, ctx.workspace, ctx.artifactsDir, contract.contentType);
+      out = await copyIntoArtifacts(lastStepId ?? workflowId, key, abs, ctx.workspace, ctx.artifactsDir, contract.contentType, ctx.usedArtifactNames);
     } catch {
       if (contract.required === true) {
         throw new MissingArtifactError(key, lastStepId);
@@ -1811,7 +1892,11 @@ async function runFinally(steps, ctx, bodyFailed) {
 async function runWorkflowInner(workflow, input, hooks, maxTotalCostUsd) {
   const state = { input, steps: {}, costBySession: /* @__PURE__ */ new Map(), maxTotalCostUsd, cachedHits: /* @__PURE__ */ new Set() };
   const ownsScope = hooks.spawned === void 0;
-  const ctx = { state, ...hooks, ...ownsScope ? { spawned: [] } : {} };
+  const ctx = {
+    state,
+    ...hooks,
+    ...ownsScope ? { spawned: [], usedArtifactNames: /* @__PURE__ */ new Set() } : {}
+  };
   let lastId;
   let bodyFailed = false;
   try {