@ikarmic/forge-core 5.1.1 → 5.3.0

package/dist/tools/search-worker.js

@@ -0,0 +1,77 @@
+/**
+ * search_files' matching, run in a worker thread with a time limit. JavaScript cannot interrupt a running regex, so a
+ * pattern that backtracks badly on the main thread froze the process (in VS Code, the extension host): in a worker it
+ * is terminated after `timeoutMs`. The worker source is a plain string, not a function's text, so a bundler cannot
+ * rename or wrap anything in it; the same string runs in-process when a worker cannot start.
+ */
+import { readFileSync } from 'node:fs';
+import { Worker } from 'node:worker_threads';
+export const DEFAULT_SEARCH_TIMEOUT_MS = 20_000;
+/** Body of `function (job, readFile)`: read each file, skip binaries, match line by line, keep context. */
+const MATCH_BODY = String.raw `
+  var regex = new RegExp(job.source, job.flags);
+  var matches = [];
+  var truncated = false;
+  var filesScanned = 0;
+  function truncateByLines(text, maxLines) {
+    var lines = text.split(/\r?\n/);
+    if (lines.length <= maxLines) return text;
+    var dropped = lines.length - maxLines;
+    return lines.slice(0, maxLines).join('\n') + '\n\n... (' + dropped + ' more line' + (dropped === 1 ? '' : 's') + ' truncated; re-read with a smaller offset to see more)';
+  }
+  for (var f = 0; f < job.files.length; f++) {
+    if (matches.length >= job.maxResults) { truncated = true; break; }
+    var file = job.files[f];
+    filesScanned++;
+    var buf;
+    try { buf = readFile(file.abs); } catch (e) { continue; }
+    if (buf.includes(0)) continue;
+    var lines = buf.toString('utf8').split(/\r?\n/);
+    for (var i = 0; i < lines.length; i++) {
+      if (matches.length >= job.maxResults) { truncated = true; break; }
+      regex.lastIndex = 0;
+      if (regex.test(lines[i])) {
+        var start = Math.max(0, i - job.contextLines);
+        var end = Math.min(lines.length - 1, i + job.contextLines);
+        var block = [];
+        for (var j = start; j <= end; j++) block.push((j === i ? '>' : ' ') + ' ' + String(j + 1).padStart(6) + '\t' + lines[j]);
+        matches.push({ path: file.rel, line: i + 1, text: truncateByLines(block.join('\n'), 10) });
+      }
+    }
+  }
+  return { matches: matches, truncated: truncated, filesScanned: filesScanned };
+`;
+const WORKER_SOURCE = `
+const { parentPort, workerData } = require('node:worker_threads');
+const fs = require('node:fs');
+const match = new Function('job', 'readFile', ${JSON.stringify(MATCH_BODY)});
+parentPort.postMessage(match(workerData, (p) => fs.readFileSync(p)));
+`;
+function matchInProcess(job) {
+    return new Function('job', 'readFile', MATCH_BODY)(job, (p) => readFileSync(p));
+}
+/** Match `job` in a worker; throws when it runs longer than `timeoutMs`. Falls back to in-process if no worker starts. */
+export function matchInWorker(job, opts) {
+    let worker;
+    try {
+        worker = (opts.startWorker ?? ((source, data) => new Worker(source, { eval: true, workerData: data })))(WORKER_SOURCE, job);
+    }
+    catch {
+        return Promise.resolve(matchInProcess(job));
+    }
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            void worker.terminate();
+            reject(new Error(`The search pattern took longer than ${Math.round(opts.timeoutMs / 1000)} s and was stopped. Simplify it (avoid repeated groups that can match the same text in several ways) or search fewer files.`));
+        }, opts.timeoutMs);
+        worker.once('message', (result) => {
+            clearTimeout(timer);
+            void worker.terminate();
+            resolve(result);
+        });
+        worker.once('error', (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}

package/dist/tools/sub-agent-wait.d.ts

@@ -1,15 +1,9 @@
 import { z } from 'zod';
 import type { ToolDefinition } from '../types.js';
 declare const params: z.ZodObject<{
-    ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
     timeout_seconds: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    ids?: string[] | undefined;
-    timeout_seconds?: number | undefined;
-}, {
-    ids?: string[] | undefined;
-    timeout_seconds?: number | undefined;
-}>;
+}, z.core.$strip>;
 export interface SubAgentWaitResult {
     agents: Array<{
         id: string;

package/dist/tools/sub-agent.d.ts

@@ -2,84 +2,16 @@ import { z } from 'zod';
 import { type AgentDef } from '../agents/agent-files.js';
 import type { AgentConfig, ModelConfig, ToolContext, ToolDefinition } from '../types.js';
 declare const params: z.ZodObject<{
-    /** The task for the sub-agent to perform. Free-form text. */
     task: z.ZodString;
-    /** Name of an agent file (`.forge/agents/<name>.md`) to run as: its prompt, tools, model and step cap. */
     agent: z.ZodOptional<z.ZodString>;
-    /** Hard cap on iterations for the sub-agent. Default 10. */
     max_iterations: z.ZodOptional<z.ZodNumber>;
-    /**
-     * Run the sub-agent without approval prompts (autonomous). Defaults to
-     * `false` even when the parent is in `--auto` mode: the sub-agent is
-     * expected to be focused and short-lived, so the explicit opt-in is
-     * deliberate to avoid runaway destructive work.
-     */
     auto: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * Working directory for the sub-agent. Defaults to the parent's cwd.
-     * Useful when the sub-task should operate on a subdirectory without
-     * dragging the parent through the navigation.
-     */
     cwd: z.ZodOptional<z.ZodString>;
-    /**
-     * Run the sub-agent in an isolated git worktree. The worktree is
-     * created at `<repoRoot>/.forge/worktrees/<label>/`, the child runs
-     * there, and the worktree is removed on completion (success or
-     * error). Falls back to plain `cwd` mode (with a stderr warning)
-     * when the parent's cwd is not inside a git repo.
-     *
-     * Pair this with `orchestrator run` parallel dispatch (v2.3) to
-     * safely run multiple specialists concurrently without them
-     * clobbering each other's files.
-     */
     use_worktree: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * Human-readable label for the worktree (used in the branch name and
-     * directory). Defaults to a random short hash. Ignored when
-     * `use_worktree` is false.
-     */
     worktree_label: z.ZodOptional<z.ZodString>;
-    /**
-     * v2.14: when `use_worktree: true`, also delete the auto-created
-     * `forge/<label>-<short-sha>` branch once the worktree's working
-     * tree is gone. Default `true` because sub-agents are short-lived
-     * and orphan branches are pure clutter.
-     *
-     * Set to `false` when you want to inspect the diff afterwards (e.g.
-     * `git diff main..forge/<label>-<sha>`) or hand the branch to a
-     * human reviewer.
-     *
-     * The branch is only deleted when no other worktree currently
-     * references it, so two Forge sessions working on the same branch
-     * won't collide.
-     */
     cleanup_branch: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * Start the child and return at once. The child keeps working while the parent continues; collect its answer with
-     * `sub_agent_wait`. Only where the surface can show background runs; elsewhere the child runs to completion as usual.
-     */
     background: z.ZodOptional<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    task: string;
-    agent?: string | undefined;
-    cwd?: string | undefined;
-    auto?: boolean | undefined;
-    background?: boolean | undefined;
-    max_iterations?: number | undefined;
-    use_worktree?: boolean | undefined;
-    worktree_label?: string | undefined;
-    cleanup_branch?: boolean | undefined;
-}, {
-    task: string;
-    agent?: string | undefined;
-    cwd?: string | undefined;
-    auto?: boolean | undefined;
-    background?: boolean | undefined;
-    max_iterations?: number | undefined;
-    use_worktree?: boolean | undefined;
-    worktree_label?: string | undefined;
-    cleanup_branch?: boolean | undefined;
-}>;
+}, z.core.$strip>;
 /** What `sub_agent { background: true }` returns instead of a result. */
 export interface SubAgentStarted {
     started: true;
@@ -145,7 +77,7 @@ export declare function childAgentConfig(setup: {
     model: ModelConfig;
     maxIterations: number;
     systemPrompt?: string;
-}, ctx: Pick<ToolContext, 'autoApproveTools' | 'permissionRules' | 'toolSandbox' | 'askBudget'>, cwd: string, auto: boolean): AgentConfig;
+}, ctx: Pick<ToolContext, 'autoApproveTools' | 'permissionRules' | 'toolSandbox' | 'askBudget' | 'commandSandbox'>, cwd: string, auto: boolean): AgentConfig;
 /** What a child runs without asking: what the parent does, else the read-only tools. Destructive tools still never run unasked. */
 export declare function childAutoApprove(ctx: Pick<ToolContext, 'autoApproveTools'>): string[];
 /** The configured sub-agent model, else the parent's, else a last-resort default. */

package/dist/tools/sub-agent.js

@@ -328,6 +328,7 @@ export function childAgentConfig(setup, ctx, cwd, auto) {
         autoApproveTools: childAutoApprove(ctx),
         ...(ctx.permissionRules ? { permissionRules: ctx.permissionRules } : {}),
         ...(ctx.toolSandbox ? { toolSandbox: ctx.toolSandbox } : {}),
+        ...(ctx.commandSandbox ? { commandSandbox: ctx.commandSandbox } : {}),
         // The same budget object, not a copy: a child that started its own four
         // would be a way around the limit the parent is under (RB-14).
         ...(ctx.askBudget ? { askBudget: ctx.askBudget } : {}),

package/dist/tools/todo.d.ts

@@ -7,26 +7,14 @@ import type { TodoItem, ToolDefinition } from '../types.js';
 declare const writeParams: z.ZodObject<{
     todos: z.ZodArray<z.ZodObject<{
         content: z.ZodString;
-        status: z.ZodEnum<["pending", "in_progress", "completed"]>;
-    }, "strip", z.ZodTypeAny, {
-        status: "pending" | "in_progress" | "completed";
-        content: string;
-    }, {
-        status: "pending" | "in_progress" | "completed";
-        content: string;
-    }>, "many">;
-}, "strip", z.ZodTypeAny, {
-    todos: {
-        status: "pending" | "in_progress" | "completed";
-        content: string;
-    }[];
-}, {
-    todos: {
-        status: "pending" | "in_progress" | "completed";
-        content: string;
-    }[];
-}>;
-declare const readParams: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+        status: z.ZodEnum<{
+            pending: "pending";
+            in_progress: "in_progress";
+            completed: "completed";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const readParams: z.ZodObject<{}, z.core.$strip>;
 export declare const todoWriteTool: ToolDefinition<z.infer<typeof writeParams>, {
     todos: TodoItem[];
 }>;

package/dist/tools/web-search.d.ts

@@ -39,13 +39,7 @@ export declare function searchWeb(cfg: WebSearchConfig, query: string, count: nu
 declare const params: z.ZodObject<{
     query: z.ZodString;
     max_results: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    query: string;
-    max_results?: number | undefined;
-}, {
-    query: string;
-    max_results?: number | undefined;
-}>;
+}, z.core.$strip>;
 export interface WebSearchToolResult {
     provider: WebSearchProvider;
     query: string;

package/dist/tools/write-file.d.ts

@@ -3,13 +3,7 @@ import type { ToolDefinition } from '../types.js';
 declare const params: z.ZodObject<{
     path: z.ZodString;
     content: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    path: string;
-    content: string;
-}, {
-    path: string;
-    content: string;
-}>;
+}, z.core.$strip>;
 export interface WriteFileResult {
     path: string;
     bytes: number;

package/dist/types.d.ts

@@ -107,6 +107,10 @@ export interface ToolContext {
      * the default `child_process` runner.
      */
     commandRunner?: CommandRunner;
+    /** How long `search_files` may match before its worker is stopped. Default 20 s. */
+    searchTimeoutMs?: number;
+    /** Run `run_command` inside the OS sandbox (`AgentConfig.commandSandbox`); handed to sub-agents. */
+    commandSandbox?: CommandSandbox;
     /** The model sub-agents use instead of the parent's (`AgentConfig.subAgentModel`). */
     subAgentModel?: ModelConfig;
     /** Folder `AGENTS.md` paths already shown in this run; `read_file` adds each folder's file once. */
@@ -176,6 +180,13 @@ export type ModelRouter = (ctx: {
     /** Tool names the model called on the previous step (empty on the first). */
     lastToolNames: string[];
 }) => ModelConfig | undefined;
+/** What `run_command`'s OS sandbox allows besides writing to the workspace and the temp folder. */
+export interface CommandSandbox {
+    /** Let commands reach the network. */
+    network: boolean;
+    /** More folders commands may write to (a package manager's cache, say). */
+    extraWritable?: string[];
+}
 /**
  * Executes one shell command on behalf of `run_command`. Return `null` to decline
  * (e.g. no terminal available); the default `child_process` runner then handles it.
@@ -250,6 +261,11 @@ export interface ChildProgressEvent {
     /** Any event the child emitted. */
     event: AgentEvent;
 }
+/**
+ * How a tool call was let through: the person approved it, a permission rule allowed it, it is on the
+ * auto-approve list, memory writes are allowed, the command is on the "Always allow" list, or the run is Autonomous.
+ */
+export type ApprovalSource = 'person' | 'rule' | 'list' | 'memory' | 'always' | 'autonomous';
 /** Streamed agent event: surfaced to the UI via the AgentRunOptions.onEvent callback. */
 export type AgentEvent = {
     type: 'text_delta';
@@ -263,11 +279,14 @@ export type AgentEvent = {
 } | {
     type: 'reasoning_done';
     text: string;
-} | {
+}
+/** `approval` says how the call was let through; absent for bookkeeping tools that never ask (the todo list). */
+ | {
     type: 'tool_call';
     name: string;
     id: string;
     args: unknown;
+    approval?: ApprovalSource;
 } | {
     type: 'tool_result';
     name: string;
@@ -343,6 +362,22 @@ export type AgentEvent = {
 } | {
     type: 'continuation'; /** 1-based count of continuations so far in this run. */
     count: number;
+}
+/**
+ * The step now running failed (a provider error worth retrying, or an empty reply) and is being asked again after
+ * `delayMs`. Everything it streamed is discarded: a UI drops the step's partial text.
+ */
+/** The model ended a turn with `open` items of its own todo list still open and was reminded once (RB-44). */
+ | {
+    type: 'todo_nudge';
+    open: number;
+} | {
+    type: 'retry';
+    kind: 'provider_error' | 'empty_reply' | 'offline';
+    attempt: number;
+    maxRetries: number;
+    delayMs: number;
+    reason: string;
 } | {
     type: 'phase';
     /** Architect/editor mode: which phase the following events belong to. */
@@ -564,6 +599,8 @@ export interface AgentConfig {
      * be surprising.
      */
     disableMemory?: boolean;
+    /** Leave out the `<stack>` block (the versions the workspace's files state). Default: included. */
+    disableStackFacts?: boolean;
     /**
      * Skip injecting `AGENTS.md` / `CLAUDE.md` / `CONVENTIONS.md` from the
      * working directory into the system prompt.
@@ -740,6 +777,23 @@ export interface AgentConfig {
      * Each continuation is a normal iteration (counts toward every cap).
      */
     maxContinuations?: number;
+    /**
+     * Retrying a step whose model call failed with something a retry can fix (429, 5xx, overload, dropped
+     * connection). Default 5 retries, back-off from 2 s (doubling, capped at 30 s) unless the provider sends
+     * retry-after. An empty or reasoning-only reply is asked for again twice, separately.
+     */
+    providerRetry?: {
+        maxRetries?: number;
+        baseDelayMs?: number;
+        /**
+         * With no network at all (DNS or route gone) the run waits instead of spending retries: it probes every
+         * `offlinePollMs` (default 3 s) for up to `maxOfflineMs` in total (default 15 min), then reports the error.
+         */
+        offlinePollMs?: number;
+        maxOfflineMs?: number;
+        /** True when the network is reachable; default dials a few public addresses over TCP. */
+        networkProbe?: () => Promise<boolean>;
+    };
     /**
      * Pick the model for each step (cheap for exploration, strong for planning…).
      * Return `undefined` to keep the current model. Cost is priced per routed model.
@@ -747,6 +801,11 @@ export interface AgentConfig {
     modelRouter?: ModelRouter;
     /** Replace how `run_command` executes. See {@link CommandRunner}. */
     commandRunner?: CommandRunner;
+    /**
+     * Confine `run_command` with the OS sandbox: bubblewrap on Linux, sandbox-exec on macOS. A command is refused when
+     * the tool is missing; Windows has no equivalent, so there commands run as before. Absent = off.
+     */
+    commandSandbox?: CommandSandbox;
     /**
      * Answers `ask_user`. When absent, or when `auto` is on, the model is not offered the tool.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikarmic/forge-core",
-  "version": "5.1.1",
+  "version": "5.3.0",
   "description": "Agent engine for IKarmic AI Forge. Model loop, tools, MCP, sandbox, memory, compaction, plan mode, skills, hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,13 +56,13 @@
     "tree-sitter-wasms": "^0.1.13",
     "undici": "^7.30.0",
     "web-tree-sitter": "0.20.8",
-    "zod": "^3.23.0"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@ai-sdk/provider": "^4.0.0",
     "@types/node": "^22.7.0",
     "typescript": "^5.6.3",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.5"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",