@ikarmic/forge-core 5.2.0 → 5.4.0

package/dist/context/compaction.js

@@ -12,6 +12,8 @@
  * dedicated cheaper model or even a deterministic extractive summarizer.
  */
 import { generateText } from 'ai';
+import { withModelRetry } from '../agent/retry.js';
+import { catalogEntry } from '../catalog/models-dev.js';
 import { mediaPartLabel, mediaPartTokens } from '../attachments.js';
 import { stripThinkTags } from '../agent/think-tags.js';
 import { overrideContextTokens } from '../model-overrides.js';
@@ -22,6 +24,12 @@ import { createLanguageModel } from '../providers.js';
  * `DEFAULT_WINDOW_TOKENS`.
  */
 export const DEFAULT_WINDOW_TOKENS = 32_000;
+/**
+ * For a hosted model nothing lists: most current ones hold 128k or more, so 32k would condense a long chat at once
+ * and the model would forget without an error (F16c). Local servers keep 32k, where the real window is usually small.
+ */
+export const HOSTED_FALLBACK_WINDOW_TOKENS = 128_000;
+const LOCAL_WINDOW_PROVIDERS = new Set(['ollama', 'lmstudio']);
 const WINDOW_SIZES = {
     // Anthropic
     'claude-3-5-sonnet': 200_000,
@@ -84,10 +92,22 @@ const WINDOW_SIZES = {
     'minimax-m3': 1_000_000,
     'minimax-m2': 204_800,
 };
+/** True when no override, catalog entry or table knows this model's window: the figure used is only a guess. */
+export function windowIsGuess(model) {
+    if (overrideContextTokens(model))
+        return false;
+    if (typeof model !== 'string' && catalogEntry(model)?.context)
+        return false;
+    const id = (typeof model === 'string' ? model : model.model).toLowerCase().replace(/^models\//, '');
+    return !Object.keys(WINDOW_SIZES).some((key) => id === key || id.includes(key));
+}
 export function getModelWindowTokens(model) {
     const overridden = overrideContextTokens(model);
     if (overridden)
         return overridden;
+    const listed = typeof model === 'string' ? undefined : catalogEntry(model)?.context;
+    if (listed)
+        return listed;
     const id = typeof model === 'string' ? model : model.model;
     const stripped = id.toLowerCase().replace(/^models\//, '');
     // Direct hit first.
@@ -99,7 +119,7 @@ export function getModelWindowTokens(model) {
         if (stripped.includes(key))
             return WINDOW_SIZES[key];
     }
-    return DEFAULT_WINDOW_TOKENS;
+    return typeof model !== 'string' && !LOCAL_WINDOW_PROVIDERS.has(model.provider) ? HOSTED_FALLBACK_WINDOW_TOKENS : DEFAULT_WINDOW_TOKENS;
 }
 /** JSON.stringify replacer that keeps image and file bytes out of a summary prompt. */
 function withoutMedia(_key, value) {
@@ -121,18 +141,48 @@ export function estimateMessageTokens(messages) {
         if (typeof m.content === 'string')
             total += estimateTokens(m.content);
         else if (Array.isArray(m.content)) {
-            for (const part of m.content) {
-                if (part && typeof part === 'object' && 'text' in part) {
-                    total += estimateTokens(String(part.text ?? ''));
-                }
-                else {
-                    total += mediaPartTokens(part);
-                }
-            }
+            for (const part of m.content)
+                total += partTokens(part);
         }
     }
     return total;
 }
+/** One content part. Tool calls and tool results are most of an agent's context, so they count (RB-56). */
+function partTokens(part) {
+    if (!part || typeof part !== 'object')
+        return 0;
+    const p = part;
+    if (typeof p.text === 'string')
+        return estimateTokens(p.text);
+    if (p.type === 'tool-call')
+        return estimateTokens(jsonText(p.input));
+    if (p.type === 'tool-result')
+        return estimateTokens(jsonText(p.output?.value));
+    return mediaPartTokens(part);
+}
+function jsonText(value) {
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value, withoutMedia) ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+/** Tool output in the summarizer's transcript is cut to this, so a few file reads cannot crowd out the decisions. */
+export const SUMMARY_TOOL_OUTPUT_CHARS = 2_000;
+function clipForSummary(text) {
+    if (text.length <= SUMMARY_TOOL_OUTPUT_CHARS)
+        return text;
+    return `${text.slice(0, SUMMARY_TOOL_OUTPUT_CHARS)}\n… [${text.length - SUMMARY_TOOL_OUTPUT_CHARS} more characters of tool output]`;
+}
+/** The first words of a compaction summary message; how the chat and exports tell it from what the person wrote. */
+export const COMPACTION_SUMMARY_PREFIX = '[Summary of earlier conversation';
+/** Whether a message is the summary that compaction put in place of older turns. */
+export function isCompactionSummary(message) {
+    return !!message && message.role === 'user' && typeof message.content === 'string' && message.content.startsWith(COMPACTION_SUMMARY_PREFIX);
+}
 /**
  * Default summarizer: calls the LLM with a structured prompt asking for
  * a Goal / Key decisions / Files touched / Open questions breakdown.
@@ -156,7 +206,10 @@ export function buildLlmSummarizer(model, modelFactory) {
                         return p;
                     if (p && typeof p === 'object' && 'text' in p)
                         return String(p.text);
-                    return mediaPartLabel(p) ?? JSON.stringify(p, withoutMedia);
+                    const part = p;
+                    if (part.type === 'tool-result')
+                        return `[${String(part.toolName)} result]\n${clipForSummary(jsonText(part.output?.value))}`;
+                    return mediaPartLabel(p) ?? clipForSummary(JSON.stringify(p, withoutMedia));
                 })
                     .join('\n');
             }
@@ -201,11 +254,12 @@ Here is the conversation to summarize:
 
 ${truncateToBudget(transcript, 60_000)}`;
         const llm = factory(model);
-        const result = await generateText({
+        const result = await withModelRetry(() => generateText({
             model: llm,
             prompt,
             maxOutputTokens: 2000,
-        });
+            maxRetries: 0,
+        }));
         // Reasoning models put an inline <think> block in the reply; it must not be stored as the summary.
         return stripThinkTags(result.text).trim();
     };
@@ -239,30 +293,41 @@ export function shouldCompactForBudget(nextPromptTokens, model, thresholdFractio
     return nextPromptTokens >= effectiveLimitTokens(model, thresholdFraction, budgetTokens);
 }
 /**
- * Compact the message history in-place. Drops the oldest N messages and
- * inserts a single `[Compacted summary of N earlier turns]` system message
- * followed by the structured summary.
+ * Compact the message history. Replaces older messages with one summary message.
  *
  * Keeps:
  *   - the original system prompt (first message, if it's a system one)
- *   - the most recent `keepRecent` turns
+ *   - the user's first request, word for word
+ *   - the most recent messages: at least `keepRecent` of them and at least `keepRecentTokens` worth, cut where a
+ *     step starts, so a tool result never loses the call that made it (RB-56)
  *
- * Replaces everything in between with a single summary.
+ * The summary is a user message (`COMPACTION_SUMMARY_PREFIX`): Gemini and Bedrock refuse a system message after the
+ * conversation has started.
  */
 export async function compactMessages(allMessages, summarizer, options = {}) {
     const keepRecent = options.keepRecent ?? 4;
-    if (allMessages.length <= keepRecent + 1) {
-        return { messages: allMessages, droppedCount: 0, savedTokens: 0, summary: '' };
-    }
+    const noChange = { messages: allMessages, droppedCount: 0, savedTokens: 0, summary: '' };
+    if (allMessages.length <= keepRecent + 1)
+        return noChange;
     const systemMessage = allMessages[0]?.role === 'system' ? allMessages[0] : undefined;
     const startIndex = systemMessage ? 1 : 0;
-    const recent = allMessages.slice(-keepRecent);
-    const toSummarize = allMessages.slice(startIndex, allMessages.length - keepRecent);
-    if (toSummarize.length === 0) {
-        return { messages: allMessages, droppedCount: 0, savedTokens: 0, summary: '' };
-    }
+    let cut = allMessages.length - keepRecent;
+    // The token floor applies once the conversation is more than twice its size, so compaction always frees most of it.
+    const want = options.keepRecentTokens ?? 0;
+    const floor = want > 0 && estimateMessageTokens(allMessages.slice(startIndex)) > 2 * want ? want : 0;
+    while (cut > startIndex + 1 && floor > 0 && estimateMessageTokens(allMessages.slice(cut)) < floor)
+        cut--;
+    // A tool message answers the assistant message just before it: never start the kept part on one.
+    while (cut > startIndex && allMessages[cut]?.role === 'tool')
+        cut--;
+    const recent = allMessages.slice(cut);
+    const toSummarize = allMessages.slice(startIndex, cut);
+    if (toSummarize.length === 0)
+        return noChange;
     // The user's original request is never summarized away: it stays verbatim right after the system prompt.
-    const pinned = toSummarize[0]?.role === 'user' ? toSummarize[0] : undefined;
+    const pinned = toSummarize[0]?.role === 'user' && !isCompactionSummary(toSummarize[0]) ? toSummarize[0] : undefined;
+    if (pinned && toSummarize.length === 1)
+        return noChange;
     const beforeTokens = estimateMessageTokens(toSummarize) - (pinned ? estimateMessageTokens([pinned]) : 0);
     const summary = await summarizer(toSummarize);
     // An empty summary (a failed or reasoning-only reply) must not replace the dropped turns with nothing.
@@ -270,8 +335,9 @@ export async function compactMessages(allMessages, summarizer, options = {}) {
         return { messages: allMessages, droppedCount: 0, savedTokens: 0, summary: '' };
     const summaryTokens = estimateTokens(summary);
     const separator = {
-        role: 'system',
-        content: `[Compacted summary of ${toSummarize.length} earlier turn${toSummarize.length === 1 ? '' : 's'}]\n\n` +
+        role: 'user',
+        content: `${COMPACTION_SUMMARY_PREFIX} (${toSummarize.length} message${toSummarize.length === 1 ? '' : 's'}), written by Forge to save context. ` +
+            `It is not a new request.]\n\n` +
             summary,
     };
     const next = [];

package/dist/context/mask.d.ts

@@ -2,9 +2,9 @@
  * Mask old tool results in the prompt that is sent to the model.
  *
  * Most of an agent run's tokens are old tool output (whole files read once, command logs) that is resent on every
- * step. This builds the outgoing prompt from the history with such results replaced by a one-line stub. It is a
- * view: the history itself (saved session, transcript) is never edited, and the stub says the tool can be called
- * again. Provider-independent: it only looks at the message shapes of the `ai` SDK.
+ * step. This replaces such results with a one-line stub that says the tool can be called again. The agent stores the
+ * stubs in the prompt history (RB-60) so a new turn starts from them; what the person sees comes from the transcript,
+ * which keeps the full results (RB-58). Provider-independent: it only looks at the message shapes of the `ai` SDK.
  * Spec: docs/superpowers/specs/2026-10-19-context-economy-design.md
  */
 import type { ModelMessage } from 'ai';
@@ -28,7 +28,13 @@ export declare function maskOldToolResults(messages: ModelMessage[], opts: MaskO
 export interface StepMaskerOptions extends MaskOptions {
     /** Start masking when the next prompt is at least this many tokens. */
     softBudgetTokens: number;
+    /** The newest tool output, up to this many tokens, is never masked (Kilo protects 40k). Default 40,000. */
+    protectTokens?: number;
 }
+/** Default for {@link StepMaskerOptions.protectTokens}. */
+export declare const MASK_PROTECT_TOKENS = 40000;
+/** Index from which the newest `protectTokens` of tool output starts: results at or after it are kept. */
+export declare function protectedFrom(messages: readonly ModelMessage[], protectTokens: number): number;
 export interface StepMasker {
     apply(messages: ModelMessage[], nextPromptTokens: number): MaskResult & {
         stepped: boolean;
@@ -36,10 +42,4 @@ export interface StepMasker {
     /** Forget the frozen boundary, for example after compaction replaced the history. */
     reset(): void;
 }
-/**
- * Masks in steps, not on every call. Many providers reuse a cached prompt prefix only while it is byte-identical, so
- * a boundary that slid forward on every turn would change the prefix on every call. Once the prompt reaches the soft
- * budget the boundary is set at the start of the recent window and held; it moves again only after at least
- * `keepRecentTurns` more turns have been added.
- */
 export declare function createStepMasker(opts: StepMaskerOptions): StepMasker;

package/dist/context/mask.js

@@ -1,3 +1,4 @@
+import { estimateMessageTokens } from './compaction.js';
 /** Results that say what a change did are kept: they are small and the model must not forget them. */
 export const NEVER_MASK_TOOLS = new Set(['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'run_command', 'sub_agent']);
 const STUB_MARK = 'result not shown to save context';
@@ -53,18 +54,46 @@ export function maskOldToolResults(messages, opts, upTo) {
     });
     return { messages: next, maskedCount, savedChars: Math.max(0, savedChars) };
 }
+/** Default for {@link StepMaskerOptions.protectTokens}. */
+export const MASK_PROTECT_TOKENS = 40_000;
+/** Index from which the newest `protectTokens` of tool output starts: results at or after it are kept. */
+export function protectedFrom(messages, protectTokens) {
+    let total = 0;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role !== 'tool')
+            continue;
+        total += estimateMessageTokens([messages[i]]);
+        if (total > protectTokens)
+            return i + 1;
+    }
+    return 0;
+}
 /**
  * Masks in steps, not on every call. Many providers reuse a cached prompt prefix only while it is byte-identical, so
  * a boundary that slid forward on every turn would change the prefix on every call. Once the prompt reaches the soft
  * budget the boundary is set at the start of the recent window and held; it moves again only after at least
  * `keepRecentTurns` more turns have been added.
  */
+/** Index just after the last message that holds a stub (0 when none). */
+function afterLastStub(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m.role !== 'tool' || !Array.isArray(m.content))
+            continue;
+        if (m.content.some((p) => p?.output && isAlreadyStub(p.output)))
+            return i + 1;
+    }
+    return 0;
+}
 export function createStepMasker(opts) {
     let frozenUpTo = 0;
     const minAdvance = opts.keepRecentTurns * 2;
     return {
         apply(messages, nextPromptTokens) {
-            const boundary = maskBoundary(messages, opts.keepRecentTurns);
+            // A history masked on an earlier turn: start from its stubs, so this turn does not move the boundary at once.
+            if (frozenUpTo === 0)
+                frozenUpTo = afterLastStub(messages);
+            const boundary = Math.min(maskBoundary(messages, opts.keepRecentTurns), protectedFrom(messages, opts.protectTokens ?? MASK_PROTECT_TOKENS));
             const stepped = nextPromptTokens >= opts.softBudgetTokens && boundary > frozenUpTo && (frozenUpTo === 0 || boundary - frozenUpTo >= minAdvance);
             if (stepped)
                 frozenUpTo = boundary;

package/dist/format/auto-format.d.ts

@@ -0,0 +1,22 @@
+import type { ToolContext } from '../types.js';
+export interface AutoFormatConfig {
+    /**
+     * Formatter commands by file extension (`"ts"`, no dot) with `"*"` for any other file. The edited file's path
+     * is appended and the command must rewrite the file in place (`prettier --write`, `gofmt -w`).
+     */
+    commands: Record<string, string>;
+    /** Per-command timeout. Default 60s. */
+    timeoutMs?: number;
+}
+export interface FormatReport {
+    /** A command was configured for this file and was started. */
+    ran: boolean;
+    /** The file's content differs from before the command. */
+    changed: boolean;
+    /** The command's own words when it failed or timed out. */
+    failed?: string;
+}
+/** Format one edited file. Never throws: a formatter that cannot run is reported in `failed`. */
+export declare function formatFile(relPath: string, config: AutoFormatConfig, ctx: ToolContext): Promise<FormatReport>;
+/** The note appended to the tool result, or '' when there is nothing to say. */
+export declare function formatMessage(relPath: string, report: FormatReport): string;

package/dist/format/auto-format.js

@@ -0,0 +1,39 @@
+/**
+ * Auto-format: after the agent writes a file, run the formatter the person configured for that file type, so the
+ * project's style is kept without spending a step on it. The formatter rewrites the file, so the tool result tells
+ * the model (`formatMessage`): the text it just wrote is no longer what is on disk.
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { commandFor, shellQuote } from '../lint/auto-lint.js';
+import { runCommandTool } from '../tools/run-command.js';
+const DEFAULT_TIMEOUT_MS = 60_000;
+const MAX_FAILURE_CHARS = 500;
+/** Format one edited file. Never throws: a formatter that cannot run is reported in `failed`. */
+export async function formatFile(relPath, config, ctx) {
+    const command = commandFor(relPath, config.commands);
+    if (!command)
+        return { ran: false, changed: false };
+    const abs = path.resolve(ctx.cwd, relPath);
+    const before = await readFile(abs).catch(() => null);
+    try {
+        const res = await runCommandTool.execute({ command: `${command} ${shellQuote(relPath)}`, timeout_ms: config.timeoutMs ?? DEFAULT_TIMEOUT_MS }, ctx);
+        if (res.exitCode !== 0 || res.timedOut) {
+            const out = [res.stdout, res.stderr].filter(Boolean).join('\n').trim();
+            return { ran: true, changed: false, failed: `${res.timedOut ? '(timed out) ' : ''}${out.slice(-MAX_FAILURE_CHARS) || `exit code ${res.exitCode}`}` };
+        }
+    }
+    catch (err) {
+        return { ran: true, changed: false, failed: err.message.slice(0, MAX_FAILURE_CHARS) };
+    }
+    const after = await readFile(abs).catch(() => null);
+    return { ran: true, changed: before !== null && after !== null && !before.equals(after) };
+}
+/** The note appended to the tool result, or '' when there is nothing to say. */
+export function formatMessage(relPath, report) {
+    if (report.failed)
+        return `[auto-format] The formatter failed on ${relPath}, so it was left as written:\n${report.failed}`;
+    if (report.changed)
+        return `[auto-format] The formatter reformatted ${relPath} after your edit. Read it again before editing it with edit_file, because the text on disk may differ from what you wrote.`;
+    return '';
+}

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, instruction?: string): string;
+export declare function commitMessagePrompt(diff: string, task?: string, instruction?: string, language?: 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, instruction?: string): Promise<string>;
+export declare function generateCommitMessage(diff: string, files: string[], model: ModelConfig | undefined, task?: string, modelFactory?: (cfg: ModelConfig) => LanguageModel, instruction?: string, language?: string): Promise<string>;
 export type UndoResult = {
     ok: true;
     commit: string;
@@ -60,4 +60,6 @@ export declare function afterRun(cwd: string, state: {
     model?: ModelConfig;
     task?: string;
     modelFactory?: (cfg: ModelConfig) => LanguageModel;
+    instruction?: string;
+    language?: string;
 }): Promise<ForgeCommit | null>;

package/dist/git/auto-commit.js

@@ -6,6 +6,7 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { generateText } from 'ai';
+import { withModelRetry } from '../agent/retry.js';
 import { stripThinkTags } from '../agent/think-tags.js';
 import { createLanguageModel } from '../providers.js';
 const execFileAsync = promisify(execFile);
@@ -112,10 +113,20 @@ export function fallbackCommitMessage(files) {
     return `forge: update ${shown}${more}`;
 }
 const MAX_DIFF_CHARS = 12_000;
-export function commitMessagePrompt(diff, task, instruction) {
+const MAX_LANGUAGE_CHARS = 40;
+/** One short line for the prompt, or '' when English or unset. The value is typed by a person and goes into a model prompt. */
+function languageLine(language) {
+    const lang = (language ?? '').replace(/\s+/g, ' ').trim().slice(0, MAX_LANGUAGE_CHARS).trim();
+    if (!lang || /^(english|en)$/i.test(lang))
+        return '';
+    return `
+
+Write the commit message in ${lang}.`;
+}
+export function commitMessagePrompt(diff, task, instruction, language) {
     const clipped = diff.length > MAX_DIFF_CHARS ? `${diff.slice(0, MAX_DIFF_CHARS)}\n[diff truncated]` : diff;
     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}`;
+    return `${lead}${languageLine(language)}${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) {
@@ -126,11 +137,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, instruction) {
+export async function generateCommitMessage(diff, files, model, task, modelFactory = createLanguageModel, instruction, language) {
     if (!model || !diff.trim())
         return fallbackCommitMessage(files);
     try {
-        const result = await generateText({ model: modelFactory(model), prompt: commitMessagePrompt(diff, task, instruction) });
+        const result = await withModelRetry(() => generateText({ model: modelFactory(model), prompt: commitMessagePrompt(diff, task, instruction, language), maxRetries: 0 }), { maxRetries: 2 });
         const message = cleanCommitMessage(result.text);
         return message || fallbackCommitMessage(files);
     }
@@ -181,6 +192,6 @@ export async function afterRun(cwd, state, options) {
     if (files.length === 0)
         return null;
     const diff = await diffForFiles(cwd, files);
-    const message = await generateCommitMessage(diff, files, options.model, options.task, options.modelFactory);
+    const message = await generateCommitMessage(diff, files, options.model, options.task, options.modelFactory, options.instruction, options.language);
     return commitFiles(cwd, files, message, options);
 }

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

@@ -17,6 +17,7 @@ export declare function githubFromEnv(env?: NodeJS.ProcessEnv): GitHubConfig | u
 export declare function parseRemote(url: string): RepoRef | null;
 export declare function repoFor(cwd: string): Promise<RepoRef>;
 export declare function currentBranch(cwd: string): Promise<string>;
+export declare function githubApi(cfg: GitHubConfig, repo: RepoRef, method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<unknown>;
 export interface PullRequestReport {
     number: number;
     title: string;

package/dist/github/github-tools.js

@@ -59,7 +59,7 @@ function clip(text, max) {
     const s = typeof text === 'string' ? text : '';
     return s.length > max ? `${s.slice(0, max)}… (${s.length - max} more characters)` : s;
 }
-async function api(cfg, repo, method, path, body, signal) {
+export async function githubApi(cfg, repo, method, path, body, signal) {
     const res = await (cfg.fetch ?? fetch)(`${repo.apiBase}${path}`, {
         method,
         headers: {
@@ -95,20 +95,20 @@ export function createGitHubReadTool(cfg) {
             let number = args.number;
             if (number === undefined) {
                 const branch = await currentBranch(ctx.cwd);
-                const open = (await api(cfg, repo, 'GET', `${base}/pulls?state=open&head=${encodeURIComponent(`${repo.owner}:${branch}`)}`, undefined, ctx.abortSignal));
+                const open = (await githubApi(cfg, repo, 'GET', `${base}/pulls?state=open&head=${encodeURIComponent(`${repo.owner}:${branch}`)}`, undefined, ctx.abortSignal));
                 if (!Array.isArray(open) || open.length === 0)
                     throw new Error(`no open pull request for branch ${branch}`);
                 number = open[0].number;
             }
-            const pr = (await api(cfg, repo, 'GET', `${base}/pulls/${number}`, undefined, ctx.abortSignal));
+            const pr = (await githubApi(cfg, repo, 'GET', `${base}/pulls/${number}`, undefined, ctx.abortSignal));
             const [reviews, comments, discussion] = (await Promise.all([
-                api(cfg, repo, 'GET', `${base}/pulls/${number}/reviews?per_page=${LIST_MAX}`, undefined, ctx.abortSignal),
-                api(cfg, repo, 'GET', `${base}/pulls/${number}/comments?per_page=${LIST_MAX}`, undefined, ctx.abortSignal),
-                api(cfg, repo, 'GET', `${base}/issues/${number}/comments?per_page=${LIST_MAX}`, undefined, ctx.abortSignal),
+                githubApi(cfg, repo, 'GET', `${base}/pulls/${number}/reviews?per_page=${LIST_MAX}`, undefined, ctx.abortSignal),
+                githubApi(cfg, repo, 'GET', `${base}/pulls/${number}/comments?per_page=${LIST_MAX}`, undefined, ctx.abortSignal),
+                githubApi(cfg, repo, 'GET', `${base}/issues/${number}/comments?per_page=${LIST_MAX}`, undefined, ctx.abortSignal),
             ]));
             const sha = pr.head?.sha;
             const checks = sha
-                ? (await api(cfg, repo, 'GET', `${base}/commits/${sha}/check-runs?per_page=${LIST_MAX}`, undefined, ctx.abortSignal).catch(() => ({ check_runs: [] })))
+                ? (await githubApi(cfg, repo, 'GET', `${base}/commits/${sha}/check-runs?per_page=${LIST_MAX}`, undefined, ctx.abortSignal).catch(() => ({ check_runs: [] })))
                     .check_runs
                 : [];
             return {
@@ -153,11 +153,11 @@ export function createGitHubCreateTool(cfg) {
             const repo = await repoFor(ctx.cwd);
             const base = `/repos/${repo.owner}/${repo.repo}`;
             const head = args.head ?? (await currentBranch(ctx.cwd));
-            const into = args.base ?? (await api(cfg, repo, 'GET', base, undefined, ctx.abortSignal)).default_branch;
+            const into = args.base ?? (await githubApi(cfg, repo, 'GET', base, undefined, ctx.abortSignal)).default_branch;
             if (head === into)
                 throw new Error(`the head branch is the base branch (${head}); work on a separate branch`);
             try {
-                const pr = (await api(cfg, repo, 'POST', `${base}/pulls`, { title: args.title, body: args.body, head, base: into, draft: args.draft ?? true }, ctx.abortSignal));
+                const pr = (await githubApi(cfg, repo, 'POST', `${base}/pulls`, { title: args.title, body: args.body, head, base: into, draft: args.draft ?? true }, ctx.abortSignal));
                 return { number: pr.number, url: String(pr.html_url), draft: pr.draft === true };
             }
             catch (err) {

package/dist/github/pr.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pull-request status and creation for a branch (F8), on the REST layer the `github_pr_*` tools use. The host supplies the
+ * token (an environment variable or VS Code's GitHub sign-in); it goes in the Authorization header and nowhere else, so
+ * no error text built here may contain it.
+ */
+import { type GitHubConfig, type RepoRef } from './github-tools.js';
+export interface PullRequestSummary {
+    number: number;
+    url: string;
+    state: 'open' | 'merged' | 'closed';
+    draft: boolean;
+    /** All checks passed, one failed, some still run, or there are none. */
+    checks: 'passing' | 'failing' | 'pending' | 'none';
+    /** The latest review of each reviewer decides: any "changes requested" wins over an approval. */
+    review: 'approved' | 'changes requested' | 'none';
+}
+/** The newest pull request from `branch` (any state), summarized, or null when there is none. */
+export declare function findPullRequest(cfg: GitHubConfig, repo: RepoRef, branch: string, signal?: AbortSignal): Promise<PullRequestSummary | null>;
+/** The repository's default branch, the usual base for a pull request. */
+export declare function defaultBranch(cfg: GitHubConfig, repo: RepoRef, signal?: AbortSignal): Promise<string>;
+export interface NewPullRequest {
+    title: string;
+    body: string;
+    /** The branch with the changes; it must already be pushed. */
+    head: string;
+    base: string;
+    /** Default true: nobody is asked to review until the author says so. */
+    draft?: boolean;
+}
+export declare function openPullRequest(cfg: GitHubConfig, repo: RepoRef, input: NewPullRequest, signal?: AbortSignal): Promise<{
+    number: number;
+    url: string;
+    draft: boolean;
+}>;

package/dist/github/pr.js

@@ -0,0 +1,70 @@
+/**
+ * Pull-request status and creation for a branch (F8), on the REST layer the `github_pr_*` tools use. The host supplies the
+ * token (an environment variable or VS Code's GitHub sign-in); it goes in the Authorization header and nowhere else, so
+ * no error text built here may contain it.
+ */
+import { githubApi } from './github-tools.js';
+const FAILED = new Set(['failure', 'timed_out', 'cancelled', 'action_required', 'startup_failure']);
+function checksOf(runs) {
+    if (runs.length === 0)
+        return 'none';
+    if (runs.some((r) => r.status !== 'completed'))
+        return runs.some((r) => FAILED.has(String(r.conclusion))) ? 'failing' : 'pending';
+    return runs.some((r) => FAILED.has(String(r.conclusion))) ? 'failing' : 'passing';
+}
+function reviewOf(reviews) {
+    const latest = new Map();
+    for (const r of reviews) {
+        const state = String(r.state);
+        // A comment does not replace an earlier verdict.
+        if (state !== 'APPROVED' && state !== 'CHANGES_REQUESTED')
+            continue;
+        latest.set(String(r.user?.login ?? 'unknown'), state);
+    }
+    const states = [...latest.values()];
+    if (states.includes('CHANGES_REQUESTED'))
+        return 'changes requested';
+    return states.includes('APPROVED') ? 'approved' : 'none';
+}
+/** The newest pull request from `branch` (any state), summarized, or null when there is none. */
+export async function findPullRequest(cfg, repo, branch, signal) {
+    const base = `/repos/${repo.owner}/${repo.repo}`;
+    const found = (await githubApi(cfg, repo, 'GET', `${base}/pulls?state=all&head=${encodeURIComponent(`${repo.owner}:${branch}`)}&per_page=1`, undefined, signal));
+    const pr = Array.isArray(found) ? found[0] : undefined;
+    if (!pr)
+        return null;
+    const number = pr.number;
+    const sha = pr.head?.sha;
+    const [runs, reviews] = await Promise.all([
+        sha ? githubApi(cfg, repo, 'GET', `${base}/commits/${sha}/check-runs?per_page=50`, undefined, signal).catch(() => ({ check_runs: [] })) : { check_runs: [] },
+        githubApi(cfg, repo, 'GET', `${base}/pulls/${number}/reviews?per_page=50`, undefined, signal).catch(() => []),
+    ]);
+    return {
+        number,
+        url: String(pr.html_url ?? ''),
+        state: pr.merged_at ? 'merged' : pr.state === 'closed' ? 'closed' : 'open',
+        draft: pr.draft === true,
+        checks: checksOf(runs.check_runs ?? []),
+        review: reviewOf(Array.isArray(reviews) ? reviews : []),
+    };
+}
+/** The repository's default branch, the usual base for a pull request. */
+export async function defaultBranch(cfg, repo, signal) {
+    const data = (await githubApi(cfg, repo, 'GET', `/repos/${repo.owner}/${repo.repo}`, undefined, signal));
+    return String(data.default_branch ?? 'main');
+}
+export async function openPullRequest(cfg, repo, input, signal) {
+    if (input.head === input.base)
+        throw new Error(`the head branch is the base branch (${input.head}); work on a separate branch`);
+    try {
+        const pr = (await githubApi(cfg, repo, 'POST', `/repos/${repo.owner}/${repo.repo}/pulls`, { title: input.title, body: input.body, head: input.head, base: input.base, draft: input.draft ?? true }, signal));
+        return { number: pr.number, url: String(pr.html_url), draft: pr.draft === true };
+    }
+    catch (err) {
+        const msg = err.message;
+        if (/HTTP 422/.test(msg) && /head|not.*found|No commits|invalid/i.test(msg)) {
+            throw new Error(`${msg}. Is ${input.head} pushed and ahead of ${input.base}? Push it with: git push -u origin ${input.head}`);
+        }
+        throw err;
+    }
+}

package/dist/human-text.d.ts

@@ -0,0 +1,6 @@
+/** `max_iterations`, `perChat` and `on-network` become "Max iterations", "Per chat" and "On network". */
+export declare function humanize(id: string): string;
+/** The name of a tool as a person would say it. */
+export declare function toolLabel(name: string): string;
+/** Why a run ended, for a line a person reads. */
+export declare function runReasonLabel(reason: string): string;

package/dist/human-text.js

@@ -0,0 +1,37 @@
+const ACRONYMS = { mcp: 'MCP', api: 'API', url: 'URL', lsp: 'LSP', ai: 'AI', pr: 'PR', os: 'OS' };
+/** `max_iterations`, `perChat` and `on-network` become "Max iterations", "Per chat" and "On network". */
+export function humanize(id) {
+    const words = id
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[\s_-]+/)
+        .filter(Boolean)
+        .map((w) => w.toLowerCase());
+    if (words.length === 0)
+        return id;
+    const first = words[0];
+    words[0] = ACRONYMS[first] ?? first.charAt(0).toUpperCase() + first.slice(1);
+    for (let i = 1; i < words.length; i++)
+        words[i] = ACRONYMS[words[i]] ?? words[i];
+    return words.join(' ');
+}
+/** The name of a tool as a person would say it. */
+export function toolLabel(name) {
+    return humanize(name);
+}
+// A Record over the reason type: a new way for a run to end is a compile error until it has words here.
+const RUN_REASONS = {
+    completed: 'Completed',
+    max_iterations: 'Step limit reached',
+    max_duration: 'Time limit reached',
+    budget_exceeded: 'Cost limit reached',
+    loop_detected: 'Stopped: repeating the same step',
+    aborted: 'Stopped',
+    error: 'Failed',
+    no_provider_key: 'No API key',
+    plan: 'Plan ready',
+    spec: 'Spec ready',
+};
+/** Why a run ended, for a line a person reads. */
+export function runReasonLabel(reason) {
+    return RUN_REASONS[reason] ?? humanize(reason);
+}