@nanhara/hara 0.0.1 → 0.33.0

package/dist/config.js

@@ -0,0 +1,114 @@
+import { homedir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+const PROVIDER_DEFAULTS = {
+    anthropic: { model: "claude-opus-4-8", envKey: "ANTHROPIC_API_KEY" },
+    qwen: {
+        model: "qwen-plus",
+        baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        envKey: "DASHSCOPE_API_KEY",
+    },
+    "qwen-oauth": { model: "coder-model", envKey: "QWEN_OAUTH_TOKEN" },
+    openai: { model: "gpt-4o-mini", envKey: "OPENAI_API_KEY" },
+};
+export const CONFIG_KEYS = ["provider", "apiKey", "model", "baseURL", "approval", "sandbox", "theme", "evolve", "assetCapture", "computerUse", "computerApps", "visionModel", "visionBaseURL", "visionApiKey", "embedProvider", "embedModel", "embedBaseURL", "embedApiKey"];
+export const APPROVAL_MODES = ["suggest", "auto-edit", "full-auto"];
+export const SANDBOX_MODES = ["off", "workspace-write", "read-only"];
+const PROJECT_ROOT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".hg"];
+export function configPath() {
+    return join(homedir(), ".hara", "config.json");
+}
+export function readRawConfig() {
+    const p = configPath();
+    if (!existsSync(p))
+        return {};
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Nearest project override `.hara/config.json`, searching cwd up to the repo root. */
+function readProjectConfig(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const p = join(dir, ".hara", "config.json");
+        if (existsSync(p)) {
+            try {
+                return JSON.parse(readFileSync(p, "utf8"));
+            }
+            catch {
+                return {};
+            }
+        }
+        if (PROJECT_ROOT_MARKERS.some((m) => existsSync(join(dir, m))))
+            break; // stop at repo root
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return {};
+}
+export function writeConfigValue(key, value) {
+    const p = configPath();
+    const cfg = readRawConfig();
+    cfg[key] = value;
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+/** Record (or clear, with cap=null) a confirmed per-model vision capability in `modelVision`. */
+export function setModelVisionOverride(model, cap) {
+    const p = configPath();
+    const cfg = readRawConfig();
+    const map = cfg.modelVision && typeof cfg.modelVision === "object" ? cfg.modelVision : {};
+    if (cap === null)
+        delete map[model];
+    else
+        map[model] = cap;
+    cfg.modelVision = map;
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+/**
+ * Effective config. Precedence (high→low): env vars > selected profile >
+ * project `.hara/config.json` > global `~/.hara/config.json` > provider defaults.
+ */
+export function loadConfig(opts = {}) {
+    const global = readRawConfig();
+    const { profiles, ...globalBase } = global;
+    const project = readProjectConfig(process.cwd());
+    const profileName = process.env.HARA_PROFILE ?? opts.profile;
+    const profile = profileName && profiles && profiles[profileName] ? profiles[profileName] : {};
+    const merged = { ...globalBase, ...project, ...profile };
+    const provider = (process.env.HARA_PROVIDER ?? merged.provider ?? "anthropic");
+    const d = PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic;
+    const model = process.env.HARA_MODEL ?? merged.model ?? d.model;
+    const baseURL = process.env.HARA_BASE_URL ?? merged.baseURL ?? d.baseURL;
+    const apiKey = process.env.HARA_API_KEY ?? process.env[d.envKey] ?? merged.apiKey;
+    const approval = (process.env.HARA_APPROVAL ?? merged.approval ?? "suggest");
+    const sandbox = (process.env.HARA_SANDBOX ?? merged.sandbox ?? "off");
+    const theme = (process.env.HARA_THEME ?? merged.theme ?? "dark");
+    const evolve = (process.env.HARA_EVOLVE ?? merged.evolve ?? "proactive");
+    const assetCapture = (process.env.HARA_ASSET_CAPTURE ?? merged.assetCapture ?? "ask");
+    const computerUse = (process.env.HARA_COMPUTER_USE ?? merged.computerUse ?? "off");
+    const computerApps = String(process.env.HARA_COMPUTER_APPS ?? merged.computerApps ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    const visionModel = process.env.HARA_VISION_MODEL ?? merged.visionModel;
+    const visionBaseURL = process.env.HARA_VISION_BASE_URL ?? merged.visionBaseURL;
+    const visionApiKey = process.env.HARA_VISION_API_KEY ?? merged.visionApiKey;
+    const modelVision = merged.modelVision && typeof merged.modelVision === "object" ? merged.modelVision : {};
+    const embedProvider = (process.env.HARA_EMBED_PROVIDER ?? merged.embedProvider ?? "off");
+    const embedModel = process.env.HARA_EMBED_MODEL ?? merged.embedModel;
+    const embedBaseURL = process.env.HARA_EMBED_BASE_URL ?? merged.embedBaseURL;
+    const embedApiKey = process.env.HARA_EMBED_API_KEY ?? merged.embedApiKey;
+    const mcpServers = {
+        ...(globalBase.mcpServers ?? {}),
+        ...(project.mcpServers ?? {}),
+        ...(profile.mcpServers ?? {}),
+    };
+    return { provider, apiKey, model, baseURL, approval, sandbox, theme, evolve, assetCapture, computerUse, computerApps, visionModel, visionBaseURL, visionApiKey, modelVision, embedProvider, embedModel, embedBaseURL, embedApiKey, mcpServers, cwd: process.cwd() };
+}
+export function providerEnvKey(provider) {
+    return (PROVIDER_DEFAULTS[provider] ?? PROVIDER_DEFAULTS.anthropic).envKey;
+}

package/dist/context/agents-md.js

@@ -0,0 +1,64 @@
+// Project-context loading (AGENTS.md) — the cross-tool standard read by Codex/Claude Code/OpenClaw.
+// Walks up from cwd to the project root, concatenates AGENTS.md files, caps total size.
+import { readFileSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+const FILENAMES = ["AGENTS.override.md", "AGENTS.md"];
+const ROOT_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", ".hg"];
+const MAX_BYTES = 32 * 1024;
+export function findProjectRoot(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        if (ROOT_MARKERS.some((m) => existsSync(join(dir, m))))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return resolve(cwd); // no marker found → treat cwd as root
+        dir = parent;
+    }
+}
+/** Concatenate AGENTS.md files from project root down to cwd (root first), capped at 32 KiB. */
+export function loadAgentsMd(cwd) {
+    const root = findProjectRoot(cwd);
+    const chain = [];
+    let dir = resolve(cwd);
+    for (;;) {
+        chain.unshift(dir);
+        if (dir === root)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    const parts = [];
+    for (const d of chain) {
+        for (const name of FILENAMES) {
+            const p = join(d, name);
+            if (existsSync(p)) {
+                try {
+                    const txt = readFileSync(p, "utf8").trim();
+                    if (txt)
+                        parts.push(`<!-- ${name} @ ${d} -->\n${txt}`);
+                }
+                catch {
+                    /* ignore unreadable */
+                }
+            }
+        }
+    }
+    let combined = parts.join("\n\n--- project-doc ---\n\n");
+    if (Buffer.byteLength(combined, "utf8") > MAX_BYTES) {
+        combined = Buffer.from(combined, "utf8").subarray(0, MAX_BYTES).toString("utf8") + "\n…[truncated]";
+    }
+    return combined;
+}
+export function hasAgentsMd(cwd) {
+    const root = findProjectRoot(cwd);
+    return FILENAMES.some((n) => existsSync(join(root, n)));
+}
+/** Prompt hara runs against itself to analyze the repo and write AGENTS.md. */
+export const INIT_PROMPT = "Explore this repository to understand it, then write a concise AGENTS.md at the project root.\n" +
+    "Use read_file, bash (e.g. `ls`, `git ls-files`, `cat`), and write_file.\n" +
+    "AGENTS.md should cover: what the project is (1-2 sentences), the directory structure, key commands " +
+    "(build / test / run / lint), and important conventions. Keep it under ~150 lines.\n" +
+    "Create it with write_file at path 'AGENTS.md', then reply with a one-line confirmation.";

package/dist/context/mentions.js

@@ -0,0 +1,90 @@
+// @file mentions — expand `@path` references in user input into appended file contents,
+// and provide fuzzy file candidates for REPL tab-completion.
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { listProjectFiles, dirPrefixes, walkFiles } from "../fs-walk.js";
+import { fuzzyRank } from "../fuzzy.js";
+import { mediaTypeFor } from "../images.js";
+const MAX_FILE = 50_000;
+// @ at start-of-string or after whitespace; capture a path with no spaces/@ (avoids emails like a@b.com)
+const MENTION_RE = /(?:^|\s)@([^\s@]+)/g;
+/** Append the contents of any @mentioned files to the input as fenced blocks. */
+export function expandMentions(input, cwd) {
+    const seen = new Set();
+    const blocks = [];
+    let m;
+    MENTION_RE.lastIndex = 0;
+    while ((m = MENTION_RE.exec(input)) !== null) {
+        const ref = m[1];
+        if (seen.has(ref))
+            continue;
+        seen.add(ref);
+        const abs = isAbsolute(ref) ? ref : resolve(cwd, ref);
+        try {
+            if (existsSync(abs)) {
+                const st = statSync(abs);
+                if (st.isFile()) {
+                    if (mediaTypeFor(abs)) {
+                        // don't inline binary image bytes as text — paste it with Ctrl+V (or drag the file in) to attach visually
+                        blocks.push(`Referenced \`${ref}\` is an image — paste it with Ctrl+V to attach it visually.`);
+                    }
+                    else {
+                        let txt = readFileSync(abs, "utf8");
+                        if (txt.length > MAX_FILE)
+                            txt = txt.slice(0, MAX_FILE) + "\n…[truncated]";
+                        blocks.push(`Referenced file \`${ref}\`:\n\`\`\`\n${txt}\n\`\`\``);
+                    }
+                }
+                else if (st.isDirectory()) {
+                    // `@dir` loads a listing of the directory's files (the agent can then read specific ones)
+                    const files = walkFiles(abs, 300);
+                    blocks.push(`Referenced directory \`${ref}\` (${files.length} files):\n\`\`\`\n${files.join("\n") || "(empty)"}\n\`\`\``);
+                }
+            }
+        }
+        catch {
+            /* ignore unreadable mention */
+        }
+    }
+    return blocks.length ? `${input}\n\n${blocks.join("\n\n")}` : input;
+}
+// Short-lived per-cwd cache so Tab completion stays snappy without re-scanning every press.
+const cache = new Map();
+const CACHE_MS = 5000;
+function projectEntries(cwd) {
+    const hit = cache.get(cwd);
+    const now = Date.now();
+    if (hit && now - hit.at < CACHE_MS)
+        return hit.entries;
+    const files = listProjectFiles(cwd);
+    // files + their directory prefixes (so `@src/` drills into the subtree)
+    const entries = [...dirPrefixes(files), ...files];
+    cache.set(cwd, { at: now, entries });
+    return entries;
+}
+/**
+ * File/dir candidates whose path matches `query`, for @ autocomplete.
+ * Recurses subdirectories (git-tracked + untracked, or a filesystem walk outside git),
+ * ranks path-prefix and basename matches first. Directories carry a trailing `/`.
+ */
+export function fileCandidates(cwd, query, limit = 25) {
+    const entries = projectEntries(cwd);
+    if (!query) {
+        // bare `@`: top-level entries, directories first
+        const top = entries.filter((e) => !e.replace(/\/$/, "").includes("/"));
+        top.sort((a, b) => (b.endsWith("/") ? 1 : 0) - (a.endsWith("/") ? 1 : 0) || a.localeCompare(b));
+        return top.slice(0, limit);
+    }
+    // drilling: `@src/` → the immediate children of src/ (directories first), like a file picker
+    if (query.endsWith("/")) {
+        const kids = entries.filter((e) => e.startsWith(query) && e !== query && !e.slice(query.length).replace(/\/$/, "").includes("/"));
+        if (kids.length) {
+            kids.sort((a, b) => (b.endsWith("/") ? 1 : 0) - (a.endsWith("/") ? 1 : 0) || a.localeCompare(b));
+            return kids.slice(0, limit);
+        }
+    }
+    // fuzzy subsequence ranking — `@scr` finds `src/`, `@idx` finds `src/index.ts`
+    return fuzzyRank(query, entries, (e) => e)
+        .slice(0, limit)
+        .map((r) => r.item);
+}

package/dist/diff.js

@@ -0,0 +1,103 @@
+// Minimal zero-dependency line diff (LCS) + colored unified-style renderer.
+// Shown to the user after an edit so a coder sees exactly what changed.
+import { stdout } from "node:process";
+import { c } from "./ui.js";
+/** Longest-common-subsequence line diff. O(n*m) — guarded by a size cap in renderDiff. */
+function lcsDiff(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const dp = Array.from({ length: n + 1 }, () => new Int32Array(m + 1));
+    for (let i = n - 1; i >= 0; i--) {
+        for (let j = m - 1; j >= 0; j--) {
+            dp[i][j] = a[i] === b[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            out.push({ t: " ", s: a[i] });
+            i++;
+            j++;
+        }
+        else if (dp[i + 1][j] >= dp[i][j + 1]) {
+            out.push({ t: "-", s: a[i] });
+            i++;
+        }
+        else {
+            out.push({ t: "+", s: b[j] });
+            j++;
+        }
+    }
+    while (i < n)
+        out.push({ t: "-", s: a[i++] });
+    while (j < m)
+        out.push({ t: "+", s: b[j++] });
+    return out;
+}
+const CONTEXT = 2;
+const MAX_LINES = 80;
+const SIZE_CAP = 4000;
+/** Colored unified-style diff for display, with context collapsing + a hard cap. "" if unchanged. */
+export function renderDiff(path, oldText, newText) {
+    if (oldText === newText)
+        return "";
+    const a = oldText.length ? oldText.split("\n") : [];
+    const b = newText.length ? newText.split("\n") : [];
+    const adds = () => ops.filter((o) => o.t === "+").length;
+    const dels = () => ops.filter((o) => o.t === "-").length;
+    if (a.length > SIZE_CAP || b.length > SIZE_CAP) {
+        return c.dim(`◇ ${path}  (${a.length}→${b.length} lines; too large to diff)\n`);
+    }
+    const ops = lcsDiff(a, b);
+    // mark which lines to show: every change ± CONTEXT lines of surrounding context
+    const show = new Array(ops.length).fill(false);
+    ops.forEach((o, k) => {
+        if (o.t !== " ")
+            for (let d = -CONTEXT; d <= CONTEXT; d++)
+                if (ops[k + d])
+                    show[k + d] = true;
+    });
+    const lines = [c.dim(`◇ ${path}  ${c.green("+" + adds())} ${c.red("-" + dels())}`)];
+    let skipping = false;
+    let shown = 0;
+    for (let k = 0; k < ops.length; k++) {
+        if (!show[k]) {
+            if (!skipping) {
+                lines.push(c.dim("  ⋯"));
+                skipping = true;
+            }
+            continue;
+        }
+        skipping = false;
+        if (shown >= MAX_LINES) {
+            lines.push(c.dim("  …(diff truncated)"));
+            break;
+        }
+        const o = ops[k];
+        if (o.t === "+")
+            lines.push(c.green(`  + ${o.s}`));
+        else if (o.t === "-")
+            lines.push(c.red(`  - ${o.s}`));
+        else
+            lines.push(c.dim(`    ${o.s}`));
+        shown++;
+    }
+    return lines.join("\n") + "\n";
+}
+/** Print a diff to the user — interactive terminal only, so pipes/tests stay clean. */
+export function showDiff(path, oldText, newText) {
+    if (!stdout.isTTY)
+        return;
+    const d = renderDiff(path, oldText, newText);
+    if (d)
+        stdout.write(d);
+}
+/** Route a diff to the UI sink (TUI) when present, else print it to the terminal. */
+export function emitDiff(path, oldText, newText, sink) {
+    if (sink)
+        sink.diff(renderDiff(path, oldText, newText));
+    else
+        showDiff(path, oldText, newText);
+}

package/dist/fs-walk.js

@@ -0,0 +1,103 @@
+// Shared filesystem walker — powers @file completion and the grep/glob tools.
+// Walks a directory tree, skipping noise dirs, capped so huge trees stay responsive.
+import { readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { execSync } from "node:child_process";
+import { fuzzyRank } from "./fuzzy.js";
+export const IGNORE_DIRS = new Set([
+    ".git", "node_modules", "dist", "build", "out", ".next", ".nuxt", ".cache",
+    "coverage", ".venv", "venv", "__pycache__", ".mypy_cache", ".pytest_cache",
+    "target", ".idea", ".vscode", ".hara", ".turbo", ".parcel-cache", "vendor",
+]);
+const toPosix = (p) => (sep === "/" ? p : p.split(sep).join("/"));
+/** Relative POSIX file paths under `root`, skipping IGNORE_DIRS, capped at `cap` files. */
+export function walkFiles(root, cap = 8000) {
+    const files = [];
+    const stack = [root];
+    while (stack.length && files.length < cap) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (files.length >= cap)
+                break;
+            if (e.name.startsWith(".") && e.name !== ".env" && e.isDirectory()) {
+                if (IGNORE_DIRS.has(e.name))
+                    continue;
+            }
+            if (e.isDirectory()) {
+                if (IGNORE_DIRS.has(e.name))
+                    continue;
+                stack.push(join(dir, e.name));
+            }
+            else if (e.isFile()) {
+                files.push(toPosix(relative(root, join(dir, e.name))));
+            }
+        }
+    }
+    return files;
+}
+/**
+ * Non-ignored files for `root`. In a git repo: tracked + untracked (respects .gitignore).
+ * Otherwise: a filesystem walk. POSIX-relative paths.
+ */
+export function listProjectFiles(root, cap = 8000) {
+    try {
+        const out = execSync("git ls-files --cached --others --exclude-standard", {
+            cwd: root,
+            encoding: "utf8",
+            maxBuffer: 32 * 1024 * 1024,
+            stdio: ["ignore", "pipe", "ignore"],
+        })
+            .split("\n")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        if (out.length)
+            return out.slice(0, cap);
+    }
+    catch {
+        /* not a git repo — fall through to fs walk */
+    }
+    return walkFiles(root, cap);
+}
+/** Directory prefixes implied by a set of file paths, e.g. "a/b/c.ts" → "a/", "a/b/". */
+export function dirPrefixes(files) {
+    const dirs = new Set();
+    for (const f of files) {
+        const parts = f.split("/");
+        let acc = "";
+        for (let i = 0; i < parts.length - 1; i++) {
+            acc += parts[i] + "/";
+            dirs.add(acc);
+        }
+    }
+    return [...dirs];
+}
+export function isProbablyBinary(buf) {
+    const n = Math.min(buf.length, 4096);
+    for (let i = 0; i < n; i++)
+        if (buf[i] === 0)
+            return true;
+    return false;
+}
+export function fileSize(p) {
+    try {
+        return statSync(p).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Up to `n` project files most similar to a (possibly mistyped) path — for did-you-mean. */
+export function nearestPaths(cwd, p, n = 3) {
+    if (!p)
+        return [];
+    return fuzzyRank(p, listProjectFiles(cwd), (f) => f)
+        .slice(0, n)
+        .map((r) => r.item);
+}

package/dist/fuzzy.js

@@ -0,0 +1,62 @@
+// Tiny zero-dependency fuzzy matcher (subsequence scoring, codex/nucleo-flavored).
+// Used for @path completion, file-path did-you-mean, and slash-command suggestions.
+/**
+ * Score how well `query` fuzzy-matches `target` (case-insensitive subsequence).
+ * Higher is better; returns null if `query` is not a subsequence of `target`.
+ * Bonuses: first char, word boundary (/ _ - . space), camelCase, consecutive runs;
+ * gap penalty for spread-out matches; mild shorter-is-better tiebreak.
+ */
+export function fuzzyScore(query, target) {
+    if (!query)
+        return 0;
+    const q = query.toLowerCase();
+    let qi = 0;
+    let score = 0;
+    let prev = -2;
+    let consec = 0;
+    for (let ti = 0; ti < target.length && qi < q.length; ti++) {
+        if (target[ti].toLowerCase() === q[qi]) {
+            let s = 16;
+            if (ti === prev + 1) {
+                consec++;
+                s += 8 * consec; // reward consecutive runs strongly so clean prefixes win
+            }
+            else
+                consec = 0;
+            if (ti === 0)
+                s += 10;
+            else {
+                const p = target[ti - 1];
+                if ("/_-. ".includes(p))
+                    s += 8; // boundary
+                else if (p === p.toLowerCase() && target[ti] !== target[ti].toLowerCase())
+                    s += 6; // camelCase
+            }
+            if (prev >= 0)
+                s -= Math.min(ti - prev - 1, 4); // gap penalty
+            score += s;
+            prev = ti;
+            qi++;
+        }
+    }
+    if (qi < q.length)
+        return null; // not all query chars consumed → no match
+    return score - target.length * 0.1;
+}
+/** Rank `items` by fuzzy match against `query`; drops non-matches; best first. */
+export function fuzzyRank(query, items, key) {
+    const out = [];
+    for (const item of items) {
+        const sc = fuzzyScore(query, key(item));
+        if (sc !== null)
+            out.push({ item, score: sc });
+    }
+    out.sort((a, b) => b.score - a.score || key(a.item).length - key(b.item).length || key(a.item).localeCompare(key(b.item)));
+    return out;
+}
+/** Up to `n` nearest strings to `query` (for did-you-mean suggestions). */
+export function nearest(query, candidates, n = 3) {
+    return fuzzyRank(query, candidates, (s) => s)
+        .slice(0, n)
+        .map((r) => r.item);
+}

package/dist/images.js

@@ -0,0 +1,146 @@
+// Image attachments for the prompt — paste a screenshot (Ctrl+V) or drag/paste an image file path.
+// Zero-dependency by design: shells out to OS tools (osascript/sips on macOS, wl-paste/xclip on
+// Linux, PowerShell on Windows) rather than pulling a native clipboard module — same posture as
+// sandbox.ts. Paths (not bytes) ride in the conversation; encoding to base64 happens at send time.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { extname, join, resolve } from "node:path";
+const MEDIA = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+export function mediaTypeFor(p) {
+    return MEDIA[extname(p).toLowerCase()] ?? null;
+}
+// Anthropic caps an image near 5 MB of base64; downsize a larger source, then hard-skip if still over.
+const DOWNSIZE_OVER = 3_600_000; // raw bytes (base64 ≈ 1.37×)
+const MAX_B64 = 5_000_000;
+/**
+ * Treat a typed/pasted string as a path to an existing image. Terminals emit a bare (often quoted or
+ * backslash-escaped) path when you drag a file in; we also accept a `file://` URL. Returns the
+ * resolved attachment, or null when it isn't an existing image file.
+ */
+export function imagePathFromPaste(raw, cwd = process.cwd()) {
+    let s = raw.trim();
+    if (!s || /[\r\n]/.test(s))
+        return null;
+    if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'")))
+        s = s.slice(1, -1);
+    if (s.startsWith("file://")) {
+        try {
+            s = decodeURIComponent(s.slice("file://".length));
+        }
+        catch {
+            return null;
+        }
+    }
+    s = s.replace(/\\ /g, " "); // un-escape dragged-in spaces
+    const mediaType = mediaTypeFor(s);
+    if (!mediaType)
+        return null;
+    const abs = resolve(cwd, s);
+    try {
+        if (!existsSync(abs) || !statSync(abs).isFile())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    return { path: abs, mediaType };
+}
+let seq = 0;
+function tmpPng() {
+    seq += 1;
+    return join(tmpdir(), `hara-clip-${process.pid}-${Date.now()}-${seq}.png`);
+}
+/**
+ * Pull an image off the OS clipboard into a temp PNG (Ctrl+V screenshot-paste). Synchronous — one
+ * short-lived helper process. Returns null when the clipboard holds no image or the tooling/platform
+ * isn't available. (Copied *files* arrive as a path instead → handled by imagePathFromPaste.)
+ */
+export function readClipboardImage() {
+    const out = tmpPng();
+    try {
+        if (process.platform === "darwin") {
+            const script = [
+                "try",
+                "  set thePng to (the clipboard as «class PNGf»)",
+                "on error",
+                '  return "NONE"',
+                "end try",
+                `set theFile to open for access POSIX file ${JSON.stringify(out)} with write permission`,
+                "write thePng to theFile",
+                "close access theFile",
+                'return "OK"',
+            ].join("\n");
+            const r = spawnSync("osascript", ["-e", script], { encoding: "utf8" });
+            if (r.status !== 0 || !String(r.stdout).includes("OK"))
+                return null;
+        }
+        else if (process.platform === "linux") {
+            if (!dumpStdout("wl-paste", ["--type", "image/png"], out) &&
+                !dumpStdout("xclip", ["-selection", "clipboard", "-t", "image/png", "-o"], out))
+                return null;
+        }
+        else if (process.platform === "win32") {
+            const ps = `Add-Type -AssemblyName System.Windows.Forms; $i=[System.Windows.Forms.Clipboard]::GetImage(); if($i){$i.Save(${JSON.stringify(out)},[System.Drawing.Imaging.ImageFormat]::Png)}else{exit 1}`;
+            if (spawnSync("powershell", ["-NoProfile", "-Command", ps], { encoding: "utf8" }).status !== 0)
+                return null;
+        }
+        else {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    try {
+        if (!existsSync(out) || statSync(out).size === 0)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    downsizeIfHuge(out);
+    return { path: out, mediaType: "image/png" };
+}
+function dumpStdout(cmd, args, outPath) {
+    try {
+        const r = spawnSync(cmd, args, { maxBuffer: 64 * 1024 * 1024 });
+        if (r.status !== 0 || !r.stdout || r.stdout.length === 0)
+            return false;
+        writeFileSync(outPath, r.stdout);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Shrink an oversized image in place (macOS `sips`, always present) to stay under the API cap. */
+function downsizeIfHuge(path) {
+    try {
+        if (statSync(path).size <= DOWNSIZE_OVER)
+            return;
+        if (process.platform === "darwin")
+            spawnSync("sips", ["--resampleHeightWidthMax", "1568", path], { encoding: "utf8" });
+    }
+    catch {
+        /* best effort — send as-is and let the provider decide */
+    }
+}
+/** Read an image file → base64 for an API request. Null when missing or still too large to send. */
+export function imageToBase64(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const b64 = readFileSync(path).toString("base64");
+        return b64.length > MAX_B64 ? null : b64;
+    }
+    catch {
+        return null;
+    }
+}