@ikarmic/forge-core 5.0.0 → 5.1.0

package/dist/mcp/oauth.js

@@ -0,0 +1,197 @@
+/**
+ * OAuth sign-in for MCP servers behind it (authorization code with PKCE, dynamic client registration).
+ * The SDK does the protocol; this file supplies what it leaves to the application: where tokens are kept,
+ * where the browser returns to (a one-shot page on 127.0.0.1), and a state value that must come back unchanged.
+ *
+ * Tokens live in `~/.forge/mcp-auth/<server>.json`, readable by the user only, one file per server URL.
+ * Signing in is always the user's act: a server that needs it is reported as such, and the browser opens only
+ * when `interactive` is set. A URL that is not http or https is never opened.
+ */
+import { randomBytes, createHash } from 'node:crypto';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import http from 'node:http';
+import { homedir } from 'node:os';
+import path from 'node:path';
+/** The server needs the user to sign in, and this connection was not allowed to ask. */
+export class McpAuthRequiredError extends Error {
+    server;
+    constructor(server) {
+        super(`MCP server "${server}" needs you to sign in`);
+        this.server = server;
+        this.name = 'McpAuthRequiredError';
+    }
+}
+export function defaultMcpAuthDir() {
+    return path.join(homedir(), '.forge', 'mcp-auth');
+}
+function fileFor(dir, serverUrl) {
+    return path.join(dir, `${createHash('sha256').update(serverUrl).digest('hex').slice(0, 32)}.json`);
+}
+export async function readSavedAuth(dir, serverUrl) {
+    try {
+        return JSON.parse(await readFile(fileFor(dir, serverUrl), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeSavedAuth(dir, auth) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await writeFile(fileFor(dir, auth.url), JSON.stringify(auth, null, 2), { encoding: 'utf8', mode: 0o600 });
+}
+export async function forgetSavedAuth(dir, serverUrl) {
+    await rm(fileFor(dir, serverUrl), { force: true });
+}
+/** A port on 127.0.0.1: the one used last time if it is free (so a registered redirect URL keeps working), else any. */
+async function freePort(preferred) {
+    const tryListen = (port) => new Promise((resolve) => {
+        const s = http.createServer();
+        s.once('error', () => resolve(undefined));
+        s.listen(port, '127.0.0.1', () => {
+            const got = s.address().port;
+            s.close(() => resolve(got));
+        });
+    });
+    return (preferred ? await tryListen(preferred) : undefined) ?? (await tryListen(0)) ?? 0;
+}
+/** A one-shot page the browser returns to. Resolves with the code; a wrong `state` is ignored, an `error` rejects. */
+async function receiveCode(port, expectedState, timeoutMs) {
+    let resolveCode;
+    let rejectCode;
+    const code = new Promise((resolve, reject) => {
+        resolveCode = resolve;
+        rejectCode = reject;
+    });
+    const page = (title) => `<!doctype html><meta charset="utf-8"><title>${title}</title><body style="font-family:sans-serif;margin:3em"><h2>${title}</h2><p>You can close this tab and go back to your editor.</p>`;
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
+        if (url.pathname !== '/callback') {
+            res.writeHead(404).end();
+            return;
+        }
+        if (url.searchParams.get('state') !== expectedState) {
+            res.writeHead(400, { 'content-type': 'text/html' }).end(page('This sign-in link is not for this session'));
+            return;
+        }
+        const error = url.searchParams.get('error');
+        const got = url.searchParams.get('code');
+        if (error || !got) {
+            res.writeHead(400, { 'content-type': 'text/html' }).end(page('Sign-in was not completed'));
+            rejectCode(new Error(`sign-in failed: ${error ?? 'no code returned'}`));
+            return;
+        }
+        res.writeHead(200, { 'content-type': 'text/html' }).end(page('Signed in to Forge'));
+        resolveCode(got);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', resolve);
+    });
+    const timer = setTimeout(() => rejectCode(new Error('sign-in timed out')), timeoutMs);
+    const close = () => {
+        clearTimeout(timer);
+        server.closeAllConnections();
+        server.close();
+    };
+    code.then(close, close);
+    return { code, close };
+}
+export class ForgeOAuthProvider {
+    serverName;
+    serverUrl;
+    dir;
+    port;
+    options;
+    verifier = '';
+    expectedState = '';
+    receiver;
+    constructor(serverName, serverUrl, dir, port, options) {
+        this.serverName = serverName;
+        this.serverUrl = serverUrl;
+        this.dir = dir;
+        this.port = port;
+        this.options = options;
+    }
+    static async create(serverName, serverUrl, options) {
+        const dir = options.storeDir ?? defaultMcpAuthDir();
+        const saved = await readSavedAuth(dir, serverUrl);
+        const port = await freePort(saved?.port);
+        await writeSavedAuth(dir, { ...(saved ?? { url: serverUrl }), url: serverUrl, port });
+        return new ForgeOAuthProvider(serverName, serverUrl, dir, port, options);
+    }
+    get redirectUrl() {
+        return `http://127.0.0.1:${this.port}/callback`;
+    }
+    get clientMetadata() {
+        return {
+            client_name: 'Ikarmic Forge',
+            redirect_uris: [this.redirectUrl],
+            grant_types: ['authorization_code', 'refresh_token'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'none',
+        };
+    }
+    state() {
+        this.expectedState = randomBytes(16).toString('hex');
+        return this.expectedState;
+    }
+    async saved() {
+        return (await readSavedAuth(this.dir, this.serverUrl)) ?? { url: this.serverUrl };
+    }
+    async clientInformation() {
+        const info = (await this.saved()).clientInformation;
+        // A registration made for another redirect URL cannot be used here: register again.
+        if (info?.redirect_uris && !info.redirect_uris.includes(this.redirectUrl))
+            return undefined;
+        return info;
+    }
+    async saveClientInformation(info) {
+        await writeSavedAuth(this.dir, { ...(await this.saved()), clientInformation: info });
+    }
+    async tokens() {
+        return (await this.saved()).tokens;
+    }
+    async saveTokens(tokens) {
+        await writeSavedAuth(this.dir, { ...(await this.saved()), tokens });
+    }
+    saveCodeVerifier(v) {
+        this.verifier = v;
+    }
+    codeVerifier() {
+        return this.verifier;
+    }
+    async invalidateCredentials(scope) {
+        const s = await this.saved();
+        if (scope === 'all' || scope === 'tokens')
+            delete s.tokens;
+        if (scope === 'all' || scope === 'client')
+            delete s.clientInformation;
+        await writeSavedAuth(this.dir, s);
+    }
+    /** Called by the SDK once it has the authorization URL. Without `interactive` this is where the connection stops. */
+    async redirectToAuthorization(url) {
+        if (!this.options.interactive)
+            throw new McpAuthRequiredError(this.serverName);
+        if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+            throw new Error(`MCP server "${this.serverName}" gave a sign-in address that is not a web page (${url.protocol}); refused`);
+        }
+        this.receiver?.close();
+        this.receiver = await receiveCode(this.port, this.expectedState, this.options.signInTimeoutMs ?? 5 * 60_000);
+        await this.options.openUrl(url.href);
+    }
+    /** After the SDK reported the sign-in as started: the code the browser brings back. */
+    async waitForCode() {
+        if (!this.receiver)
+            throw new Error('no sign-in is waiting');
+        try {
+            return await this.receiver.code;
+        }
+        finally {
+            this.receiver = undefined;
+        }
+    }
+    cancel() {
+        this.receiver?.close();
+        this.receiver = undefined;
+    }
+}

package/dist/mcp/resource-tools.d.ts

@@ -0,0 +1,8 @@
+import type { ConnectedMcpServer } from './mcp-client.js';
+import type { ToolDefinition } from '../types.js';
+/**
+ * `mcp_list_resources` and `mcp_read_resource`: let the model see and read what connected MCP servers publish
+ * (notes, files, schemas). Both only read, so neither asks for approval. `servers` is a function because
+ * servers connect, fail and reconnect while a chat is open.
+ */
+export declare function createMcpResourceTools(servers: () => readonly ConnectedMcpServer[]): ToolDefinition[];

package/dist/mcp/resource-tools.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+const MAX_RESOURCE_CHARS = 100_000;
+/**
+ * `mcp_list_resources` and `mcp_read_resource`: let the model see and read what connected MCP servers publish
+ * (notes, files, schemas). Both only read, so neither asks for approval. `servers` is a function because
+ * servers connect, fail and reconnect while a chat is open.
+ */
+export function createMcpResourceTools(servers) {
+    const listParams = z.object({ server: z.string().optional().describe('Only this MCP server. Omit for every server.') });
+    const readParams = z.object({
+        server: z.string().describe('MCP server name, as shown by mcp_list_resources.'),
+        uri: z.string().describe('Resource URI, as shown by mcp_list_resources.'),
+    });
+    const list = {
+        name: 'mcp_list_resources',
+        description: 'List the resources (documents, data, files) that connected MCP servers publish. Returns each resource server, uri, name and description.',
+        parameters: listParams,
+        execute: async (args) => {
+            const out = [];
+            for (const s of servers()) {
+                if (args.server && s.name !== args.server)
+                    continue;
+                try {
+                    const { resources } = await s.client.listResources();
+                    for (const r of resources) {
+                        out.push({ server: s.name, uri: r.uri, name: r.name, ...(r.description ? { description: r.description } : {}), ...(r.mimeType ? { mimeType: r.mimeType } : {}) });
+                    }
+                }
+                catch {
+                    // A server without resources support (or one that is down) just contributes nothing.
+                }
+            }
+            return { resources: out };
+        },
+    };
+    const read = {
+        name: 'mcp_read_resource',
+        description: 'Read one resource from a connected MCP server by its server name and uri (see mcp_list_resources).',
+        parameters: readParams,
+        execute: async (args) => {
+            const server = servers().find((s) => s.name === args.server);
+            if (!server)
+                throw new Error(`No MCP server "${args.server}" is connected.`);
+            const result = await server.client.readResource({ uri: args.uri });
+            const text = result.contents
+                .map((c) => ('text' in c && typeof c.text === 'string' ? c.text : `[binary content${c.mimeType ? `, ${c.mimeType}` : ''}]`))
+                .join('\n');
+            return {
+                server: args.server,
+                uri: args.uri,
+                text: text.length > MAX_RESOURCE_CHARS ? `${text.slice(0, MAX_RESOURCE_CHARS)}\n…(truncated)` : text,
+            };
+        },
+    };
+    return [list, read];
+}

package/dist/memory/session-digest.d.ts

@@ -0,0 +1,12 @@
+import type { LanguageModel } from 'ai';
+import type { ModelConfig } from '../types.js';
+export interface DigestItem {
+    role: 'user' | 'assistant';
+    text: string;
+}
+/** A conversation with fewer than two user messages is a question, not work worth remembering. */
+export declare function shouldDigest(items: readonly DigestItem[]): boolean;
+/** The model's reply as a digest: think block, fences and quotes removed; undefined when nothing usable is left (RB-1). */
+export declare function cleanDigest(reply: string): string | undefined;
+/** Summarise a finished chat for project memory with `model` (usually the cheap model); never throws. */
+export declare function generateSessionDigest(items: readonly DigestItem[], model: ModelConfig | undefined, modelFactory?: (cfg: ModelConfig) => LanguageModel): Promise<string | undefined>;

package/dist/memory/session-digest.js

@@ -0,0 +1,47 @@
+import { generateText } from 'ai';
+import { stripThinkTags } from '../agent/think-tags.js';
+import { createLanguageModel } from '../providers.js';
+const MAX_DIGEST_CHARS = 600;
+const MAX_INPUT_CHARS = 12_000;
+const INSTRUCTION = 'Below is a conversation between a user and a coding agent. Write what a later session needs to know: what was changed or decided, which files were involved, and anything left undone. ' +
+    'Two to five short bullet lines, each starting with "- ". Do not copy code. Reply with the bullets only, no preface, no code fences.';
+/** A conversation with fewer than two user messages is a question, not work worth remembering. */
+export function shouldDigest(items) {
+    return items.filter((i) => i.role === 'user').length >= 2;
+}
+/** The model's reply as a digest: think block, fences and quotes removed; undefined when nothing usable is left (RB-1). */
+export function cleanDigest(reply) {
+    const text = stripThinkTags(reply)
+        .trim()
+        .replace(/^```[a-z]*\s*\n?/i, '')
+        .replace(/\n?```$/, '')
+        .trim()
+        .replace(/^["'“”](.*)["'“”]$/s, '$1')
+        .trim();
+    if (!text)
+        return undefined;
+    return text.length > MAX_DIGEST_CHARS ? `${text.slice(0, MAX_DIGEST_CHARS - 1).trimEnd()}…` : text;
+}
+/** The end of the conversation, which is where its outcome is, within the input budget. */
+function transcript(items) {
+    const lines = items.map((i) => `${i.role === 'user' ? 'User' : 'Agent'}: ${i.text.trim()}`);
+    let out = '';
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (out.length + lines[i].length > MAX_INPUT_CHARS)
+            break;
+        out = `${lines[i]}\n\n${out}`;
+    }
+    return out.trim();
+}
+/** Summarise a finished chat for project memory with `model` (usually the cheap model); never throws. */
+export async function generateSessionDigest(items, model, modelFactory = createLanguageModel) {
+    if (!model || !shouldDigest(items))
+        return undefined;
+    try {
+        const result = await generateText({ model: modelFactory(model), prompt: `${INSTRUCTION}\n\nConversation:\n${transcript(items)}` });
+        return cleanDigest(result.text);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/memory/stale.js

@@ -5,6 +5,7 @@
  */
 import { stat } from 'node:fs/promises';
 import path from 'node:path';
+import { isOutsideRel } from '../tools/shared.js';
 /** Key a section in the stale map. */
 export function staleKey(s) {
     return `${s.source}#${s.heading}`;
@@ -23,7 +24,7 @@ export async function checkStale(sections, root, opts = {}) {
             const file = hash === -1 ? ref : ref.slice(0, hash);
             const symbol = hash === -1 ? '' : ref.slice(hash + 1);
             const rel = path.relative(root, path.resolve(root, file));
-            if (path.isAbsolute(file) || rel.startsWith('..') || path.isAbsolute(rel)) {
+            if (path.isAbsolute(file) || isOutsideRel(rel)) {
                 reasons.push(`${ref} is outside the project`);
                 continue;
             }

package/dist/model-alias.d.ts

@@ -1,4 +1,11 @@
-import type { ProviderName } from './types.js';
+/**
+ * User-defined model aliases from `~/.forge/config.json`:
+ *   "aliases": { "fast": "anthropic:claude-haiku-4-5", "big": "opus" }
+ * A value is `provider:model` or a bare model id (current provider), and may
+ * name another alias.
+ */
+import { type CustomProviderConfig, type ProviderEndpoint } from './custom-providers.js';
+import type { ModelConfig, ProviderName } from './types.js';
 export type ModelAliases = Record<string, string>;
 /** Follow alias links from `name`. Names that are not aliases come back unchanged. */
 export declare function expandModelAlias(name: string, aliases: ModelAliases | undefined): string;
@@ -7,9 +14,18 @@ export declare function splitModelRef(ref: string): {
     provider?: ProviderName;
     model: string;
 };
-export declare function resolveModelAlias(name: string, aliases: ModelAliases | undefined, defaultProvider: ProviderName): {
+/**
+ * `provider:model` for the eleven built-in providers, and `id:model` for a preset or `customProviders` id
+ * (`groq:llama-3.3-70b-versatile`), which resolves to an openai-compatible model with its endpoint. Ollama and
+ * LM Studio use `name:tag` model ids (`mistral:7b`), so for them only a prefix the user defined counts.
+ */
+export declare function resolveModelAlias(name: string, aliases: ModelAliases | undefined, defaultProvider: ProviderName, custom?: Record<string, CustomProviderConfig>): {
     provider: ProviderName;
     model: string;
+    endpoint?: ProviderEndpoint;
 };
+export type ResolvedModelRef = ReturnType<typeof resolveModelAlias>;
+/** A resolved model reference laid over a base model: the base's other settings stay, its endpoint never leaks into a different provider. */
+export declare function applyResolved(base: ModelConfig, resolved: ResolvedModelRef): ModelConfig;
 /** Human-readable alias list for `forge config`; '' when there are none. */
 export declare function formatAliasTable(aliases: ModelAliases | undefined): string;

package/dist/model-alias.js

@@ -4,6 +4,7 @@
  * A value is `provider:model` or a bare model id (current provider), and may
  * name another alias.
  */
+import { PROVIDER_PRESETS, apiModelId, registeredCustomProviders, resolveProviderEndpoint } from './custom-providers.js';
 import { MODEL_CATALOG } from './model-catalog.js';
 const MAX_HOPS = 5;
 const PROVIDERS = new Set(Object.keys(MODEL_CATALOG));
@@ -34,9 +35,32 @@ export function splitModelRef(ref) {
     }
     return { model: ref };
 }
-export function resolveModelAlias(name, aliases, defaultProvider) {
-    const { provider, model } = splitModelRef(expandModelAlias(name, aliases));
-    return { provider: provider ?? defaultProvider, model };
+/**
+ * `provider:model` for the eleven built-in providers, and `id:model` for a preset or `customProviders` id
+ * (`groq:llama-3.3-70b-versatile`), which resolves to an openai-compatible model with its endpoint. Ollama and
+ * LM Studio use `name:tag` model ids (`mistral:7b`), so for them only a prefix the user defined counts.
+ */
+export function resolveModelAlias(name, aliases, defaultProvider, custom) {
+    const providers = custom ?? registeredCustomProviders();
+    const expanded = expandModelAlias(name, aliases);
+    const { provider, model } = splitModelRef(expanded);
+    if (provider)
+        return { provider, model };
+    const idx = expanded.indexOf(':');
+    if (idx > 0) {
+        const prefix = expanded.slice(0, idx);
+        const local = defaultProvider === 'ollama' || defaultProvider === 'lmstudio';
+        const known = Object.prototype.hasOwnProperty.call(providers ?? {}, prefix) || (!local && Object.prototype.hasOwnProperty.call(PROVIDER_PRESETS, prefix));
+        const endpoint = known ? resolveProviderEndpoint(prefix, providers) : undefined;
+        if (endpoint)
+            return { provider: 'openai-compatible', model: apiModelId(prefix, expanded.slice(idx + 1), providers), endpoint };
+    }
+    return { provider: defaultProvider, model };
+}
+/** A resolved model reference laid over a base model: the base's other settings stay, its endpoint never leaks into a different provider. */
+export function applyResolved(base, resolved) {
+    const { endpoint: _stale, ...rest } = base;
+    return { ...rest, ...resolved };
 }
 /** Human-readable alias list for `forge config`; '' when there are none. */
 export function formatAliasTable(aliases) {

package/dist/model-catalog.js

@@ -38,7 +38,6 @@ export const MODEL_CATALOG = {
         { id: 'MiniMax-M3', label: 'MiniMax M3' },
         { id: 'MiniMax-M2.7', label: 'MiniMax M2.7' },
         { id: 'MiniMax-M2.7-highspeed', label: 'MiniMax M2.7 highspeed' },
-        { id: 'MiniMax-M2', label: 'MiniMax M2' },
     ],
     bedrock: [
         { id: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0', label: 'Claude Sonnet 4.5 (Bedrock, US)' },

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>;