@ikarmic/forge-core 5.0.0 → 5.1.1

package/dist/model-list.js

@@ -1,3 +1,4 @@
+import { installedFetch } from './policy/proxy.js';
 /** Providers whose catalog can be listed over HTTP. Bedrock, Vertex and Azure list per account, not per key. */
 export const LISTABLE_PROVIDERS = ['openai', 'anthropic', 'google', 'openrouter', 'minimax', 'ollama', 'lmstudio', 'openai-compatible'];
 /** OpenAI's `/models` also returns embeddings, speech, images and moderation models; none can chat. */
@@ -68,7 +69,7 @@ export async function fetchProviderModels(provider, opts = {}) {
     if (needsKey && !opts.apiKey)
         throw new Error('Add an API key to see the current models.');
     const { url, headers } = requestFor(provider, opts);
-    const doFetch = opts.fetch ?? fetch;
+    const doFetch = opts.fetch ?? installedFetch() ?? fetch;
     let res;
     try {
         res = await doFetch(url, { headers, ...(opts.signal ? { signal: opts.signal } : {}) });

package/dist/model-overrides.d.ts

@@ -0,0 +1,30 @@
+import type { CustomProviderConfig } from './custom-providers.js';
+import type { ModelConfig } from './types.js';
+/**
+ * Per-model numbers the user knows better than the built-in tables: context and output limits and prices.
+ * Keys are `provider:model`, `<named provider id>:model`, or a bare model id (any provider). The hosts register
+ * the map at the start of every run; the context-window and pricing lookups consult it first.
+ */
+export interface ModelOverride {
+    limit?: {
+        context?: number;
+        output?: number;
+    };
+    cost?: {
+        input?: number;
+        output?: number;
+    };
+}
+export type ModelOverrides = Record<string, ModelOverride>;
+export declare function registerModelOverrides(map: ModelOverrides | undefined): void;
+/** The override for a model, trying the named provider's key, then `provider:model`, then the bare model id. */
+export declare function getModelOverride(model: string | ModelConfig): ModelOverride | undefined;
+/** The context window an override sets, or undefined (zero, negative and non-numbers are ignored). */
+export declare function overrideContextTokens(model: string | ModelConfig): number | undefined;
+/** The prices an override sets; both rates must be given and not negative. */
+export declare function overrideCost(model: string | ModelConfig): {
+    input: number;
+    output: number;
+} | undefined;
+/** Overrides from the `limit` and `cost` of each model under `customProviders`, keyed by provider id and API model id. */
+export declare function overridesFromProviders(custom: Record<string, CustomProviderConfig> | undefined): ModelOverrides;

package/dist/model-overrides.js

@@ -0,0 +1,48 @@
+import { apiModelId } from './custom-providers.js';
+let current = {};
+export function registerModelOverrides(map) {
+    current = map ?? {};
+}
+const lower = (map) => new Map(Object.entries(map).map(([k, v]) => [k.toLowerCase(), v]));
+/** The override for a model, trying the named provider's key, then `provider:model`, then the bare model id. */
+export function getModelOverride(model) {
+    if (Object.keys(current).length === 0)
+        return undefined;
+    const table = lower(current);
+    const id = (typeof model === 'string' ? model : model.model).toLowerCase();
+    if (typeof model !== 'string') {
+        if (model.endpoint) {
+            const named = table.get(`${model.endpoint.id}:${id}`.toLowerCase());
+            if (named)
+                return named;
+        }
+        const scoped = table.get(`${model.provider}:${id}`);
+        if (scoped)
+            return scoped;
+    }
+    return table.get(id);
+}
+const positive = (n) => typeof n === 'number' && Number.isFinite(n) && n > 0;
+const nonNegative = (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+/** The context window an override sets, or undefined (zero, negative and non-numbers are ignored). */
+export function overrideContextTokens(model) {
+    const c = getModelOverride(model)?.limit?.context;
+    return positive(c) ? c : undefined;
+}
+/** The prices an override sets; both rates must be given and not negative. */
+export function overrideCost(model) {
+    const c = getModelOverride(model)?.cost;
+    return c && nonNegative(c.input) && nonNegative(c.output) ? { input: c.input, output: c.output } : undefined;
+}
+/** Overrides from the `limit` and `cost` of each model under `customProviders`, keyed by provider id and API model id. */
+export function overridesFromProviders(custom) {
+    const out = {};
+    for (const [id, provider] of Object.entries(custom ?? {})) {
+        for (const [key, m] of Object.entries(provider.models ?? {})) {
+            if (!m.limit && !m.cost)
+                continue;
+            out[`${id}:${apiModelId(id, key, custom)}`] = { ...(m.limit ? { limit: m.limit } : {}), ...(m.cost ? { cost: m.cost } : {}) };
+        }
+    }
+    return out;
+}

package/dist/orchestrator/specialists-registry.js

@@ -28,11 +28,11 @@
  * are fine (Map operations are atomic in V8); we don't need locks.
  */
 import { readFileSync } from 'node:fs';
-import { mkdir, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { resolve as resolvePath } from 'node:path';
 import { SUPPORTED_PROVIDERS } from '../config.js';
 import { BUILTIN_SPECIALISTS } from './specialists.js';
+import { updateJsonFile } from '../config-file.js';
 /** Sentinel key the module-level Map lives behind. */
 const REGISTRY = new Map();
 /**
@@ -167,8 +167,7 @@ export async function saveSpecialistsToConfig(entries, configPath) {
         validateSpecialistConfig(entry, configDir);
     }
     const file = { version: 1, specialists: entries };
-    await mkdir(configDir, { recursive: true });
-    await writeFile(path, JSON.stringify(file, null, 2) + '\n', 'utf8');
+    await updateJsonFile(path, () => file);
 }
 /**
  * Pure validator: returns a normalized {@link SpecialistConfig}.

package/dist/orchestrator/specialists.js

@@ -31,7 +31,7 @@ Strict rules:
 
 Output format: plain markdown. The orchestrator will pass your plan to the CODE specialist.`,
         allowedTools: ['read_file', 'list_files', 'search_files', 'run_command', 'memory_read'],
-        forbiddenTools: ['write_file', 'edit_file', 'edit_notebook', 'sub_agent'],
+        forbiddenTools: ['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'sub_agent'],
         maxIterations: 8,
         auto: false,
     },
@@ -67,7 +67,7 @@ Strict rules:
 
 Output format: plain markdown.`,
         allowedTools: ['read_file', 'list_files', 'search_files', 'run_command', 'memory_read'],
-        forbiddenTools: ['write_file', 'edit_file', 'edit_notebook', 'sub_agent'],
+        forbiddenTools: ['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'sub_agent'],
         maxIterations: 15,
         auto: false,
     },
@@ -84,7 +84,7 @@ Strict rules:
 
 Output format: plain markdown.`,
         allowedTools: ['read_file', 'list_files', 'search_files', 'fetch_url', 'memory_read'],
-        forbiddenTools: ['write_file', 'edit_file', 'edit_notebook', 'run_command', 'sub_agent'],
+        forbiddenTools: ['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'run_command', 'sub_agent'],
         maxIterations: 5,
         auto: false,
     },
@@ -102,7 +102,7 @@ Strict rules:
 
 Output format: plain markdown.`,
         allowedTools: ['read_file', 'list_files', 'search_files', 'memory_read'],
-        forbiddenTools: ['write_file', 'edit_file', 'edit_notebook', 'run_command', 'sub_agent'],
+        forbiddenTools: ['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'run_command', 'sub_agent'],
         maxIterations: 6,
         auto: false,
     },

package/dist/policy/ca-certs.d.ts

@@ -0,0 +1,8 @@
+export interface CaCertificates {
+    /** The contents of each readable file that holds at least one PEM certificate. */
+    pems: string[];
+    warnings: string[];
+}
+export declare function readCaCertificates(files: readonly string[], opts?: {
+    home?: string;
+}): CaCertificates;

package/dist/policy/ca-certs.js

@@ -0,0 +1,30 @@
+/**
+ * Extra certificate authorities for company networks that inspect TLS with their own root. Node reads
+ * `NODE_EXTRA_CA_CERTS` only at process start, which an editor extension cannot set, so the files are read here
+ * and handed to the HTTP dispatcher (see installProxy).
+ */
+import { readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function readCaCertificates(files, opts = {}) {
+    const home = opts.home ?? os.homedir();
+    const pems = [];
+    const warnings = [];
+    for (const raw of files) {
+        const file = raw.trim();
+        if (!file)
+            continue;
+        const resolved = file === '~' || file.startsWith('~/') || file.startsWith('~\\') ? path.join(home, file.slice(1)) : file;
+        try {
+            const text = readFileSync(resolved, 'utf8');
+            if (/-----BEGIN CERTIFICATE-----/.test(text))
+                pems.push(text);
+            else
+                warnings.push(`${file}: no PEM certificate found; ignored`);
+        }
+        catch (err) {
+            warnings.push(`${file}: ${err.message}; ignored`);
+        }
+    }
+    return { pems, warnings };
+}

package/dist/policy/proxy.d.ts

@@ -14,7 +14,14 @@ export interface ProxySettings {
 export declare function proxyFromEnv(env?: NodeJS.ProcessEnv): ProxySettings;
 export declare function hasProxy(p: ProxySettings): boolean;
 /**
- * Route all `fetch` traffic through the proxy in `settings` (default: the environment).
- * Idempotent. Returns whether a proxy was installed.
+ * A fetch that goes through the dispatcher installed by {@link installProxy} (the proxy and the extra CA roots), or
+ * undefined when none is installed. Needed because a host can replace the global `fetch` with one that ignores the
+ * global dispatcher: VS Code does in its extension host. Calls that must honour the proxy and the roots pass this one
+ * explicitly instead of relying on the global.
  */
-export declare function installProxy(settings?: ProxySettings): Promise<boolean>;
+export declare function installedFetch(): typeof fetch | undefined;
+/**
+ * Route all `fetch` traffic through the proxy in `settings` (default: the environment) and trust `extraCa`
+ * (PEM text) on top of the built-in roots. Idempotent. Returns whether anything was installed.
+ */
+export declare function installProxy(settings?: ProxySettings, extraCa?: readonly string[]): Promise<boolean>;

package/dist/policy/proxy.js

@@ -5,6 +5,8 @@
  * well-known global symbol, so installing it from the npm `undici` package also
  * routes Node's bundled fetch.
  */
+import https from 'node:https';
+import { rootCertificates } from 'node:tls';
 /** Proxy settings from the standard environment variables (either case). */
 export function proxyFromEnv(env = process.env) {
     const pick = (a, b) => env[a] || env[b] || undefined;
@@ -17,15 +19,40 @@ export function hasProxy(p) {
     return Boolean(p.https || p.http);
 }
 let installed = false;
+let installedFetchFn;
 /**
- * Route all `fetch` traffic through the proxy in `settings` (default: the environment).
- * Idempotent. Returns whether a proxy was installed.
+ * A fetch that goes through the dispatcher installed by {@link installProxy} (the proxy and the extra CA roots), or
+ * undefined when none is installed. Needed because a host can replace the global `fetch` with one that ignores the
+ * global dispatcher: VS Code does in its extension host. Calls that must honour the proxy and the roots pass this one
+ * explicitly instead of relying on the global.
  */
-export async function installProxy(settings = proxyFromEnv()) {
-    if (installed || !hasProxy(settings))
+export function installedFetch() {
+    return installedFetchFn;
+}
+/**
+ * Route all `fetch` traffic through the proxy in `settings` (default: the environment) and trust `extraCa`
+ * (PEM text) on top of the built-in roots. Idempotent. Returns whether anything was installed.
+ */
+export async function installProxy(settings = proxyFromEnv(), extraCa = []) {
+    if (installed || (!hasProxy(settings) && extraCa.length === 0))
         return false;
-    const { EnvHttpProxyAgent, setGlobalDispatcher } = await import('undici');
-    setGlobalDispatcher(new EnvHttpProxyAgent({
+    const { Agent, EnvHttpProxyAgent, fetch: undiciFetch, setGlobalDispatcher } = await import('undici');
+    const useDispatcher = (dispatcher) => {
+        setGlobalDispatcher(dispatcher);
+        installedFetchFn = ((input, init) => undiciFetch(input, { ...init, dispatcher }));
+    };
+    const tls = extraCa.length > 0 ? { ca: [...rootCertificates, ...extraCa] } : undefined;
+    // Not everything goes through undici: VS Code replaces the extension host's fetch with one built on node:https, which
+    // reads the global agent. Trust the roots there too.
+    if (tls)
+        https.globalAgent.options.ca = tls.ca;
+    if (!hasProxy(settings)) {
+        useDispatcher(new Agent({ connect: tls }));
+        installed = true;
+        return true;
+    }
+    useDispatcher(new EnvHttpProxyAgent({
+        ...(tls ? { requestTls: tls, proxyTls: tls } : {}),
         // Plain-http targets are forwarded as absolute-URI requests (the classic proxy protocol);
         // https targets always use CONNECT tunnels.
         proxyTunnel: false,

package/dist/pricing.js

@@ -1,3 +1,4 @@
+import { overrideCost } from './model-overrides.js';
 /**
  * Pricing table. Keys are matched with case-insensitive substring matching
  * against the model id (after stripping any "models/" / "claude-" /
@@ -99,6 +100,9 @@ export function lookupPricing(model, override) {
     const cache = typeof model === 'string' ? {} : cacheMultipliersFor(model);
     if (override)
         return { ...cache, ...override, known: true };
+    const configured = overrideCost(model);
+    if (configured)
+        return { ...cache, ...configured, known: true };
     const id = (typeof model === 'string' ? model : model.model).toLowerCase();
     // Strip only the OpenRouter-style 'models/' prefix so 'models/gemini-1.5-pro'
     // resolves the same way as 'gemini-1.5-pro'. We do NOT strip provider prefixes

package/dist/providers.d.ts

@@ -1,4 +1,5 @@
 import type { LanguageModel } from 'ai';
+import type { ProviderEndpoint } from './custom-providers.js';
 import type { ModelConfig, ProviderName } from './types.js';
 /**
  * Build a Vercel AI SDK `LanguageModel` from a `ModelConfig`.
@@ -14,6 +15,12 @@ import type { ModelConfig, ProviderName } from './types.js';
  * dependency footprint small (no separate `ollama-ai-provider` or
  * `openrouter-ai-provider` packages).
  */
+/**
+ * A model on a named provider: the OpenAI chat protocol (default) or the Anthropic message protocol, at the
+ * endpoint's URL with its key and headers. `timeoutMs` and `chunkTimeoutMs` wrap the HTTP calls.
+ * `fetchImpl` exists for tests.
+ */
+export declare function createEndpointModel(endpoint: ProviderEndpoint, model: string, fetchImpl?: typeof fetch): LanguageModel;
 export declare function createLanguageModel(config: ModelConfig): LanguageModel;
 /**
  * Resolve a model from the environment when no config is supplied. Throws a

package/dist/providers.js

@@ -1,7 +1,10 @@
 import { anthropic } from '@ai-sdk/anthropic';
-import { google } from '@ai-sdk/google';
+import { createGoogleGenerativeAI, google } from '@ai-sdk/google';
+import { createAnthropic } from '@ai-sdk/anthropic';
 import { createOpenAI, openai } from '@ai-sdk/openai';
 import { defaultModelFor, hasProviderKey } from './config.js';
+import { installedFetch } from './policy/proxy.js';
+import { withTimeouts } from './timed-fetch.js';
 import { lazyLanguageModel } from './lazy-model.js';
 /**
  * Default Ollama base URL. Ollama serves an OpenAI-compatible API at
@@ -33,25 +36,51 @@ const MINIMAX_BASE_URL = 'https://api.minimax.io/v1';
  * dependency footprint small (no separate `ollama-ai-provider` or
  * `openrouter-ai-provider` packages).
  */
+/**
+ * A model on a named provider: the OpenAI chat protocol (default) or the Anthropic message protocol, at the
+ * endpoint's URL with its key and headers. `timeoutMs` and `chunkTimeoutMs` wrap the HTTP calls.
+ * `fetchImpl` exists for tests.
+ */
+export function createEndpointModel(endpoint, model, fetchImpl = installedFetch() ?? fetch) {
+    const timed = withTimeouts(fetchImpl, { ...(endpoint.timeoutMs ? { timeoutMs: endpoint.timeoutMs } : {}), ...(endpoint.chunkTimeoutMs ? { chunkTimeoutMs: endpoint.chunkTimeoutMs } : {}) });
+    const common = {
+        baseURL: endpoint.baseUrl,
+        ...(endpoint.headers ? { headers: endpoint.headers } : {}),
+        fetch: timed,
+    };
+    if (endpoint.api === 'anthropic')
+        return createAnthropic({ ...common, apiKey: endpoint.apiKey ?? '' })(model);
+    return createOpenAI({ ...common, apiKey: endpoint.apiKey ?? 'none' }).chat(model);
+}
+/** `{ fetch }` when a proxy or extra CA roots are installed (see installedFetch), else nothing: the SDK then uses the global one. */
+function viaInstalled() {
+    const f = installedFetch();
+    return f ? { fetch: f } : {};
+}
 export function createLanguageModel(config) {
+    if (config.endpoint)
+        return createEndpointModel(config.endpoint, config.model);
+    const net = viaInstalled();
     switch (config.provider) {
         case 'openai':
-            return openai(config.model);
+            return net.fetch ? createOpenAI(net)(config.model) : openai(config.model);
         case 'anthropic':
-            return anthropic(config.model);
+            return net.fetch ? createAnthropic(net)(config.model) : anthropic(config.model);
         case 'google':
-            return google(config.model);
+            return net.fetch ? createGoogleGenerativeAI(net)(config.model) : google(config.model);
         case 'ollama':
             return createOpenAI({
                 baseURL: process.env.OLLAMA_BASE_URL ?? DEFAULT_OLLAMA_BASE_URL,
                 // Ollama doesn't require an API key: pass a placeholder so the
                 // OpenAI SDK's auth header doesn't trip on undefined.
                 apiKey: process.env.OLLAMA_API_KEY ?? 'ollama',
+                ...net,
             }).chat(config.model);
         case 'openrouter':
             return createOpenAI({
                 baseURL: OPENROUTER_BASE_URL,
                 apiKey: process.env.OPENROUTER_API_KEY ?? '',
+                ...net,
                 headers: {
                     // OpenRouter recommends an app-name header so they can attribute
                     // traffic; helps if you ever need to reach support.
@@ -64,18 +93,20 @@ export function createLanguageModel(config) {
             return createOpenAI({
                 baseURL: process.env.MINIMAX_BASE_URL ?? MINIMAX_BASE_URL,
                 apiKey: process.env.MINIMAX_API_KEY ?? '',
+                ...net,
             }).chat(config.model);
         case 'lmstudio':
             return createOpenAI({
                 baseURL: process.env.LMSTUDIO_BASE_URL ?? DEFAULT_LMSTUDIO_BASE_URL,
                 apiKey: process.env.LMSTUDIO_API_KEY ?? 'lm-studio',
+                ...net,
             }).chat(config.model);
         case 'openai-compatible': {
             const baseURL = process.env.OPENAI_COMPATIBLE_BASE_URL;
             if (!baseURL) {
                 throw new Error('Provider "openai-compatible" needs OPENAI_COMPATIBLE_BASE_URL (e.g. http://localhost:8000/v1).');
             }
-            return createOpenAI({ baseURL, apiKey: process.env.OPENAI_COMPATIBLE_API_KEY ?? 'none' }).chat(config.model);
+            return createOpenAI({ baseURL, apiKey: process.env.OPENAI_COMPATIBLE_API_KEY ?? 'none', ...net }).chat(config.model);
         }
         // The three cloud-account SDKs are heavy (~1.2 s to import together), so they load on first use.
         case 'bedrock':
@@ -83,6 +114,7 @@ export function createLanguageModel(config) {
                 const { createAmazonBedrock } = await import('@ai-sdk/amazon-bedrock');
                 return createAmazonBedrock({
                     region: process.env.AWS_REGION ?? 'us-east-1',
+                    ...net,
                     ...(process.env.AWS_BEARER_TOKEN_BEDROCK ? { apiKey: process.env.AWS_BEARER_TOKEN_BEDROCK } : {}),
                     ...(process.env.AWS_ACCESS_KEY_ID && process.env.AWS_SECRET_ACCESS_KEY
                         ? {
@@ -99,12 +131,14 @@ export function createLanguageModel(config) {
                 return createVertex({
                     ...(process.env.GOOGLE_VERTEX_PROJECT ? { project: process.env.GOOGLE_VERTEX_PROJECT } : {}),
                     location: process.env.GOOGLE_VERTEX_LOCATION ?? 'us-central1',
+                    ...net,
                 })(config.model);
             });
         case 'azure':
             return lazyLanguageModel({ provider: 'azure', modelId: config.model }, async () => {
                 const { createAzure } = await import('@ai-sdk/azure');
                 return createAzure({
+                    ...net,
                     ...(process.env.AZURE_API_KEY ? { apiKey: process.env.AZURE_API_KEY } : {}),
                     ...(process.env.AZURE_RESOURCE_NAME ? { resourceName: process.env.AZURE_RESOURCE_NAME } : {}),
                     ...(process.env.AZURE_OPENAI_BASE_URL ? { baseURL: process.env.AZURE_OPENAI_BASE_URL } : {}),

package/dist/semantic/embedder.d.ts

@@ -26,6 +26,21 @@ export interface OpenAiCompatibleEmbedderOptions {
     fetchImpl?: typeof fetch;
 }
 export declare function openAiCompatibleEmbedder(options: OpenAiCompatibleEmbedderOptions): Embedder;
+export interface EmbedderSpec {
+    kind: 'hashing' | 'openai' | 'ollama' | 'custom';
+    model?: string;
+    /** For `custom`: an OpenAI-compatible `/embeddings` endpoint, up to and including `/v1`. */
+    baseUrl?: string;
+    /** For `custom`: the name of the environment variable holding the key (never the key itself). */
+    apiKeyEnv?: string;
+    batchSize?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * An embedder from explicit settings. A choice that lacks what it needs (no key, no endpoint) gives the offline
+ * hashing embedder rather than an embedder that fails every search.
+ */
+export declare function buildEmbedder(spec: EmbedderSpec, env?: NodeJS.ProcessEnv): Embedder;
 /**
  * `FORGE_EMBED_PROVIDER` = `hashing` (default) | `openai` | `ollama`.
  * `FORGE_EMBED_MODEL` overrides the model. Falls back to hashing when the

package/dist/semantic/embedder.js

@@ -85,6 +85,31 @@ export function openAiCompatibleEmbedder(options) {
         },
     };
 }
+/**
+ * An embedder from explicit settings. A choice that lacks what it needs (no key, no endpoint) gives the offline
+ * hashing embedder rather than an embedder that fails every search.
+ */
+export function buildEmbedder(spec, env = process.env) {
+    const common = { ...(spec.batchSize ? { batchSize: spec.batchSize } : {}), ...(spec.fetchImpl ? { fetchImpl: spec.fetchImpl } : {}) };
+    switch (spec.kind) {
+        case 'openai':
+            if (!env.OPENAI_API_KEY)
+                return hashingEmbedder();
+            return openAiCompatibleEmbedder({ baseUrl: env.OPENAI_BASE_URL ?? 'https://api.openai.com/v1', model: spec.model || 'text-embedding-3-small', apiKey: env.OPENAI_API_KEY, ...common });
+        case 'ollama': {
+            const host = (env.OLLAMA_BASE_URL ?? 'http://localhost:11434').replace(/\/+$/, '').replace(/\/v1$/, '');
+            return openAiCompatibleEmbedder({ baseUrl: `${host}/v1`, model: spec.model || 'nomic-embed-text', ...common });
+        }
+        case 'custom': {
+            if (!spec.baseUrl || !spec.model)
+                return hashingEmbedder();
+            const apiKey = spec.apiKeyEnv ? env[spec.apiKeyEnv] : undefined;
+            return openAiCompatibleEmbedder({ baseUrl: spec.baseUrl, model: spec.model, ...(apiKey ? { apiKey } : {}), ...common });
+        }
+        default:
+            return hashingEmbedder();
+    }
+}
 /**
  * `FORGE_EMBED_PROVIDER` = `hashing` (default) | `openai` | `ollama`.
  * `FORGE_EMBED_MODEL` overrides the model. Falls back to hashing when the

package/dist/semantic/semantic-index.d.ts

@@ -1,5 +1,13 @@
 import { type Embedder } from './embedder.js';
 import { type SemanticManifest } from './vector-store.js';
+export interface SemanticOptions {
+    /** File extensions to index, with the dot. Default: the common source and Markdown ones. */
+    extensions?: readonly string[];
+    /** Hits scoring below this (cosine similarity) are left out. Default: none cut. */
+    minScore?: number;
+}
+/** `"ts, .py,md"` as `['.ts', '.py', '.md']`; undefined (use the defaults) when nothing usable is left. */
+export declare function parseExtensions(text: string | undefined): string[] | undefined;
 export interface SemanticHit {
     path: string;
     startLine: number;
@@ -8,5 +16,5 @@ export interface SemanticHit {
     snippet: string;
 }
 /** Bring `.forge/index/embeddings.json` up to date: re-embed only changed files, drop deleted ones. */
-export declare function ensureSemanticFresh(cwd: string, embedder: Embedder): Promise<SemanticManifest>;
-export declare function searchSemantic(cwd: string, embedder: Embedder, query: string, k?: number): Promise<SemanticHit[]>;
+export declare function ensureSemanticFresh(cwd: string, embedder: Embedder, options?: SemanticOptions): Promise<SemanticManifest>;
+export declare function searchSemantic(cwd: string, embedder: Embedder, query: string, k?: number, options?: SemanticOptions): Promise<SemanticHit[]>;

package/dist/semantic/semantic-index.js

@@ -7,9 +7,17 @@ import { chunkSource } from './chunker.js';
 import { cosine } from './embedder.js';
 import { decodeVector, encodeVector, loadSemanticManifest, saveSemanticManifest } from './vector-store.js';
 const EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.py', '.go', '.rs', '.java', '.md']);
+/** `"ts, .py,md"` as `['.ts', '.py', '.md']`; undefined (use the defaults) when nothing usable is left. */
+export function parseExtensions(text) {
+    const list = (text ?? '')
+        .split(',')
+        .map((e) => e.trim().toLowerCase().replace(/^\.?/, '.'))
+        .filter((e) => /^\.[a-z0-9]{1,12}$/.test(e));
+    return list.length ? [...new Set(list)] : undefined;
+}
 const MAX_FILE_BYTES = 512 * 1024;
 const SNIPPET_LINES = 40;
-async function collect(cwd) {
+async function collect(cwd, extensions) {
     const out = [];
     const rules = IgnoreRules.forRoot(cwd);
     async function walk(dir) {
@@ -29,7 +37,7 @@ async function collect(cwd) {
             if (entry.isDirectory()) {
                 await walk(abs);
             }
-            else if (entry.isFile() && EXTENSIONS.has(path.extname(entry.name))) {
+            else if (entry.isFile() && extensions.has(path.extname(entry.name).toLowerCase())) {
                 const s = await stat(abs);
                 if (s.size <= MAX_FILE_BYTES) {
                     out.push({ rel: path.relative(cwd, abs).split(path.sep).join('/'), abs, ext: path.extname(entry.name), mtimeMs: s.mtimeMs });
@@ -41,9 +49,9 @@ async function collect(cwd) {
     return out;
 }
 /** Bring `.forge/index/embeddings.json` up to date: re-embed only changed files, drop deleted ones. */
-export async function ensureSemanticFresh(cwd, embedder) {
+export async function ensureSemanticFresh(cwd, embedder, options = {}) {
     const manifest = await loadSemanticManifest(cwd, embedder.id);
-    const files = await collect(cwd);
+    const files = await collect(cwd, options.extensions ? new Set(options.extensions) : EXTENSIONS);
     const seen = new Set(files.map((f) => f.rel));
     let changed = false;
     for (const f of files) {
@@ -68,8 +76,8 @@ export async function ensureSemanticFresh(cwd, embedder) {
         await saveSemanticManifest(cwd, manifest);
     return manifest;
 }
-export async function searchSemantic(cwd, embedder, query, k = 8) {
-    const manifest = await ensureSemanticFresh(cwd, embedder);
+export async function searchSemantic(cwd, embedder, query, k = 8, options = {}) {
+    const manifest = await ensureSemanticFresh(cwd, embedder, options);
     const [q] = await embedder.embed([query]);
     if (!q)
         return [];
@@ -80,7 +88,8 @@ export async function searchSemantic(cwd, embedder, query, k = 8) {
     }
     scored.sort((a, b) => b.score - a.score);
     const hits = [];
-    for (const top of scored.slice(0, k)) {
+    const floor = options.minScore;
+    for (const top of scored.filter((c) => floor === undefined || c.score >= floor).slice(0, k)) {
         let text;
         try {
             const lines = (await readFile(path.join(cwd, top.rel), 'utf8')).split(/\r?\n/);

package/dist/sessions/session-store.js

@@ -155,7 +155,8 @@ function extractPreview(messages) {
     if (!firstUser)
         return undefined;
     const rawText = typeof firstUser.content === 'string' ? firstUser.content : extractText(firstUser.content);
-    const text = rawText === undefined ? undefined : stripSteering(rawText);
+    // The `<context ...>` blocks an @mention appends are attachments, not the user's words.
+    const text = rawText === undefined ? undefined : stripSteering(rawText).replace(/\n\n<context [^>]*>[\s\S]*?<\/context>/g, '');
     if (!text)
         return undefined;
     const oneLine = text.replace(/\s+/g, ' ').trim();

package/dist/skills/builtin.d.ts

@@ -0,0 +1,2 @@
+import type { Skill } from './types.js';
+export declare function builtinSkills(): Skill[];

package/dist/skills/builtin.js

@@ -0,0 +1,68 @@
+import { USER_ONLY_CONFIG_KEYS } from '../config-merge.js';
+/** One line per key of `~/.forge/config.json`. Typed against the file's keys: a new key does not compile until it has a line. */
+const KEY_HELP = {
+    provider: 'default provider id',
+    model: 'default model id, alias or provider:model',
+    completionModel: 'model for inline completion',
+    compactionModel: 'model that writes the summary when a long chat is condensed',
+    disabledProviders: 'providers hidden from the model picker',
+    reasoningEffort: 'none, minimal, low, medium, high or xhigh',
+    autoApproveTools: 'tools that run without asking',
+    autoApproveCommands: 'commands you chose "Always allow"; written by Forge, do not hand-edit',
+    permission: 'ordered rules per tool kind (read, edit, bash, webfetch, websearch, task, external_directory), each allow, ask or deny; the last match wins',
+    customProviders: 'providers beyond the built-in ones: id to { name, baseUrl, apiKeyEnv or apiKey, headers, api, timeoutMs, models }',
+    modelOverrides: 'context and output limits and prices per model',
+    modelFilters: 'per provider whitelist and blacklist of model ids',
+    subagentModel: 'model sub-agents use when none is named',
+    instructions: 'extra instruction files, globs and http(s) URLs added to the system prompt',
+    skillPaths: 'extra folders, or http(s) URLs of a skill file or a skill index ({ "skills": [{ "url": "..." }] }), to read skills from',
+    caCertificates: 'PEM files of extra certificate authorities to trust; needs a reload',
+    aliases: 'short names for models',
+    modeModels: 'model per chat mode',
+    sessionRetentionDays: 'delete saved chats older than this many days',
+    display: 'blockDefault (collapsed or expanded), detail (compact or full), showReasoning (true or false), and blocks: per kind of block, reasoning (hidden, collapsed or expanded) and terminal, edit, mcp (collapsed or expanded). The kinds are exactly reasoning, terminal, edit and mcp; use no other name',
+};
+function configBody() {
+    const userOnly = USER_ONLY_CONFIG_KEYS.join(', ');
+    const keys = Object.keys(KEY_HELP).map((k) => `- \`${k}\`: ${KEY_HELP[k]}`).join('\n');
+    return `# Changing Forge's settings
+
+Use this when the user asks to change how Forge behaves: a model, a provider, permissions, MCP servers, agents, commands, skills.
+
+## Where things live
+
+- \`~/.forge/config.json\`: the user's own settings. Applies in every project.
+- \`<workspace>/.forge/config.json\`: the project's settings, read only when the workspace is trusted. It can set provider, model, completionModel, compactionModel, reasoningEffort, subagentModel, modelOverrides, aliases, modeModels and display, and add stricter permission rules (ask, deny). It can never loosen anything.
+- User-only keys (a project file cannot set them, Forge ignores them there with a warning): ${userOnly}.
+- \`~/.forge/mcp.json\` and \`<workspace>/.forge/mcp.json\`: MCP servers, \`{ "mcpServers": { "name": { "command", "args", "env" } or { "url", "headers" } } }\`.
+- \`<workspace>/.forge/agents/*.md\` and \`~/.forge/agents/*.md\`: agents; front matter (description, mode, model, tools, deny, steps, temperature) then the system prompt.
+- \`<workspace>/.forge/commands/*.md\` and \`~/.forge/commands/*.md\`: slash commands; \`$ARGUMENTS\` is replaced by what the user types after the name.
+- \`<workspace>/.forge/skills/\`, \`<workspace>/skills/\`, \`~/.forge/skills/\`: skills.
+- \`AGENTS.md\` (or \`CLAUDE.md\`) in the workspace or a folder: instructions for the model.
+- In VS Code the same choices also exist as \`forge.*\` settings, edited on the Forge Settings page or in settings.json.
+
+## Keys of config.json
+
+${keys}
+
+## How to change them
+
+0. Your file tools only reach the workspace, so you cannot edit \`~/.forge/config.json\`. For a key the project file may set (see above), edit \`<workspace>/.forge/config.json\` and say plainly that the change is workspace-scoped (only for this workspace, and only when it is trusted). For a user-only key, or when the person wants it everywhere, show the exact JSON to add and tell them to paste it into \`~/.forge/config.json\` or use the Forge Settings page; do not write it into the project file.
+1. Read the file first. If it does not exist, create it with only the keys you are setting.
+2. Change only what was asked. Keep every other key and keep the file valid JSON (double quotes, no trailing commas, no comments).
+3. A secret never goes in a project file. Name an environment variable (\`apiKeyEnv\`) instead of pasting a key.
+4. Do not widen permissions (\`autoApproveTools\`, \`permission\` allow rules, \`autoApproveCommands\`) unless the user named what to allow. A general request such as "make the prompts go away" or "allow everything" names nothing: do not write it, and never grant \`run_command\`, \`write_file\`, \`edit_file\`, \`apply_patch\` or \`sub_agent\` because of it. Say in one sentence why, then offer the narrow forms: allow one named tool, or choose "Always allow" on a specific command when its card appears. When you do widen, say what the change allows.
+5. After saving, say what changed and where. Most changes apply on the next message; \`caCertificates\` and the language need a window reload, MCP servers and skills need \`/reload\`.
+6. Do not run Forge commands that write to the real \`~/.forge\` to test a change. Edit the file and let the user check it.
+`;
+}
+export function builtinSkills() {
+    return [
+        {
+            name: 'forge-config',
+            description: "Change Forge's own settings: models, providers, permissions, MCP servers, agents, commands, skills and instructions. Use when the user asks to configure or set up Forge itself.",
+            body: configBody(),
+            source: { kind: 'builtin', path: '(built into Forge)' },
+        },
+    ];
+}