lazyclaw 6.3.1 → 6.4.0

package/providers/ollama.mjs

@@ -45,6 +45,61 @@ class ConnectionError extends Error {
   }
 }
 
+class TimeoutError extends Error {
+  constructor(idleMs) {
+    super(`ollama: idle timeout — no stream activity for ${idleMs}ms`);
+    this.name = 'TimeoutError';
+    this.code = 'TIMEOUT';
+    this.idleMs = idleMs;
+  }
+}
+
+const DEFAULT_IDLE_TIMEOUT_MS = 120000;
+
+// Resolve the IDLE (inter-chunk) timeout once per request: opts override
+// wins, then env LAZYCLAW_REQUEST_TIMEOUT_MS (positive int), else 120s.
+function resolveIdleTimeoutMs(opts) {
+  if (Number.isFinite(opts?.idleTimeoutMs) && opts.idleTimeoutMs > 0) return opts.idleTimeoutMs;
+  const raw = parseInt(process.env.LAZYCLAW_REQUEST_TIMEOUT_MS ?? '', 10);
+  if (Number.isFinite(raw) && raw > 0) return raw;
+  return DEFAULT_IDLE_TIMEOUT_MS;
+}
+
+// Wrap a chunk iterator with an IDLE timeout: abort only when NO chunk has
+// arrived for idleMs (the timer resets on every received chunk, and also
+// guards the connect/first-byte phase). This is NOT a total-duration cap,
+// so a long but healthy generation that streams steadily is never aborted.
+// `controller` is aborted on idle expiry so the real connection tears down.
+async function* iterateWithIdleTimeout(body, idleMs, controller) {
+  const iterator = iterateBody(body)[Symbol.asyncIterator]();
+  try {
+    while (true) {
+      let timer;
+      const idle = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          reject(new TimeoutError(idleMs));
+        }, idleMs);
+      });
+      let step;
+      try {
+        step = await Promise.race([iterator.next(), idle]);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (step.done) return;
+      yield step.value;
+    }
+  } finally {
+    // Best-effort, NON-awaited cleanup: on idle abort the underlying reader
+    // may be suspended on a read that never settles, so awaiting return()
+    // would re-hang us. The controller abort already tears down the socket.
+    if (typeof iterator.return === 'function') {
+      try { Promise.resolve(iterator.return()).catch(() => {}); } catch { /* ignore */ }
+    }
+  }
+}
+
 async function* iterateBody(body) {
   if (body && typeof body.getReader === 'function') {
     const reader = body.getReader();
@@ -64,6 +119,28 @@ async function* iterateBody(body) {
   throw new Error('ollama: response body is not iterable');
 }
 
+// The final `done:true` frame carries prompt_eval_count (input) / eval_count
+// (output) and a done_reason. Report tokens via onUsage (cost 0 for a local
+// model) and signal a num_predict/context cut (done_reason 'length') so the
+// caller can warn rather than treat a truncated answer as complete.
+function _emitOllamaDone(obj, opts) {
+  const inT = obj.prompt_eval_count;
+  const outT = obj.eval_count;
+  if ((inT != null || outT != null) && typeof opts.onUsage === 'function') {
+    try {
+      opts.onUsage({
+        inputTokens: inT ?? null,
+        outputTokens: outT ?? null,
+        totalTokens: (inT ?? 0) + (outT ?? 0),
+        totalCostUsd: 0,
+      });
+    } catch { /* never fail the stream on a usage callback */ }
+  }
+  if (obj.done_reason === 'length' && typeof opts.onTruncated === 'function') {
+    try { opts.onTruncated('length'); } catch { /* never fail the stream on a callback */ }
+  }
+}
+
 export const ollamaProvider = {
   name: 'ollama',
   /**
@@ -87,13 +164,28 @@ export const ollamaProvider = {
 
     if (opts.signal?.aborted) throw new AbortError('aborted before request');
 
+    // Compose the caller's signal with an internal controller that the idle
+    // timeout aborts. The composed signal goes to fetch so a stalled
+    // connection (or a user cancel) tears down the real socket.
+    const idleMs = resolveIdleTimeoutMs(opts);
+    const idleController = new AbortController();
+    const fetchSignal = opts.signal
+      ? (typeof AbortSignal.any === 'function'
+          ? AbortSignal.any([opts.signal, idleController.signal])
+          : idleController.signal)
+      : idleController.signal;
+    const forwardCallerAbort = () => idleController.abort();
+    if (opts.signal && typeof AbortSignal.any !== 'function') {
+      opts.signal.addEventListener('abort', forwardCallerAbort, { once: true });
+    }
+
     let res;
     try {
       res = await fetchFn(`${baseUrl}/api/chat`, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify({ model, messages: apiMessages, stream: true }),
-        signal: opts.signal,
+        signal: fetchSignal,
       });
     } catch (err) {
       // Distinguish "ollama isn't running" from generic network errors so
@@ -112,7 +204,10 @@ export const ollamaProvider = {
 
     const decoder = new TextDecoder('utf-8', { fatal: false });
     let buffer = '';
-    for await (const chunk of iterateBody(res.body)) {
+    try {
+    for await (const chunk of iterateWithIdleTimeout(res.body, idleMs, idleController)) {
+      // A user cancel surfaces as an idle-controller abort too; map it back
+      // to ABORT so it stays distinguishable from a TIMEOUT.
       if (opts.signal?.aborted) throw new AbortError('aborted mid-stream');
       buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
       // Ollama is newline-delimited JSON, not SSE — split on '\n', parse
@@ -125,7 +220,7 @@ export const ollamaProvider = {
         try {
           const obj = JSON.parse(line);
           if (obj?.message?.content) yield obj.message.content;
-          if (obj?.done) return;
+          if (obj?.done) { _emitOllamaDone(obj, opts); return; }
           if (obj?.error) throw new ApiError(500, obj.error);
         } catch (err) {
           if (err instanceof ApiError) throw err;
@@ -133,6 +228,11 @@ export const ollamaProvider = {
         }
       }
     }
+    } finally {
+      if (opts.signal && typeof AbortSignal.any !== 'function') {
+        opts.signal.removeEventListener('abort', forwardCallerAbort);
+      }
+    }
     // Any trailing bytes the decoder still holds onto get flushed and
     // parsed once. Empty after a clean stream.
     const tail = decoder.decode();
@@ -140,6 +240,7 @@ export const ollamaProvider = {
       try {
         const obj = JSON.parse(tail);
         if (obj?.message?.content) yield obj.message.content;
+        if (obj?.done) _emitOllamaDone(obj, opts);
       } catch { /* malformed tail — drop */ }
     }
   },

package/providers/openai.mjs

@@ -14,6 +14,13 @@
 
 const DEFAULT_MAX_TOKENS = 4096;
 
+// OpenAI o-series reasoning models (o1/o3/o4...) reject `max_tokens` with
+// HTTP 400 'Unsupported parameter: max_tokens, use max_completion_tokens'.
+// They are surfaced in this provider's own suggestedModels (registry.mjs).
+function isReasoningModel(model) {
+  return /^o\d/i.test(String(model || ''));
+}
+
 class InvalidApiKeyError extends Error {
   constructor(message = 'invalid OpenAI api key') {
     super(message);
@@ -41,6 +48,61 @@ class RateLimitError extends Error {
   }
 }
 
+class TimeoutError extends Error {
+  constructor(idleMs) {
+    super(`openai: idle timeout — no stream activity for ${idleMs}ms`);
+    this.name = 'TimeoutError';
+    this.code = 'TIMEOUT';
+    this.idleMs = idleMs;
+  }
+}
+
+const DEFAULT_IDLE_TIMEOUT_MS = 120000;
+
+// Resolve the IDLE (inter-chunk) timeout once per request: opts override
+// wins, then env LAZYCLAW_REQUEST_TIMEOUT_MS (positive int), else 120s.
+function resolveIdleTimeoutMs(opts) {
+  if (Number.isFinite(opts?.idleTimeoutMs) && opts.idleTimeoutMs > 0) return opts.idleTimeoutMs;
+  const raw = parseInt(process.env.LAZYCLAW_REQUEST_TIMEOUT_MS ?? '', 10);
+  if (Number.isFinite(raw) && raw > 0) return raw;
+  return DEFAULT_IDLE_TIMEOUT_MS;
+}
+
+// Wrap a chunk iterator with an IDLE timeout: abort only when NO chunk has
+// arrived for idleMs (the timer resets on every received chunk, and also
+// guards the connect/first-byte phase). This is NOT a total-duration cap,
+// so a long but healthy generation that streams steadily is never aborted.
+// `controller` is aborted on idle expiry so the real connection tears down.
+async function* iterateWithIdleTimeout(body, idleMs, controller) {
+  const iterator = iterateBody(body)[Symbol.asyncIterator]();
+  try {
+    while (true) {
+      let timer;
+      const idle = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          reject(new TimeoutError(idleMs));
+        }, idleMs);
+      });
+      let step;
+      try {
+        step = await Promise.race([iterator.next(), idle]);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (step.done) return;
+      yield step.value;
+    }
+  } finally {
+    // Best-effort, NON-awaited cleanup: on idle abort the underlying reader
+    // may be suspended on a read that never settles, so awaiting return()
+    // would re-hang us. The controller abort already tears down the socket.
+    if (typeof iterator.return === 'function') {
+      try { Promise.resolve(iterator.return()).catch(() => {}); } catch { /* ignore */ }
+    }
+  }
+}
+
 class ApiError extends Error {
   constructor(status, body) {
     super(`openai api ${status}: ${String(body).slice(0, 200)}`);
@@ -120,10 +182,14 @@ export const openaiProvider = {
 
     const body = {
       model,
-      max_tokens: opts.maxTokens || DEFAULT_MAX_TOKENS,
       stream: true,
       messages: apiMessages,
     };
+    // Reasoning models take max_completion_tokens; everything else takes
+    // max_tokens. Never emit both — the o-series rejects max_tokens.
+    const tokenCap = opts.maxTokens || DEFAULT_MAX_TOKENS;
+    if (isReasoningModel(model)) body.max_completion_tokens = tokenCap;
+    else body.max_tokens = tokenCap;
     // Tool-use passthrough mirrors the anthropic provider: opts.tools is an
     // array of OpenAI-shaped tools. opts.toolChoice maps to tool_choice.
     if (Array.isArray(opts.tools) && opts.tools.length > 0) {
@@ -140,6 +206,20 @@ export const openaiProvider = {
     }
 
     if (opts.signal?.aborted) throw new AbortError('aborted before request');
+    // Compose the caller's signal with an internal controller that the idle
+    // timeout aborts. The composed signal goes to fetch so a stalled
+    // connection (or a user cancel) tears down the real socket.
+    const idleMs = resolveIdleTimeoutMs(opts);
+    const idleController = new AbortController();
+    const fetchSignal = opts.signal
+      ? (typeof AbortSignal.any === 'function'
+          ? AbortSignal.any([opts.signal, idleController.signal])
+          : idleController.signal)
+      : idleController.signal;
+    const forwardCallerAbort = () => idleController.abort();
+    if (opts.signal && typeof AbortSignal.any !== 'function') {
+      opts.signal.addEventListener('abort', forwardCallerAbort, { once: true });
+    }
     const res = await fetchFn('https://api.openai.com/v1/chat/completions', {
       method: 'POST',
       headers: {
@@ -147,7 +227,7 @@ export const openaiProvider = {
         'authorization': `Bearer ${opts.apiKey}`,
       },
       body: JSON.stringify(body),
-      signal: opts.signal,
+      signal: fetchSignal,
     });
 
     if (!res.ok) {
@@ -165,6 +245,7 @@ export const openaiProvider = {
     // shape that mirrors the anthropic provider's onUsage payload so
     // callers don't have to special-case per provider.
     let usage = null;
+    let lastFinish = null;
     // OpenAI streams tool_calls as deltas with an `index` we use as the
     // accumulation key. Each delta may carry a partial id, name, and/or
     // arguments string. We assemble until the stream signals
@@ -187,7 +268,25 @@ export const openaiProvider = {
         });
       } catch { /* never let a callback abort the stream */ }
     };
-    for await (const chunk of iterateBody(res.body)) {
+    // Fire onUsage + (if truncated) onTruncated EXACTLY ONCE — from the [DONE]
+    // sentinel, or from the post-loop flush if the upstream closed after the
+    // usage frame without ever sending [DONE].
+    let finalized = false;
+    const finalize = () => {
+      if (finalized) return;
+      finalized = true;
+      for (const idx of Array.from(toolCallsByIndex.keys())) flushToolCall(idx);
+      if (usage && typeof opts.onUsage === 'function') {
+        try { opts.onUsage(usage); } catch { /* never let a callback abort */ }
+      }
+      if (lastFinish === 'length' && typeof opts.onTruncated === 'function') {
+        try { opts.onTruncated('length'); } catch { /* ditto */ }
+      }
+    };
+    try {
+    for await (const chunk of iterateWithIdleTimeout(res.body, idleMs, idleController)) {
+      // A user cancel surfaces as an idle-controller abort too; map it back
+      // to ABORT so it stays distinguishable from a TIMEOUT.
       if (opts.signal?.aborted) throw new AbortError('aborted mid-stream');
       buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
       let consumed = 0;
@@ -195,11 +294,7 @@ export const openaiProvider = {
         consumed = frame.nextCursor;
         if (!frame.data) continue;
         if (frame.data === '[DONE]') {
-          // Drain any tool calls that haven't been flushed by finish_reason.
-          for (const idx of Array.from(toolCallsByIndex.keys())) flushToolCall(idx);
-          if (usage && typeof opts.onUsage === 'function') {
-            try { opts.onUsage(usage); } catch { /* never let a callback abort */ }
-          }
+          finalize();
           return;
         }
         try {
@@ -226,6 +321,7 @@ export const openaiProvider = {
               toolCallsByIndex.set(idx, cur);
             }
           }
+          if (choice?.finish_reason) lastFinish = choice.finish_reason;
           if (choice?.finish_reason === 'tool_calls') {
             for (const idx of Array.from(toolCallsByIndex.keys())) flushToolCall(idx);
           }
@@ -235,6 +331,12 @@ export const openaiProvider = {
       }
       if (consumed > 0) buffer = buffer.slice(consumed);
     }
+    } finally {
+      if (opts.signal && typeof AbortSignal.any !== 'function') {
+        opts.signal.removeEventListener('abort', forwardCallerAbort);
+      }
+    }
+    finalize();   // flush captured usage/truncation if the stream ended without [DONE]
     const tail = decoder.decode();
     if (tail) buffer += tail;
   },

package/providers/openai_compat.mjs

@@ -48,6 +48,61 @@ class RateLimitError extends Error {
   }
 }
 
+class TimeoutError extends Error {
+  constructor(idleMs) {
+    super(`openai-compat: idle timeout — no stream activity for ${idleMs}ms`);
+    this.name = 'TimeoutError';
+    this.code = 'TIMEOUT';
+    this.idleMs = idleMs;
+  }
+}
+
+const DEFAULT_IDLE_TIMEOUT_MS = 120000;
+
+// Resolve the IDLE (inter-chunk) timeout once per request: opts override
+// wins, then env LAZYCLAW_REQUEST_TIMEOUT_MS (positive int), else 120s.
+function resolveIdleTimeoutMs(opts) {
+  if (Number.isFinite(opts?.idleTimeoutMs) && opts.idleTimeoutMs > 0) return opts.idleTimeoutMs;
+  const raw = parseInt(process.env.LAZYCLAW_REQUEST_TIMEOUT_MS ?? '', 10);
+  if (Number.isFinite(raw) && raw > 0) return raw;
+  return DEFAULT_IDLE_TIMEOUT_MS;
+}
+
+// Wrap a chunk iterator with an IDLE timeout: abort only when NO chunk has
+// arrived for idleMs (the timer resets on every received chunk, and also
+// guards the connect/first-byte phase). This is NOT a total-duration cap,
+// so a long but healthy generation that streams steadily is never aborted.
+// `controller` is aborted on idle expiry so the real connection tears down.
+async function* iterateWithIdleTimeout(body, idleMs, controller) {
+  const iterator = iterateBody(body)[Symbol.asyncIterator]();
+  try {
+    while (true) {
+      let timer;
+      const idle = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          reject(new TimeoutError(idleMs));
+        }, idleMs);
+      });
+      let step;
+      try {
+        step = await Promise.race([iterator.next(), idle]);
+      } finally {
+        clearTimeout(timer);
+      }
+      if (step.done) return;
+      yield step.value;
+    }
+  } finally {
+    // Best-effort, NON-awaited cleanup: on idle abort the underlying reader
+    // may be suspended on a read that never settles, so awaiting return()
+    // would re-hang us. The controller abort already tears down the socket.
+    if (typeof iterator.return === 'function') {
+      try { Promise.resolve(iterator.return()).catch(() => {}); } catch { /* ignore */ }
+    }
+  }
+}
+
 class ApiError extends Error {
   constructor(status, body) {
     super(`openai-compat ${status}: ${String(body).slice(0, 200)}`);
@@ -175,12 +230,26 @@ export function makeOpenAICompatProvider(cfg) {
       if (apiKey) headers['authorization'] = `Bearer ${apiKey}`;
 
       if (opts.signal?.aborted) throw new AbortError('aborted before request');
+      // Compose the caller's signal with an internal controller that the idle
+      // timeout aborts. The composed signal goes to fetch so a stalled
+      // connection (or a user cancel) tears down the real socket.
+      const idleMs = resolveIdleTimeoutMs(opts);
+      const idleController = new AbortController();
+      const fetchSignal = opts.signal
+        ? (typeof AbortSignal.any === 'function'
+            ? AbortSignal.any([opts.signal, idleController.signal])
+            : idleController.signal)
+        : idleController.signal;
+      const forwardCallerAbort = () => idleController.abort();
+      if (opts.signal && typeof AbortSignal.any !== 'function') {
+        opts.signal.addEventListener('abort', forwardCallerAbort, { once: true });
+      }
       const url = `${baseUrl}/chat/completions`;
       const res = await fetchFn(url, {
         method: 'POST',
         headers,
         body: JSON.stringify(body),
-        signal: opts.signal,
+        signal: fetchSignal,
       });
 
       if (!res.ok) {
@@ -193,6 +262,7 @@ export function makeOpenAICompatProvider(cfg) {
       const decoder = new TextDecoder('utf-8', { fatal: false });
       let buffer = '';
       let usage = null;
+      let lastFinish = null;
       const toolCallsByIndex = new Map();
       const flushToolCall = (idx) => {
         const tc = toolCallsByIndex.get(idx);
@@ -211,7 +281,24 @@ export function makeOpenAICompatProvider(cfg) {
           });
         } catch { /* never let a callback abort the stream */ }
       };
-      for await (const chunk of iterateBody(res.body)) {
+      // Fire onUsage + (if truncated) onTruncated EXACTLY ONCE — from [DONE] or
+      // the post-loop flush if the upstream closes without the sentinel.
+      let finalized = false;
+      const finalize = () => {
+        if (finalized) return;
+        finalized = true;
+        for (const idx of Array.from(toolCallsByIndex.keys())) flushToolCall(idx);
+        if (usage && typeof opts.onUsage === 'function') {
+          try { opts.onUsage(usage); } catch { /* swallow */ }
+        }
+        if (lastFinish === 'length' && typeof opts.onTruncated === 'function') {
+          try { opts.onTruncated('length'); } catch { /* swallow */ }
+        }
+      };
+      try {
+      for await (const chunk of iterateWithIdleTimeout(res.body, idleMs, idleController)) {
+        // A user cancel surfaces as an idle-controller abort too; map it back
+        // to ABORT so it stays distinguishable from a TIMEOUT.
         if (opts.signal?.aborted) throw new AbortError('aborted mid-stream');
         buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
         let consumed = 0;
@@ -219,10 +306,7 @@ export function makeOpenAICompatProvider(cfg) {
           consumed = frame.nextCursor;
           if (!frame.data) continue;
           if (frame.data === '[DONE]') {
-            for (const idx of Array.from(toolCallsByIndex.keys())) flushToolCall(idx);
-            if (usage && typeof opts.onUsage === 'function') {
-              try { opts.onUsage(usage); } catch { /* swallow */ }
-            }
+            finalize();
             return;
           }
           try {
@@ -247,6 +331,7 @@ export function makeOpenAICompatProvider(cfg) {
                 toolCallsByIndex.set(idx, cur);
               }
             }
+            if (choice?.finish_reason) lastFinish = choice.finish_reason;
             if (choice?.finish_reason === 'tool_calls') {
               for (const idx of Array.from(toolCallsByIndex.keys())) flushToolCall(idx);
             }
@@ -256,6 +341,12 @@ export function makeOpenAICompatProvider(cfg) {
         }
         if (consumed > 0) buffer = buffer.slice(consumed);
       }
+      } finally {
+        if (opts.signal && typeof AbortSignal.any !== 'function') {
+          opts.signal.removeEventListener('abort', forwardCallerAbort);
+        }
+      }
+      finalize();   // flush captured usage/truncation if the stream ended without [DONE]
       const tail = decoder.decode();
       if (tail) buffer += tail;
     },

package/providers/orchestrator.mjs

@@ -27,7 +27,8 @@
 //         "gemini:gemini-2.5-pro"
 //       ],
 //       "maxSubtasks": 5,       // optional, default 5
-//       "concurrency": 0        // optional, 0 = sequential (visible streaming)
+//       "concurrency": 0        // optional; default = min(3, workers), parallel.
+//                               //   0 or 1 = sequential (visible live streaming)
 //     }
 //   }
 //
@@ -86,6 +87,24 @@ function _bestPlanArray(text) {
   return null;
 }
 
+// Default worker-pool concurrency when cfg.orchestrator.concurrency is unset.
+// Parallel is the point of a worker pool; an unconfigured fleet should not run
+// subtasks one at a time. Clamped to the worker count at the call site, and an
+// explicit 0/1 still selects the sequential live-streaming path.
+const DEFAULT_CONCURRENCY = 3;
+
+// Opt-in agentic workers (cfg.orchestrator.agenticWorkers): an EXECUTE worker
+// runs through runAgentTurn so it can actually DO work with its tools (shell,
+// file read, recall) instead of only streaming text. Default OFF — the
+// text-streaming path is byte-stable. Tool calls are confined by the sandbox
+// the caller passes; the loop is bounded by workerMaxIterations.
+const DEFAULT_WORKER_TOOLS = ['bash', 'read', 'grep', 'recall'];
+const DEFAULT_WORKER_MAX_ITERATIONS = 8;
+const AGENTIC_WORKER_ROLE =
+  'You are an orchestrator worker. Complete ONLY the assigned subtask. Use your ' +
+  'tools (shell, file read, grep, recall) to do real work when useful, then report ' +
+  'the result concisely. Do not ask questions — act, then summarise what you found.';
+
 const PLANNER_SYSTEM = `You are an orchestrator that decomposes a user request into independent subtasks for parallel worker agents.
 
 Rules:
@@ -262,9 +281,47 @@ export function makeOrchestratorProvider(opts = {}) {
       //                        regardless of which worker finished first.
       // The number is clamped to [1, workers.length] so a runaway value
       // can't accidentally over-subscribe a single worker.
-      const rawConcurrency = Number.isFinite(o.concurrency) ? Math.floor(o.concurrency) : 1;
+      const rawConcurrency = Number.isFinite(o.concurrency) ? Math.floor(o.concurrency) : DEFAULT_CONCURRENCY;
       const concurrency = Math.max(1, Math.min(rawConcurrency, workers.length));
       yield `### 2. Executing ${trimmed.length} subtask${trimmed.length === 1 ? '' : 's'}${concurrency > 1 ? ` (concurrency=${concurrency}, parallel)` : ''}\n\n`;
+
+      // Run one worker on one subtask through the agentic tool loop. Confined by
+      // the caller's sandbox; bounded by workerMaxIterations; abort-propagating.
+      const _runAgenticWorker = async (worker, sub) => {
+        const { runAgentTurn } = await import('../mas/agent_turn.mjs');
+        const r = await runAgentTurn({
+          agent: {
+            name: worker.name, provider: worker.name, model: worker.model,
+            role: AGENTIC_WORKER_ROLE,
+            tools: Array.isArray(o.workerTools) ? o.workerTools : DEFAULT_WORKER_TOOLS,
+          },
+          userMessage: sub.task,
+          configDir: callerOpts.configDir,
+          cwd: callerOpts.cwd,
+          apiKey: keyResolver(cfg, worker.name),
+          fetchImpl: callerOpts.fetchImpl,
+          sandbox: callerOpts.sandbox,
+          signal: callerOpts.signal,
+          maxIterations: Number.isFinite(o.workerMaxIterations) ? o.workerMaxIterations : DEFAULT_WORKER_MAX_ITERATIONS,
+        });
+        return r.text || '';
+      };
+      // Worker output as a chunk stream. agenticWorkers OFF (default) → the
+      // provider's live token stream, byte-stable. ON → one buffered chunk with
+      // the agent turn's final answer (tool work happened inside).
+      const _workerChunks = async function* (worker, sub) {
+        if (o.agenticWorkers) {
+          const text = await _runAgenticWorker(worker, sub);
+          if (text) yield text;
+          return;
+        }
+        yield* worker.prov.sendMessage([{ role: 'user', content: sub.task }], {
+          apiKey: keyResolver(cfg, worker.name),
+          model: worker.model || undefined,
+          signal: callerOpts.signal,
+        });
+      };
+
       const results = [];
       if (concurrency <= 1) {
         // Sequential streaming path — historical default, preserved.
@@ -274,11 +331,7 @@ export function makeOrchestratorProvider(opts = {}) {
           yield `**Subtask ${sub.id}** \`${worker.name}${worker.model ? ':' + worker.model : ''}\` — ${sub.task}\n\n`;
           let res = '';
           try {
-            for await (const chunk of worker.prov.sendMessage([{ role: 'user', content: sub.task }], {
-              apiKey: keyResolver(cfg, worker.name),
-              model: worker.model || undefined,
-              signal: callerOpts.signal,
-            })) {
+            for await (const chunk of _workerChunks(worker, sub)) {
               const s = String(chunk);
               res += s;
               yield s;
@@ -301,11 +354,7 @@ export function makeOrchestratorProvider(opts = {}) {
           const chunks = [];
           let error = null;
           try {
-            for await (const chunk of worker.prov.sendMessage([{ role: 'user', content: sub.task }], {
-              apiKey: keyResolver(cfg, worker.name),
-              model: worker.model || undefined,
-              signal: callerOpts.signal,
-            })) {
+            for await (const chunk of _workerChunks(worker, sub)) {
               chunks.push(String(chunk));
             }
           } catch (e) {
@@ -393,3 +442,54 @@ export function makeOrchestratorProvider(opts = {}) {
     },
   };
 }
+
+// Minimal one-shot worker dispatch for the `delegate` agent tool.
+//
+// `delegate` hands a single subtask to ONE provider — no plan/synthesis.
+// It reuses the same spec-resolution + key-resolution infra the
+// orchestrator's EXECUTE phase uses (a "<provider>[:<model>]" spec routed
+// through PROVIDERS/PROVIDER_INFO, key via lib/config::_resolveAuthKey),
+// but as a standalone call so the `delegate` tool actually runs.
+//
+// Imports are lazy so this module keeps its leaf static-dep graph (it must
+// NOT statically import ./registry.mjs — that re-forms the registry↔orch
+// cycle; see the header note above).
+//
+// job = { worker: '<provider>[:<model>]', prompt, model? }
+// returns { ok:true, text } | { ok:false, error }
+export async function dispatchWorker(job = {}) {
+  const workerSpec = String(job?.worker || '');
+  const prompt = String(job?.prompt || '');
+  if (!workerSpec || !prompt) return { ok: false, error: 'delegate: worker + prompt required' };
+
+  let registry, config;
+  try {
+    registry = await import('./registry.mjs');
+    config = await import('../lib/config.mjs');
+  } catch (e) {
+    return { ok: false, error: `delegate: failed to load provider infra: ${e?.message || String(e)}` };
+  }
+
+  const lookup = (p) => ({ prov: registry.PROVIDERS[p], info: registry.PROVIDER_INFO[p] });
+  const worker = _lookupProvider(workerSpec, lookup);
+  if (!worker) return { ok: false, error: `delegate: unknown worker provider "${_parseSpec(workerSpec).provider}"` };
+  if (worker.name === 'orchestrator') return { ok: false, error: 'delegate: worker cannot be "orchestrator"' };
+  // Explicit job.model overrides the model parsed from the spec.
+  const model = String(job?.model || '') || worker.model || '';
+
+  const cfg = config.readConfig() || {};
+  const apiKey = config._resolveAuthKey(cfg, worker.name);
+
+  let text = '';
+  try {
+    for await (const chunk of worker.prov.sendMessage([{ role: 'user', content: prompt }], {
+      apiKey,
+      model: model || undefined,
+    })) {
+      text += String(chunk);
+    }
+  } catch (e) {
+    return { ok: false, error: `delegate: ${worker.name} error: ${e?.message || String(e)}` };
+  }
+  return { ok: true, text };
+}