@ikarmic/forge-core 5.0.0 → 5.1.0

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 asked for exactly that, and 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)' },
+        },
+    ];
+}

package/dist/skills/index.d.ts

@@ -6,6 +6,8 @@
  * internal directory layout.
  */
 export type { Skill, SkillRegistry, SkillRoots, SkillSource } from './types.js';
+export { builtinSkills } from './builtin.js';
+export { loadRemoteSkills } from './remote.js';
 export { GLOBAL_SKILLS_DIR, LOCAL_SKILLS_DIR, PROJECT_SKILLS_DIR, discoverSkills, loadSkillsRegistry, loadSkillsRegistryAsync, parseSkillsDir, resolveSkillRoots, skillsRegistryFromList, } from './loader.js';
 export { parseSkill } from './parser.js';
 export { buildSkillsBlock, composeSkillsPrompt, scoreSkill, selectSkills, } from './activator.js';

package/dist/skills/index.js

@@ -5,6 +5,8 @@
  * callers can use skills + the community catalog without knowing the
  * internal directory layout.
  */
+export { builtinSkills } from './builtin.js';
+export { loadRemoteSkills } from './remote.js';
 export { GLOBAL_SKILLS_DIR, LOCAL_SKILLS_DIR, PROJECT_SKILLS_DIR, discoverSkills, loadSkillsRegistry, loadSkillsRegistryAsync, parseSkillsDir, resolveSkillRoots, skillsRegistryFromList, } from './loader.js';
 export { parseSkill } from './parser.js';
 export { buildSkillsBlock, composeSkillsPrompt, scoreSkill, selectSkills, } from './activator.js';

package/dist/skills/loader.d.ts

@@ -6,6 +6,7 @@
  * root wins (local > project > global). The result is an immutable
  * snapshot: call {@link reload} to re-read disk.
  */
+import { type RemoteSkillOptions } from './remote.js';
 import type { Skill, SkillRegistry, SkillRoots, SkillSource } from './types.js';
 /** Local skill root: `<cwd>/skills/`. Lives next to the project's source so it can be checked into git. */
 export declare const LOCAL_SKILLS_DIR = "skills";
@@ -31,7 +32,9 @@ export declare function parseSkillsDir(dir: string, kind: SkillSource['kind']):
  * Discover all skills visible from `cwd`. Walks local → project → global,
  * merges, and resolves duplicates by precedence (first-wins).
  */
-export declare function discoverSkills(cwd: string): Promise<Skill[]>;
+export declare function discoverSkills(cwd: string, extraDirs?: readonly string[], remote?: RemoteSkillOptions & {
+    onWarning?: (warning: string) => void;
+}): Promise<Skill[]>;
 /**
  * Build an immutable registry from a pre-loaded skill list. Use this when
  * tests want to inject a known set without touching the filesystem. Use
@@ -42,9 +45,13 @@ export declare function skillsRegistryFromList(skills: Skill[], roots: SkillRoot
  * Build a registry by discovering skills from disk relative to `cwd`.
  * The registry caches its initial load; call `reload()` to refresh.
  */
-export declare function loadSkillsRegistry(cwd: string): SkillRegistry;
+export declare function loadSkillsRegistry(cwd: string, extraDirs?: readonly string[], remote?: RemoteSkillOptions & {
+    onWarning?: (warning: string) => void;
+}): SkillRegistry;
 /**
  * Async variant: build a registry and immediately load its initial contents.
  * Useful for callers that want a fully-populated registry in one step.
  */
-export declare function loadSkillsRegistryAsync(cwd: string): Promise<SkillRegistry>;
+export declare function loadSkillsRegistryAsync(cwd: string, extraDirs?: readonly string[], remote?: RemoteSkillOptions & {
+    onWarning?: (warning: string) => void;
+}): Promise<SkillRegistry>;

package/dist/skills/loader.js

@@ -11,6 +11,8 @@ import { readdir, readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { discoverPlugins } from '../plugins/loader.js';
+import { builtinSkills } from './builtin.js';
+import { isHttpUrl, loadRemoteSkills } from './remote.js';
 import { parseSkill } from './parser.js';
 /** Local skill root: `<cwd>/skills/`. Lives next to the project's source so it can be checked into git. */
 export const LOCAL_SKILLS_DIR = 'skills';
@@ -61,19 +63,30 @@ export async function parseSkillsDir(dir, kind) {
  * Discover all skills visible from `cwd`. Walks local → project → global,
  * merges, and resolves duplicates by precedence (first-wins).
  */
-export async function discoverSkills(cwd) {
+export async function discoverSkills(cwd, extraDirs = [], remote = {}) {
     const roots = resolveSkillRoots(cwd);
     const [localSkills, projectSkills, globalSkills] = await Promise.all([
         parseSkillsDir(roots.local, 'local'),
         parseSkillsDir(roots.project, 'project'),
         parseSkillsDir(roots.global, 'global'),
     ]);
+    // Folders named in the `skillPaths` setting rank after the user's own folders and before plugins.
+    // An entry that is an http(s) URL is fetched (one skill file, or an index of them); the rest are folders.
+    const extraSkills = (await Promise.all(extraDirs.map(async (d) => {
+        if (isHttpUrl(d)) {
+            const got = await loadRemoteSkills(d, remote);
+            for (const w of got.warnings)
+                remote.onWarning?.(w);
+            return got.skills;
+        }
+        return parseSkillsDir(path.resolve(cwd, d.startsWith('~') ? path.join(homedir(), d.slice(1)) : d), 'global');
+    }))).flat();
     // Plugin skills rank below the user's own: they never shadow a skill written locally.
     const pluginSkills = (await Promise.all((await discoverPlugins(cwd)).map((p) => (p.skillsDir ? parseSkillsDir(p.skillsDir, p.scope) : Promise.resolve([]))))).flat();
-    // Order matters: first to claim a name wins. local > project > global > plugins.
+    // Order matters: first to claim a name wins. local > project > global > plugins > built in.
     const seen = new Set();
     const merged = [];
-    for (const list of [localSkills, projectSkills, globalSkills, pluginSkills]) {
+    for (const list of [localSkills, projectSkills, globalSkills, extraSkills, pluginSkills, builtinSkills()]) {
         for (const skill of list) {
             if (seen.has(skill.name))
                 continue;
@@ -105,11 +118,11 @@ export function skillsRegistryFromList(skills, roots) {
  * Build a registry by discovering skills from disk relative to `cwd`.
  * The registry caches its initial load; call `reload()` to refresh.
  */
-export function loadSkillsRegistry(cwd) {
+export function loadSkillsRegistry(cwd, extraDirs = [], remote = {}) {
     const roots = resolveSkillRoots(cwd);
     let cache = null;
     const refresh = async () => {
-        cache = await discoverSkills(cwd);
+        cache = await discoverSkills(cwd, extraDirs, remote);
         return cache;
     };
     return {
@@ -123,8 +136,8 @@ export function loadSkillsRegistry(cwd) {
  * Async variant: build a registry and immediately load its initial contents.
  * Useful for callers that want a fully-populated registry in one step.
  */
-export async function loadSkillsRegistryAsync(cwd) {
-    const registry = loadSkillsRegistry(cwd);
+export async function loadSkillsRegistryAsync(cwd, extraDirs = [], remote = {}) {
+    const registry = loadSkillsRegistry(cwd, extraDirs, remote);
     await registry.reload();
     return registry;
 }

package/dist/skills/marketplace.js

@@ -11,6 +11,7 @@
 import { normalizeGithubSource } from '../mcp/marketplace.js';
 import { parseSkill } from './parser.js';
 import { DEFAULT_SKILL_CATALOG_URL, SKILL_CATALOG_VERSION, } from './marketplace-types.js';
+import { isOutsideRel } from '../tools/shared.js';
 /**
  * Sanitize a catalog-provided name to a safe filename charset before it is
  * used to build a path on disk. Mirrors `installDirNameFor`'s sanitization
@@ -168,7 +169,7 @@ export async function installSkillFromCatalog(params) {
     const filePath = path.join(dest, `${safeName}.md`);
     const resolvedDest = path.resolve(dest);
     const rel = path.relative(resolvedDest, path.resolve(filePath));
-    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    if (isOutsideRel(rel)) {
         return null;
     }
     await fs.writeFile(filePath, rawContent, 'utf8');

package/dist/skills/remote.d.ts

@@ -0,0 +1,14 @@
+import type { Skill } from './types.js';
+export interface RemoteSkillOptions {
+    fetch?: typeof fetch;
+    /** Defaults to `~/.forge/skill-cache`. */
+    cacheDir?: string;
+    ttlMs?: number;
+    now?: () => number;
+}
+export interface RemoteSkills {
+    skills: Skill[];
+    warnings: string[];
+}
+export declare const isHttpUrl: (s: string) => boolean;
+export declare function loadRemoteSkills(url: string, options?: RemoteSkillOptions): Promise<RemoteSkills>;