@pellux/goodvibes-sdk 0.37.2 → 1.0.0

package/dist/platform/tools/agent/wrfc-batch-policy.d.ts

@@ -1,5 +1,18 @@
 import type { AgentInput } from './schema.js';
 type BatchTask = NonNullable<AgentInput['tasks']>[number];
+/**
+ * True when the text explicitly asks for a parallel / per-unit / separate-agent
+ * fan-out. Exported for the TUI collapse guard so both guards honour the same
+ * explicit-intent precedent.
+ */
+export declare function userRequestsParallelFanout(text: string | undefined): boolean;
+/**
+ * True when a constraint's text describes the agent topology (parallelism /
+ * spawn-count / separate-agent-per-unit) a fan-out collapse removes. Consulted by
+ * the WRFC controller — only for chains created via a collapse — to mark such a
+ * constraint system-unsatisfiable so it can never fail the review.
+ */
+export declare function isFanoutShapeConstraintText(text: string | undefined): boolean;
 export interface WrfcBatchPolicyDecision {
     readonly kind: 'independent' | 'collapse-to-wrfc';
     readonly reason?: string | undefined;

package/dist/platform/tools/agent/wrfc-batch-policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrfc-batch-policy.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/agent/wrfc-batch-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,KAAK,SAAS,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AA4B1D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,kBAAkB,CAAC;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACzD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACxD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,0BAA0B,CAAC;IACxE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACxD;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE9E;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAAC,GAAG,OAAO,CAIxF;AA0ED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,mBAAmB,GAAG,MAAM,CAAC,EACrD,YAAY,EAAE,MAAM,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAA;CAAE,CAwCnF;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,mBAAmB,CAAC,EAC5C,YAAY,EAAE,MAAM,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAA;CAAE,CAoBnF;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACxD,GAAG,0BAA0B,CA2B7B;AAoED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,UAAU,GAAG,uBAAuB,CAsJlF"}
+{"version":3,"file":"wrfc-batch-policy.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/agent/wrfc-batch-policy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,KAAK,SAAS,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAiD1D;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE5E;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE7E;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,kBAAkB,CAAC;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACzD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACxD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,yBAAyB,GAAG,0BAA0B,CAAC;IACxE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACxD;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE9E;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAAC,GAAG,OAAO,CAIxF;AA0ED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,mBAAmB,GAAG,MAAM,CAAC,EACrD,YAAY,EAAE,MAAM,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAA;CAAE,CAwCnF;AAED,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,mBAAmB,CAAC,EAC5C,YAAY,EAAE,MAAM,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAA;CAAE,CAoBnF;AAED,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACtD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACxD,GAAG,0BAA0B,CA2B7B;AAoED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,UAAU,GAAG,uBAAuB,CAmLlF"}

package/dist/platform/tools/agent/wrfc-batch-policy.js

@@ -12,6 +12,40 @@ const ROLE_ACTION_RE = /\b(?:test|tests|testing|review|reviews|reviewing|verify|
 const IMPLEMENTATION_ACTION_RE = /\b(?:build|implement|create|add|write|fix|repair|update|refactor|change|modify|deliver|make)\b/i;
 const DESIGN_ONLY_ACTION_RE = /\b(?:design|plan|outline|specify|propose|describe)\b/i;
 const NO_WRITE_RE = /\b(?:do\s+not|don't|without)\s+(?:write|modify|edit|create|change)\s+(?:files?|code|source|implementation)\b|\bno[-\s]?write\b|\bread[-\s]?only\b/i;
+/**
+ * High-precision detector for an EXPLICIT user request to run separate agents in
+ * parallel / one per unit of work. This is user intent, exactly like
+ * userProhibitsDelegation is (see wrfc-routing.ts): when the user asks for a
+ * parallel fan-out, the topology guard must not silently collapse it into one
+ * chain. Conservative by design — a plain "build X" never matches; only phrasings
+ * that name a parallel/per-item/separate-agent shape do.
+ */
+const PARALLEL_FANOUT_REQUEST_RE = /\b(?:in\s+parallel|concurrent(?:ly)?)\b|\b(?:separate|independent|dedicated|its?\s+own|one)\s+(?:sub[-\s]?)?agents?\b|\b(?:sub[-\s]?)?agents?\s+(?:in\s+parallel|per\b|for\s+each\b)|\b(?:one|a\s+separate|a\s+dedicated)\s+(?:sub[-\s]?)?agent\s+per\b|\bfan[-\s]?out\b|\bper[-\s]?file\s+(?:sub[-\s]?)?agents?\b/i;
+/**
+ * Detects a constraint whose satisfaction depends on the agent TOPOLOGY the guard
+ * just removed — parallelism, spawn count, or per-unit separate-agent shape. Used
+ * ONLY in combination with a recorded fanoutCollapse (never as a blanket drop): a
+ * constraint matching this shape after a fan-out was collapsed cannot be satisfied
+ * by any fix agent, because the system removed its precondition.
+ */
+const FANOUT_SHAPE_CONSTRAINT_RE = /\b(?:in\s+parallel|parallel(?:ism|ly)?|concurrent(?:ly|cy)?)\b|\b(?:separate|independent|dedicated|distinct|individual|its?\s+own|one|multiple|several)\s+(?:sub[-\s]?)?agents?\b|\b(?:sub[-\s]?)?agents?\s+(?:in\s+parallel|per\b|for\s+each\b|running\s+concurrently)|\b(?:one|a\s+separate|a\s+dedicated|a\s+distinct)\s+(?:sub[-\s]?)?agent\s+per\b|\bfan[-\s]?out\b|\bper[-\s]?file\s+(?:sub[-\s]?)?agents?\b|\bspawn(?:ing)?\s+(?:a\s+)?(?:separate|multiple|several|\d+)\b/i;
+/**
+ * True when the text explicitly asks for a parallel / per-unit / separate-agent
+ * fan-out. Exported for the TUI collapse guard so both guards honour the same
+ * explicit-intent precedent.
+ */
+export function userRequestsParallelFanout(text) {
+    return typeof text === 'string' && PARALLEL_FANOUT_REQUEST_RE.test(text);
+}
+/**
+ * True when a constraint's text describes the agent topology (parallelism /
+ * spawn-count / separate-agent-per-unit) a fan-out collapse removes. Consulted by
+ * the WRFC controller — only for chains created via a collapse — to mark such a
+ * constraint system-unsatisfiable so it can never fail the review.
+ */
+export function isFanoutShapeConstraintText(text) {
+    return typeof text === 'string' && FANOUT_SHAPE_CONSTRAINT_RE.test(text);
+}
 export function isRootReviewRoleTemplate(template) {
     return ROOT_REVIEW_ROLE_TEMPLATES.has((template ?? '').trim().toLowerCase());
 }
@@ -238,6 +272,21 @@ export function evaluateWrfcBatchPolicy(input) {
         if (!wantsWrfc || implementationTaskIndexes.length <= 1) {
             return { kind: 'independent' };
         }
+        // Ruling (WO UX-A item 1): an explicit parallel / per-unit fan-out request is
+        // user intent, exactly like userProhibitsDelegation. When the user explicitly
+        // asked for separate agents in parallel and the batch is a set of independent
+        // implementation deliverables (NOT role-fragmentation — that branch is handled
+        // below), do NOT collapse: honour the request and let the deliverables fan out
+        // (each keeps its own reviewMode). This prevents the unsatisfiable-constraint
+        // billing loop at the source; the collapse paths below still carry a
+        // fanoutCollapse marker as defense-in-depth for the collapses that do happen.
+        const explicitParallel = userRequestsParallelFanout(normalizeTaskText(input.authoritativeTask) ?? normalizeTaskText(input.task));
+        if (explicitParallel) {
+            return {
+                kind: 'independent',
+                reason: `explicit parallel fan-out requested for ${implementationTaskIndexes.length} independent deliverables; honoring the request instead of collapsing into one chain`,
+            };
+        }
         const authoritativeTask = normalizeTaskText(input.authoritativeTask)
             ?? normalizeTaskText(input.task)
             ?? `Complete and integrate ${implementationTaskIndexes.length} reviewed deliverables.`;
@@ -280,6 +329,10 @@ export function evaluateWrfcBatchPolicy(input) {
             dangerously_disable_wrfc: false,
             cohort: input.cohort,
             wrfcSubtasks: implementationTaskIndexes.map((index) => normalizeCompoundSubtask(tasks[index], authoritativeTask)),
+            fanoutCollapse: {
+                requestedAgentCount: implementationTaskIndexes.length,
+                requestedShape: `${implementationTaskIndexes.length} separate implementation agents`,
+            },
         };
         return {
             kind: 'collapse-to-wrfc',
@@ -344,6 +397,13 @@ export function evaluateWrfcBatchPolicy(input) {
         parentNodeId: ownerTask.parentNodeId ?? input.parentNodeId,
         dangerously_disable_wrfc: false,
         cohort: input.cohort,
+        // A role-fragmentation collapse never honours "separate reviewer/tester roots"
+        // (those are lifecycle phases, not what the user asked for). But if the user
+        // ALSO asked for a parallel fan-out, record it so any parallelism/spawn-count
+        // constraint the collapse invalidated cannot fail the review.
+        ...(userRequestsParallelFanout(normalizeTaskText(input.authoritativeTask) ?? normalizeTaskText(input.task))
+            ? { fanoutCollapse: { requestedAgentCount: tasks.length, requestedShape: `${tasks.length} separate agents` } }
+            : {}),
     };
     return {
         kind: 'collapse-to-wrfc',

package/dist/platform/tools/exec/runtime.d.ts

@@ -18,5 +18,15 @@ export declare function isRetryableExecResult(result: ExecCommandResult, allowed
 export declare function createExecTool(processManager: ProcessManager, options?: {
     readonly featureFlags?: Pick<FeatureFlagManager, 'isEnabled'> | null | undefined;
     readonly overflowHandler?: OverflowHandler | undefined;
+    /**
+     * Default working directory used when a call omits the top-level
+     * working_dir (and no single command supplies one to promote). Callers
+     * register this tool with the session/project working directory they
+     * already have in hand (see tools/index.ts registerAllTools) so the
+     * parameter stays genuinely optional for the model instead of a
+     * mandatory-in-practice field that fails a call after the user has
+     * already approved it.
+     */
+    readonly defaultWorkingDirectory?: string | undefined;
 }): Tool;
 //# sourceMappingURL=runtime.d.ts.map

package/dist/platform/tools/exec/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/exec/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAGjD,OAAO,EAAqB,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,EAA+B,iBAAiB,EAAiB,MAAM,aAAa,CAAC;AACjG,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAG9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAse/E;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC,GAC3D,OAAO,CA2CT;AA8ID,wBAAgB,cAAc,CAC5B,cAAc,EAAE,cAAc,EAC9B,OAAO,GAAE;IACP,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IACjF,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;CACnD,GACL,IAAI,CA6FN"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/exec/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAGjD,OAAO,EAAqB,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC3E,OAAO,KAAK,EAA+B,iBAAiB,EAAiB,MAAM,aAAa,CAAC;AACjG,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAG9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAykB/E;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,aAAa,CAAC,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC,GAC3D,OAAO,CA8CT;AAsJD,wBAAgB,cAAc,CAC5B,cAAc,EAAE,cAAc,EAC9B,OAAO,GAAE;IACP,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IACjF,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IACvD;;;;;;;;OAQG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClD,GACL,IAAI,CA8FN"}

package/dist/platform/tools/exec/runtime.js

@@ -30,11 +30,28 @@ function decodeCmd(cmdInput) {
         return cmdInput.cmd;
     throw new Error('Each command must have either cmd or cmd_base64');
 }
-function requireWorkingDirectory(input) {
-    if (!input.working_dir || input.working_dir.trim().length === 0) {
-        throw new Error('exec requires an explicit working_dir');
+/**
+ * Resolve the effective working directory for an exec call.
+ *
+ * An explicit `working_dir` on the input always wins. Otherwise falls back to
+ * `defaultWorkingDirectory` — the session/tool-context working directory,
+ * threaded in by the caller (see createExecTool) — so a model that omits
+ * working_dir still runs in a sensible place instead of failing outright
+ * after the user has already approved the call (the approval card's
+ * "Directory" line is sourced from the same session working directory
+ * independently of this arg, so it was already showing the truth the whole
+ * time — see permissions/prompt.ts on the TUI side). Throws only when
+ * neither is available, which should not happen in practice since every
+ * tool-registration path supplies a defaultWorkingDirectory.
+ */
+function requireWorkingDirectory(input, defaultWorkingDirectory) {
+    const explicit = input.working_dir?.trim();
+    if (explicit)
+        return explicit;
+    if (defaultWorkingDirectory && defaultWorkingDirectory.trim().length > 0) {
+        return defaultWorkingDirectory;
     }
-    return input.working_dir;
+    throw new Error('exec requires an explicit working_dir');
 }
 function normalizeExecInput(input) {
     const hasTopLevelWorkingDir = Boolean(input.working_dir?.trim());
@@ -107,6 +124,40 @@ function applyExpectations(result, expect, exitCode) {
 function buildTimedOutResult(cmdStr, cwd, durationMs, progressFile) {
     return { cmd: cmdStr, exit_code: null, stdout: '', stderr: '', success: false, timed_out: true, duration_ms: durationMs, cwd, ...(progressFile ? { progress_file: progressFile } : {}) };
 }
+/** Wave-4 cooperative cancellation (wo701): mirrors buildTimedOutResult's shape for the AbortSignal path. */
+function buildCancelledResult(cmdStr, cwd, durationMs) {
+    return { cmd: cmdStr, exit_code: null, stdout: '', stderr: '', success: false, cancelled: true, duration_ms: durationMs, cwd };
+}
+/**
+ * Grace window for draining a killed child's stdout/stderr after a
+ * timeout/abort stop before returning regardless. Kept well under the
+ * cancellation-latency budget the cooperative-cancellation tests assert
+ * (< 5s).
+ */
+const POST_STOP_DRAIN_GRACE_MS = 500;
+/**
+ * Wave-4 cooperative cancellation (wo701): after a timeout/abort kill the
+ * child has already been SIGKILL'd, but a grandchild that inherited the
+ * stdout/stderr pipe can hold it open, so reading those streams to EOF may
+ * never settle. Awaiting the full IO promise unbounded here could therefore
+ * block until the grandchild's own duration elapses (observed as a hang under
+ * loaded CI). A cancelled/timed-out result never depends on fully-drained
+ * content, so bound the wait to a short grace window and return regardless.
+ * The still-pending IO promise is defused so it can never surface as an
+ * unhandled rejection; the grace timer is unref'd so it cannot keep the event
+ * loop (or a test runner) alive.
+ */
+async function drainAfterStop(io, graceMs) {
+    const settled = io.then(() => undefined, () => undefined);
+    let timer;
+    const grace = new Promise((resolve) => {
+        timer = setTimeout(resolve, graceMs);
+        timer.unref?.();
+    });
+    await Promise.race([settled, grace]);
+    if (timer)
+        clearTimeout(timer);
+}
 function getProgressDirectory(workingDirectory) {
     return join(workingDirectory, ...OVERFLOW_SUBDIR);
 }
@@ -144,7 +195,7 @@ async function spawnBackground(processManager, cmd, cwd, env) {
 function handleBgSpecialCommand(processManager, cmd) {
     return processManager.handleCommand(cmd);
 }
-async function runCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout) {
+async function runCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal) {
     const guardResult = await guardExecCommand(cmdStr, DEFAULT_ALLOWED_CLASSES, featureFlags);
     if (!guardResult.allowed) {
         const denial = formatDenialResponse(guardResult, cmdStr);
@@ -163,18 +214,25 @@ async function runCommand(processManager, overflowHandler, featureFlags, cmdStr,
     const timeoutMs = cmdInput.timeout_ms ?? globalTimeout;
     const mergedEnv = { ...buildCleanEnv(), ...cmdInput.env };
     const startTime = Date.now();
+    // Wave-4 cooperative cancellation (wo701) is wired for the foreground and
+    // progress-streamed paths (the common cases — progress auto-engages once
+    // timeout_ms exceeds PROGRESS_AUTO_THRESHOLD_MS, which the 120s default
+    // timeout always does). `until`-pattern commands are explicitly deferred
+    // (see the WO report) — the timeout kill-timer they already have still
+    // applies, just not an external AbortSignal.
     if (cmdInput.until) {
         return runUntil(processManager, overflowHandler, cmdStr, cmdInput, cwd, mergedEnv, timeoutMs, startTime);
     }
     const useProgress = cmdInput.progress === true || timeoutMs > PROGRESS_AUTO_THRESHOLD_MS;
     if (useProgress) {
-        return runCommandWithProgress(processManager, overflowHandler, cmdStr, cmdInput, workingDirectory, cwd, mergedEnv, timeoutMs, startTime);
+        return runCommandWithProgress(processManager, overflowHandler, cmdStr, cmdInput, workingDirectory, cwd, mergedEnv, timeoutMs, startTime, signal);
     }
     const proc = Bun.spawn(['/bin/sh', '-c', cmdStr], { ...(cwd !== undefined ? { cwd } : {}), env: mergedEnv, stdout: 'pipe', stderr: 'pipe' });
     let timedOut = false;
+    let cancelled = false;
     let killTimer;
-    let timeoutResolve;
-    const timeoutSentinel = new Promise((res) => { timeoutResolve = res; });
+    let stopResolve;
+    const stopSentinel = new Promise((res) => { stopResolve = res; });
     killTimer = setTimeout(async () => {
         timedOut = true;
         try {
@@ -186,9 +244,31 @@ async function runCommand(processManager, overflowHandler, featureFlags, cmdStr,
             // The process may have already exited before kill.
             logger.debug('[ExecRuntime] kill on timeout failed (process may have exited)', { error: String(err) });
         }
-        timeoutResolve();
+        stopResolve();
     }, timeoutMs);
     killTimer.unref?.();
+    const onAbort = () => {
+        if (timedOut || cancelled)
+            return;
+        cancelled = true;
+        void (async () => {
+            try {
+                proc.kill('SIGTERM');
+                await sleep(200);
+                proc.kill('SIGKILL');
+            }
+            catch (err) {
+                logger.debug('[ExecRuntime] kill on cancellation failed (process may have exited)', { error: String(err) });
+            }
+            stopResolve();
+        })();
+    };
+    if (signal) {
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+    }
     try {
         const procPromise = Promise.all([
             new Response(proc.stdout).text(),
@@ -198,20 +278,18 @@ async function runCommand(processManager, overflowHandler, featureFlags, cmdStr,
         let procResult;
         await Promise.race([
             procPromise.then((r) => { procResult = r; }),
-            timeoutSentinel,
+            stopSentinel,
         ]);
         clearTimeout(killTimer);
-        if (timedOut) {
-            try {
-                await procPromise;
-            }
-            catch (error) {
-                logger.debug('exec foreground command collection failed after timeout', {
-                    command: cmdStr,
-                    error: summarizeError(error),
-                });
-            }
-            return buildTimedOutResult(cmdStr, cwd, Date.now() - startTime);
+        if (signal)
+            signal.removeEventListener('abort', onAbort);
+        if (timedOut || cancelled) {
+            // Bounded drain: the child is already killed; never block past a short
+            // grace window on streams an orphaned grandchild may keep open.
+            await drainAfterStop(procPromise, POST_STOP_DRAIN_GRACE_MS);
+            return timedOut
+                ? buildTimedOutResult(cmdStr, cwd, Date.now() - startTime)
+                : buildCancelledResult(cmdStr, cwd, Date.now() - startTime);
         }
         const [stdoutRaw, stderrRaw, exitCode] = procResult;
         const stdoutResult = truncate(overflowHandler, stdoutRaw, 'stdout');
@@ -233,16 +311,19 @@ async function runCommand(processManager, overflowHandler, featureFlags, cmdStr,
     }
     catch (err) {
         clearTimeout(killTimer);
+        if (signal)
+            signal.removeEventListener('abort', onAbort);
         throw err;
     }
 }
-async function runCommandWithProgress(_processManager, overflowHandler, cmdStr, cmdInput, workingDirectory, cwd, mergedEnv, timeoutMs, startTime) {
+async function runCommandWithProgress(_processManager, overflowHandler, cmdStr, cmdInput, workingDirectory, cwd, mergedEnv, timeoutMs, startTime, signal) {
     const progressFile = initProgressFile(cmdStr, workingDirectory);
     const proc = Bun.spawn(['/bin/sh', '-c', cmdStr], { ...(cwd !== undefined ? { cwd } : {}), env: mergedEnv, stdout: 'pipe', stderr: 'pipe' });
     let timedOut = false;
+    let cancelled = false;
     let killTimer;
-    let timeoutResolve;
-    const timeoutSentinel = new Promise((res) => { timeoutResolve = res; });
+    let stopResolve;
+    const stopSentinel = new Promise((res) => { stopResolve = res; });
     killTimer = setTimeout(async () => {
         timedOut = true;
         try {
@@ -254,9 +335,32 @@ async function runCommandWithProgress(_processManager, overflowHandler, cmdStr,
             logger.debug('[ExecRuntime] kill on streamed timeout failed (process may have exited)', { error: String(err) });
         }
         progressFile.append('# Timed out\n');
-        timeoutResolve();
+        stopResolve();
     }, timeoutMs);
     killTimer.unref?.();
+    const onAbort = () => {
+        if (timedOut || cancelled)
+            return;
+        cancelled = true;
+        void (async () => {
+            try {
+                proc.kill('SIGTERM');
+                await sleep(200);
+                proc.kill('SIGKILL');
+            }
+            catch (err) {
+                logger.debug('[ExecRuntime] kill on cancellation failed (process may have exited)', { error: String(err) });
+            }
+            progressFile.append('# Cancelled\n');
+            stopResolve();
+        })();
+    };
+    if (signal) {
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+    }
     let stdoutBuf = '';
     let stderrBuf = '';
     const warnings = [];
@@ -304,19 +408,18 @@ async function runCommandWithProgress(_processManager, overflowHandler, cmdStr,
         }
     };
     const ioPromise = Promise.all([readStdout(), readStderr(), proc.exited]);
-    await Promise.race([ioPromise, timeoutSentinel]);
+    await Promise.race([ioPromise, stopSentinel]);
     clearTimeout(killTimer);
-    if (timedOut) {
-        try {
-            await ioPromise;
-        }
-        catch (error) {
-            logger.debug('exec progress command IO collection failed after timeout', {
-                command: cmdStr,
-                error: summarizeError(error),
-            });
-        }
-        return { ...buildTimedOutResult(cmdStr, cwd, Date.now() - startTime, progressFile.path), stdout: stdoutBuf, stderr: stderrBuf };
+    if (signal)
+        signal.removeEventListener('abort', onAbort);
+    if (timedOut || cancelled) {
+        // Bounded drain: the child is already killed; never block past a short
+        // grace window on streams an orphaned grandchild may keep open. stdoutBuf/
+        // stderrBuf already hold whatever the background readers captured so far.
+        await drainAfterStop(ioPromise, POST_STOP_DRAIN_GRACE_MS);
+        return timedOut
+            ? { ...buildTimedOutResult(cmdStr, cwd, Date.now() - startTime, progressFile.path), stdout: stdoutBuf, stderr: stderrBuf }
+            : { ...buildCancelledResult(cmdStr, cwd, Date.now() - startTime), stdout: stdoutBuf, stderr: stderrBuf, progress_file: progressFile.path };
     }
     const ioResult = await ioPromise.catch((error) => {
         logger.warn('exec progress command IO collection failed', {
@@ -440,6 +543,10 @@ export function isRetryableExecResult(result, allowed) {
     // Timed-out commands are never auto-retried — callers must decide
     if (result.timed_out)
         return false;
+    // Cancelled commands (Wave 4, wo701) must never be retried — retrying
+    // after an operator/engine kill would defeat the cancellation entirely.
+    if (result.cancelled)
+        return false;
     const combined = `${result.stdout}\n${result.stderr}`;
     // Terminal errors — always skip retry
     const TERMINAL_PATTERNS = [
@@ -476,9 +583,9 @@ export function isRetryableExecResult(result, allowed) {
     }
     return false;
 }
-async function runWithRetry(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout) {
+async function runWithRetry(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal) {
     if (!cmdInput.retry) {
-        return runCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout);
+        return runCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal);
     }
     const maxRetries = Math.min(cmdInput.retry.max ?? 3, 10);
     const delayMs = cmdInput.retry.delay_ms ?? 1000;
@@ -487,7 +594,7 @@ async function runWithRetry(processManager, overflowHandler, featureFlags, cmdSt
     const retryOn = cmdInput.retry.on;
     let lastResult;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        lastResult = await runCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout);
+        lastResult = await runCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal);
         if (lastResult.success) {
             return { ...lastResult, retries: attempt };
         }
@@ -504,18 +611,21 @@ async function runWithRetry(processManager, overflowHandler, featureFlags, cmdSt
     }
     return { ...lastResult, retries: maxRetries };
 }
-async function executeResolvedCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout) {
+async function executeResolvedCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal) {
     const bgSpecial = handleBgSpecialCommand(processManager, cmdStr);
     if (bgSpecial)
         return bgSpecial;
     if (cmdInput.background) {
+        // Background processes intentionally outlive this tool call — cancelling
+        // the caller's item/agent must not kill a process the user asked to
+        // detach, so `signal` is deliberately not threaded here.
         return spawnBackground(processManager, cmdStr, resolveCwd(cmdInput.cwd, workingDirectory), cmdInput.env);
     }
-    return runWithRetry(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout);
+    return runWithRetry(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal);
 }
-async function executeResolvedCommands(processManager, overflowHandler, featureFlags, resolvedCmds, parallel, workingDirectory, globalTimeout, failFast) {
+async function executeResolvedCommands(processManager, overflowHandler, featureFlags, resolvedCmds, parallel, workingDirectory, globalTimeout, failFast, signal) {
     if (parallel) {
-        return mapWithConcurrency(resolvedCmds, MAX_PARALLEL_EXEC_COMMANDS, ({ cmdStr, cmdInput }) => executeResolvedCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout));
+        return mapWithConcurrency(resolvedCmds, MAX_PARALLEL_EXEC_COMMANDS, ({ cmdStr, cmdInput }) => executeResolvedCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal));
     }
     const results = [];
     let stopped = false;
@@ -524,7 +634,7 @@ async function executeResolvedCommands(processManager, overflowHandler, featureF
             results.push({ cmd: cmdStr, exit_code: null, stdout: '', stderr: '', success: false, skipped: true });
             continue;
         }
-        const result = await executeResolvedCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout);
+        const result = await executeResolvedCommand(processManager, overflowHandler, featureFlags, cmdStr, cmdInput, workingDirectory, globalTimeout, signal);
         results.push(result);
         if (failFast && !result.success) {
             stopped = true;
@@ -550,6 +660,7 @@ function formatResult(result, verbosity) {
                 stderr: firstStderr,
                 ...(result.expectation_error && { expectation_error: result.expectation_error }),
                 ...(result.timed_out && { timed_out: true }),
+                ...(result.cancelled && { cancelled: true }),
                 ...(result.process_id && { process_id: result.process_id, pid: result.pid }),
                 ...(result.progress_file && { progress_file: result.progress_file }),
                 ...(result.warnings && { warnings: result.warnings }),
@@ -567,6 +678,7 @@ function formatResult(result, verbosity) {
                 stderr: result.stderr,
                 ...(result.expectation_error && { expectation_error: result.expectation_error }),
                 ...(result.timed_out && { timed_out: true }),
+                ...(result.cancelled && { cancelled: true }),
                 ...(result.process_id && { process_id: result.process_id, pid: result.pid }),
                 ...(result.stdout_truncated && { stdout_truncated: true }),
                 ...(result.stderr_truncated && { stderr_truncated: true }),
@@ -593,7 +705,7 @@ export function createExecTool(processManager, options = {}) {
             supportsProgress: true,
             supportsStreamingOutput: true,
         },
-        async execute(args) {
+        async execute(args, opts) {
             try {
                 if (!Array.isArray(args['commands']) || args['commands'].length === 0) {
                     return { success: false, error: 'commands must be a non-empty array' };
@@ -602,7 +714,7 @@ export function createExecTool(processManager, options = {}) {
                     return { success: false, error: `Too many commands: maximum ${MAX_EXEC_COMMANDS} per exec call` };
                 }
                 const input = normalizeExecInput(args);
-                const workingDirectory = requireWorkingDirectory(input);
+                const workingDirectory = requireWorkingDirectory(input, options.defaultWorkingDirectory);
                 const verbosity = input.verbosity ?? 'standard';
                 const globalTimeout = input.timeout_ms ?? DEFAULT_TIMEOUT_MS;
                 const failFast = input.fail_fast === true || input.stop_on_error === true;
@@ -627,7 +739,7 @@ export function createExecTool(processManager, options = {}) {
                     }
                     resolvedCmds.push({ cmdStr, cmdInput });
                 }
-                const results = await executeResolvedCommands(processManager, overflowHandler, featureFlags, resolvedCmds, input.parallel === true, workingDirectory, globalTimeout, failFast);
+                const results = await executeResolvedCommands(processManager, overflowHandler, featureFlags, resolvedCmds, input.parallel === true, workingDirectory, globalTimeout, failFast, opts?.signal);
                 const formatted = results.map((r) => formatResult(r, verbosity));
                 const allSuccess = results.every((r) => r.success);
                 const responseData = formatted.length === 1 ? { ...formatted[0] } : { commands: formatted, total: formatted.length };
@@ -641,7 +753,7 @@ export function createExecTool(processManager, options = {}) {
                 const failed = results.filter((r) => !r.success);
                 const errorSummary = failed.length > 0
                     ? `${failed.length} of ${results.length} command(s) failed: `
-                        + failed.map((r) => `'${r.cmd}'${r.skipped ? ' (skipped)' : ` exit ${r.exit_code}${r.timed_out ? ' (timed out)' : ''}`}`).join('; ')
+                        + failed.map((r) => `'${r.cmd}'${r.skipped ? ' (skipped)' : ` exit ${r.exit_code}${r.timed_out ? ' (timed out)' : r.cancelled ? ' (cancelled)' : ''}`}`).join('; ')
                     : undefined;
                 return {
                     success: allSuccess,

package/dist/platform/tools/exec/schema.d.ts

@@ -133,7 +133,7 @@ export declare const EXEC_TOOL_SCHEMA: {
         };
         readonly working_dir: {
             readonly type: "string";
-            readonly description: "Global working directory applied to all commands unless overridden per-command.";
+            readonly description: string;
         };
         readonly timeout_ms: {
             readonly type: "integer";
@@ -269,6 +269,8 @@ export interface ExecCommandResult {
     expectation_error?: string | undefined;
     /** Set when command exceeded timeout. */
     timed_out?: boolean | undefined;
+    /** Set when an external AbortSignal cancelled the command (Wave 4, wo701 — orchestration engine cancellation). Never combined with timed_out. */
+    cancelled?: boolean | undefined;
     /** Set when command ran in background. */
     process_id?: string | undefined;
     pid?: number | undefined;

package/dist/platform/tools/exec/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/exec/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/exec/schema.ts"],"names":[],"mappings":"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"}

package/dist/platform/tools/exec/schema.js

@@ -131,7 +131,8 @@ export const EXEC_TOOL_SCHEMA = {
         },
         working_dir: {
             type: 'string',
-            description: 'Global working directory applied to all commands unless overridden per-command.',
+            description: 'Global working directory applied to all commands unless overridden per-command.'
+                + ' Optional — defaults to the session\'s working directory when omitted.',
         },
         timeout_ms: {
             type: 'integer',

package/dist/platform/tools/fetch/runtime.d.ts

@@ -6,6 +6,13 @@ import type { FeatureFlagManager } from '../../runtime/feature-flags/index.js';
 export interface FetchRuntimeDeps {
     readonly serviceRegistry?: Pick<ServiceRegistry, 'resolveAuth'> | null | undefined;
     readonly featureFlags?: Pick<FeatureFlagManager, 'isEnabled'> | null | undefined;
+    /**
+     * Wave-4 cooperative cancellation (wo701): an externally-supplied signal,
+     * combined with each request's own per-URL timeout signal via
+     * `AbortSignal.any`. Optional and additive — omitted, behavior is
+     * unchanged from before this field existed.
+     */
+    readonly signal?: AbortSignal | undefined;
 }
 interface CacheEntry {
     data: FetchUrlResult;

package/dist/platform/tools/fetch/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/fetch/runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAkB,MAAM,sBAAsB,CAAC;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAsF,MAAM,aAAa,CAAC;AAClI,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAM/E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IACnF,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;CAClF;AAED,UAAU,UAAU;IAClB,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AASD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiC;IAC/D,OAAO,CAAC,eAAe,CAAK;IAE5B,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAOtE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IAiBxC,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;CAkFpF;AAED,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC,CAE5G;AAseD,wBAAgB,eAAe,CAC7B,IAAI,GAAE,gBAAqB,EAC3B,OAAO,sBAA4B,GAClC,IAAI,CAiCN"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../../src/platform/tools/fetch/runtime.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAkB,MAAM,sBAAsB,CAAC;AAEjE,OAAO,KAAK,EAAE,UAAU,EAAsF,MAAM,aAAa,CAAC;AAClI,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAM/E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,eAAe,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IACnF,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;IACjF;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED,UAAU,UAAU;IAClB,IAAI,EAAE,cAAc,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AASD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiC;IAC/D,OAAO,CAAC,eAAe,CAAK;IAE5B,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAOtE,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IAiBxC,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC;CAkFpF;AAED,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC,CAE5G;AA0eD,wBAAgB,eAAe,CAC7B,IAAI,GAAE,gBAAqB,EAC3B,OAAO,sBAA4B,GAClC,IAAI,CAqCN"}

package/dist/platform/tools/fetch/runtime.js

@@ -165,8 +165,9 @@ function encodeFormBodyData(bodyData) {
     }
     return params.toString();
 }
-async function fetchOneRaw(urlInput, headers, method, body, effectiveUrl, trustTierConfig, sanitizationEnabled) {
-    const { signal, dispose } = createTimeoutController(urlInput.timeout_ms ?? DEFAULT_TIMEOUT_MS);
+async function fetchOneRaw(urlInput, headers, method, body, effectiveUrl, trustTierConfig, sanitizationEnabled, externalSignal) {
+    const { signal: timeoutSignal, dispose } = createTimeoutController(urlInput.timeout_ms ?? DEFAULT_TIMEOUT_MS);
+    const signal = externalSignal ? AbortSignal.any([timeoutSignal, externalSignal]) : timeoutSignal;
     try {
         return sanitizationEnabled
             ? await fetchWithValidatedRedirects({
@@ -353,14 +354,14 @@ async function fetchOne(urlInput, opts, runtime) {
     const { headers, body: requestBody } = await prepareFetchRequest(urlInput, deps);
     const startTime = performance.now();
     try {
-        let response = await fetchOneRaw(urlInput, headers, method, requestBody, effectiveUrl, trustTierConfig, sanitizationEnabled);
+        let response = await fetchOneRaw(urlInput, headers, method, requestBody, effectiveUrl, trustTierConfig, sanitizationEnabled, deps.signal);
         const retryOnAuth = urlInput.retry_on_auth ?? (urlInput.service !== undefined);
         if (response.status === 401 && retryOnAuth && urlInput.service && !(requestBody instanceof FormData)) {
             const refreshedHeaders = await deps.serviceRegistry?.resolveAuth(urlInput.service);
             if (refreshedHeaders) {
                 const retryHeaders = { ...headers };
                 Object.assign(retryHeaders, refreshedHeaders);
-                response = await fetchOneRaw(urlInput, retryHeaders, method, requestBody, effectiveUrl, trustTierConfig, sanitizationEnabled);
+                response = await fetchOneRaw(urlInput, retryHeaders, method, requestBody, effectiveUrl, trustTierConfig, sanitizationEnabled, deps.signal);
             }
         }
         const durationMs = Math.round(performance.now() - startTime);
@@ -503,13 +504,14 @@ export function createFetchTool(deps = {}, runtime = new FetchRuntimeService())
             supportsProgress: true,
             supportsStreamingOutput: true,
         },
-        async execute(args) {
+        async execute(args, opts) {
             if (!Array.isArray(args.urls) || args.urls.length === 0) {
                 return { success: false, error: 'Missing or empty "urls" array' };
             }
             try {
                 const input = { ...args, urls: args.urls };
-                const output = await runtime.execute(input, deps);
+                const effectiveDeps = opts?.signal ? { ...deps, signal: opts.signal } : deps;
+                const output = await runtime.execute(input, effectiveDeps);
                 return { success: true, output: JSON.stringify(output) };
             }
             catch (err) {