@tianmucreations/jeeves 0.2.0

package/dist/ink/AlternateScreen.js

@@ -0,0 +1,106 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// ─────────────────────────────────────────────────────────────────────────────
+// DO NOT CHANGE THE HOOK. THE TAKEOVER MUST STAY INSIDE useInsertionEffect.
+// ─────────────────────────────────────────────────────────────────────────────
+// This component implements Claude Code's alternate-screen takeover (published
+// source: alejandrobalderas/claude-code-from-source, chapter 13). The
+// ENTER_ALT_SCREEN escape sequence must reach the terminal BEFORE the first
+// render frame is flushed. react-reconciler calls resetAfterCommit between the
+// mutation and layout commit phases, and Ink's resetAfterCommit triggers the
+// first onRender - the first frame write to the terminal.
+//
+// useLayoutEffect and useEffect both run AFTER that first onRender. "Upgrade"
+// this to either hook and the first frame paints to the MAIN screen buffer,
+// producing a visible flash before the switch - and macOS Terminal.app then
+// archives that pre-app frame into its scrollback at the moment the app
+// switches, so the shell history stays reachable by scrolling forever. That is
+// the exact bug this file exists to prevent; it took days to diagnose and the
+// answer was published all along. Only useInsertionEffect fires before
+// resetAfterCommit. This is not a stylistic choice. Do not "improve" it.
+//
+// The escape order is equally deliberate: 1049h (take over the window) → 2J
+// (clear the fresh alternate screen) → 3J (erase the scrollback the switch
+// archived) → H (home the cursor), in one write. Entering first means the main
+// screen is never wiped, so quitting restores the shell's own screen exactly.
+// Ink's built-in alternateScreen render option is NOT used: it is not needed
+// here and mixing the two mechanisms invites double switches.
+// ─────────────────────────────────────────────────────────────────────────────
+import { useEffect, useInsertionEffect } from 'react';
+import { Box, useStdout } from 'ink';
+import { createRequire } from 'node:module';
+// signal-exit covers the termination signals beyond exit and SIGINT
+// (SIGTERM, SIGHUP) with correct exit codes. Already in the tree as Ink's own
+// dependency; declared ours.
+const onSignalExit = createRequire(import.meta.url)('signal-exit');
+const ENTER_ALT_SCREEN = '\x1b[?1049h';
+const CLEAR_SCREEN = '\x1b[2J';
+const ERASE_SCROLLBACK = '\x1b[3J';
+const HOME_CURSOR = '\x1b[H';
+const LEAVE_ALT_SCREEN = '\x1b[?1049l';
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+let altScreenActive = false;
+let cleanupRegistered = false;
+function write(data) {
+    try {
+        process.stdout.write(data);
+    }
+    catch {
+        // A closed stream must never crash the takeover or the exit path.
+    }
+}
+// Claude Code's Ink fork exposes this on the render instance; stock Ink has no
+// such method, so the notification lives here: the flag that says the
+// alternate screen owns the terminal, consulted by every exit path below.
+export function setAltScreenActive(active, mouseTracking) {
+    altScreenActive = active;
+    // Mouse tracking is deliberately left off: it would break click-drag text
+    // selection in Terminal.app, and the app already owns scrolling by key.
+    void mouseTracking;
+}
+// Hands the terminal back. Safe to call from anywhere, any number of times.
+// The scrollback erase follows the switch back because macOS Terminal.app
+// archives the app's own frames into the scrollback at hand-back (measured),
+// and they must not linger; the cursor comes back on for the shell.
+export function leaveAltScreen() {
+    if (!altScreenActive)
+        return;
+    altScreenActive = false;
+    write(LEAVE_ALT_SCREEN + ERASE_SCROLLBACK + SHOW_CURSOR);
+}
+// The terminal must always be restored. process handlers per the mechanism,
+// plus signal-exit so kill signals re-raise with correct exit codes.
+function registerCleanup() {
+    if (cleanupRegistered)
+        return;
+    cleanupRegistered = true;
+    process.on('exit', () => leaveAltScreen());
+    process.on('SIGINT', () => {
+        leaveAltScreen();
+        process.exit(130);
+    });
+    onSignalExit(() => leaveAltScreen(), { alwaysLast: false });
+}
+export function AlternateScreen({ children }) {
+    const { stdout } = useStdout();
+    // Entered once, before the first frame, in Claude Code's order: take over
+    // the window first, then clear the fresh alternate screen, erase the
+    // scrollback the switch archived, and home the cursor. Because the main
+    // screen is never wiped, the shell's own screen survives for a perfect
+    // restore on exit. The cursor is hidden for the same reason Ink's own mode
+    // hides it. Empty dependency array: this runs exactly once, on mount.
+    useInsertionEffect(() => {
+        write(ENTER_ALT_SCREEN + CLEAR_SCREEN + ERASE_SCROLLBACK + HOME_CURSOR + HIDE_CURSOR);
+        setAltScreenActive(true, false);
+        registerCleanup();
+    }, []);
+    // On unmount the terminal is handed back too (the app unmounts before the
+    // process exits on /exit and Ctrl+C).
+    useEffect(() => {
+        return () => leaveAltScreen();
+    }, []);
+    const rows = Math.max(stdout.rows ?? 24, 8);
+    // The alternate screen has no native scrollback, so the app owns its own
+    // scrolling: everything is constrained to the terminal's row count.
+    return (_jsx(Box, { height: rows, flexDirection: "column", overflow: "hidden", children: children }));
+}

package/dist/keys/store.js

@@ -0,0 +1,58 @@
+const SERVICE = 'jeeves';
+let cached = null;
+async function load() {
+    // Escape hatch for automated tests so they never touch the real credential store.
+    if (process.env.JEEVES_SKIP_KEYCHAIN === '1')
+        return null;
+    if (cached === null) {
+        const mod = await import('keytar');
+        cached = (mod.default ?? mod);
+    }
+    return cached;
+}
+export async function setKey(provider, key) {
+    try {
+        const keytar = await load();
+        if (!keytar)
+            return false;
+        await keytar.setPassword(SERVICE, provider, key);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function getKey(provider) {
+    try {
+        const keytar = await load();
+        if (!keytar)
+            return null;
+        return await keytar.getPassword(SERVICE, provider);
+    }
+    catch {
+        return null;
+    }
+}
+export async function deleteKey(provider) {
+    try {
+        const keytar = await load();
+        if (!keytar)
+            return false;
+        return await keytar.deletePassword(SERVICE, provider);
+    }
+    catch {
+        return false;
+    }
+}
+export async function listProviders() {
+    try {
+        const keytar = await load();
+        if (!keytar)
+            return [];
+        const credentials = await keytar.findCredentials(SERVICE);
+        return credentials.map((credential) => credential.account);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/models/filter.js

@@ -0,0 +1,4 @@
+// A model can drive the agent only if OpenRouter reports tool support (spec 4.1).
+export function isToolCapable(model) {
+    return model.supportedParameters.includes('tools') || model.supportedParameters.includes('tool_choice');
+}

package/dist/models/registry.js

@@ -0,0 +1,112 @@
+import { getModelCache, setModelCache } from '../platform/config.js';
+const MODELS_URL = 'https://openrouter.ai/api/v1/models';
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+function toNumber(value) {
+    const parsed = typeof value === 'number' ? value : Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+// Maps the public OpenRouter models payload into the picker's model records.
+export function normalizeModels(body) {
+    if (typeof body !== 'object' || body === null)
+        return [];
+    const data = body.data;
+    if (!Array.isArray(data))
+        return [];
+    const models = [];
+    for (const raw of data) {
+        if (typeof raw !== 'object' || raw === null)
+            continue;
+        const entry = raw;
+        const id = typeof entry.id === 'string' ? entry.id : '';
+        if (!id)
+            continue;
+        const pricing = (typeof entry.pricing === 'object' && entry.pricing !== null ? entry.pricing : {});
+        models.push({
+            id,
+            name: typeof entry.name === 'string' && entry.name.length > 0 ? entry.name : id,
+            contextLength: typeof entry.context_length === 'number' ? entry.context_length : 0,
+            promptPrice: toNumber(pricing.prompt),
+            completionPrice: toNumber(pricing.completion),
+            supportedParameters: Array.isArray(entry.supported_parameters)
+                ? entry.supported_parameters.filter((param) => typeof param === 'string')
+                : [],
+            provider: id.includes('/') ? id.slice(0, id.indexOf('/')) : 'openrouter',
+        });
+    }
+    return models;
+}
+// Loads the model list: fresh weekly fetch, cached in the config directory,
+// with graceful fallback to the cache when the network fails.
+export async function loadModels() {
+    const cache = getModelCache();
+    if (cache && Date.now() - cache.fetchedAt < WEEK_MS) {
+        return { models: normalizeModels(cache.raw), error: '' };
+    }
+    try {
+        const response = await fetch(MODELS_URL);
+        if (!response.ok)
+            throw new Error(`the models list is unavailable (${response.status})`);
+        const body = await response.json();
+        setModelCache(body, Date.now());
+        return { models: normalizeModels(body), error: '' };
+    }
+    catch (error) {
+        if (cache) {
+            return { models: normalizeModels(cache.raw), error: 'Could not refresh the model list - showing the saved copy.' };
+        }
+        return { models: [], error: `Could not load the model list: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+export function compactContext(tokens) {
+    if (tokens >= 1_000_000)
+        return `${(tokens / 1_000_000).toFixed(1)}M`;
+    if (tokens >= 1000)
+        return `${Math.round(tokens / 1000)}k`;
+    return `${tokens}`;
+}
+// A short, human-first shortlist. Each entry lists candidate ids so the row
+// survives catalog drift; the first id found in the catalog wins.
+export const CURATED_MODELS = [
+    { ids: ['z-ai/glm-5.3', 'z-ai/glm-5.3-flash', 'z-ai/glm-5.2'], blurb: 'best value' },
+    { ids: ['deepseek/deepseek-v4-flash-0731', 'deepseek/deepseek-v4-flash', 'deepseek/deepseek-v3.2'], blurb: 'cheapest' },
+    { ids: ['anthropic/claude-opus-5', 'anthropic/claude-opus-4.8', 'anthropic/claude-sonnet-5'], blurb: 'best quality' },
+    { ids: ['openai/gpt-5.5', 'openai/gpt-5.4', 'openai/gpt-5.1'], blurb: 'strong all-rounder' },
+    { ids: ['google/gemini-3.1-pro-preview', 'google/gemini-3-pro-preview', 'google/gemini-2.5-pro'], blurb: 'huge memory' },
+    { ids: ['qwen/qwen3-coder-plus', 'qwen/qwen3-coder', 'qwen/qwen3-coder-flash'], blurb: 'good for code' },
+];
+export function resolveCurated(models) {
+    const byId = new Map(models.map((model) => [model.id, model]));
+    const picks = [];
+    for (const entry of CURATED_MODELS) {
+        for (const id of entry.ids) {
+            const model = byId.get(id);
+            if (model) {
+                picks.push({ model, blurb: entry.blurb });
+                break;
+            }
+        }
+    }
+    return picks;
+}
+// Strips the "Provider: " prefix OpenRouter puts in display names.
+export function cleanModelName(name) {
+    const stripped = name.replace(/^[A-Za-z][A-Za-z0-9 .-]*: /, '');
+    return stripped.length > 0 ? stripped : name;
+}
+export function compactPrice(prompt, completion, priceLabel) {
+    if (priceLabel)
+        return priceLabel;
+    if (prompt === 0 && completion === 0)
+        return 'free';
+    // OpenRouter marks router models with negative sentinels; their price varies by routed model.
+    if (prompt < 0 || completion < 0)
+        return 'varies';
+    const perMillion = (value) => `$${(value * 1_000_000).toFixed(2)}`;
+    return `${perMillion(prompt)}/${perMillion(completion)} per M`;
+}
+// Assumption: OpenRouter's models endpoint carries no speed data, so the indicator uses
+// naming conventions (flash/turbo/mini/air/haiku/nano/instant) as a rough hint.
+export function isFastModel(model) {
+    const name = `${model.name} ${model.id}`.toLowerCase();
+    return ['flash', 'turbo', 'mini', 'air', 'haiku', 'nano', 'instant'].some((hint) => name.includes(hint));
+}

package/dist/platform/config.js

@@ -0,0 +1,60 @@
+import Conf from 'conf';
+// Persistent settings. Phase 7 expands this into the full config surface
+// (default model, favourites, recents, verbose flag). API keys are NEVER stored here (spec 5.3).
+// Tests run against their own settings file so they never touch - or race on - the real one.
+const config = new Conf({
+    projectName: process.env.NODE_ENV === 'test' ? 'jeeves-tests' : 'jeeves',
+});
+const VALID_METRICS = ['session', 'context', 'cache', 'today', 'credit', 'speed'];
+// Metrics a power user has chosen to hide from the footer - hiding is opt-in, never required.
+export function getHiddenMetrics() {
+    const stored = config.get('hiddenMetrics') ?? [];
+    return stored.filter((metric) => VALID_METRICS.includes(metric));
+}
+export function setHiddenMetrics(metrics) {
+    config.set('hiddenMetrics', metrics.filter((metric) => VALID_METRICS.includes(metric)));
+}
+export function getFavorites() {
+    return config.get('favorites') ?? [];
+}
+export function setFavorites(models) {
+    config.set('favorites', models);
+}
+export function getRecents() {
+    return config.get('recents') ?? [];
+}
+export function setRecents(models) {
+    config.set('recents', models.slice(0, 10));
+}
+// Recently chosen project folders, newest first; the list grows automatically.
+export function getRecentProjects() {
+    return config.get('projects') ?? [];
+}
+export function setRecentProjects(projects) {
+    config.set('projects', projects.slice(0, 10));
+}
+export function getModelCache() {
+    return config.get('modelCache') ?? null;
+}
+export function setModelCache(raw, fetchedAt) {
+    config.set('modelCache', { raw, fetchedAt });
+}
+// The default model and provider persist between sessions; API keys never do (spec 7).
+export function getDefaultModel() {
+    return config.get('defaultModel') ?? null;
+}
+export function setDefaultModel(model) {
+    config.set('defaultModel', model);
+}
+export function getDefaultProvider() {
+    return config.get('defaultProvider') ?? null;
+}
+export function setDefaultProvider(provider) {
+    config.set('defaultProvider', provider);
+}
+export function getVerbosePreference() {
+    return config.get('verbose') ?? false;
+}
+export function setVerbosePreference(value) {
+    config.set('verbose', value);
+}

package/dist/platform/paths.js

@@ -0,0 +1,60 @@
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { existsSync, readdirSync } from 'node:fs';
+// Path helpers. Resolving against the current folder keeps behaviour identical on macOS, Windows, and Linux.
+export function resolveFromCwd(p) {
+    return path.resolve(p);
+}
+// The standard user locations the folder browser offers first; only existing ones are shown.
+export function homeLocations() {
+    const home = homedir();
+    const candidates = [
+        { label: 'Desktop', folder: 'Desktop' },
+        { label: 'Documents', folder: 'Documents' },
+        { label: 'Downloads', folder: 'Downloads' },
+        { label: 'Home', folder: '' },
+        { label: 'Pictures', folder: 'Pictures' },
+        { label: 'Music', folder: 'Music' },
+        { label: 'Movies', folder: 'Movies' },
+    ];
+    return candidates
+        .filter((candidate) => candidate.folder === '' || existsSync(path.join(home, candidate.folder)))
+        .map((candidate) => ({ name: candidate.label, path: candidate.folder === '' ? home : path.join(home, candidate.folder) }));
+}
+// Lists the subfolders of a directory, hiding dot-folders; failures are reported, never thrown.
+export function listSubfolders(dir) {
+    try {
+        const entries = readdirSync(dir, { withFileTypes: true });
+        const folders = entries
+            .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+            .map((entry) => ({ name: entry.name, path: path.join(dir, entry.name) }))
+            .sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
+        return { folders, error: '' };
+    }
+    catch {
+        return { folders: [], error: 'This folder could not be opened.' };
+    }
+}
+// Short display form for paths: the home folder becomes ~.
+export function displayPath(p) {
+    const home = homedir();
+    if (p === home)
+        return '~';
+    if (p.startsWith(home + path.sep)) {
+        return '~' + p.slice(home.length);
+    }
+    return p;
+}
+// Returns a plain-English problem with a proposed project name, or null when the name is fine.
+export function projectNameProblem(name) {
+    const trimmed = name.trim();
+    if (!trimmed)
+        return 'Give the project a name first.';
+    if (/[/\\:*?"<>|]/.test(trimmed)) {
+        return 'Names cannot contain / \\ : * ? " < > or | - try another name.';
+    }
+    if (trimmed === '.' || trimmed === '..') {
+        return 'That is not a valid name - try another.';
+    }
+    return null;
+}

package/dist/platform/shell.js

@@ -0,0 +1,9 @@
+import process from 'node:process';
+// bash on macOS and Linux, PowerShell on Windows, chosen from process.platform
+// (spec Phase 8). execa resolves the program through PATH on every platform.
+export function getShell(platform = process.platform) {
+    if (platform === 'win32') {
+        return { program: 'powershell.exe', flag: '-Command' };
+    }
+    return { program: 'bash', flag: '-c' };
+}

package/dist/providers/index.js

@@ -0,0 +1,165 @@
+import { createOpenRouterProvider, fetchCreditInfo } from './openrouter.js';
+import { createOllamaProvider } from './ollama.js';
+import { createZaiProvider } from './zai.js';
+import { session } from '../state/session.js';
+import { getKey, setKey, deleteKey, listProviders } from '../keys/store.js';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+let active = null;
+let resolvedKey = null;
+let zaiKey = null;
+let keySource = null;
+// The calm provider list shared by the model picker and the key screens.
+export const PROVIDER_ROWS = [
+    { id: 'openrouter', label: 'OpenRouter', description: 'one key unlocks 400+ models - recommended' },
+    { id: 'zai', label: 'Z.ai', description: 'GLM Coding Plan - $18/month flat - best for heavy daily use' },
+    { id: 'anthropic', label: 'Anthropic', description: 'direct connection' },
+    { id: 'openai', label: 'OpenAI', description: 'direct connection' },
+    { id: 'google', label: 'Google', description: 'direct connection' },
+    { id: 'xai', label: 'xAI', description: 'direct connection' },
+    { id: 'groq', label: 'Groq', description: 'direct connection' },
+    { id: 'mistral', label: 'Mistral', description: 'direct connection' },
+    { id: 'ollama', label: 'Ollama', description: 'local models, no key needed' },
+];
+export function getKeySource() {
+    return keySource;
+}
+// Whether a stored key (or keyless local mode) makes a provider usable today.
+export function hasCredentialsFor(providerId) {
+    if (providerId === 'openrouter')
+        return resolvedKey !== null;
+    if (providerId === 'zai')
+        return zaiKey !== null;
+    if (providerId === 'ollama')
+        return true;
+    return false;
+}
+export function hasCredentials() {
+    return hasCredentialsFor(session.providerId);
+}
+// Startup key resolution: the Keychain wins; a .env file is a development fallback
+// that gets migrated into the Keychain on first launch. The first access may pop a
+// macOS permission dialog - that is expected and allowed once.
+export async function initKeys() {
+    const storedZai = await getKey('zai');
+    if (storedZai && storedZai.length > 0) {
+        zaiKey = storedZai;
+    }
+    const stored = await getKey('openrouter');
+    if (stored && stored.length > 0) {
+        resolvedKey = stored;
+        keySource = 'keychain';
+        return;
+    }
+    const envKey = process.env.OPENROUTER_API_KEY;
+    if (envKey && envKey.length > 0) {
+        const moved = await setKey('openrouter', envKey);
+        if (moved) {
+            removeEnvFile();
+            session.addNotice('Your API key was moved from the .env file into your Mac keychain. The .env file has been removed.');
+        }
+        else {
+            session.addNotice('The Mac keychain was not reachable, so the .env development file is being used. Run /keys to store the key securely.');
+        }
+        resolvedKey = envKey;
+        keySource = moved ? 'keychain' : 'env';
+    }
+}
+// Only removes the single-key development file this project created - never a custom one.
+function removeEnvFile() {
+    const envPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '.env');
+    if (!existsSync(envPath))
+        return;
+    try {
+        const lines = readFileSync(envPath, 'utf8')
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0);
+        if (lines.length > 0 && lines.every((line) => line.startsWith('OPENROUTER_API_KEY='))) {
+            rmSync(envPath);
+        }
+    }
+    catch {
+        // Cleanup failures must never break startup.
+    }
+}
+// Saves the OpenRouter key in the Keychain and activates it immediately.
+export async function storeOpenRouterKey(key) {
+    const saved = await setKey('openrouter', key);
+    if (!saved)
+        return false;
+    resolvedKey = key;
+    keySource = 'keychain';
+    active = null;
+    return true;
+}
+// Saves the Z.ai key (GLM Coding Plan) in the Keychain and activates it immediately.
+export async function storeZaiKey(key) {
+    const saved = await setKey('zai', key);
+    if (!saved)
+        return false;
+    zaiKey = key;
+    return true;
+}
+export async function removeZaiKey() {
+    await deleteKey('zai');
+    zaiKey = null;
+}
+// Removes the stored OpenRouter key; an env key becomes the fallback again.
+export async function removeOpenRouterKey() {
+    await deleteKey('openrouter');
+    active = null;
+    const envKey = process.env.OPENROUTER_API_KEY;
+    if (envKey && envKey.length > 0) {
+        resolvedKey = envKey;
+        keySource = 'env';
+        return 'env';
+    }
+    resolvedKey = null;
+    keySource = null;
+    return null;
+}
+export function getActiveProvider() {
+    if (session.providerId === 'ollama') {
+        return createOllamaProvider();
+    }
+    if (session.providerId === 'zai') {
+        if (!zaiKey) {
+            throw new Error('No Z.ai key found. Add one with /keys.');
+        }
+        return createZaiProvider(zaiKey);
+    }
+    if (!resolvedKey) {
+        throw new Error('No OpenRouter API key found. Add one with /keys.');
+    }
+    if (!active) {
+        active = createOpenRouterProvider(resolvedKey);
+    }
+    return active;
+}
+// Best-effort credit refresh. The management key sees the real account balance;
+// the inference key only sees its own spending cap, which is labelled as such.
+// Local Ollama has no credit balance, and failures are silent.
+export async function refreshCredit() {
+    if (session.providerId !== 'openrouter')
+        return;
+    const managementKey = await getKey('openrouter-management');
+    if (managementKey) {
+        const info = await fetchCreditInfo(managementKey);
+        if (info) {
+            session.setCredit(info.used, info.limit, info.remaining, true);
+            return;
+        }
+    }
+    if (!resolvedKey)
+        return;
+    const info = await fetchCreditInfo(resolvedKey);
+    if (info) {
+        session.setCredit(info.used, info.limit, info.remaining, false);
+    }
+}
+// Which providers have a key in the OS credential store.
+export async function storedKeyProviders() {
+    return listProviders();
+}