@yagni-app/code-staging 0.0.0 → 0.1.0-staging.1002.1

package/dist/extension/chipEditor.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Chip-editor for image paste.
+ *
+ * Goal: pasting a screenshot into the `yagni` prompt should drop an inline
+ * `[Image #N]` chip at the cursor (like Claude Code), not a raw temp-file path.
+ *
+ * pi already implements cross-platform clipboard-image paste, but its default
+ * editor writes the image to a temp file and inserts the *path* as literal
+ * text. This module replaces the editor (via `ctx.ui.setEditorComponent`) with
+ * a `CustomEditor` subclass that owns the paste handler, stashes the image, and
+ * inserts a styled `[Image #N]` token as the text source-of-truth. An `input`
+ * transform (registered alongside) parses those tokens back into real
+ * `ImageContent[]` attachments so the image reaches the model.
+ *
+ * No fork, no patch: both the editor override and the input transform are
+ * first-class pi extension surfaces. The chip is a *styled text token* — the
+ * literal text is the source of truth, so undo/cursor/history and the
+ * chip→model mapping all share one string and can't desync.
+ *
+ * Validated against pi 0.83.0 (spike, 5/5): the subclass owns `onPasteImage`
+ * because `setCustomEditorComponent` only fills it when unset, and jiti aliases
+ * the extension's pi imports to the same module instance pi uses.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+import type { EditorOptions, EditorTheme, TUI } from "@earendil-works/pi-tui";
+export interface ClipboardImage {
+    bytes: Uint8Array;
+    mimeType: string;
+}
+/** Injectable clipboard-image reader seam (tests stub it; prod reads the OS). */
+export type ClipboardImageReader = () => Promise<ClipboardImage | null>;
+interface StashedImage {
+    n: number;
+    bytes: Uint8Array;
+    mimeType: string;
+}
+/** The attachment shape pi's `input` transform forwards to the model. */
+export interface ImageAttachment {
+    type: "image";
+    data: string;
+    mimeType: string;
+}
+/**
+ * If `data` is a complete bracketed-paste payload, return its inner content;
+ * otherwise null. pi's Terminal re-wraps every paste with these markers before
+ * the editor sees it, so a whole-payload match is the unambiguous paste signal.
+ */
+export declare function unwrapBracketedPaste(data: string): string | null;
+/**
+ * Recognize a pasted temp-image path written by a Ghostty-based terminal
+ * (cmux, Ghostty). Those terminals name the file `clipboard-<ts>-<id>.<ext>`
+ * in the system temp dir. We match strictly — clipboard- prefix, image
+ * extension, real file, and genuine image magic bytes — so a path the user
+ * typed by hand (e.g. /Users/me/photo.png) is never silently converted.
+ * Returns the decoded image, or null when the pasted text is not one such path.
+ */
+export declare function readPastedImagePath(pastedText: string): ClipboardImage | null;
+/**
+ * Read an image from the system clipboard without forking pi. Best-effort and
+ * cross-platform: native module if present, else osascript/pngpaste (macOS),
+ * wl-paste (Wayland), xclip (X11), PowerShell (Windows/WSL). Returns null when
+ * the clipboard holds no image (caller then pastes text instead).
+ */
+export declare const defaultClipboardImageReader: ClipboardImageReader;
+/**
+ * A CustomEditor that turns clipboard image paste into numbered `[Image #N]`
+ * chips. The image bytes live here, keyed by chip number; the editor text holds
+ * only the token, which is the durable, undo-friendly source of truth.
+ */
+export declare class ChipEditor extends CustomEditor {
+    private stashed;
+    private chipCounter;
+    private readImage;
+    constructor(tui: TUI, theme: EditorTheme, keybindings: ConstructorParameters<typeof CustomEditor>[2], readImage?: ClipboardImageReader, options?: EditorOptions);
+    /**
+     * Paste-image must fire on Cmd+V too (Claude Code parity on macOS). Claude
+     * Code's own approach is iTerm2-specific — "Cmd+V ... maps to Ctrl+V" — i.e.
+     * it relies on the terminal delivering Cmd+V AS Ctrl+V. We do the same: match
+     * ctrl+v + alt+v (win32/WSL) explicitly, and super+v only as a bonus for
+     * Kitty-protocol terminals that genuinely deliver the Cmd modifier.
+     */
+    handleInput(data: string): void;
+    private pasteChip;
+    private dropChip;
+    /** Every image stashed on this editor (used by the input transform). */
+    allStashed(): StashedImage[];
+    /** Drop all stashed images. Called after a successful submit so a sent image
+     * is not re-attached to the next message. */
+    clearStash(): void;
+    /** Re-style the chip tokens so they read as chips; layout is untouched. */
+    render(width: number): string[];
+}
+/**
+ * Build the `input` transform handler: parse `[Image #N]` markers in the
+ * submitted text into `ImageAttachment[]` for the model. Unknown/removed chip
+ * numbers are ignored (the image was deleted from the prompt), and a prompt
+ * with no live chips passes through untouched.
+ */
+export declare function makeChipInputTransform(getImages: () => StashedImage[]): (event: {
+    text: string;
+    images?: unknown;
+}) => {
+    action: "transform";
+    text: string;
+    images: ImageAttachment[];
+} | {
+    action: "continue";
+};
+/**
+ * Register the chip editor + the input transform on a session. Called on
+ * `session_start` in TUI mode. The factory registers each constructed editor in
+ * the shared registry; the transform reads the union of live editors' stashes.
+ */
+export declare function registerChipEditor(pi: ExtensionAPI): void;
+export {};
+//# sourceMappingURL=chipEditor.d.ts.map

package/dist/extension/chipEditor.js

@@ -0,0 +1,369 @@
+/**
+ * Chip-editor for image paste.
+ *
+ * Goal: pasting a screenshot into the `yagni` prompt should drop an inline
+ * `[Image #N]` chip at the cursor (like Claude Code), not a raw temp-file path.
+ *
+ * pi already implements cross-platform clipboard-image paste, but its default
+ * editor writes the image to a temp file and inserts the *path* as literal
+ * text. This module replaces the editor (via `ctx.ui.setEditorComponent`) with
+ * a `CustomEditor` subclass that owns the paste handler, stashes the image, and
+ * inserts a styled `[Image #N]` token as the text source-of-truth. An `input`
+ * transform (registered alongside) parses those tokens back into real
+ * `ImageContent[]` attachments so the image reaches the model.
+ *
+ * No fork, no patch: both the editor override and the input transform are
+ * first-class pi extension surfaces. The chip is a *styled text token* — the
+ * literal text is the source of truth, so undo/cursor/history and the
+ * chip→model mapping all share one string and can't desync.
+ *
+ * Validated against pi 0.83.0 (spike, 5/5): the subclass owns `onPasteImage`
+ * because `setCustomEditorComponent` only fills it when unset, and jiti aliases
+ * the extension's pi imports to the same module instance pi uses.
+ */
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+import { matchesKey } from "@earendil-works/pi-tui";
+import { spawnSync } from "node:child_process";
+import { readFileSync, unlinkSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, basename } from "node:path";
+import { randomUUID } from "node:crypto";
+import { logImagePaste } from "./diagnostics.js";
+/** Matches the `[Image #N]` chip token in the editor text. */
+const CHIP_RE = /\[Image #(\d+)\]/g;
+/** Inverse-video wrap so the chip token reads as a chip, not plain text. */
+const CHIP_ON = "";
+const CHIP_OFF = "";
+const PASTE_START = "\x1b[200~";
+const PASTE_END = "\x1b[201~";
+/**
+ * If `data` is a complete bracketed-paste payload, return its inner content;
+ * otherwise null. pi's Terminal re-wraps every paste with these markers before
+ * the editor sees it, so a whole-payload match is the unambiguous paste signal.
+ */
+export function unwrapBracketedPaste(data) {
+    if (!data.startsWith(PASTE_START) || !data.endsWith(PASTE_END))
+        return null;
+    return data.slice(PASTE_START.length, data.length - PASTE_END.length);
+}
+const IMAGE_EXT_MIME = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    bmp: "image/bmp",
+    tiff: "image/tiff",
+    tif: "image/tiff",
+};
+// PNG/JPEG/GIF/WEBP magic bytes, so we only convert a path that is genuinely a
+// decodable image — never a same-named text file or a path the user typed.
+const IMAGE_MAGIC = [
+    [[0x89, 0x50, 0x4e, 0x47], "image/png"],
+    [[0xff, 0xd8, 0xff], "image/jpeg"],
+    [[0x47, 0x49, 0x46, 0x38], "image/gif"], // GIF8
+    [[0x52, 0x49, 0x46, 0x46], "image/webp"], // RIFF (webp container)
+];
+/**
+ * Recognize a pasted temp-image path written by a Ghostty-based terminal
+ * (cmux, Ghostty). Those terminals name the file `clipboard-<ts>-<id>.<ext>`
+ * in the system temp dir. We match strictly — clipboard- prefix, image
+ * extension, real file, and genuine image magic bytes — so a path the user
+ * typed by hand (e.g. /Users/me/photo.png) is never silently converted.
+ * Returns the decoded image, or null when the pasted text is not one such path.
+ */
+export function readPastedImagePath(pastedText) {
+    const trimmed = pastedText.trim();
+    if (trimmed.includes("\n") || trimmed.includes(" "))
+        return null; // one token only
+    // Validate the RAW input first: an attacker could smuggle the `clipboard-`
+    // prefix through backslash escapes (e.g. `\c\l\i\p\b\o\a\r\d-`), so we
+    // must confirm the un-escaped form is a well-formed tmp image path before any
+    // unescaping or path resolution. cmux tmp paths contain no escapable chars
+    // (no spaces/metacharacters), so a legitimate paste has NO backslashes at all.
+    if (trimmed.includes("\\"))
+        return null; // escapes => not a plain cmux tmp path
+    const path = trimmed;
+    if (!path.startsWith("/"))
+        return null;
+    const name = basename(path);
+    if (!name.startsWith("clipboard-"))
+        return null;
+    const ext = name.split(".").pop()?.toLowerCase() ?? "";
+    if (!(ext in IMAGE_EXT_MIME))
+        return null;
+    if (!existsSync(path))
+        return null;
+    let bytes;
+    try {
+        bytes = readFileSync(path);
+    }
+    catch {
+        return null;
+    }
+    if (bytes.length === 0)
+        return null;
+    for (const [magic, mime] of IMAGE_MAGIC) {
+        if (magic.every((b, i) => bytes[i] === b))
+            return { bytes, mimeType: mime };
+    }
+    return null;
+}
+/**
+ * Read an image from the system clipboard without forking pi. Best-effort and
+ * cross-platform: native module if present, else osascript/pngpaste (macOS),
+ * wl-paste (Wayland), xclip (X11), PowerShell (Windows/WSL). Returns null when
+ * the clipboard holds no image (caller then pastes text instead).
+ */
+export const defaultClipboardImageReader = async () => {
+    const platform = process.platform;
+    try {
+        if (platform === "darwin") {
+            return readMacClipboardImage();
+        }
+        if (platform === "linux") {
+            return readLinuxClipboardImage();
+        }
+        if (platform === "win32") {
+            return readWindowsClipboardImage();
+        }
+    }
+    catch {
+        // Fall through — a clipboard read failure must never break the prompt.
+    }
+    return null;
+};
+function runBase64(command, args, timeoutMs = 3000) {
+    const res = spawnSync(command, args, { timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 });
+    if (res.error || res.status !== 0)
+        return null;
+    const out = Buffer.isBuffer(res.stdout) ? res.stdout : Buffer.from(res.stdout ?? "");
+    return out.length > 0 ? out : null;
+}
+function readMacClipboardImage() {
+    // pngpaste writes the clipboard image to a PNG file (cleanest on macOS).
+    const dest = join(tmpdir(), `yagni-clip-${randomUUID()}.png`);
+    try {
+        const res = spawnSync("pngpaste", [dest], { timeout: 3000 });
+        if (res.error || res.status !== 0)
+            return null;
+        const bytes = readFileSync(dest);
+        return bytes.length > 0 ? { bytes, mimeType: "image/png" } : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        try {
+            unlinkSync(dest);
+        }
+        catch {
+            /* best effort */
+        }
+    }
+}
+function readLinuxClipboardImage() {
+    // Wayland: list types, prefer a supported image type, then read it.
+    const types = runBase64("wl-paste", ["--list-types"], 1000);
+    if (types) {
+        const list = types.toString("utf8").split(/\r?\n/).map((t) => t.trim());
+        const preferred = ["image/png", "image/jpeg", "image/webp", "image/gif"].find((t) => list.includes(t));
+        if (preferred) {
+            const data = runBase64("wl-paste", ["--type", preferred, "--no-newline"]);
+            if (data)
+                return { bytes: data, mimeType: preferred };
+        }
+    }
+    // X11 fallback.
+    const xclip = runBase64("xclip", ["-selection", "clipboard", "-t", "image/png", "-o"]);
+    return xclip ? { bytes: xclip, mimeType: "image/png" } : null;
+}
+function readWindowsClipboardImage() {
+    // PowerShell: get the clipboard image and emit it as base64 PNG.
+    const script = "Add-Type -AssemblyName System.Windows.Forms,System.Drawing;" +
+        "$i=[System.Windows.Forms.Clipboard]::GetImage();" +
+        "if($i -eq $null){exit 1};" +
+        "$ms=New-Object System.IO.MemoryStream;" +
+        "$i.Save($ms,[System.Drawing.Imaging.ImageFormat]::Png);" +
+        "[Console]::Out.Write([Convert]::ToBase64String($ms.ToArray()))";
+    const out = runBase64("powershell", ["-NoProfile", "-NonInteractive", "-Command", script], 5000);
+    if (!out)
+        return null;
+    const b64 = out.toString("utf8").trim();
+    if (!b64)
+        return null;
+    return { bytes: Buffer.from(b64, "base64"), mimeType: "image/png" };
+}
+/**
+ * A CustomEditor that turns clipboard image paste into numbered `[Image #N]`
+ * chips. The image bytes live here, keyed by chip number; the editor text holds
+ * only the token, which is the durable, undo-friendly source of truth.
+ */
+export class ChipEditor extends CustomEditor {
+    stashed = [];
+    chipCounter = 0;
+    readImage;
+    constructor(tui, theme, keybindings, readImage = defaultClipboardImageReader, options) {
+        super(tui, theme, keybindings, options);
+        this.readImage = readImage;
+        // Own the paste handler. pi's setCustomEditorComponent only fills
+        // onPasteImage when unset, so this assignment wins over pi's default.
+        this.onPasteImage = () => void this.pasteChip();
+    }
+    /**
+     * Paste-image must fire on Cmd+V too (Claude Code parity on macOS). Claude
+     * Code's own approach is iTerm2-specific — "Cmd+V ... maps to Ctrl+V" — i.e.
+     * it relies on the terminal delivering Cmd+V AS Ctrl+V. We do the same: match
+     * ctrl+v + alt+v (win32/WSL) explicitly, and super+v only as a bonus for
+     * Kitty-protocol terminals that genuinely deliver the Cmd modifier.
+     */
+    handleInput(data) {
+        // Cmd+V on Ghostty-based terminals (cmux, Ghostty): the terminal writes the
+        // clipboard image to a temp file and pastes its PATH as bracketed text, so
+        // the payload arrives here as "\x1b[200~<path>\x1b[201~" (pi's Terminal
+        // re-wraps it). handlePaste is private and consumed inside super.handleInput,
+        // so we strip the markers here and convert a bare image path to a chip.
+        const unwrapped = unwrapBracketedPaste(data);
+        if (unwrapped !== null) {
+            const image = readPastedImagePath(unwrapped);
+            logImagePaste({
+                event: "paste_path",
+                outcome: image ? "ok" : "passthrough",
+                mimeType: image?.mimeType,
+                bytes: image?.bytes.length,
+                file: image ? unwrapped : undefined,
+                detail: image ? undefined : `not a lone image path: ${unwrapped.slice(0, 60)}`,
+            });
+            if (image) {
+                this.dropChip(image.bytes, image.mimeType);
+                return;
+            }
+            // Not a lone image path — re-wrap and let pi handle the paste normally.
+            super.handleInput(data);
+            return;
+        }
+        // iTerm2 / Terminal.app: Cmd+V arrives as the raw Ctrl+V bytes.
+        if (matchesKey(data, "ctrl+v") || matchesKey(data, "alt+v") || matchesKey(data, "super+v")) {
+            this.onPasteImage?.();
+            return;
+        }
+        super.handleInput(data);
+    }
+    async pasteChip() {
+        const image = await this.readImage().catch(() => null);
+        logImagePaste({
+            event: "paste_key",
+            outcome: image ? "ok" : "passthrough",
+            mimeType: image?.mimeType,
+            bytes: image?.bytes.length,
+            detail: image ? undefined : "clipboard held no image",
+        });
+        if (!image)
+            return; // no image on the clipboard — leave the prompt untouched
+        this.dropChip(image.bytes, image.mimeType);
+    }
+    dropChip(bytes, mimeType) {
+        const n = ++this.chipCounter;
+        this.stashed.push({ n, bytes, mimeType });
+        logImagePaste({ event: "chip_drop", outcome: "ok", mimeType, bytes: bytes.length, imageCount: n });
+        this.insertTextAtCursor(`[Image #${n}]`);
+    }
+    /** Every image stashed on this editor (used by the input transform). */
+    allStashed() {
+        return this.stashed;
+    }
+    /** Drop all stashed images. Called after a successful submit so a sent image
+     * is not re-attached to the next message. */
+    clearStash() {
+        this.stashed = [];
+    }
+    /** Re-style the chip tokens so they read as chips; layout is untouched. */
+    render(width) {
+        return super
+            .render(width)
+            .map((line) => line.replace(CHIP_RE, (m) => `${CHIP_ON}${m}${CHIP_OFF}`));
+    }
+}
+/**
+ * Build the `input` transform handler: parse `[Image #N]` markers in the
+ * submitted text into `ImageAttachment[]` for the model. Unknown/removed chip
+ * numbers are ignored (the image was deleted from the prompt), and a prompt
+ * with no live chips passes through untouched.
+ */
+export function makeChipInputTransform(getImages) {
+    return (event) => {
+        const byN = new Map(getImages().map((s) => [s.n, s]));
+        const attached = [];
+        for (const m of event.text.matchAll(CHIP_RE)) {
+            const img = byN.get(Number(m[1]));
+            if (img) {
+                attached.push({
+                    type: "image",
+                    mimeType: img.mimeType,
+                    data: Buffer.from(img.bytes).toString("base64"),
+                });
+            }
+        }
+        if (attached.length === 0)
+            return { action: "continue" };
+        return { action: "transform", text: event.text, images: attached };
+    };
+}
+/**
+ * Every ChipEditor instance pi has live. pi may recreate the editor (session
+ * reset, restore-default, model switch), so the input transform must read from
+ * ALL live instances, not a single captured reference that can go stale. Each
+ * editor registers itself on construction. The registry holds each editor by
+ * weak reference so an orphaned editor (and its stashed image bytes) can be
+ * garbage-collected once pi drops it; dead refs are pruned on each read. A
+ * plain Set would leak them across session resets / model switches.
+ */
+const liveChipEditors = new Set();
+/** Live editors with dead weak refs pruned. */
+function currentChipEditors() {
+    const live = [];
+    for (const ref of liveChipEditors) {
+        const editor = ref.deref();
+        if (editor)
+            live.push(editor);
+        else
+            liveChipEditors.delete(ref);
+    }
+    return live;
+}
+/**
+ * Register the chip editor + the input transform on a session. Called on
+ * `session_start` in TUI mode. The factory registers each constructed editor in
+ * the shared registry; the transform reads the union of live editors' stashes.
+ */
+export function registerChipEditor(pi) {
+    pi.on("session_start", (_event, ctx) => {
+        if (ctx.mode !== "tui" || !ctx.hasUI)
+            return;
+        ctx.ui.setEditorComponent((tui, theme, keybindings) => {
+            const editor = new ChipEditor(tui, theme, keybindings);
+            liveChipEditors.add(new WeakRef(editor));
+            return editor;
+        });
+    });
+    pi.on("input", (event) => {
+        // pi clears the editor (getText() === "") before emitting `input`, so the
+        // transform must match chip markers against the EVENT text, not the editor.
+        // Union every live editor's stash and resolve markers by chip number.
+        const editors = currentChipEditors();
+        const stashed = editors.flatMap((e) => e.allStashed());
+        const result = makeChipInputTransform(() => stashed)(event);
+        // A successful transform means the images were handed to the model; clear
+        // the stash so they are not re-attached to the next message.
+        if (result.action === "transform")
+            editors.forEach((e) => e.clearStash());
+        logImagePaste({
+            event: "transform",
+            outcome: result.action === "transform" ? "ok" : "passthrough",
+            imageCount: result.action === "transform" ? result.images.length : 0,
+            detail: `stashed=${stashed.length} action=${result.action}`,
+        });
+        return result;
+    });
+}
+//# sourceMappingURL=chipEditor.js.map

package/dist/extension/config.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Configuration + catalog-fetch helpers for the YAGNI pi extension.
+ *
+ * `YAGNI_BASE_URL` and `YAGNI_TOKEN` are read from the process environment,
+ * which the `yagni` launcher is responsible for populating. `YAGNI_CODE_DEBUG`
+ * (any truthy value) is an optional operator switch that surfaces fail-soft
+ * diagnostics on stderr, e.g. why a /go run could not be recorded (HTTP status +
+ * a token-free body excerpt); off by default and never required.
+ */
+/** A single model entry as returned by the YAGNI backend catalog endpoint. */
+export interface ModelEntry {
+    id: string;
+    name: string;
+    reasoning: boolean;
+    contextWindow: number;
+    maxTokens: number;
+    /**
+     * Supported input modalities for this tier. Catalog-driven so a vision-capable
+     * tier can receive images with no pi change (pi does the image plumbing via
+     * ProviderModelConfig.input). Optional; defaults to text-only when absent.
+     */
+    input?: ("text" | "image")[];
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+}
+/**
+ * Resolve the YAGNI backend base URL from the environment.
+ *
+ * Falls back to {@link DEFAULT_BASE_URL}, trims whitespace, and strips a single
+ * trailing slash so callers can safely append paths.
+ */
+export declare function resolveBaseUrl(env?: NodeJS.ProcessEnv): string;
+/** Read the bearer token used to authenticate with the YAGNI backend. */
+export declare function getToken(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Read the workspace id the token is bound to, forwarded by the launcher as
+ * `YAGNI_WORKSPACE_ID` (from the stored credentials). Used to key the one-time
+ * init-pass marker ({@link initDone}). Absent on older logins (treated as
+ * unknown → the marker gate degrades to freshness-only, still fail-closed).
+ */
+export declare function getWorkspaceId(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * Read the token's ISO expiry, forwarded by the launcher as
+ * `YAGNI_TOKEN_EXPIRES_AT`. Absent on older logins (treated as unknown).
+ */
+export declare function getTokenExpiresAt(env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * How close to expiry the token can be before the session-start notice fires.
+ * A long session can outlive its token, so a single heads-up lets the user
+ * re-login before completions and grounding tools start 401-ing mid-flight.
+ */
+export declare const EXPIRY_NOTICE_THRESHOLD_MS: number;
+/** A one-line expiry notice to surface at session start, or null when none. */
+export interface ExpiryNotice {
+    message: string;
+    type: "warning" | "error";
+}
+/**
+ * Pure helper: given the token's ISO expiry and the current time, return the
+ * notice to surface at session start, or null when there is nothing to say
+ * (missing/unparseable expiry, or comfortably valid). Never throws. This only
+ * reads the expiry; it never refreshes the token (no new auth surface).
+ */
+export declare function tokenExpiryNotice(expiresAt: string | undefined, nowMs: number, thresholdMs?: number): ExpiryNotice | null;
+/** Options for {@link fetchCatalog}. */
+export interface FetchCatalogOptions {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Fetch the YAGNI model catalog at startup.
+ *
+ * @throws an actionable Error (mentioning `yagni login`) on any non-2xx
+ * response so the launcher can surface a clear re-authentication prompt.
+ */
+export declare function fetchCatalog(opts: FetchCatalogOptions): Promise<ModelEntry[]>;
+/** The startup company brief returned by GET /api/yagni-code/context. */
+export interface ContextBrief {
+    brief: string;
+    sources: Array<{
+        title: string;
+        url: string;
+    }>;
+    /**
+     * Judgment-corpus sizes (additive; §2). Absent on older backends. The
+     * extension skips ambient recall entirely when `counts.decisions < 3`.
+     */
+    counts?: {
+        decisions: number;
+        corrections: number;
+    };
+}
+/** Options for {@link fetchContextBrief}. */
+export interface FetchContextBriefOptions {
+    baseUrl: string;
+    getToken: () => string | undefined;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Fetch the workspace company brief at startup.
+ *
+ * Unlike {@link fetchCatalog}, this is BEST-EFFORT: a missing or failed brief
+ * must never block the agent (it still works, just without boot-time grounding).
+ * Returns `null` on any non-2xx response or network error.
+ */
+export declare function fetchContextBrief(opts: FetchContextBriefOptions): Promise<ContextBrief | null>;
+//# sourceMappingURL=config.d.ts.map