@ikarmic/forge-core 5.0.0 → 5.1.1

package/dist/types.d.ts

@@ -1,6 +1,8 @@
 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 { Answer } from './journey/types.js';
 import type { SkillRegistry } from './skills/types.js';
 /**
  * The summarizer takes a chunk of messages and returns a structured
@@ -20,6 +22,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 +34,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 +43,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 +65,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 +107,37 @@ 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>;
+    /**
+     * How many questions this run may still ask (a guided journey's interview
+     * budget). Mutated in place as questions are asked, and handed to a child
+     * agent so a child cannot start a fresh four (RB-14). Absent means no limit.
+     */
+    askBudget?: {
+        max: number;
+        used: number;
+    };
+    /** 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 +285,9 @@ export type AgentEvent = {
     name: string;
     id: string;
     args: unknown;
+} | {
+    type: 'todo_updated';
+    todos: TodoItem[];
 } | {
     type: 'iteration';
     iteration: number;
@@ -514,11 +569,24 @@ 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.
      */
     projectCommands?: string;
+    /**
+     * Answers the person gave in a guided journey's interview, rendered into the
+     * system prompt as a `<journey-answers>` block. The interview runs before the
+     * first agent run, because the blocks are assembled only on a session's first
+     * turn (see `buildInitialMessages`), so answers that arrive later cannot enter.
+     */
+    journeyAnswers?: Answer[];
     /**
      * Override the byte budget for memory injected into the system prompt.
      * Default 8 KB. Larger budgets use more context window but surface more
@@ -609,6 +677,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 +696,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 +747,26 @@ 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>;
+    /**
+     * How many `ask_user` questions this run may ask. Reaches tools as
+     * `ToolContext.askBudget` and is handed down to sub-agents. Absent means no limit.
+     */
+    askBudget?: {
+        max: number;
+        used: number;
+    };
+    /** 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.1",
   "description": "Agent engine for IKarmic AI Forge. Model loop, tools, MCP, sandbox, memory, compaction, plan mode, skills, hooks.",
   "type": "module",
   "main": "./dist/index.js",