reasonix 0.28.0 → 0.29.0

package/dist/index.d.ts

@@ -694,6 +694,8 @@ interface ToolDefinition<A = any, R = any> {
     readOnly?: boolean;
     /** Per-args check; takes precedence over `readOnly`. e.g. `run_command` + allowlisted argv. */
     readOnlyCheck?: (args: A) => boolean;
+    /** Safe to dispatch concurrently with other parallel-safe calls in the same turn. Default false — opt-in only. */
+    parallelSafe?: boolean;
     fn: (args: A, ctx?: ToolCallContext) => R | Promise<R>;
 }
 interface ToolRegistryOptions {
@@ -729,6 +731,8 @@ declare class ToolRegistry {
     get size(): number;
     /** True if a registered tool's schema was flattened for the model. */
     wasFlattened(name: string): boolean;
+    /** Unknown / unannotated tools default to false — third-party MCP tools must opt in. */
+    isParallelSafe(name: string): boolean;
     specs(): ToolSpec[];
     dispatch(name: string, argumentsRaw: string | Record<string, unknown>, opts?: {
         signal?: AbortSignal;
@@ -840,6 +844,7 @@ declare class CacheFirstLoop {
     private modelForCurrentCall;
     /** Returns true ONLY on the tipping call — caller surfaces a one-shot warning. */
     private noteToolFailureSignal;
+    private runOneToolCall;
     private buildMessages;
     abort(): void;
     /** Drop the last user message + everything after; caller re-sends. Persists to session file. */
@@ -1102,6 +1107,8 @@ declare function registerPlanTool(registry: ToolRegistry, opts?: PlanToolOptions
 /** Side-channel — subagents run inside a tool-dispatch frame, can't go through parent's `LoopEvent` stream. */
 interface SubagentEvent {
     kind: "start" | "progress" | "end" | "inner" | "phase";
+    /** Stable per-spawn id; lets the UI key parallel runs apart instead of overwriting one shared row. */
+    runId: string;
     task: string;
     skillName?: string;
     model?: string;

package/dist/index.js

@@ -1046,6 +1046,10 @@ var ToolRegistry = class {
   wasFlattened(name) {
     return Boolean(this._tools.get(name)?.flatSchema);
   }
+  /** Unknown / unannotated tools default to false — third-party MCP tools must opt in. */
+  isParallelSafe(name) {
+    return this._tools.get(name)?.parallelSafe === true;
+  }
   specs() {
     return [...this._tools.values()].map((t) => ({
       type: "function",
@@ -2640,6 +2644,48 @@ var CacheFirstLoop = class {
     this._escalateThisTurn = true;
     return true;
   }
+  async runOneToolCall(call, signal) {
+    const name = call.function?.name ?? "";
+    const args = call.function?.arguments ?? "{}";
+    const parsedArgs = safeParseToolArgs(args);
+    const preReport = await runHooks({
+      hooks: this.hooks,
+      payload: {
+        event: "PreToolUse",
+        cwd: this.hookCwd,
+        toolName: name,
+        toolArgs: parsedArgs
+      }
+    });
+    const preWarnings = [...hookWarnings(preReport.outcomes, this._turn)];
+    if (preReport.blocked) {
+      const blocking = preReport.outcomes[preReport.outcomes.length - 1];
+      const reason = (blocking?.stderr || blocking?.stdout || "blocked by PreToolUse hook").trim();
+      return {
+        preWarnings,
+        postWarnings: [],
+        result: `[hook block] ${blocking?.hook.command ?? "<unknown>"}
+${reason}`
+      };
+    }
+    const result = await this.tools.dispatch(name, args, {
+      signal,
+      maxResultTokens: DEFAULT_MAX_RESULT_TOKENS,
+      confirmationGate: this.confirmationGate
+    });
+    const postReport = await runHooks({
+      hooks: this.hooks,
+      payload: {
+        event: "PostToolUse",
+        cwd: this.hookCwd,
+        toolName: name,
+        toolArgs: parsedArgs,
+        toolResult: result
+      }
+    });
+    const postWarnings = [...hookWarnings(postReport.outcomes, this._turn)];
+    return { preWarnings, postWarnings, result };
+  }
   buildMessages(pendingUser) {
     const healed = healLoadedMessages(this.log.toMessages(), DEFAULT_MAX_RESULT_CHARS);
     const msgs = [...this.prefix.toMessages(), ...healed.messages];
@@ -3131,71 +3177,69 @@ var CacheFirstLoop = class {
         yield* forceSummaryAfterIterLimit(this.summaryContext(), { reason: "context-guard" });
         return;
       }
-      for (const call of repairedCalls) {
-        const name = call.function?.name ?? "";
-        const args = call.function?.arguments ?? "{}";
-        yield {
-          turn: this._turn,
-          role: "tool_start",
-          content: "",
-          toolName: name,
-          toolArgs: args
-        };
-        const parsedArgs = safeParseToolArgs(args);
-        const preReport = await runHooks({
-          hooks: this.hooks,
-          payload: {
-            event: "PreToolUse",
-            cwd: this.hookCwd,
-            toolName: name,
-            toolArgs: parsedArgs
+      const dispatchSerial = (process.env.REASONIX_TOOL_DISPATCH ?? "auto").toLowerCase() === "serial";
+      const parallelMaxParsed = Number.parseInt(process.env.REASONIX_PARALLEL_MAX ?? "", 10);
+      const parallelMax = Number.isFinite(parallelMaxParsed) && parallelMaxParsed >= 1 ? Math.min(parallelMaxParsed, 16) : 3;
+      let callIdx = 0;
+      while (callIdx < repairedCalls.length) {
+        const chunk = [];
+        if (!dispatchSerial) {
+          while (callIdx < repairedCalls.length && chunk.length < parallelMax && this.tools.isParallelSafe(repairedCalls[callIdx]?.function?.name ?? "")) {
+            chunk.push(repairedCalls[callIdx++]);
           }
-        });
-        for (const w of hookWarnings(preReport.outcomes, this._turn)) yield w;
-        let result;
-        if (preReport.blocked) {
-          const blocking = preReport.outcomes[preReport.outcomes.length - 1];
-          const reason = (blocking?.stderr || blocking?.stdout || "blocked by PreToolUse hook").trim();
-          result = `[hook block] ${blocking?.hook.command ?? "<unknown>"}
-${reason}`;
-        } else {
-          result = await this.tools.dispatch(name, args, {
-            signal,
-            maxResultTokens: DEFAULT_MAX_RESULT_TOKENS,
-            confirmationGate: this.confirmationGate
-          });
-          const postReport = await runHooks({
-            hooks: this.hooks,
-            payload: {
-              event: "PostToolUse",
-              cwd: this.hookCwd,
-              toolName: name,
-              toolArgs: parsedArgs,
-              toolResult: result
-            }
-          });
-          for (const w of hookWarnings(postReport.outcomes, this._turn)) yield w;
         }
-        this.appendAndPersist({
-          role: "tool",
-          tool_call_id: call.id ?? "",
-          name,
-          content: result
-        });
-        if (this.noteToolFailureSignal(result)) {
+        if (chunk.length === 0) {
+          chunk.push(repairedCalls[callIdx++]);
+        }
+        for (const call of chunk) {
           yield {
             turn: this._turn,
-            role: "warning",
-            content: `\u21E7 auto-escalating to ${ESCALATION_MODEL} for the rest of this turn \u2014 flash hit ${this._turnFailures.formatBreakdown()}. Next turn falls back to ${this.model} unless /pro is armed.`
+            role: "tool_start",
+            content: "",
+            toolName: call.function?.name ?? "",
+            toolArgs: call.function?.arguments ?? "{}"
+          };
+        }
+        const settled = await Promise.allSettled(chunk.map((c) => this.runOneToolCall(c, signal)));
+        for (let k = 0; k < chunk.length; k++) {
+          const call = chunk[k];
+          const name = call.function?.name ?? "";
+          const args = call.function?.arguments ?? "{}";
+          const s = settled[k];
+          let result;
+          let preWarnings = [];
+          let postWarnings = [];
+          if (s.status === "fulfilled") {
+            preWarnings = s.value.preWarnings;
+            postWarnings = s.value.postWarnings;
+            result = s.value.result;
+          } else {
+            const err = s.reason instanceof Error ? s.reason : new Error(String(s.reason));
+            result = JSON.stringify({ error: `${err.name}: ${err.message}` });
+          }
+          for (const w of preWarnings) yield w;
+          for (const w of postWarnings) yield w;
+          this.appendAndPersist({
+            role: "tool",
+            tool_call_id: call.id ?? "",
+            name,
+            content: result
+          });
+          if (this.noteToolFailureSignal(result)) {
+            yield {
+              turn: this._turn,
+              role: "warning",
+              content: `\u21E7 auto-escalating to ${ESCALATION_MODEL} for the rest of this turn \u2014 flash hit ${this._turnFailures.formatBreakdown()}. Next turn falls back to ${this.model} unless /pro is armed.`
+            };
+          }
+          yield {
+            turn: this._turn,
+            role: "tool",
+            content: result,
+            toolName: name,
+            toolArgs: args
           };
         }
-        yield {
-          turn: this._turn,
-          role: "tool",
-          content: result,
-          toolName: name,
-          toolArgs: args
-        };
       }
     }
     yield* forceSummaryAfterIterLimit(this.summaryContext(), { reason: "budget" });
@@ -4604,6 +4648,7 @@ function registerFilesystemTools(registry, opts) {
   };
   registry.register({
     name: "read_file",
+    parallelSafe: true,
     description: `Read a file under the sandbox root. To save context, PREFER to scope the read instead of pulling the whole file:
   - head: N  \u2192 first N lines (imports, public API, small configs)
   - tail: N  \u2192 last N lines (recently-added code, log tails)
@@ -4687,6 +4732,7 @@ ${slice.join("\n")}`;
   });
   registry.register({
     name: "list_directory",
+    parallelSafe: true,
     description: "List entries in a directory under the sandbox root. Returns one line per entry, marking directories with a trailing slash. Not recursive \u2014 use directory_tree for that.",
     readOnly: true,
     parameters: {
@@ -4707,6 +4753,7 @@ ${slice.join("\n")}`;
   });
   registry.register({
     name: "directory_tree",
+    parallelSafe: true,
     description: `Recursively list entries in a directory. Shows indented tree structure with directories marked '/'. Budget-aware by default:
   - maxDepth defaults to 2 (root + one level). A depth-4 tree on a real repo blew ~5K tokens in one call. If you truly need deeper, pass maxDepth:N explicitly.
   - Skips ${[...SKIP_DIR_NAMES].sort().join(", ")} unless include_deps:true. Traversing into node_modules / .git / dist is almost always token-waste.
@@ -4785,6 +4832,7 @@ Prefer \`list_directory\` for a single-level view, \`search_files\` to find spec
   });
   registry.register({
     name: "search_files",
+    parallelSafe: true,
     description: "Find files whose NAME matches a substring or regex. Case-insensitive. Walks the directory recursively under the sandbox root. Returns one path per line. Skips dependency / VCS / build directories (node_modules, .git, dist, build, .next, target, .venv) by default.",
     readOnly: true,
     parameters: {
@@ -4810,6 +4858,7 @@ Prefer \`list_directory\` for a single-level view, \`search_files\` to find spec
   });
   registry.register({
     name: "search_content",
+    parallelSafe: true,
     description: "Recursively grep file CONTENTS for a substring or regex. This is the right tool for 'find all places that call X', 'where is Y referenced', 'what files contain Z'. Different from search_files (which matches FILE NAMES). Returns one match per line in 'path:line: text' format. Skips dependency / VCS / build directories (node_modules, .git, dist, build, .next, target, .venv) and binary files by default.",
     readOnly: true,
     parameters: {
@@ -4852,6 +4901,7 @@ Prefer \`list_directory\` for a single-level view, \`search_files\` to find spec
   });
   registry.register({
     name: "get_file_info",
+    parallelSafe: true,
     description: "Stat a path under the sandbox root. Returns type (file|directory|symlink), size in bytes, mtime in ISO-8601.",
     readOnly: true,
     parameters: {
@@ -5032,6 +5082,7 @@ function registerMemoryTools(registry, opts = {}) {
     name: "recall_memory",
     description: "Read the full body of a memory file when its MEMORY.md one-liner (already in the system prompt) isn't enough detail. Most of the time the index suffices \u2014 only call this when the user's question genuinely requires the full context.",
     readOnly: true,
+    parallelSafe: true,
     parameters: {
       type: "object",
       properties: {
@@ -5458,6 +5509,11 @@ function getSubagentType(name) {
 }
 
 // src/tools/subagent.ts
+var runIdCounter = 0;
+function nextRunId() {
+  runIdCounter++;
+  return `sub-${runIdCounter.toString(36)}`;
+}
 var DEFAULT_SUBAGENT_SYSTEM = `You are a Reasonix subagent. The parent agent spawned you to handle one focused subtask, then return.
 
 Rules:
@@ -5486,9 +5542,11 @@ async function spawnSubagent(opts) {
   const sink = opts.sink;
   const skillName = opts.skillName;
   const startedAt = Date.now();
+  const runId = nextRunId();
   const taskPreview = opts.task.length > 30 ? `${opts.task.slice(0, 30)}\u2026` : opts.task;
   sink?.current?.({
     kind: "start",
+    runId,
     task: taskPreview,
     skillName,
     model,
@@ -5501,6 +5559,7 @@ async function spawnSubagent(opts) {
       const errorMessage2 = `subagent allow-list names tool(s) not registered in the parent: ${missing.join(", ")}. Fix the skill's \`allowed-tools\` frontmatter or check spelling.`;
       sink?.current?.({
         kind: "end",
+        runId,
         task: taskPreview,
         skillName,
         model,
@@ -5562,12 +5621,13 @@ async function spawnSubagent(opts) {
   let summarisingEmitted = false;
   try {
     for await (const ev of childLoop.step(opts.task)) {
-      sink?.current?.({ kind: "inner", task: taskPreview, skillName, model, inner: ev });
+      sink?.current?.({ kind: "inner", runId, task: taskPreview, skillName, model, inner: ev });
       if (ev.role === "tool") {
         toolIter++;
         summarisingEmitted = false;
         sink?.current?.({
           kind: "progress",
+          runId,
           task: taskPreview,
           skillName,
           model,
@@ -5579,6 +5639,7 @@ async function spawnSubagent(opts) {
         summarisingEmitted = true;
         sink?.current?.({
           kind: "phase",
+          runId,
           task: taskPreview,
           skillName,
           model,
@@ -5615,6 +5676,7 @@ async function spawnSubagent(opts) {
 [\u2026truncated ${final.length - maxResultChars} chars; ask the subagent for a tighter summary if you need more.]` : final;
   sink?.current?.({
     kind: "end",
+    runId,
     task: taskPreview,
     skillName,
     model,
@@ -5678,6 +5740,7 @@ function registerSubagentTool(parentRegistry, opts) {
   const sink = opts.sink;
   parentRegistry.register({
     name: SUBAGENT_TOOL_NAME,
+    parallelSafe: true,
     description: "Spawn an isolated subagent to handle a self-contained subtask in a fresh context, returning only its final answer. Use for: deep codebase exploration that would flood the main context, multi-step research where you only need the conclusion, or any focused subtask whose intermediate reasoning the user does not need to see. The subagent inherits all your tools (filesystem, shell, web, MCP, etc.) but runs in its own isolated message log \u2014 its tool calls and reasoning never enter your context. Only the final assistant message comes back as this tool's result. Keep tasks focused; the subagent has a stricter iter budget than you do.",
     parameters: {
       type: "object",
@@ -7103,6 +7166,7 @@ function registerShellTools(registry, opts) {
     name: "job_output",
     description: "Read the latest output of a background job started with `run_background`. By default returns the tail of the buffer (last 80 lines). Pass `since` (the `byteLength` from a previous call) to stream only new content incrementally. Tells you whether the job is still running, so you can stop polling when it's done.",
     readOnly: true,
+    parallelSafe: true,
     parameters: {
       type: "object",
       properties: {
@@ -7147,6 +7211,7 @@ function registerShellTools(registry, opts) {
     name: "list_jobs",
     description: "List every background job started this session \u2014 running and exited \u2014 with id, command, pid, status. Use when you've lost track of which job_id corresponds to which process, or to see what's still alive.",
     readOnly: true,
+    parallelSafe: true,
     parameters: { type: "object", properties: {} },
     fn: async () => {
       const all = jobs.list();
@@ -7404,6 +7469,7 @@ function registerWebTools(registry, opts = {}) {
     name: "web_search",
     description: "Search the public web. Returns ranked results with title, url, and snippet. Call this when the answer's correctness depends on current state \u2014 anything that changes over time (events, prices, releases, status of a thing in the real world). Composing such answers from training memory invents stale numbers; search first, then ground the answer in the results. For evergreen / definitional questions you don't need this.",
     readOnly: true,
+    parallelSafe: true,
     parameters: {
       type: "object",
       properties: {
@@ -7427,6 +7493,7 @@ function registerWebTools(registry, opts = {}) {
     name: "web_fetch",
     description: "Download a URL and return its visible text content (HTML pages get scripts/styles/nav stripped). Truncated at the tool-result cap. Use after web_search when a snippet isn't enough.",
     readOnly: true,
+    parallelSafe: true,
     parameters: {
       type: "object",
       properties: {