@ikarmic/forge-core 5.0.0 → 5.1.0

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

@@ -0,0 +1,12 @@
+/**
+ * The tools that change files. Anything that lists "the write tools" (read-only modes, plan and ask modes, dry
+ * runs, checkpoints, permission rules) must include every one of these; `tests/write-tools-guard.test.ts` scans
+ * the code for lists that do not. Add a new file-changing tool here and in that scan's failures.
+ */
+export declare const FILE_WRITE_TOOL_NAMES: readonly ["write_file", "edit_file", "edit_notebook", "apply_patch"];
+/**
+ * The files a tool call works on: every file of an `apply_patch` (its paths are inside the patch text), else the
+ * call's `path`. Anything that reacts to "a file was written or read" (auto-lint, steering, changed-file lists) uses
+ * this, never `args.path` alone.
+ */
+export declare function filesTouchedBy(toolName: string, args: unknown): string[];

package/dist/tools/write-tools.js

@@ -0,0 +1,18 @@
+import { patchedPaths } from './apply-patch.js';
+/**
+ * The tools that change files. Anything that lists "the write tools" (read-only modes, plan and ask modes, dry
+ * runs, checkpoints, permission rules) must include every one of these; `tests/write-tools-guard.test.ts` scans
+ * the code for lists that do not. Add a new file-changing tool here and in that scan's failures.
+ */
+export const FILE_WRITE_TOOL_NAMES = ['write_file', 'edit_file', 'edit_notebook', 'apply_patch'];
+/**
+ * The files a tool call works on: every file of an `apply_patch` (its paths are inside the patch text), else the
+ * call's `path`. Anything that reacts to "a file was written or read" (auto-lint, steering, changed-file lists) uses
+ * this, never `args.path` alone.
+ */
+export function filesTouchedBy(toolName, args) {
+    const a = (args ?? {});
+    if (toolName === 'apply_patch')
+        return typeof a.patch === 'string' ? patchedPaths(a.patch) : [];
+    return typeof a.path === 'string' ? [a.path] : [];
+}

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { ModelMessage, LanguageModel } from 'ai';
 import type { z } from 'zod';
+import type { BackgroundAgents } from './agent/background.js';
 import type { Attachment } from './attachments.js';
 import type { SkillRegistry } from './skills/types.js';
 /**
@@ -20,6 +21,11 @@ export type ProviderName = 'openai' | 'anthropic' | 'google' | 'ollama' | 'openr
 export interface ModelConfig {
     provider: ProviderName;
     model: string;
+    /**
+     * A named provider (preset or `customProviders`) resolved to where the call goes. Set together with
+     * `provider: 'openai-compatible'`; `createLanguageModel` then ignores the OPENAI_COMPATIBLE_* environment.
+     */
+    endpoint?: import('./custom-providers.js').ProviderEndpoint;
     /**
      * Reasoning effort for models that support it. Passed straight through
      * to the AI SDK's own unified `reasoning` call option: no per-provider
@@ -27,6 +33,8 @@ export interface ModelConfig {
      * behavior, unchanged from today.
      */
     reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh';
+    /** Sampling temperature (0 to 2); omitted = the provider's default. Set by an agent file. */
+    temperature?: number;
 }
 /**
  * A tool definition as the agent sees it: a name, a Zod parameter schema, and
@@ -34,6 +42,18 @@ export interface ModelConfig {
  * so it can decide whether to expose the `execute` function (autonomous mode)
  * or strip it (interactive mode where approval is required).
  */
+/** A question for the person (`ask_user`). */
+export interface UserQuestion {
+    question: string;
+    options?: string[];
+    allowCustom?: boolean;
+}
+/** One step of the agent's checklist (`todo_write`). */
+export interface TodoItem {
+    id: string;
+    content: string;
+    status: 'pending' | 'in_progress' | 'completed';
+}
 export interface ToolDefinition<TArgs = unknown, TResult = unknown> {
     name: string;
     description: string;
@@ -44,6 +64,8 @@ export interface ToolDefinition<TArgs = unknown, TResult = unknown> {
      * approval even in `--auto` mode unless the user passes `--yes-destructive`.
      */
     destructive?: boolean;
+    /** True for tools that only change the session's own bookkeeping (the todo list): never asked about, whatever the mode. */
+    noApproval?: boolean;
     /**
      * Optional text shown in the approval prompt so the user sees what the call
      * will change (for example a diff). Failures are swallowed: no preview, still asked.
@@ -84,8 +106,28 @@ export interface ToolContext {
      * the default `child_process` runner.
      */
     commandRunner?: CommandRunner;
+    /** 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. */
+    shownFolderInstructions?: Set<string>;
+    /** Longest output `run_command` returns per stream before cutting the middle (`AgentConfig.maxToolOutputChars`). */
+    maxOutputChars?: number;
+    /** Asks the person a question (`ask_user`); absent when no surface can answer. */
+    askUser?: (question: UserQuestion, signal?: AbortSignal) => Promise<string>;
+    /** The run's todo list. `set` also tells the UI (`todo_updated`). Supplied by the Agent. */
+    todos?: {
+        get(): TodoItem[];
+        set(todos: TodoItem[]): void;
+    };
     /** The run's abort signal; long-running tools (run_command) stop when it fires. */
     abortSignal?: AbortSignal;
+    /** The tools the parent runs without asking; a sub-agent starts from the same list (it has no one to ask). */
+    autoApproveTools?: readonly string[];
+    /** The parent's permission rules and tool sandbox, handed to a sub-agent so it cannot step around them. */
+    permissionRules?: import('./tools/permission-rules.js').PermissionConfig;
+    toolSandbox?: ToolSandbox;
+    /** Where `sub_agent { background: true }` runs go; absent where no surface can show them (the child then runs to completion as usual). */
+    background?: BackgroundAgents;
     /** Longest body `memory_write` accepts, in characters; absent = the default of 1200. */
     memoryMaxBodyChars?: number;
     /** A command that outlives its timeout must be stopped, not left running (verification checks; a dev server must not be). */
@@ -233,6 +275,9 @@ export type AgentEvent = {
     name: string;
     id: string;
     args: unknown;
+} | {
+    type: 'todo_updated';
+    todos: TodoItem[];
 } | {
     type: 'iteration';
     iteration: number;
@@ -514,6 +559,12 @@ export interface AgentConfig {
      * working directory into the system prompt.
      */
     disableProjectInstructions?: boolean;
+    /** Extra instruction sources (files, globs, URLs) from the user's `instructions` setting. */
+    extraInstructions?: string[];
+    /** What connected MCP servers say about using them (see `mcpInstructionsBlock`); added to the system prompt as it is. */
+    mcpInstructions?: string;
+    /** Longest `run_command` output per stream, in characters. Default 200000. */
+    maxToolOutputChars?: number;
     /**
      * A ready-made `<project-commands>` block (see `formatProjectCommandsBlock`) telling the model how
      * this project is checked and built. Added to the system prompt after the project instructions.
@@ -609,6 +660,9 @@ export interface AgentConfig {
      */
     semanticSearch?: {
         embedder?: import('./semantic/embedder.js').Embedder;
+        extensions?: string[];
+        minScore?: number;
+        defaultLimit?: number;
     };
     /**
      * After the model finishes a run that edited files, run these commands and
@@ -625,6 +679,13 @@ export interface AgentConfig {
      * "a destructive tool is never auto-approved"; see `isListedCommand`.
      */
     autoApproveCommands?: string[];
+    /**
+     * Ordered permission rules (`read`, `edit`, `bash`, `webfetch`, `websearch`, `task`, `external_directory`, `*`):
+     * the last matching rule wins; `deny` blocks the call, `ask` always prompts (even in `auto` mode), `allow` runs it
+     * without a prompt. `.env` reads and commands that reach outside `cwd` prompt unless a rule says otherwise.
+     * See tools/permission-rules.ts.
+     */
+    permissionRules?: import('./tools/permission-rules.js').PermissionConfig;
     /**
      * Put a token-budgeted outline of the codebase (files and their top symbol
      * signatures, ranked by how much other code depends on them) in the system prompt.
@@ -669,6 +730,18 @@ export interface AgentConfig {
     modelRouter?: ModelRouter;
     /** Replace how `run_command` executes. See {@link CommandRunner}. */
     commandRunner?: CommandRunner;
+    /**
+     * Answers `ask_user`. When absent, or when `auto` is on, the model is not offered the tool.
+     */
+    askUser?: (question: UserQuestion, signal?: AbortSignal) => Promise<string>;
+    /** The model `sub_agent` children run on; the parent's model when unset. */
+    subAgentModel?: ModelConfig;
+    /** Where background sub-agents are kept between messages. Without it `sub_agent { background: true }` runs the child to completion. */
+    backgroundAgents?: BackgroundAgents;
+    /** The todo list a run starts with (the chat keeps it between turns). */
+    initialTodos?: TodoItem[];
+    /** Never offer `ask_user`, even when `askUser` is set (a goal run must not stop to ask). */
+    disableAskUser?: boolean;
     /** Custom approval callback. If absent, uses an internal yes/no gate. */
     approve?: (event: ApprovalRequest) => Promise<ApprovalDecision> | ApprovalDecision;
     /** Abort signal. */

package/dist/worktree/worktree.d.ts

@@ -237,6 +237,7 @@ export declare class WorktreeManager {
      * clean up so we don't leak orphan directories.
      */
     create(opts?: CreateOptions): Promise<WorktreeInfo>;
+    private createNow;
     /**
      * Remove a worktree previously created by this manager. By default
      * refuses if the worktree is dirty (uncommitted changes); pass
@@ -252,6 +253,7 @@ export declare class WorktreeManager {
      * outcome (e.g. emit "removed worktree + branch X" on the CLI).
      */
     remove(worktreePath: string, opts?: RemoveOptions): Promise<RemoveResult>;
+    private removeNow;
     /**
      * Best-effort cleanup of every worktree this manager created. Used
      * by the sub_agent tool's finally block so a child crash doesn't
@@ -270,6 +272,7 @@ export declare class WorktreeManager {
      * leak.
      */
     pruneStale(): Promise<number>;
+    private pruneStaleNow;
     /**
      * List worktrees under our `.forge/worktrees/` directory. Returns
      * the empty array when none exist or git isn't available.

package/dist/worktree/worktree.js

@@ -284,6 +284,9 @@ export class WorktreeManager {
      * clean up so we don't leak orphan directories.
      */
     async create(opts = {}) {
+        return onRepoQueue(this.repoRoot, () => this.createNow(opts));
+    }
+    async createNow(opts) {
         // Generate a label + branch name first so we can pass them to git.
         const label = opts.label ? sanitizeLabel(opts.label) : randomLabel();
         const branch = opts.branchName ?? `forge/${label}-${await shortSha(this.repoRoot)}`;
@@ -341,6 +344,9 @@ export class WorktreeManager {
      * outcome (e.g. emit "removed worktree + branch X" on the CLI).
      */
     async remove(worktreePath, opts = {}) {
+        return onRepoQueue(this.repoRoot, () => this.removeNow(worktreePath, opts));
+    }
+    async removeNow(worktreePath, opts) {
         const resolved = path.resolve(worktreePath);
         const normalizedRoot = path.resolve(this.worktreesRoot);
         if (!resolved.startsWith(normalizedRoot + path.sep) && resolved !== normalizedRoot) {
@@ -395,6 +401,9 @@ export class WorktreeManager {
      * leak.
      */
     async pruneStale() {
+        return onRepoQueue(this.repoRoot, () => this.pruneStaleNow());
+    }
+    async pruneStaleNow() {
         let pruned = 0;
         try {
             const { stdout } = await runGit(this.repoRoot, [
@@ -626,6 +635,19 @@ export function canonicalPath(p) {
  * with the stderr message in the Error. We use `execFile` (not `exec`)
  * so user-controlled input can't shell-inject.
  */
+const repoQueues = new Map();
+/**
+ * Run `work` after every earlier queued worktree change of the same repository has finished. Parallel steps create
+ * and remove worktrees at the same moment, and two `git worktree add` / `remove` calls on one repository fight over
+ * git's lock files; one of them then fails at random, mostly under load. The agents still run in parallel: only these
+ * short git changes take turns.
+ */
+function onRepoQueue(repoRoot, work) {
+    const key = canonicalPath(repoRoot);
+    const next = (repoQueues.get(key) ?? Promise.resolve()).then(work, work);
+    repoQueues.set(key, next.catch(() => undefined));
+    return next;
+}
 async function runGit(cwd, args) {
     return await execFileAsync('git', args, { cwd, maxBuffer: 16 * 1024 * 1024 });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikarmic/forge-core",
-  "version": "5.0.0",
+  "version": "5.1.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",