@ikarmic/forge-core 5.0.0 → 5.1.1

package/dist/custom-providers.js

@@ -0,0 +1,120 @@
+/**
+ * Named providers beyond the built-in eleven: a table of well-known OpenAI-compatible services plus whatever the
+ * user defines under `customProviders` in `~/.forge/config.json`. A model on one of them is written `id:model`
+ * (e.g. `groq:llama-3.3-70b-versatile`) and resolves to an endpoint (base URL, key, headers) that
+ * `createLanguageModel` calls with the OpenAI chat or Anthropic message style. Pure; nothing here reads files.
+ */
+/** Defaults for services that speak the OpenAI chat protocol. Any field can be overridden under `customProviders`. */
+export const PROVIDER_PRESETS = {
+    groq: { name: 'Groq', baseUrl: 'https://api.groq.com/openai/v1', apiKeyEnv: 'GROQ_API_KEY' },
+    deepseek: { name: 'DeepSeek', baseUrl: 'https://api.deepseek.com/v1', apiKeyEnv: 'DEEPSEEK_API_KEY' },
+    mistral: { name: 'Mistral', baseUrl: 'https://api.mistral.ai/v1', apiKeyEnv: 'MISTRAL_API_KEY' },
+    xai: { name: 'xAI', baseUrl: 'https://api.x.ai/v1', apiKeyEnv: 'XAI_API_KEY' },
+    cerebras: { name: 'Cerebras', baseUrl: 'https://api.cerebras.ai/v1', apiKeyEnv: 'CEREBRAS_API_KEY' },
+    fireworks: { name: 'Fireworks', baseUrl: 'https://api.fireworks.ai/inference/v1', apiKeyEnv: 'FIREWORKS_API_KEY' },
+    together: { name: 'Together AI', baseUrl: 'https://api.together.xyz/v1', apiKeyEnv: 'TOGETHER_API_KEY' },
+    moonshot: { name: 'Moonshot', baseUrl: 'https://api.moonshot.ai/v1', apiKeyEnv: 'MOONSHOT_API_KEY' },
+    nebius: { name: 'Nebius', baseUrl: 'https://api.studio.nebius.com/v1', apiKeyEnv: 'NEBIUS_API_KEY' },
+    vercel: { name: 'Vercel AI Gateway', baseUrl: 'https://ai-gateway.vercel.sh/v1', apiKeyEnv: 'AI_GATEWAY_API_KEY' },
+    perplexity: { name: 'Perplexity', baseUrl: 'https://api.perplexity.ai', apiKeyEnv: 'PERPLEXITY_API_KEY' },
+    deepinfra: { name: 'DeepInfra', baseUrl: 'https://api.deepinfra.com/v1/openai', apiKeyEnv: 'DEEPINFRA_API_KEY' },
+    sambanova: { name: 'SambaNova', baseUrl: 'https://api.sambanova.ai/v1', apiKeyEnv: 'SAMBANOVA_API_KEY' },
+    hyperbolic: { name: 'Hyperbolic', baseUrl: 'https://api.hyperbolic.xyz/v1', apiKeyEnv: 'HYPERBOLIC_API_KEY' },
+    huggingface: { name: 'Hugging Face', baseUrl: 'https://router.huggingface.co/v1', apiKeyEnv: 'HF_TOKEN' },
+    alibaba: { name: 'Alibaba Qwen', baseUrl: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1', apiKeyEnv: 'DASHSCOPE_API_KEY' },
+    venice: { name: 'Venice', baseUrl: 'https://api.venice.ai/api/v1', apiKeyEnv: 'VENICE_API_KEY' },
+    requesty: { name: 'Requesty', baseUrl: 'https://router.requesty.ai/v1', apiKeyEnv: 'REQUESTY_API_KEY' },
+    poolside: { name: 'Poolside', baseUrl: 'https://inference.poolside.ai/v1', apiKeyEnv: 'POOLSIDE_API_KEY' },
+    zenmux: { name: 'ZenMux', baseUrl: 'https://zenmux.ai/api/v1', apiKeyEnv: 'ZENMUX_API_KEY' },
+};
+const BUILTIN_IDS = new Set(['openai', 'anthropic', 'google', 'ollama', 'openrouter', 'minimax', 'bedrock', 'vertex', 'azure', 'lmstudio', 'openai-compatible', 'auto']);
+const ID = /^[a-z0-9][a-z0-9_-]*$/;
+const trimSlash = (url) => url.replace(/\/+$/, '');
+const positive = (n) => typeof n === 'number' && Number.isFinite(n) && n > 0;
+/** Why an entry of `customProviders` cannot be used, one problem per bad entry. A preset id may omit its URL. */
+export function customProviderProblems(custom) {
+    const out = [];
+    for (const [id, c] of Object.entries(custom ?? {})) {
+        if (BUILTIN_IDS.has(id))
+            out.push({ id, message: `"${id}" is a built-in provider name; pick another id.` });
+        else if (!ID.test(id))
+            out.push({ id, message: `"${id}" is not a valid id: use lowercase letters, digits, - and _.` });
+        else if (!c || typeof c !== 'object')
+            out.push({ id, message: `"${id}" must be an object.` });
+        else {
+            const url = c.baseUrl ?? PROVIDER_PRESETS[id]?.baseUrl;
+            if (!url)
+                out.push({ id, message: `"${id}" needs a baseUrl.` });
+            else if (!/^https?:\/\//i.test(url))
+                out.push({ id, message: `"${id}" baseUrl must start with http:// or https://.` });
+            else if (c.timeoutMs !== undefined && !positive(c.timeoutMs))
+                out.push({ id, message: `"${id}" timeoutMs must be a positive number.` });
+            else if (c.chunkTimeoutMs !== undefined && !positive(c.chunkTimeoutMs))
+                out.push({ id, message: `"${id}" chunkTimeoutMs must be a positive number.` });
+        }
+    }
+    return out;
+}
+let registered;
+/**
+ * The `customProviders` of the running host, so every place that turns a model name into a model (aliases,
+ * the cheap model, sub-agents, the picker) sees them without each call site passing the config along.
+ * Hosts register at the start of every run; tests reset with `undefined`.
+ */
+export function registerCustomProviders(custom) {
+    registered = custom;
+}
+export function registeredCustomProviders() {
+    return registered;
+}
+let registeredFilters;
+/** `modelFilters` of the running host (per provider id), read by the model pickers. */
+export function registerModelFilters(filters) {
+    registeredFilters = filters;
+}
+/** The filter for a provider id: the registered `modelFilters` entry, else the whitelist/blacklist on its custom provider. */
+export function modelFilterFor(providerId) {
+    return registeredFilters?.[providerId] ?? (registered?.[providerId]?.whitelist || registered?.[providerId]?.blacklist
+        ? { ...(registered[providerId].whitelist ? { whitelist: registered[providerId].whitelist } : {}), ...(registered[providerId].blacklist ? { blacklist: registered[providerId].blacklist } : {}) }
+        : undefined);
+}
+/** Preset ids and custom ids, once each; a built-in id never appears. */
+export function knownProviderIds(custom) {
+    const ids = new Set(Object.keys(PROVIDER_PRESETS));
+    for (const id of Object.keys(custom ?? {}))
+        if (!BUILTIN_IDS.has(id))
+            ids.add(id);
+    return [...ids];
+}
+/** The endpoint for a provider id, or undefined when the id is built-in, unknown, or has no usable URL. */
+export function resolveProviderEndpoint(id, custom, env = process.env) {
+    if (BUILTIN_IDS.has(id))
+        return undefined;
+    const preset = PROVIDER_PRESETS[id];
+    const c = custom?.[id];
+    const baseUrl = c?.baseUrl ?? preset?.baseUrl;
+    if (!baseUrl || (!c && !preset))
+        return undefined;
+    const keyEnv = c?.apiKeyEnv ?? preset?.apiKeyEnv;
+    const apiKey = c?.apiKey ?? (keyEnv ? env[keyEnv] : undefined);
+    return {
+        id,
+        name: c?.name ?? preset?.name ?? id,
+        baseUrl: trimSlash(baseUrl),
+        ...(apiKey ? { apiKey } : {}),
+        ...(c?.headers ? { headers: c.headers } : {}),
+        api: c?.api ?? preset?.api ?? 'openai-compatible',
+        ...(c?.timeoutMs ? { timeoutMs: c.timeoutMs } : {}),
+        ...(c?.chunkTimeoutMs ? { chunkTimeoutMs: c.chunkTimeoutMs } : {}),
+    };
+}
+/** The id the API expects for a model key (`models.<key>.id`), or the key itself. */
+export function apiModelId(providerId, modelKey, custom) {
+    return custom?.[providerId]?.models?.[modelKey]?.id ?? modelKey;
+}
+/** Apply a provider's `whitelist` (only these) then `blacklist` (not these) to a model list. */
+export function filterModels(entries, filter) {
+    const allow = filter?.whitelist?.length ? new Set(filter.whitelist) : undefined;
+    const block = filter?.blacklist?.length ? new Set(filter.blacklist) : undefined;
+    return entries.filter((e) => (!allow || allow.has(e.id)) && (!block || !block.has(e.id)));
+}

package/dist/git/auto-commit.d.ts

@@ -27,11 +27,11 @@ export declare function commitDirty(cwd: string, options?: GitCommitOptions): Pr
 export declare function diffForFiles(cwd: string, files: string[]): Promise<string>;
 /** Deterministic message used when no model is available or it fails. */
 export declare function fallbackCommitMessage(files: string[]): string;
-export declare function commitMessagePrompt(diff: string, task?: string): string;
+export declare function commitMessagePrompt(diff: string, task?: string, instruction?: string): string;
 /** Strip an inline `<think>` block (MiniMax and other reasoning models) and the fences/quotes a model may wrap around the message. */
 export declare function cleanCommitMessage(text: string): string;
 /** Draft a commit message with `model` (typically the cheap model); never throws. */
-export declare function generateCommitMessage(diff: string, files: string[], model: ModelConfig | undefined, task?: string, modelFactory?: (cfg: ModelConfig) => LanguageModel): Promise<string>;
+export declare function generateCommitMessage(diff: string, files: string[], model: ModelConfig | undefined, task?: string, modelFactory?: (cfg: ModelConfig) => LanguageModel, instruction?: string): Promise<string>;
 export type UndoResult = {
     ok: true;
     commit: string;

package/dist/git/auto-commit.js

@@ -112,9 +112,10 @@ export function fallbackCommitMessage(files) {
     return `forge: update ${shown}${more}`;
 }
 const MAX_DIFF_CHARS = 12_000;
-export function commitMessagePrompt(diff, task) {
+export function commitMessagePrompt(diff, task, instruction) {
     const clipped = diff.length > MAX_DIFF_CHARS ? `${diff.slice(0, MAX_DIFF_CHARS)}\n[diff truncated]` : diff;
-    return `Write a git commit message for this diff in conventional-commit style (type(scope): subject, imperative mood, under 72 characters). Add a short body only if the change needs explaining. Reply with the message only, no quotes or code fences.${task ? `\n\nThe change was made for this request: ${task}` : ''}\n\n${clipped}`;
+    const lead = instruction?.trim() || 'Write a git commit message for this diff in conventional-commit style (type(scope): subject, imperative mood, under 72 characters). Add a short body only if the change needs explaining. Reply with the message only, no quotes or code fences.';
+    return `${lead}${task ? `\n\nThe change was made for this request: ${task}` : ''}\n\n${clipped}`;
 }
 /** Strip an inline `<think>` block (MiniMax and other reasoning models) and the fences/quotes a model may wrap around the message. */
 export function cleanCommitMessage(text) {
@@ -125,11 +126,11 @@ export function cleanCommitMessage(text) {
         .trim();
 }
 /** Draft a commit message with `model` (typically the cheap model); never throws. */
-export async function generateCommitMessage(diff, files, model, task, modelFactory = createLanguageModel) {
+export async function generateCommitMessage(diff, files, model, task, modelFactory = createLanguageModel, instruction) {
     if (!model || !diff.trim())
         return fallbackCommitMessage(files);
     try {
-        const result = await generateText({ model: modelFactory(model), prompt: commitMessagePrompt(diff, task) });
+        const result = await generateText({ model: modelFactory(model), prompt: commitMessagePrompt(diff, task, instruction) });
         const message = cleanCommitMessage(result.text);
         return message || fallbackCommitMessage(files);
     }

package/dist/github/github-tools.d.ts

@@ -62,14 +62,14 @@ declare const createParams: z.ZodObject<{
     head: z.ZodOptional<z.ZodString>;
     draft: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
-    title: string;
     body: string;
+    title: string;
     draft?: boolean | undefined;
     base?: string | undefined;
     head?: string | undefined;
 }, {
-    title: string;
     body: string;
+    title: string;
     draft?: boolean | undefined;
     base?: string | undefined;
     head?: string | undefined;

package/dist/hooks/runner.js

@@ -15,6 +15,7 @@
 import { spawn } from 'node:child_process';
 import { execFileSync } from 'node:child_process';
 import { redact } from '../tools/redact.js';
+import { shellEnv } from '../tools/shell-env.js';
 /** Compute the env-var map for an event. */
 export function eventToEnv(event) {
     const env = {
@@ -98,11 +99,11 @@ export function runHook(event, config) {
             proc = spawn(config.command, [], {
                 shell: true,
                 detached: process.platform !== 'win32',
-                env: {
+                env: shellEnv({
                     ...process.env,
                     ...(config.env ?? {}),
                     ...eventToEnv(event),
-                },
+                }),
                 stdio: ['ignore', 'pipe', 'pipe'],
                 windowsHide: true,
             });

package/dist/import/claude-code.d.ts

@@ -0,0 +1,39 @@
+import type { McpServerSpec } from '../mcp/mcp-config.js';
+export type ImportScope = 'user' | 'project';
+export interface ClaudeImportPlan {
+    mcp: Array<{
+        name: string;
+        spec: McpServerSpec;
+        scope: ImportScope;
+        from: string;
+    }>;
+    /** Folders to add to `skillPaths` (`~/...` or relative to the workspace). */
+    skillPaths: string[];
+    agents: Array<{
+        name: string;
+        scope: ImportScope;
+        text: string;
+        from: string;
+    }>;
+    commands: Array<{
+        name: string;
+        scope: ImportScope;
+        text: string;
+        from: string;
+    }>;
+    notes: string[];
+}
+export interface ImportRoots {
+    home: string;
+    cwd: string;
+}
+export declare function planClaudeImport(roots: ImportRoots): Promise<ClaudeImportPlan>;
+export interface ApplyOptions extends ImportRoots {
+    /** Defaults to `<home>/.forge/config.json`. */
+    configPath?: string;
+}
+export interface ApplyResult {
+    written: string[];
+    skipped: string[];
+}
+export declare function applyClaudeImport(plan: ClaudeImportPlan, opts: ApplyOptions): Promise<ApplyResult>;

package/dist/import/claude-code.js

@@ -0,0 +1,254 @@
+/**
+ * Bring a Claude Code setup over to Forge: MCP servers, skill folders, sub-agents and slash commands.
+ * `planClaudeImport` only reads; `applyClaudeImport` writes into Forge's own locations and never replaces
+ * something that is already there. What Forge has no equivalent for (permissions, hooks) is listed in `notes`.
+ * A converted agent is never given more tools than the original: tools that map to nothing leave it read-only.
+ */
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { loadForgeConfigFile, saveForgeConfigFile } from '../config-file.js';
+import { parseFrontmatter } from '../skills/parser.js';
+const TOOL_MAP = {
+    Read: ['read_file'],
+    Grep: ['search_files'],
+    Glob: ['list_files'],
+    LS: ['list_files'],
+    Write: ['write_file'],
+    Edit: ['edit_file'],
+    MultiEdit: ['edit_file'],
+    NotebookEdit: ['edit_notebook'],
+    Bash: ['run_command'],
+    WebFetch: ['fetch_url'],
+    WebSearch: ['web_search'],
+    TodoWrite: ['todo_write', 'todo_read'],
+};
+const READ_ONLY_FALLBACK = ['read_file', 'list_files', 'search_files'];
+const COMMAND_NAME = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+/** A command body that runs a shell line (!`cmd`) or pulls in a file (@path.ext) in Claude Code. */
+const CLAUDE_INLINE = /(^|\s)!`|(^|\s)@\S+\.\w+/;
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+async function readJson(file) {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function isDir(dir) {
+    try {
+        await readdir(dir);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function mdFiles(dir) {
+    try {
+        return (await readdir(dir)).filter((n) => n.toLowerCase().endsWith('.md')).sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** One Claude Code server entry as a Forge spec, or undefined when it has neither a command nor a URL. */
+function convertServer(raw) {
+    if (!isObject(raw))
+        return undefined;
+    const str = (v) => (typeof v === 'string' && v ? v : undefined);
+    const strList = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : undefined);
+    const strMap = (v) => isObject(v) ? Object.fromEntries(Object.entries(v).filter((e) => typeof e[1] === 'string')) : undefined;
+    const command = str(raw.command);
+    const url = str(raw.url);
+    if (!command && !url)
+        return undefined;
+    const type = raw.type === 'http' ? 'streamable-http' : raw.type === 'sse' ? 'sse' : raw.type === 'stdio' ? 'stdio' : undefined;
+    const args = strList(raw.args);
+    const env = strMap(raw.env);
+    const headers = strMap(raw.headers);
+    return {
+        ...(type ? { type } : {}),
+        ...(command ? { command } : {}),
+        ...(args ? { args } : {}),
+        ...(env && Object.keys(env).length ? { env } : {}),
+        ...(url ? { url } : {}),
+        ...(headers && Object.keys(headers).length ? { headers } : {}),
+    };
+}
+function collectServers(servers, scope, from, plan, seen) {
+    if (!isObject(servers))
+        return;
+    for (const [name, raw] of Object.entries(servers)) {
+        const key = `${scope}:${name}`;
+        if (seen.has(key))
+            continue;
+        const spec = convertServer(raw);
+        if (!spec) {
+            plan.notes.push(`${from}: MCP server "${name}" has no command or url; not imported`);
+            continue;
+        }
+        seen.add(key);
+        plan.mcp.push({ name, spec, scope, from });
+    }
+}
+const norm = (p) => p.replace(/\\/g, '/').replace(/\/$/, '').toLowerCase();
+function agentSlug(name) {
+    return name.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^[^a-z0-9]+|-+$/g, '').slice(0, 64);
+}
+function oneLine(s) {
+    return s.replace(/\\n/g, ' ').replace(/\s+/g, ' ').trim();
+}
+function convertAgent(file, text, notes) {
+    const { fields, body } = parseFrontmatter(text.replace(/\r\n/g, '\n'));
+    const label = path.basename(file);
+    const description = oneLine(fields.get('description') ?? '');
+    if (!description) {
+        notes.push(`${label}: no description; agent not imported`);
+        return undefined;
+    }
+    const name = agentSlug(fields.get('name') || label.replace(/\.md$/i, ''));
+    if (!name) {
+        notes.push(`${label}: no usable name; agent not imported`);
+        return undefined;
+    }
+    let tools;
+    const rawTools = fields.get('tools');
+    if (rawTools !== undefined && rawTools.trim()) {
+        const wanted = rawTools.split(',').map((s) => s.trim()).filter(Boolean);
+        const mapped = new Set();
+        for (const w of wanted) {
+            const base = w.replace(/\(.*$/, '');
+            if (base !== w)
+                notes.push(`${label}: "${w}" limited a tool by pattern in Claude Code; Forge permission rules decide that now`);
+            for (const t of TOOL_MAP[base] ?? [])
+                mapped.add(t);
+            if (!TOOL_MAP[base] && base !== 'Task')
+                notes.push(`${label}: tool "${base}" has no Forge equivalent; left out`);
+        }
+        tools = mapped.size > 0 ? [...mapped] : READ_ONLY_FALLBACK;
+        if (mapped.size === 0)
+            notes.push(`${label}: none of its tools map to Forge; imported as read-only`);
+    }
+    const front = ['---', `description: ${description}`, 'mode: subagent', ...(tools ? [`tools: ${tools.join(', ')}`] : []), '---'];
+    return { name, text: `${front.join('\n')}\n${body.trim()}\n` };
+}
+function convertCommand(file, text, notes) {
+    const label = path.basename(file);
+    const name = label.replace(/\.md$/i, '');
+    if (!COMMAND_NAME.test(name)) {
+        notes.push(`${label}: not a valid command name (letters, digits, - and _); not imported`);
+        return undefined;
+    }
+    const { fields, body } = parseFrontmatter(text.replace(/\r\n/g, '\n'));
+    const description = oneLine(fields.get('description') ?? '');
+    if (CLAUDE_INLINE.test(body))
+        notes.push(`${label}: runs a shell line or pulls in a file inside the prompt in Claude Code; Forge sends that text as it is`);
+    const head = description ? `---\ndescription: ${description}\n---\n` : '';
+    return { name, text: `${head}${body.replace(/\s+$/, '')}\n` };
+}
+export async function planClaudeImport(roots) {
+    const { home, cwd } = roots;
+    const plan = { mcp: [], skillPaths: [], agents: [], commands: [], notes: [] };
+    const seen = new Set();
+    const claudeJson = await readJson(path.join(home, '.claude.json'));
+    if (isObject(claudeJson)) {
+        collectServers(claudeJson.mcpServers, 'user', '~/.claude.json', plan, seen);
+        if (isObject(claudeJson.projects)) {
+            for (const [dir, value] of Object.entries(claudeJson.projects)) {
+                if (norm(dir) === norm(cwd) && isObject(value))
+                    collectServers(value.mcpServers, 'project', '~/.claude.json (this project)', plan, seen);
+            }
+        }
+    }
+    const projectMcp = await readJson(path.join(cwd, '.mcp.json'));
+    if (isObject(projectMcp))
+        collectServers(projectMcp.mcpServers, 'project', '.mcp.json', plan, seen);
+    if (await isDir(path.join(home, '.claude', 'skills')))
+        plan.skillPaths.push('~/.claude/skills');
+    if (await isDir(path.join(cwd, '.claude', 'skills')))
+        plan.skillPaths.push('.claude/skills');
+    const places = [
+        ['user', path.join(home, '.claude')],
+        ['project', path.join(cwd, '.claude')],
+    ];
+    for (const [scope, base] of places) {
+        for (const n of await mdFiles(path.join(base, 'agents'))) {
+            const file = path.join(base, 'agents', n);
+            const out = convertAgent(file, await readFile(file, 'utf8'), plan.notes);
+            if (out)
+                plan.agents.push({ ...out, scope, from: file });
+        }
+        for (const n of await mdFiles(path.join(base, 'commands'))) {
+            const file = path.join(base, 'commands', n);
+            const out = convertCommand(file, await readFile(file, 'utf8'), plan.notes);
+            if (out)
+                plan.commands.push({ ...out, scope, from: file });
+        }
+        const settings = await readJson(path.join(base, 'settings.json'));
+        if (isObject(settings)) {
+            const where = `${scope === 'user' ? '~' : '.'}/.claude/settings.json`;
+            if (settings.permissions !== undefined)
+                plan.notes.push(`${where}: permissions are not imported; set Forge permission rules instead`);
+            if (settings.hooks !== undefined)
+                plan.notes.push(`${where}: hooks are not imported`);
+        }
+    }
+    return plan;
+}
+async function writeNew(file, text, result) {
+    await mkdir(path.dirname(file), { recursive: true });
+    try {
+        await writeFile(file, text, { encoding: 'utf8', flag: 'wx' });
+        result.written.push(file);
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            result.skipped.push(`${file} already exists`);
+        else
+            throw err;
+    }
+}
+export async function applyClaudeImport(plan, opts) {
+    const { home, cwd } = opts;
+    const result = { written: [], skipped: [] };
+    const forgeDir = (scope) => path.join(scope === 'user' ? home : cwd, '.forge');
+    for (const scope of ['user', 'project']) {
+        const items = plan.mcp.filter((m) => m.scope === scope);
+        if (items.length === 0)
+            continue;
+        const file = path.join(forgeDir(scope), 'mcp.json');
+        const existing = await readJson(file);
+        const servers = isObject(existing) && isObject(existing.mcpServers) ? { ...existing.mcpServers } : {};
+        let added = 0;
+        for (const m of items) {
+            if (m.name in servers) {
+                result.skipped.push(`MCP server "${m.name}" already in ${file}`);
+            }
+            else {
+                servers[m.name] = m.spec;
+                added += 1;
+            }
+        }
+        if (added > 0) {
+            await mkdir(path.dirname(file), { recursive: true });
+            await writeFile(file, JSON.stringify({ ...(isObject(existing) ? existing : {}), mcpServers: servers }, null, 2) + '\n', 'utf8');
+            result.written.push(file);
+        }
+    }
+    for (const a of plan.agents)
+        await writeNew(path.join(forgeDir(a.scope), 'agents', `${a.name}.md`), a.text, result);
+    for (const c of plan.commands)
+        await writeNew(path.join(forgeDir(c.scope), 'commands', `${c.name}.md`), c.text, result);
+    if (plan.skillPaths.length > 0) {
+        const configPath = opts.configPath ?? path.join(home, '.forge', 'config.json');
+        const { config } = await loadForgeConfigFile(configPath);
+        const current = config.skillPaths ?? [];
+        const add = plan.skillPaths.filter((p) => !current.includes(p));
+        if (add.length > 0) {
+            await saveForgeConfigFile({ skillPaths: [...current, ...add] }, configPath);
+            result.written.push(configPath);
+        }
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -36,17 +36,17 @@ export type { MemoryForgetResult, MemoryReadResult, MemoryWriteResult } from './
 export { buildLlmSummarizer, compactMessages, estimateMessageTokens, estimateTokens, getModelWindowTokens, shouldCompact, } from './context/compaction.js';
 export type { CompactionResult, Summarizer } from './context/compaction.js';
 export { defaultModelFor, detectProvider, envVarForProvider, fastDefaultFor, hasProviderKey, readModelConfigFromEnv, resolveApiKey, SUPPORTED_PROVIDERS, } from './config.js';
-export { loadMcpConfig, parseMcpConfig, connectAll, connectOne, closeAll, mcpResultToValue, jsonSchemaToZod, } from './mcp/index.js';
+export { loadMcpConfig, parseMcpConfig, connectAll, connectOne, closeAll, mcpResultToValue, mcpInstructionsBlock, createMcpResourceTools, jsonSchemaToZod, } from './mcp/index.js';
 export type { McpConfigFile, McpServerSpec, ConnectedMcpServer, } from './mcp/index.js';
 export { createLanguageModel, formatModelId, pickAvailableProvider, resolveModelFromEnv, resolveModelFromEnvAsync } from './providers.js';
 export { defaultSessionDir, generateSessionId, saveSession, loadSession, deleteSession, listSessions, findLatestSession, formatSessionMarkdown, formatSessionJson, appendedSince, summarizeMessage, watchSession, searchSessions, sessionText, pruneSessions, pruneByRetention, } from './sessions/index.js';
 export type { Session, ListEntry, FormatOptions, SessionUpdate, WatchSessionOptions, SessionMatch, SearchSessionsOptions, SessionPruneOptions, SessionPruneResult } from './sessions/index.js';
 export { commandDirs, expandCustomCommand, formatCustomCommands, loadCustomCommands, parseCommandFile, type CustomCommand, } from './commands/custom-commands.js';
 export { BUILTIN_TOOLS, editFileTool, fetchUrlTool, findSymbolTool, listFilesTool, memoryReadTool, memoryForgetTool, memoryWriteTool, readFileTool, runCommandTool, searchFilesTool, subAgentTool, writeFileTool, checkPolicyViolation, globToRegex, mergeToolSandbox, normalizePathPattern, pathMatchesAny, redact, countRedactions, buildRules, ToolResultCache, buildCacheKey, cachedExecute, } from './tools/index.js';
-export type { AgentConfig, AgentEvent, AgentRunOptions, AgentRunReason, AgentRunResult, AnyLanguageModel, ApprovalDecision, CommandRunner, ModelRouter, VerifyConfig, ApprovalRequest, LanguageModelFactory, ModelConfig, PricePerMillionTokens, ProviderName, RedactOptions, ToolContext, ToolDefinition, ToolPolicy, ToolSandbox, } from './types.js';
+export type { AgentConfig, AgentEvent, AgentRunOptions, AgentRunReason, AgentRunResult, AnyLanguageModel, ApprovalDecision, CommandRunner, ModelRouter, VerifyConfig, ApprovalRequest, LanguageModelFactory, ModelConfig, PricePerMillionTokens, ProviderName, RedactOptions, TodoItem, ToolContext, UserQuestion, ToolDefinition, ToolPolicy, ToolSandbox, } from './types.js';
 export type { CacheKeyParts, CacheStats } from './tools/index.js';
 export type { RedactionRule, RedactionResult } from './tools/index.js';
-export { buildSkillsBlock, composeSkillsPrompt, discoverSkills, fetchSkillsCatalog, installSkillFromCatalog, loadSkillsRegistry, loadSkillsRegistryAsync, parseSkill, parseSkillsDir, resolveSkillRoots, scoreSkill, searchSkills, selectSkills, skillsRegistryFromList, DEFAULT_SKILL_CATALOG_URL, GLOBAL_SKILLS_DIR, LOCAL_SKILLS_DIR, PROJECT_SKILLS_DIR, SKILL_CATALOG_VERSION, } from './skills/index.js';
+export { buildSkillsBlock, builtinSkills, composeSkillsPrompt, discoverSkills, fetchSkillsCatalog, installSkillFromCatalog, loadSkillsRegistry, loadSkillsRegistryAsync, parseSkill, parseSkillsDir, resolveSkillRoots, scoreSkill, searchSkills, selectSkills, skillsRegistryFromList, DEFAULT_SKILL_CATALOG_URL, GLOBAL_SKILLS_DIR, LOCAL_SKILLS_DIR, PROJECT_SKILLS_DIR, SKILL_CATALOG_VERSION, } from './skills/index.js';
 export type { Skill, SkillCatalog, SkillCatalogEntry, SkillRegistry, SkillRoots, SkillSearchResult, SkillSource, } from './skills/index.js';
 export { cosine, embedderFromEnv, hashingEmbedder, openAiCompatibleEmbedder, } from './semantic/embedder.js';
 export type { Embedder, OpenAiCompatibleEmbedderOptions } from './semantic/embedder.js';
@@ -63,7 +63,13 @@ export { PolicyError, applyPolicy, assertProviderAllowed, filterMcpServers, getO
 export type { OrgPolicy } from './policy/policy.js';
 export { createFileAuditSink, defaultAuditFile, scrubArgs } from './policy/audit.js';
 export type { AuditEntry, AuditSink } from './policy/audit.js';
-export { hasProxy, installProxy, proxyFromEnv } from './policy/proxy.js';
+export { hasProxy, installProxy, installedFetch, proxyFromEnv } from './policy/proxy.js';
+export { readCaCertificates } from './policy/ca-certs.js';
+export { BackgroundAgents, MAX_RUNNING_BACKGROUND, backgroundResultsBlock } from './agent/background.js';
+export type { BackgroundAgent, BackgroundState } from './agent/background.js';
+export { applyClaudeImport, planClaudeImport } from './import/claude-code.js';
+export type { ApplyResult, ClaudeImportPlan } from './import/claude-code.js';
+export type { CaCertificates } from './policy/ca-certs.js';
 export type { ProxySettings } from './policy/proxy.js';
 export { AGENT_HOOK_TOOLS, createAgentHookRunner, DEFAULT_AGENT_HOOK_TIMEOUT_MS, DEFAULT_HOOK_TIMEOUT_MS, HooksBus, eventFilePath, eventToEnv, eventToolName, globalSettingsPath, hooksBusFromConfig, loadHooksConfig, matcherMatches, projectSettingsPath, runHook, validateHooksConfig, HOOK_EVENT_NAMES, shouldIgnoreWatchPath, FileChangeCoalescer, watchFilesystem, } from './hooks/index.js';
 export type { AgentHookConfig, AgentHookRunner, AgentHookRunnerOptions, ShellHookConfig, ForgeSettings, HookConfig, HookDispatchLog, HookEvent, HookEventName, FileChangeType, HookMatcherEntry, HookRunResult, HooksConfig, LoadHooksResult, } from './hooks/index.js';
@@ -74,7 +80,7 @@ export type { InstalledMcpServer, InstalledServerMetadata, MarketplaceCatalog, M
 export { MARKETPLACE_CATALOG_VERSION } from './mcp/marketplace-types.js';
 export { CheckpointStore, type CheckpointStoreLimits } from './checkpoints/index.js';
 export type { CaptureOptions, Checkpoint, CheckpointFile, CheckpointFileStatus, CheckpointSummary, CheckpointTrigger, PruneResult, RestoreResult, } from './checkpoints/index.js';
-export { SpecStore, isSafeSpecId, runKey, slugifyTaskForSpecId, SPEC_READONLY_TOOLS, splitSpecSections, convertToCheckboxes, parseTasks, setTaskDone, changedSince, changeSize, keepDoneTasks, referencedPaths, specDrift, syncSpecTask } from './specs/index.js';
+export { SpecStore, isSafeSpecId, runKey, slugifyTaskForSpecId, SPEC_READONLY_TOOLS, splitRequirementsDesign, splitSpecSections, splitTasksSection, convertToCheckboxes, parseTasks, setTaskDone, changedSince, changeSize, keepDoneTasks, referencedPaths, specDrift, syncSpecTask } from './specs/index.js';
 export type { SpecDraft, SpecRunRecord, SpecRuns, SpecSections, SpecSummary, SpecTask, SpecDrift } from './specs/index.js';
 export { BUILTIN_SPECIALISTS, defaultConfigPath, effectiveToolsFor, BOARD_TOOL_NAMES, createBoardTools, DEFAULT_BOARD_CAP, getRegisteredSpecialist, getSpecialist, MessageBoard, listSpecialists, loadSpecialistsFromConfig, parseRouterOutput, registerSpecialist, resolveEffectiveModel, ROUTER_SYSTEM_PROMPT, runOrchestrator, runRouter, saveSpecialistsToConfig, unregisterSpecialist, validateSpecialistConfig, _resetSpecialistsForTests, _customSpecialistCount, } from './orchestrator/index.js';
 export type { BoardMessage } from './orchestrator/index.js';
@@ -87,10 +93,21 @@ export { branchChangedFiles, branchDiff, commitAllInWorktree, compareWorktreeCon
 export type { MergeResult, WorktreeCommit, CreateOptions, RemoveOptions, RemoveResult, WorktreeContextSnapshot, WorktreeInfo, WorktreeMismatchKind, WorktreeMismatchResult, } from './worktree/index.js';
 export { formatSteeringLine, isSafeSteeringName, loadSteering, overrideFilePath, parseSteering, pathMatchesGlob, readOverride, selectAtStart, selectOnToolTouch, setSteeringDisabled, stripSteering, wrapSteering, } from './steering/index.js';
 export type { StartSelection, SteeringConfig, SteeringDoc, SteeringInclusion, SteeringLoadResult, SteeringSkip, } from './steering/index.js';
+export { CONFIG_KEY_COVERAGE, FORGE_CONFIG_SCHEMA } from './config-schema.js';
+export { FILE_WRITE_TOOL_NAMES, filesTouchedBy } from './tools/write-tools.js';
+export { shellEnv } from './tools/shell-env.js';
+export { previewPatch } from './tools/apply-patch.js';
+export type { PatchPreview } from './tools/apply-patch.js';
+export { applyPatchTool, parsePatch, patchedPaths } from './tools/apply-patch.js';
+export { buildEmbedder, type EmbedderSpec } from './semantic/embedder.js';
+export { parseExtensions, type SemanticOptions } from './semantic/semantic-index.js';
+export { cleanDigest, generateSessionDigest, shouldDigest, type DigestItem } from './memory/session-digest.js';
+export { buildExtraInstructionsBlock } from './steering/extra-instructions.js';
 export { buildProjectInstructionsBlock, PROJECT_INSTRUCTION_FILES } from './steering/project-instructions.js';
 export { aiCommentTask, findAiComments, triggerOf } from './ai-comments/index.js';
 export type { AiComment, AiCommentAction, AiCommentFile } from './ai-comments/index.js';
 export * from './git/index.js';
+export * from './journey/index.js';
 export * from './repomap/index.js';
 export * from './lint/index.js';
 export { findSyntaxErrors } from './code-index/parser.js';
@@ -98,7 +115,19 @@ export type { SyntaxProblem } from './code-index/parser.js';
 export * from './lsp/index.js';
 export * from './plugins/index.js';
 export { READ_ONLY_TOOLS, resolveAutoApprove } from './tools/read-only.js';
+export { compilePermissionRules, evaluatePermission, isSensitiveFile, permissionFor, splitShellCommands, touchesOutsideCwd } from './tools/permission-rules.js';
+export type { PermissionAction, PermissionConfig, PermissionRule } from './tools/permission-rules.js';
 export { autoRunCommands, autoRunFingerprint, detectProjectChecks, formatProjectCommandsBlock, projectScriptsFingerprint } from './verify/index.js';
 export { isAlwaysAllowable, isListedCommand, needsScriptFingerprint, normalizeCommand } from './tools/command-allow.js';
 export type { CheckKind, DetectedCheck, DetectedChecks } from './verify/index.js';
 export { IgnoreRules, IGNORE_FILE_NAMES, findGitRoot } from './tools/ignore-rules.js';
+export { MAX_OBJECTIVE_CHARS, applyTurnOutcome, createGoalReportTool, goalPrompt, pauseGoal, resumeGoal, startGoal } from './agent/goal.js';
+export type { GoalReport, GoalState, GoalStatus, TurnOutcome } from './agent/goal.js';
+export { loadMergedForgeConfig, projectConfigPath } from './config-merge.js';
+export { PROVIDER_PRESETS, apiModelId, customProviderProblems, filterModels, knownProviderIds, modelFilterFor, registerCustomProviders, registerModelFilters, registeredCustomProviders, resolveProviderEndpoint, } from './custom-providers.js';
+export type { CustomModelConfig, CustomProviderConfig, EndpointApi, ProviderEndpoint, ProviderPreset } from './custom-providers.js';
+export { withTimeouts, type FetchTimeouts } from './timed-fetch.js';
+export { createEndpointModel } from './providers.js';
+export { agentToSpecialist, loadAgentFiles, parseAgentFile, registerAgentDefs, registeredAgent, registeredAgents, type AgentDef } from './agents/agent-files.js';
+export { applyResolved, type ResolvedModelRef } from './model-alias.js';
+export { getModelOverride, overridesFromProviders, registerModelOverrides, type ModelOverride, type ModelOverrides } from './model-overrides.js';