taskflow-core 0.2.9 → 0.3.0-beta.1

package/dist/runtime.js

@@ -593,6 +593,52 @@ function flowTreeUsesCwdBridge(def, loadFlow, seenUses = new Set()) {
     }
     return false;
 }
+function flowTreeUsesDeclaredEffects(def, loadFlow, seenUses = new Set()) {
+    if (def.contextSharing === true || def.phases.some((phase) => phase.shareContext === true))
+        return true;
+    if (def.phases.some((phase) => phase.effects !== undefined))
+        return true;
+    for (const phase of def.phases) {
+        const type = phase.type ?? "agent";
+        if ((type === "flow" || type === "expand") && phase.def !== undefined) {
+            // Inline definitions are resolved before their parent phase cache lookup.
+            // Statically inspect authored object/JSON forms. An interpolated/malformed
+            // form is capability-bearing until resolution proves otherwise: otherwise a
+            // prior parent cache row could skip a newly generated resource transaction.
+            const parsed = typeof phase.def === "string" ? safeParse(phase.def) : phase.def;
+            if (parsed === undefined &&
+                typeof phase.def === "string" &&
+                !/[{](?:steps[.]|args[.]|previous[.]|item(?:[.}]|\b)|loop[.]|reflexion[}])/.test(phase.def)) {
+                // A malformed authored literal cannot resolve into a child at runtime;
+                // preserve the established fail-open/cleanup path. Interpolated strings
+                // remain unknown and therefore authority-bearing until resolved.
+                continue;
+            }
+            const child = normalizeInlineDef(parsed, phase.id);
+            if (!child)
+                return true;
+            if (flowTreeUsesDeclaredEffects(child, loadFlow, seenUses))
+                return true;
+        }
+        if (type === "flow" && phase.use) {
+            if (seenUses.has(phase.use))
+                continue;
+            seenUses.add(phase.use);
+            if (!loadFlow)
+                return true;
+            try {
+                const child = loadFlow(phase.use);
+                if (child && flowTreeUsesDeclaredEffects(child, loadFlow, seenUses))
+                    return true;
+            }
+            catch {
+                // A mutable/unavailable saved flow is authority-bearing until proven otherwise.
+                return true;
+            }
+        }
+    }
+    return false;
+}
 /**
  * Freeze the saved-flow namespace for one top-level execution. Capability
  * discovery and phase execution must observe the same definition, including
@@ -600,18 +646,21 @@ function flowTreeUsesCwdBridge(def, loadFlow, seenUses = new Set()) {
  * after the root binding and cache policy were decided.
  */
 function snapshotFlowLoader(deps) {
-    if (!deps.loadFlow || deps._flowLoaderSnapshot)
+    if ((!deps.loadSavedFlow && !deps.loadFlow) || deps._flowLoaderSnapshot)
         return deps;
-    const source = deps.loadFlow;
+    const source = deps.loadSavedFlow
+        ?? ((name) => {
+            const def = deps.loadFlow?.(name);
+            return def === undefined ? undefined : { def };
+        });
     const snapshot = new Map();
-    const loadFlow = (name) => {
+    const loadSavedFlow = (name) => {
         let entry = snapshot.get(name);
         if (!entry) {
             try {
                 const loaded = source(name);
-                // Loader-owned objects may be mutated asynchronously. Capability scan
-                // and execution operate on a detached structured snapshot, never the
-                // loader's live reference.
+                // Definition and provenance are detached and cached as one value, so
+                // mutable discovery cannot pair data from one flow with another path.
                 entry = { ok: true, value: loaded === undefined ? undefined : structuredClone(loaded) };
             }
             catch (error) {
@@ -623,7 +672,8 @@ function snapshotFlowLoader(deps) {
             throw entry.error;
         return entry.value;
     };
-    return { ...deps, loadFlow, _flowLoaderSnapshot: snapshot };
+    const loadFlow = (name) => loadSavedFlow(name)?.def;
+    return { ...deps, loadFlow, loadSavedFlow, _flowLoaderSnapshot: snapshot };
 }
 function sameDirectoryIdentity(a, b) {
     return !!a && !!b && a.canonicalPath === b.canonicalPath && a.device === b.device && a.inode === b.inode;
@@ -860,9 +910,131 @@ async function executePhaseImpl(phase, state, deps, prior, emitProgress, _retryD
         }
         return ps;
     };
+    const executeInnerWithDeclaredEffects = async (innerDeps) => {
+        const effects = phase.effects;
+        if (effects === undefined || (Array.isArray(effects) && effects.length === 0)) {
+            return executePhaseInner(phase, state, innerDeps, prior, emitProgress, _retryDepth, innerOpts);
+        }
+        if (!Array.isArray(effects)) {
+            return {
+                id: phase.id,
+                status: "failed",
+                error: "trusted-effects admission failed (effects-not-array): effects must be an array",
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            };
+        }
+        const te = await import("./effects/index.js");
+        const effectValidation = te.validateDeclaredEffectsBeforeAdmission(effects);
+        if (!effectValidation.ok) {
+            return {
+                id: phase.id,
+                status: "failed",
+                error: `trusted-effects admission failed (${effectValidation.code}): ${effectValidation.reason}`,
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            };
+        }
+        const hasWrites = te.hasDeclaredFsWriteEffects(effects);
+        let binding = innerDeps._workspaceBinding;
+        if (hasWrites && !binding) {
+            const effectiveCwd = resolveEffCwd(innerDeps, phase);
+            try {
+                binding = await innerDeps.workspaceSession?.bindPhase({
+                    invocationRoot: effectiveCwd,
+                    runId: state.runId,
+                    phaseId: phase.id,
+                    argDefinitions: state.def.args ?? {},
+                    argValues: state.args,
+                });
+            }
+            catch (error) {
+                return {
+                    id: phase.id,
+                    status: "failed",
+                    error: error instanceof Error ? error.message : String(error),
+                    endedAt: Date.now(),
+                    usage: emptyUsage(),
+                };
+            }
+        }
+        if (hasWrites && !binding) {
+            return {
+                id: phase.id,
+                status: "failed",
+                error: "TFWS_RESOURCE_AUTHORITY_UNAVAILABLE: declared fs.write requires a workspace authority binding",
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            };
+        }
+        const admitted = binding
+            ? await te.preparePhaseDeclaredFsWrites(binding, { effects, signal: innerDeps.signal })
+            : { ok: true, prepared: undefined };
+        if (!admitted.ok) {
+            return {
+                id: phase.id,
+                status: "failed",
+                error: `trusted-effects admission failed (${admitted.code}): ${admitted.reason}`,
+                endedAt: Date.now(),
+                usage: emptyUsage(),
+            };
+        }
+        let ps;
+        try {
+            // The file transaction owns admission for declared targets. Do not open a
+            // second broad generation-only intent around each nested runner call.
+            ps = await executePhaseInner(phase, state, hasWrites
+                ? { ...innerDeps, _workspaceBinding: undefined, _disableCache: true }
+                : innerDeps, prior, emitProgress, _retryDepth, innerOpts);
+        }
+        catch (error) {
+            if (admitted.prepared) {
+                await te.rejectPreparedDeclaredFsWrites(admitted.prepared, `phase body threw: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            throw error;
+        }
+        if (!admitted.prepared)
+            return ps;
+        if (ps.status !== "done") {
+            try {
+                await te.rejectPreparedDeclaredFsWrites(admitted.prepared, ps.error ?? `phase ended with status ${ps.status}`);
+            }
+            catch (error) {
+                return {
+                    ...ps,
+                    status: "failed",
+                    error: `${ps.error ?? "phase failed"}; trusted-effects restore failed: ${error instanceof Error ? error.message : String(error)}`,
+                    endedAt: Date.now(),
+                };
+            }
+            return ps;
+        }
+        const finalized = await te.finalizePreparedDeclaredFsWrites(admitted.prepared, ps.output ?? "");
+        if (!finalized.ok) {
+            return {
+                ...ps,
+                status: "failed",
+                error: `trusted-effects finalize failed (${finalized.code}): ${finalized.reason}`,
+                sideEffect: true,
+                endedAt: Date.now(),
+            };
+        }
+        return {
+            ...ps,
+            sideEffect: finalized.committedPaths.length > 0 || ps.sideEffect,
+            warnings: finalized.committedPaths.length === 0
+                ? ps.warnings
+                : [
+                    ...(ps.warnings ?? []),
+                    `trusted-effects: committed ${finalized.committedPaths.join(", ")} via resource intent ${finalized.intentId}`,
+                ],
+        };
+    };
     const cwdArg = cwdArgName(phase.cwd);
     let innerOpts = { ...opts, upstreamDeps: deps };
-    if ((cwdArg !== undefined || deps._dynamic === true || deps._cwdBoundary !== undefined) && phase.when !== undefined) {
+    if ((cwdArg !== undefined || deps._dynamic === true || deps._cwdBoundary !== undefined ||
+        (Array.isArray(phase.effects) && (phase.effects?.length ?? 0) > 0)) &&
+        phase.when !== undefined) {
         const whenReadRefs = [];
         const whenCtx = buildInterpolationContext(state, lastCompletedOutput(state, phase), undefined, (ref) => whenReadRefs.push(ref));
         const whenResult = evaluateCondition(phase.when, whenCtx);
@@ -960,7 +1132,7 @@ async function executePhaseImpl(phase, state, deps, prior, emitProgress, _retryD
             _disableCache: true,
             _workspaceBinding: workspaceBinding,
         };
-        const ps = await executePhaseInner(phase, state, innerDeps, prior, emitProgress, _retryDepth, innerOpts);
+        const ps = await executeInnerWithDeclaredEffects(innerDeps);
         ps.warnings = [
             ...(ps.warnings ?? []),
             `cwd bridge: resolve-only {args.${cwdArg}} -> ${bound.value.logicalPath}; principal/root authorization, cross-process lease, and write journal are active, but filesystem access outside this directory is not sandbox-enforced`,
@@ -1006,17 +1178,17 @@ async function executePhaseImpl(phase, state, deps, prior, emitProgress, _retryD
                 usage: emptyUsage(),
             });
         }
-        return stamp(await executePhaseInner(phase, state, {
+        return stamp(await executeInnerWithDeclaredEffects({
             ...deps,
             _cwdOverride: selected.canonicalPath,
             _cwdBoundary: selected.canonicalPath,
             _cacheCwdIdentity: selected.canonicalPath,
             _workspaceBinding: narrowedBinding,
-        }, prior, emitProgress, _retryDepth, innerOpts));
+        }));
     }
     // Non-keyword cwd (or none): no workspace lifecycle — run directly.
     if (!isWorkspaceKeyword(phase.cwd)) {
-        return stamp(await executePhaseInner(phase, state, deps, prior, emitProgress, _retryDepth, innerOpts));
+        return stamp(await executeInnerWithDeclaredEffects(deps));
     }
     let ws;
     try {
@@ -1032,7 +1204,7 @@ async function executePhaseImpl(phase, state, deps, prior, emitProgress, _retryD
     }
     const innerDeps = ws ? { ...deps, _cwdOverride: ws.dir, _cacheCwdIdentity: ws.dir } : deps;
     try {
-        const ps = await executePhaseInner(phase, state, innerDeps, prior, emitProgress, _retryDepth, innerOpts);
+        const ps = await executeInnerWithDeclaredEffects(innerDeps);
         if (ws && (ws.kind !== "inherited" || ws.note)) {
             const tag = ws.kind === "inherited" ? "workspace" : `workspace:${ws.kind}`;
             const msg = ws.note ? `${tag} — ${ws.note}` : `${tag} at ${ws.dir}`;
@@ -1150,6 +1322,11 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
     if (phase.idempotent === false) {
         cacheScope = "off";
     }
+    // Declared fs.write → resource transaction finalize; never cache-skip promotion.
+    if (Array.isArray(phase.effects) &&
+        (phase.effects ?? []).some((e) => e?.kind === "fs.write")) {
+        cacheScope = "off";
+    }
     if (deps._disableCache) {
         cacheScope = "off";
     }
@@ -1165,7 +1342,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         flowDefHash: state.flowDefHash === "failed" ? undefined : state.flowDefHash,
         phaseFp: state.phaseFingerprints?.[phase.id],
         forceRerun: opts?.forceRerun,
-        thinking: phase.thinking,
+        thinking: phase.thinking ?? deps.globalThinking,
         tools: phase.tools,
         preRead,
         agentScope: state.def.agentScope,
@@ -2154,7 +2331,7 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
     }
     // script — zero-token shell (spawn/timeout/size caps in runtime/phases/script.ts)
     if (type === "script") {
-        const { runScriptCommand, scriptResultToPhaseState, scriptSpawnErrorToPhaseState } = await import("./runtime/phases/script.js");
+        const { resolveScriptCwd, runScriptCommand, scriptResultToPhaseState, scriptSpawnErrorToPhaseState } = await import("./runtime/phases/script.js");
         const cmd = phase.run;
         if (!cmd) {
             return {
@@ -2179,18 +2356,44 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         if (stdinInterp?.missing.length)
             warnUnresolvedRefs(phase.id, stdinInterp.missing);
         const stdinInput = stdinInterp?.text;
-        const ck = cacheKeys(cc, [phase.id, JSON.stringify(interpRunText), stdinInput ?? ""]);
+        const reads = readRefs.length ? readRefsToReads(readRefs, state) : undefined;
+        let scriptCwd;
+        const hasExplicitScriptCwd = deps._cwdOverride !== undefined || phase.cwd !== undefined;
+        try {
+            scriptCwd = resolveScriptCwd({
+                executionCwd: effCwd,
+                hasExplicitCwd: hasExplicitScriptCwd,
+                scriptCwd: state.def.scriptCwd,
+                flowSourceFile: state.flowSourceFile,
+                flowSourceDirIdentity: state.flowSourceDirIdentity,
+            });
+        }
+        catch (err) {
+            return scriptSpawnErrorToPhaseState(phase.id, err, {
+                inputHash: hashInput(phase.id, JSON.stringify(interpRunText), stdinInput ?? "", "script-cwd-unresolved"),
+                reads,
+            });
+        }
+        if (deps._cwdBoundary && !isPathWithin(deps._cwdBoundary, scriptCwd)) {
+            return scriptSpawnErrorToPhaseState(phase.id, new Error("TF_CWD_BOUNDARY_ESCAPE: script cwd must remain inside the inherited cwd boundary"), {
+                inputHash: hashInput(phase.id, JSON.stringify(interpRunText), stdinInput ?? "", "script-cwd-boundary-escape"),
+                reads,
+            });
+        }
+        const ck = cacheKeys(cc, [phase.id, JSON.stringify(interpRunText), stdinInput ?? "", `cwd:${scriptCwd}`]);
         const inputHash = ck.key;
         const cached = cachedPhase(cc, ck);
         if (cached)
             return cached;
         const SCRIPT_TIMEOUT_MS = phase.timeout ?? 60_000;
-        const reads = readRefs.length ? readRefsToReads(readRefs, state) : undefined;
         try {
             const invoke = () => runScriptCommand({
                 interpRunText,
                 arrayForm: Array.isArray(cmd),
-                cwd: effCwd,
+                cwd: scriptCwd,
+                cwdIdentity: !hasExplicitScriptCwd && state.def.scriptCwd === "flow"
+                    ? state.flowSourceDirIdentity
+                    : undefined,
                 signal: deps.signal,
                 stdinInput,
                 timeoutMs: SCRIPT_TIMEOUT_MS,
@@ -2420,6 +2623,8 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             }
         }
         let subDef;
+        let subFlowSourceFile;
+        let subFlowSourceDirIdentity;
         let name;
         let recursionKey; // identity used for cache key + recursion guard
         if (type === "expand" && !hasDef) {
@@ -2526,11 +2731,14 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             const useName = phase.use;
             if (!useName)
                 return failPhase(phase.id, `flow phase '${phase.id}' requires 'use' or 'def'`);
-            if (!deps.loadFlow)
+            if (!deps.loadSavedFlow)
                 return failPhase(phase.id, `flow phase '${phase.id}': no sub-flow loader available`);
-            subDef = deps.loadFlow(useName);
-            if (!subDef)
+            const loaded = deps.loadSavedFlow(useName);
+            if (!loaded)
                 return failPhase(phase.id, `flow phase '${phase.id}': saved flow not found: '${useName}'`);
+            subDef = loaded.def;
+            subFlowSourceFile = loaded.filePath;
+            subFlowSourceDirIdentity = loaded.sourceDirIdentity;
             name = useName;
             recursionKey = useName;
         }
@@ -2553,7 +2761,9 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
         // change between the root pre-scan and this phase (or return aliases), and
         // a bridge-bearing child must never be skipped by a cached parent result.
         const nestedBridgeTree = flowTreeUsesCwdBridge(subDef, deps.loadFlow);
-        if (nestedBridgeTree)
+        const nestedEffectsTree = flowTreeUsesDeclaredEffects(subDef, deps.loadFlow);
+        const nestedResourceTree = nestedBridgeTree || nestedEffectsTree;
+        if (nestedResourceTree)
             deps._disableCache = true;
         // Plugin-error verifier preflight (no-spend gate) BEFORE cache/resume reuse,
         // for SAVED-USE children only. Inline-def children are already gated by the
@@ -2571,11 +2781,11 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
                 return failPhase(phase.id, `flow phase '${phase.id}': sub-flow '${subDef.name}' failed verifier preflight: ${flowPluginErrors.join("; ")}`);
             }
         }
-        const flowCc = nestedBridgeTree ? { ...cc, scope: "off" } : cc;
+        const flowCc = nestedResourceTree ? { ...cc, scope: "off" } : cc;
         // Every sub-flow cache identity includes the resolved definition. A saved
         // flow's name alone is insufficient: its contents can change without the
         // parent definition moving.
-        const flowIdentity = `${hasDef ? "def" : "flow"}:${name}:${JSON.stringify(subDef)}`;
+        const flowIdentity = `${hasDef ? "def" : "flow"}:${name}:${JSON.stringify(subDef)}:source:${subFlowSourceFile ?? ""}:source-dir:${JSON.stringify(subFlowSourceDirIdentity ?? null)}`;
         const ck = cacheKeys(flowCc, [phase.id, flowIdentity, preRead, JSON.stringify(subArgs)]);
         const inputHash = ck.key;
         const cached = cachedPhase(flowCc, ck);
@@ -2606,6 +2816,8 @@ async function executePhaseInner(phase, state, deps, prior, emitProgress, _retry
             createdAt: Date.now(),
             updatedAt: Date.now(),
             cwd: effCwd,
+            flowSourceFile: subFlowSourceFile,
+            flowSourceDirIdentity: subFlowSourceDirIdentity,
         };
         // B8: pass this flow phase's preRead content to every sub-flow phase by
         // wrapping runTask — sub-phase preRead still gets prepended on top of it.
@@ -3728,11 +3940,25 @@ export async function executeTaskflow(state, deps) {
     // mutations or let downstream phases observe stale files. Disable cache and
     // within-run resume reuse across the complete reachable flow tree.
     const bridgeTree = flowTreeUsesCwdBridge(def, deps.loadFlow);
+    const effectsTree = flowTreeUsesDeclaredEffects(def, deps.loadFlow);
+    const resourceTree = bridgeTree || effectsTree;
+    if (effectsTree) {
+        const { validateComposedEffectFlow } = await import("./effects/validate.js");
+        const labelFlow = validateComposedEffectFlow({ name: def.name, phases: def.phases }, {
+            resolveFlow: deps.loadFlow,
+        });
+        if (!labelFlow.ok) {
+            return failBeforeExecution(`Taskflow '${def.name}' EffectIR label flow is invalid: ${labelFlow.issues
+                .filter((issue) => issue.severity === "error")
+                .map((issue) => issue.message)
+                .join("; ")}`);
+        }
+    }
     // Persisted binding is a permanent taint bit: saved-flow definitions can
     // change between resumes, but prior outputs may already depend on filesystem
     // mutations. Never regain cache/rebind privileges merely because the current
     // snapshot no longer declares the bridge.
-    const bridgeTainted = bridgeTree || state.cwdRootBinding !== undefined;
+    const bridgeTainted = resourceTree || state.cwdRootBinding !== undefined;
     if (bridgeTainted) {
         const invocationRoot = directoryIdentity(deps.cwd);
         const statePathRoot = directoryIdentity(state.cwd);
@@ -3744,12 +3970,12 @@ export async function executeTaskflow(state, deps) {
         // phase previously executed without a persisted root binding. Conversely,
         // a host's launch snapshot proves root continuity, not prior bridge
         // authorization: adding a bridge after ordinary phases ran still fails.
-        const isLegacyResume = bridgeTree && recordedRoot === undefined && hasExecutablePriorState;
+        const isLegacyResume = resourceTree && recordedRoot === undefined && hasExecutablePriorState;
         if (isLegacyResume ||
             !sameDirectoryIdentity(statePathRoot, invocationRoot) ||
             (launchRoot !== undefined && !sameDirectoryIdentity(launchRoot, invocationRoot)) ||
             (recordedRoot !== undefined && !sameDirectoryIdentity(recordedRoot, invocationRoot))) {
-            return failBeforeExecution(`Taskflow '${def.name}' cwd-bridge invocation root does not match the run's persisted root; start a new run instead of rebinding on resume`);
+            return failBeforeExecution(`Taskflow '${def.name}' resource-authority invocation root does not match the run's persisted root; start a new run instead of rebinding on resume`);
         }
         state.cwdRootBinding ??= invocationRoot;
         // Freeze the invocation root to the canonical identity we just bound. In
@@ -3765,7 +3991,7 @@ export async function executeTaskflow(state, deps) {
     // control/durability scaffold. This does not upgrade its assurance: the
     // session is deliberately labelled resolve-only and no OS sandbox claim is
     // made. A native session must come from an exact approved host baseline cell.
-    if (bridgeTree && deps.cwdBridgeMode === "resolve-only" && !deps.workspaceSession) {
+    if (resourceTree && (effectsTree || deps.cwdBridgeMode === "resolve-only") && !deps.workspaceSession) {
         try {
             deps = {
                 ...deps,
@@ -3822,7 +4048,7 @@ export async function executeTaskflow(state, deps) {
         // not yet persist compatible input hashes, so it must never blindly trust a
         // prior `done` row.
         const hasPriorState = Object.keys(state.phases).length > 0;
-        if (eventKernelEnabled(deps) && deps._cwdBoundary === undefined && !hasPriorState && canUseEventKernel(def, deps.loadFlow)) {
+        if (eventKernelEnabled(deps) && !effectsTree && deps._cwdBoundary === undefined && !hasPriorState && canUseEventKernel(def, deps.loadFlow)) {
             if (!deps.runTask) {
                 throw new Error("event kernel requires RuntimeDeps.runTask");
             }
@@ -3840,6 +4066,7 @@ export async function executeTaskflow(state, deps) {
                 verifiers: deps.verifiers,
                 requestApproval: deps.requestApproval,
                 loadFlow: deps.loadFlow,
+                loadSavedFlow: deps.loadSavedFlow,
                 _stack: deps._stack,
                 _dynamic: deps._dynamic,
             });