@ikarmic/forge-core 5.0.0 → 5.1.1

package/dist/config-schema.d.ts

@@ -0,0 +1,340 @@
+import type { ForgeConfigFile } from './config-file.js';
+/** Compile-time proof that the schema below covers every key of `ForgeConfigFile`: add a key there and this stops compiling. */
+export declare const CONFIG_KEY_COVERAGE: Record<keyof ForgeConfigFile, true>;
+/** JSON Schema (draft-07) for `~/.forge/config.json` and `<workspace>/.forge/config.json`. */
+export declare const FORGE_CONFIG_SCHEMA: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "Ikarmic Forge config";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly provider: {
+            readonly description: "The model provider to use.";
+            readonly enum: readonly import("./types.js").ProviderName[];
+        };
+        readonly model: {
+            readonly type: "string";
+            readonly description: "The model id, an alias, or provider:model.";
+        };
+        readonly completionModel: {
+            readonly type: "string";
+            readonly description: "Model for inline completion; empty uses the main model.";
+        };
+        readonly compactionModel: {
+            readonly type: "string";
+            readonly description: "Model that writes the summary when a long chat is condensed; empty uses the main model.";
+        };
+        readonly disabledProviders: {
+            readonly type: "array";
+            readonly description: "Providers hidden from the model picker.";
+            readonly items: {
+                readonly enum: readonly import("./types.js").ProviderName[];
+            };
+        };
+        readonly reasoningEffort: {
+            readonly enum: readonly ["none", "minimal", "low", "medium", "high", "xhigh"];
+            readonly description: "Reasoning effort for models that support it.";
+        };
+        readonly autoApproveTools: {
+            readonly description: "Tools that run without asking. Default: the read-only tools. Destructive tools always ask. User config only.";
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly autoApproveCommands: {
+            readonly type: "object";
+            readonly description: "Commands you chose \"Always allow\", per workspace path. Written by Forge; user config only.";
+            readonly additionalProperties: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly command: {
+                            readonly type: "string";
+                        };
+                        readonly fingerprint: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly required: readonly ["command"];
+                };
+            };
+        };
+        readonly permission: {
+            readonly type: "object";
+            readonly description: "Ordered permission rules. Each permission (read, edit, bash, webfetch, websearch, task, external_directory) is an action or a pattern to action map; the last matching rule wins. A project file can only tighten (ask, deny).";
+            readonly additionalProperties: {
+                readonly oneOf: readonly [{
+                    readonly enum: readonly ["allow", "ask", "deny"];
+                }, {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly enum: readonly ["allow", "ask", "deny"];
+                    };
+                }];
+            };
+        };
+        readonly customProviders: {
+            readonly type: "object";
+            readonly description: "Providers beyond the built-in ones, by id. A preset id (groq, deepseek, mistral, ...) needs only a key; any other id needs a baseUrl. A model on one is written id:model. User config only.";
+            readonly additionalProperties: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly baseUrl: {
+                        readonly type: "string";
+                        readonly format: "uri";
+                    };
+                    readonly apiKey: {
+                        readonly type: "string";
+                        readonly description: "Stored as plain text; prefer apiKeyEnv.";
+                    };
+                    readonly apiKeyEnv: {
+                        readonly type: "string";
+                        readonly description: "Name of the environment variable that holds the key.";
+                    };
+                    readonly headers: {
+                        readonly type: "object";
+                        readonly additionalProperties: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly api: {
+                        readonly enum: readonly ["openai-compatible", "anthropic"];
+                    };
+                    readonly timeoutMs: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                    };
+                    readonly chunkTimeoutMs: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                    };
+                    readonly models: {
+                        readonly type: "object";
+                        readonly additionalProperties: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly id: {
+                                    readonly type: "string";
+                                    readonly description: "The id sent to the API when it differs from the key here.";
+                                };
+                                readonly name: {
+                                    readonly type: "string";
+                                };
+                                readonly limit: {
+                                    readonly type: "object";
+                                    readonly properties: {
+                                        readonly context: {
+                                            readonly type: "integer";
+                                            readonly minimum: 1;
+                                        };
+                                        readonly output: {
+                                            readonly type: "integer";
+                                            readonly minimum: 1;
+                                        };
+                                    };
+                                    readonly additionalProperties: false;
+                                };
+                                readonly cost: {
+                                    readonly type: "object";
+                                    readonly description: "Price per million tokens.";
+                                    readonly properties: {
+                                        readonly input: {
+                                            readonly type: "number";
+                                            readonly minimum: 0;
+                                        };
+                                        readonly output: {
+                                            readonly type: "number";
+                                            readonly minimum: 0;
+                                        };
+                                    };
+                                    readonly additionalProperties: false;
+                                };
+                                readonly toolCall: {
+                                    readonly type: "boolean";
+                                };
+                                readonly reasoning: {
+                                    readonly type: "boolean";
+                                };
+                                readonly modalities: {
+                                    readonly type: "object";
+                                    readonly properties: {
+                                        readonly input: {
+                                            readonly type: "array";
+                                            readonly items: {
+                                                readonly type: "string";
+                                            };
+                                        };
+                                        readonly output: {
+                                            readonly type: "array";
+                                            readonly items: {
+                                                readonly type: "string";
+                                            };
+                                        };
+                                    };
+                                    readonly required: readonly ["input", "output"];
+                                };
+                            };
+                        };
+                    };
+                    readonly whitelist: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly blacklist: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+        };
+        readonly modelOverrides: {
+            readonly type: "object";
+            readonly description: "Context and output limits and prices per model, keyed provider:model, id:model or a bare model id.";
+            readonly additionalProperties: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly limit: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly context: {
+                                readonly type: "integer";
+                                readonly minimum: 1;
+                            };
+                            readonly output: {
+                                readonly type: "integer";
+                                readonly minimum: 1;
+                            };
+                        };
+                        readonly additionalProperties: false;
+                    };
+                    readonly cost: {
+                        readonly type: "object";
+                        readonly description: "Price per million tokens.";
+                        readonly properties: {
+                            readonly input: {
+                                readonly type: "number";
+                                readonly minimum: 0;
+                            };
+                            readonly output: {
+                                readonly type: "number";
+                                readonly minimum: 0;
+                            };
+                        };
+                        readonly additionalProperties: false;
+                    };
+                };
+                readonly additionalProperties: false;
+            };
+        };
+        readonly modelFilters: {
+            readonly type: "object";
+            readonly description: "Per provider, which model ids the pickers list: whitelist (only these), then blacklist (not these).";
+            readonly additionalProperties: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly whitelist: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly blacklist: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+                readonly additionalProperties: false;
+            };
+        };
+        readonly subagentModel: {
+            readonly type: "string";
+            readonly description: "The model sub-agents use when the model does not name one; empty means the chat model.";
+        };
+        readonly instructions: {
+            readonly description: "Extra instruction sources added to the system prompt: files, globs (relative to the workspace) and http(s) URLs. User config only.";
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly skillPaths: {
+            readonly description: "Extra places to read skills from: folders (absolute, ~/..., or relative to the workspace) or http(s) URLs of a skill file or a skill index. User config only.";
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly caCertificates: {
+            readonly description: "PEM files of extra certificate authorities to trust (absolute or ~/...), for networks that re-sign TLS. Needs a window reload. User config only.";
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly aliases: {
+            readonly type: "object";
+            readonly description: "Short names for models, for example \"fast\": \"anthropic:claude-haiku-4-5\".";
+            readonly additionalProperties: {
+                readonly type: "string";
+            };
+        };
+        readonly modeModels: {
+            readonly type: "object";
+            readonly description: "Model for a chat mode that has none of its own: mode id to model.";
+            readonly additionalProperties: {
+                readonly type: "string";
+            };
+        };
+        readonly sessionRetentionDays: {
+            readonly type: "integer";
+            readonly minimum: 1;
+            readonly description: "Delete saved chats not updated for this many days when the extension starts. Unset keeps everything. User config only.";
+        };
+        readonly display: {
+            readonly type: "object";
+            readonly description: "How blocks in the chat are shown.";
+            readonly properties: {
+                readonly blockDefault: {
+                    readonly enum: readonly ["collapsed", "expanded"];
+                };
+                readonly detail: {
+                    readonly enum: readonly ["compact", "full"];
+                };
+                readonly showReasoning: {
+                    readonly type: "boolean";
+                };
+                readonly blocks: {
+                    readonly type: "object";
+                    readonly description: "Per kind of block: reasoning, terminal (command output), edit (file edits), mcp (MCP tool results).";
+                    readonly properties: {
+                        readonly reasoning: {
+                            readonly enum: readonly ["hidden", "collapsed", "expanded"];
+                        };
+                        readonly terminal: {
+                            readonly enum: readonly ["collapsed", "expanded"];
+                        };
+                        readonly edit: {
+                            readonly enum: readonly ["collapsed", "expanded"];
+                        };
+                        readonly mcp: {
+                            readonly enum: readonly ["collapsed", "expanded"];
+                        };
+                    };
+                    readonly additionalProperties: false;
+                };
+            };
+            readonly additionalProperties: false;
+        };
+    };
+};

package/dist/config-schema.js

@@ -0,0 +1,126 @@
+import { SUPPORTED_PROVIDERS } from './config.js';
+/** Compile-time proof that the schema below covers every key of `ForgeConfigFile`: add a key there and this stops compiling. */
+export const CONFIG_KEY_COVERAGE = {
+    provider: true,
+    model: true,
+    completionModel: true,
+    compactionModel: true,
+    disabledProviders: true,
+    reasoningEffort: true,
+    autoApproveTools: true,
+    autoApproveCommands: true,
+    permission: true,
+    customProviders: true,
+    modelOverrides: true,
+    modelFilters: true,
+    subagentModel: true,
+    instructions: true,
+    skillPaths: true,
+    caCertificates: true,
+    aliases: true,
+    modeModels: true,
+    sessionRetentionDays: true,
+    display: true,
+};
+const strings = { type: 'array', items: { type: 'string' } };
+const limit = { type: 'object', properties: { context: { type: 'integer', minimum: 1 }, output: { type: 'integer', minimum: 1 } }, additionalProperties: false };
+const cost = { type: 'object', description: 'Price per million tokens.', properties: { input: { type: 'number', minimum: 0 }, output: { type: 'number', minimum: 0 } }, additionalProperties: false };
+const action = { enum: ['allow', 'ask', 'deny'] };
+/** JSON Schema (draft-07) for `~/.forge/config.json` and `<workspace>/.forge/config.json`. */
+export const FORGE_CONFIG_SCHEMA = {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    title: 'Ikarmic Forge config',
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        provider: { description: 'The model provider to use.', enum: [...SUPPORTED_PROVIDERS] },
+        model: { type: 'string', description: 'The model id, an alias, or provider:model.' },
+        completionModel: { type: 'string', description: 'Model for inline completion; empty uses the main model.' },
+        compactionModel: { type: 'string', description: 'Model that writes the summary when a long chat is condensed; empty uses the main model.' },
+        disabledProviders: { type: 'array', description: 'Providers hidden from the model picker.', items: { enum: [...SUPPORTED_PROVIDERS] } },
+        reasoningEffort: { enum: ['none', 'minimal', 'low', 'medium', 'high', 'xhigh'], description: 'Reasoning effort for models that support it.' },
+        autoApproveTools: { ...strings, description: 'Tools that run without asking. Default: the read-only tools. Destructive tools always ask. User config only.' },
+        autoApproveCommands: {
+            type: 'object',
+            description: 'Commands you chose "Always allow", per workspace path. Written by Forge; user config only.',
+            additionalProperties: { type: 'array', items: { type: 'object', properties: { command: { type: 'string' }, fingerprint: { type: 'string' } }, required: ['command'] } },
+        },
+        permission: {
+            type: 'object',
+            description: 'Ordered permission rules. Each permission (read, edit, bash, webfetch, websearch, task, external_directory) is an action or a pattern to action map; the last matching rule wins. A project file can only tighten (ask, deny).',
+            additionalProperties: { oneOf: [action, { type: 'object', additionalProperties: action }] },
+        },
+        customProviders: {
+            type: 'object',
+            description: 'Providers beyond the built-in ones, by id. A preset id (groq, deepseek, mistral, ...) needs only a key; any other id needs a baseUrl. A model on one is written id:model. User config only.',
+            additionalProperties: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                    baseUrl: { type: 'string', format: 'uri' },
+                    apiKey: { type: 'string', description: 'Stored as plain text; prefer apiKeyEnv.' },
+                    apiKeyEnv: { type: 'string', description: 'Name of the environment variable that holds the key.' },
+                    headers: { type: 'object', additionalProperties: { type: 'string' } },
+                    api: { enum: ['openai-compatible', 'anthropic'] },
+                    timeoutMs: { type: 'integer', minimum: 1 },
+                    chunkTimeoutMs: { type: 'integer', minimum: 1 },
+                    models: {
+                        type: 'object',
+                        additionalProperties: {
+                            type: 'object',
+                            properties: {
+                                id: { type: 'string', description: 'The id sent to the API when it differs from the key here.' },
+                                name: { type: 'string' },
+                                limit,
+                                cost,
+                                toolCall: { type: 'boolean' },
+                                reasoning: { type: 'boolean' },
+                                modalities: { type: 'object', properties: { input: strings, output: strings }, required: ['input', 'output'] },
+                            },
+                        },
+                    },
+                    whitelist: strings,
+                    blacklist: strings,
+                },
+            },
+        },
+        modelOverrides: {
+            type: 'object',
+            description: 'Context and output limits and prices per model, keyed provider:model, id:model or a bare model id.',
+            additionalProperties: { type: 'object', properties: { limit, cost }, additionalProperties: false },
+        },
+        modelFilters: {
+            type: 'object',
+            description: 'Per provider, which model ids the pickers list: whitelist (only these), then blacklist (not these).',
+            additionalProperties: { type: 'object', properties: { whitelist: strings, blacklist: strings }, additionalProperties: false },
+        },
+        subagentModel: { type: 'string', description: 'The model sub-agents use when the model does not name one; empty means the chat model.' },
+        instructions: { ...strings, description: 'Extra instruction sources added to the system prompt: files, globs (relative to the workspace) and http(s) URLs. User config only.' },
+        skillPaths: { ...strings, description: 'Extra places to read skills from: folders (absolute, ~/..., or relative to the workspace) or http(s) URLs of a skill file or a skill index. User config only.' },
+        caCertificates: { ...strings, description: 'PEM files of extra certificate authorities to trust (absolute or ~/...), for networks that re-sign TLS. Needs a window reload. User config only.' },
+        aliases: { type: 'object', description: 'Short names for models, for example "fast": "anthropic:claude-haiku-4-5".', additionalProperties: { type: 'string' } },
+        modeModels: { type: 'object', description: 'Model for a chat mode that has none of its own: mode id to model.', additionalProperties: { type: 'string' } },
+        sessionRetentionDays: { type: 'integer', minimum: 1, description: 'Delete saved chats not updated for this many days when the extension starts. Unset keeps everything. User config only.' },
+        display: {
+            type: 'object',
+            description: 'How blocks in the chat are shown.',
+            properties: {
+                blockDefault: { enum: ['collapsed', 'expanded'] },
+                detail: { enum: ['compact', 'full'] },
+                showReasoning: { type: 'boolean' },
+                blocks: {
+                    type: 'object',
+                    description: 'Per kind of block: reasoning, terminal (command output), edit (file edits), mcp (MCP tool results).',
+                    properties: {
+                        reasoning: { enum: ['hidden', 'collapsed', 'expanded'] },
+                        terminal: { enum: ['collapsed', 'expanded'] },
+                        edit: { enum: ['collapsed', 'expanded'] },
+                        mcp: { enum: ['collapsed', 'expanded'] },
+                    },
+                    additionalProperties: false,
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+};

package/dist/config.js

@@ -125,7 +125,8 @@ export function fastDefaultFor(provider) {
         case 'openrouter':
             return 'openai/gpt-4o-mini';
         case 'minimax':
-            return 'MiniMax-M2';
+            // MiniMax-M2 was retired (error 2069). M3 answered a completion fastest in a live check.
+            return 'MiniMax-M3';
         case 'bedrock':
             return 'us.anthropic.claude-haiku-4-5-20251001-v1:0';
         case 'vertex':

package/dist/context/compaction.js

@@ -14,6 +14,7 @@
 import { generateText } from 'ai';
 import { mediaPartLabel, mediaPartTokens } from '../attachments.js';
 import { stripThinkTags } from '../agent/think-tags.js';
+import { overrideContextTokens } from '../model-overrides.js';
 import { createLanguageModel } from '../providers.js';
 /**
  * Approximate model context window (input) in tokens. Used to decide when
@@ -84,6 +85,9 @@ const WINDOW_SIZES = {
     'minimax-m2': 204_800,
 };
 export function getModelWindowTokens(model) {
+    const overridden = overrideContextTokens(model);
+    if (overridden)
+        return overridden;
     const id = typeof model === 'string' ? model : model.model;
     const stripped = id.toLowerCase().replace(/^models\//, '');
     // Direct hit first.

package/dist/context/mask.js

@@ -1,5 +1,5 @@
 /** Results that say what a change did are kept: they are small and the model must not forget them. */
-export const NEVER_MASK_TOOLS = new Set(['write_file', 'edit_file', 'edit_notebook', 'run_command', 'sub_agent']);
+export const NEVER_MASK_TOOLS = new Set(['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'run_command', 'sub_agent']);
 const STUB_MARK = 'result not shown to save context';
 /** Index of the first message of the last `keepRecentTurns` assistant turns (0 when there are not that many). */
 export function maskBoundary(messages, keepRecentTurns) {

package/dist/custom-providers.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Named providers beyond the built-in eleven: a table of well-known OpenAI-compatible services plus whatever the
+ * user defines under `customProviders` in `~/.forge/config.json`. A model on one of them is written `id:model`
+ * (e.g. `groq:llama-3.3-70b-versatile`) and resolves to an endpoint (base URL, key, headers) that
+ * `createLanguageModel` calls with the OpenAI chat or Anthropic message style. Pure; nothing here reads files.
+ */
+export type EndpointApi = 'openai-compatible' | 'anthropic';
+export interface CustomModelConfig {
+    /** The id sent to the API when the key used in Forge differs from it. */
+    id?: string;
+    name?: string;
+    limit?: {
+        context?: number;
+        output?: number;
+    };
+    cost?: {
+        input?: number;
+        output?: number;
+    };
+    toolCall?: boolean;
+    reasoning?: boolean;
+    modalities?: {
+        input: string[];
+        output: string[];
+    };
+}
+export interface CustomProviderConfig {
+    name?: string;
+    baseUrl?: string;
+    /** Stored as plain text in the config file; prefer `apiKeyEnv`. */
+    apiKey?: string;
+    /** Name of the environment variable that holds the key. */
+    apiKeyEnv?: string;
+    headers?: Record<string, string>;
+    api?: EndpointApi;
+    /** Give up on a request that has not answered after this many milliseconds. */
+    timeoutMs?: number;
+    /** Abort a streamed answer that stays silent this long. */
+    chunkTimeoutMs?: number;
+    models?: Record<string, CustomModelConfig>;
+    whitelist?: string[];
+    blacklist?: string[];
+}
+/** Where a call goes: the resolved form of a provider, carried on `ModelConfig.endpoint`. */
+export interface ProviderEndpoint {
+    id: string;
+    name: string;
+    baseUrl: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    api: EndpointApi;
+    timeoutMs?: number;
+    chunkTimeoutMs?: number;
+}
+export interface ProviderPreset {
+    name: string;
+    baseUrl: string;
+    apiKeyEnv: string;
+    api?: EndpointApi;
+}
+/** Defaults for services that speak the OpenAI chat protocol. Any field can be overridden under `customProviders`. */
+export declare const PROVIDER_PRESETS: Readonly<Record<string, ProviderPreset>>;
+/** Why an entry of `customProviders` cannot be used, one problem per bad entry. A preset id may omit its URL. */
+export declare function customProviderProblems(custom: Record<string, CustomProviderConfig> | undefined): Array<{
+    id: string;
+    message: string;
+}>;
+/**
+ * The `customProviders` of the running host, so every place that turns a model name into a model (aliases,
+ * the cheap model, sub-agents, the picker) sees them without each call site passing the config along.
+ * Hosts register at the start of every run; tests reset with `undefined`.
+ */
+export declare function registerCustomProviders(custom: Record<string, CustomProviderConfig> | undefined): void;
+export declare function registeredCustomProviders(): Record<string, CustomProviderConfig> | undefined;
+export interface ModelFilter {
+    whitelist?: string[];
+    blacklist?: string[];
+}
+/** `modelFilters` of the running host (per provider id), read by the model pickers. */
+export declare function registerModelFilters(filters: Record<string, ModelFilter> | undefined): void;
+/** The filter for a provider id: the registered `modelFilters` entry, else the whitelist/blacklist on its custom provider. */
+export declare function modelFilterFor(providerId: string): ModelFilter | undefined;
+/** Preset ids and custom ids, once each; a built-in id never appears. */
+export declare function knownProviderIds(custom: Record<string, CustomProviderConfig> | undefined): string[];
+/** The endpoint for a provider id, or undefined when the id is built-in, unknown, or has no usable URL. */
+export declare function resolveProviderEndpoint(id: string, custom: Record<string, CustomProviderConfig> | undefined, env?: NodeJS.ProcessEnv): ProviderEndpoint | undefined;
+/** The id the API expects for a model key (`models.<key>.id`), or the key itself. */
+export declare function apiModelId(providerId: string, modelKey: string, custom: Record<string, CustomProviderConfig> | undefined): string;
+/** Apply a provider's `whitelist` (only these) then `blacklist` (not these) to a model list. */
+export declare function filterModels<T extends {
+    id: string;
+}>(entries: readonly T[], filter: {
+    whitelist?: string[];
+    blacklist?: string[];
+} | undefined): T[];