@manishbht/helpcode 0.2.3 → 0.3.5

package/dist/src/core/gemini.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Minimal client for the Google Gemini API (free tier), via REST.
+ *
+ * Mirrors the Ollama client's discipline:
+ *   - Zero runtime dependencies: plain fetch, no SDK.
+ *   - fetch is injectable so tests never hit the live API and CI passes offline.
+ *   - Every failure becomes a GeminiError; callers fall back to a cheaper
+ *     worker (local) or deterministic path. The remote path can NEVER break the
+ *     core flow.
+ *
+ * PRIVACY: the free tier may use inputs/outputs to train Google's models. The
+ * sous-chef privacy gate (core/souschef.ts) ensures only non-code task input
+ * (decomposition) reaches here unless the user opts into allowRemoteCode. This
+ * client does not enforce that — it's enforced upstream at routing time.
+ */
+export declare class GeminiError extends Error {
+    /** True if the failure was a 429 RESOURCE_EXHAUSTED (free quota used up). */
+    readonly quotaExhausted: boolean;
+    constructor(message: string, quotaExhausted?: boolean);
+}
+type FetchImpl = (url: string, init?: RequestInit) => Promise<Response>;
+export interface GeminiCallOptions {
+    fetchImpl?: FetchImpl;
+}
+export interface GeminiConfig {
+    apiKey: string;
+    /** Model id, e.g. "gemini-2.5-flash-lite". */
+    model: string;
+    timeoutMs: number;
+}
+/** Build the generateContent endpoint URL for a model + key. */
+export declare function buildGeminiUrl(model: string, apiKey: string): string;
+/** Extract concatenated text from a generateContent response body. */
+export declare function parseGeminiResponse(body: any): string;
+/**
+ * Generate text from Gemini. Returns the model's text on success; throws a
+ * GeminiError on any failure (with quotaExhausted set for 429s so the router
+ * can mark the provider throttled).
+ */
+export declare function geminiGenerate(prompt: string, config: GeminiConfig, opts?: GeminiCallOptions): Promise<string>;
+export {};

package/dist/src/core/gemini.js

@@ -0,0 +1,91 @@
+/**
+ * Minimal client for the Google Gemini API (free tier), via REST.
+ *
+ * Mirrors the Ollama client's discipline:
+ *   - Zero runtime dependencies: plain fetch, no SDK.
+ *   - fetch is injectable so tests never hit the live API and CI passes offline.
+ *   - Every failure becomes a GeminiError; callers fall back to a cheaper
+ *     worker (local) or deterministic path. The remote path can NEVER break the
+ *     core flow.
+ *
+ * PRIVACY: the free tier may use inputs/outputs to train Google's models. The
+ * sous-chef privacy gate (core/souschef.ts) ensures only non-code task input
+ * (decomposition) reaches here unless the user opts into allowRemoteCode. This
+ * client does not enforce that — it's enforced upstream at routing time.
+ */
+export class GeminiError extends Error {
+    /** True if the failure was a 429 RESOURCE_EXHAUSTED (free quota used up). */
+    quotaExhausted;
+    constructor(message, quotaExhausted = false) {
+        super(message);
+        this.name = 'GeminiError';
+        this.quotaExhausted = quotaExhausted;
+    }
+}
+const DEFAULT_GENERATE_TIMEOUT = 20000;
+const API_BASE = 'https://generativelanguage.googleapis.com/v1beta/models';
+/** Build the generateContent endpoint URL for a model + key. */
+export function buildGeminiUrl(model, apiKey) {
+    return `${API_BASE}/${model}:generateContent?key=${apiKey}`;
+}
+/** Extract concatenated text from a generateContent response body. */
+export function parseGeminiResponse(body) {
+    const cand = body?.candidates?.[0];
+    const parts = cand?.content?.parts;
+    if (!Array.isArray(parts))
+        return '';
+    return parts.map((p) => (typeof p?.text === 'string' ? p.text : '')).join('');
+}
+function getFetch(opts) {
+    return opts?.fetchImpl ?? globalThis.fetch;
+}
+/**
+ * Generate text from Gemini. Returns the model's text on success; throws a
+ * GeminiError on any failure (with quotaExhausted set for 429s so the router
+ * can mark the provider throttled).
+ */
+export async function geminiGenerate(prompt, config, opts) {
+    const fetchImpl = getFetch(opts);
+    const timeoutMs = config.timeoutMs ?? DEFAULT_GENERATE_TIMEOUT;
+    const url = buildGeminiUrl(config.model, config.apiKey);
+    const requestBody = {
+        contents: [{ parts: [{ text: prompt }] }],
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(requestBody),
+            signal: controller.signal,
+        });
+    }
+    catch (e) {
+        clearTimeout(timer);
+        const why = e?.name === 'AbortError' ? 'timed out' : e.message;
+        throw new GeminiError(`request failed: ${why}`);
+    }
+    clearTimeout(timer);
+    // Parse the body (may be an error envelope).
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        throw new GeminiError(`bad response (status ${response.status}, non-JSON body)`);
+    }
+    if (!response.ok) {
+        const status = body?.error?.status ?? '';
+        const msg = body?.error?.message ?? `HTTP ${response.status}`;
+        const isQuota = response.status === 429 || status === 'RESOURCE_EXHAUSTED';
+        throw new GeminiError(`Gemini error: ${msg}`, isQuota);
+    }
+    const text = parseGeminiResponse(body).trim();
+    if (!text) {
+        throw new GeminiError('Gemini returned no usable text');
+    }
+    return text;
+}
+//# sourceMappingURL=gemini.js.map

package/dist/src/core/gemini.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini.js","sourceRoot":"","sources":["../../../src/core/gemini.ts"],"names":[],"mappings":"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"}

package/dist/src/core/keys.d.ts

@@ -0,0 +1,29 @@
+/**
+ * API key loading for remote sous-chefs (v0.3.2).
+ *
+ * Keys are secrets and must never touch project.json (which is committed).
+ * Resolution order:
+ *   1. GEMINI_API_KEY environment variable  (precedence; nothing on disk)
+ *   2. .helpcode/keys.json  { "gemini": "..." }  (gitignored by init)
+ *
+ * Returns null if no key is configured — in which case the remote sous-chef
+ * simply doesn't exist and helpcode behaves exactly as v0.3.1 (local only).
+ * Never throws: a missing or malformed keys.json yields null, not an error.
+ */
+/**
+ * Resolve the Gemini API key. `env` is injectable for testing (defaults to
+ * process.env). Returns the key string, or null if none is configured.
+ */
+export declare function loadGeminiKey(cwd?: string, env?: Record<string, string | undefined>): string | null;
+/**
+ * Resolve an API key for any provider, by its env var name, with the same
+ * precedence: env var first, then .helpcode/keys.json (keyed by a short name).
+ * `envVar` is e.g. "XAI_API_KEY"; `fileKey` is the keys.json field, e.g. "grok".
+ */
+export declare function loadProviderKey(envVar: string, fileKey: string, cwd?: string, env?: Record<string, string | undefined>): string | null;
+/**
+ * Whether a keys.json exists but is NOT gitignored — a footgun worth warning
+ * about (the user could commit their key). Best-effort: checks for a literal
+ * keys.json or .helpcode/ entry in .gitignore.
+ */
+export declare function keysFileAtRiskOfCommit(cwd?: string): boolean;

package/dist/src/core/keys.js

@@ -0,0 +1,92 @@
+/**
+ * API key loading for remote sous-chefs (v0.3.2).
+ *
+ * Keys are secrets and must never touch project.json (which is committed).
+ * Resolution order:
+ *   1. GEMINI_API_KEY environment variable  (precedence; nothing on disk)
+ *   2. .helpcode/keys.json  { "gemini": "..." }  (gitignored by init)
+ *
+ * Returns null if no key is configured — in which case the remote sous-chef
+ * simply doesn't exist and helpcode behaves exactly as v0.3.1 (local only).
+ * Never throws: a missing or malformed keys.json yields null, not an error.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+const KEYS_FILE = path.join('.helpcode', 'keys.json');
+/**
+ * Resolve the Gemini API key. `env` is injectable for testing (defaults to
+ * process.env). Returns the key string, or null if none is configured.
+ */
+export function loadGeminiKey(cwd = process.cwd(), env = process.env) {
+    // 1. Environment variable wins (and leaves nothing on disk).
+    const fromEnv = env.GEMINI_API_KEY;
+    if (typeof fromEnv === 'string' && fromEnv.trim().length > 0) {
+        return fromEnv.trim();
+    }
+    // 2. .helpcode/keys.json
+    const file = path.join(cwd, KEYS_FILE);
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        const k = parsed?.gemini;
+        if (typeof k === 'string' && k.trim().length > 0)
+            return k.trim();
+        return null;
+    }
+    catch {
+        // Malformed file: behave as if no key (never throw).
+        return null;
+    }
+}
+/**
+ * Resolve an API key for any provider, by its env var name, with the same
+ * precedence: env var first, then .helpcode/keys.json (keyed by a short name).
+ * `envVar` is e.g. "XAI_API_KEY"; `fileKey` is the keys.json field, e.g. "grok".
+ */
+export function loadProviderKey(envVar, fileKey, cwd = process.cwd(), env = process.env) {
+    const fromEnv = env[envVar];
+    if (typeof fromEnv === 'string' && fromEnv.trim().length > 0) {
+        return fromEnv.trim();
+    }
+    const file = path.join(cwd, KEYS_FILE);
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        const k = parsed?.[fileKey];
+        if (typeof k === 'string' && k.trim().length > 0)
+            return k.trim();
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a keys.json exists but is NOT gitignored — a footgun worth warning
+ * about (the user could commit their key). Best-effort: checks for a literal
+ * keys.json or .helpcode/ entry in .gitignore.
+ */
+export function keysFileAtRiskOfCommit(cwd = process.cwd()) {
+    const keysPath = path.join(cwd, KEYS_FILE);
+    if (!fs.existsSync(keysPath))
+        return false;
+    const gitignorePath = path.join(cwd, '.gitignore');
+    if (!fs.existsSync(gitignorePath))
+        return true; // exists, nothing ignoring it
+    try {
+        const ignore = fs.readFileSync(gitignorePath, 'utf-8');
+        const lines = ignore.split(/\r?\n/).map(l => l.trim());
+        const covered = lines.some(l => l === '.helpcode/' ||
+            l === '.helpcode' ||
+            l === '.helpcode/keys.json' ||
+            l === 'keys.json' ||
+            l === '.helpcode/*');
+        return !covered;
+    }
+    catch {
+        return true;
+    }
+}
+//# sourceMappingURL=keys.js.map

package/dist/src/core/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../src/core/keys.ts"],"names":[],"mappings":"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"}

package/dist/src/core/llmSelector.d.ts

@@ -56,6 +56,12 @@ export declare function parseSelectionResponse(response: string, candidates: Can
  * "model ran but found nothing" (empty array) from "couldn't reach model"
  * (throw) — both lead to fallback, but the caller may log them differently.
  */
+/**
+ * Backend-agnostic file selection: builds the prompt, calls the provided
+ * generate function (Ollama or Gemini or any text model), parses + validates.
+ * The empty-file filter and hallucination guard apply regardless of backend.
+ */
+export declare function selectFilesWithGenerate(task: string, candidatePaths: string[], projectRoot: string, count: number, generateFn: (prompt: string) => Promise<string>): Promise<Selection[]>;
 export declare function llmSelectFiles(task: string, candidatePaths: string[], projectRoot: string, opts: {
     host: string;
     model: string;

package/dist/src/core/llmSelector.js

@@ -71,7 +71,8 @@ export function buildSelectionPrompt(task, candidates, count) {
         lines.push(`- ${c.path}: ${c.signature}`);
     }
     lines.push('');
-    lines.push(`Return the ${count} files most relevant to the task, most relevant first.`);
+    lines.push(`Return UP TO ${count} files that are genuinely relevant to the task, most relevant first.`);
+    lines.push('Include FEWER than ' + count + ' if fewer are truly relevant — do not pad the list with files that are empty or unrelated.');
     lines.push('Format each line exactly as:');
     lines.push('  PATH | one-line reason');
     lines.push('Only use paths from the candidate list above. No prose, no other text.');
@@ -118,17 +119,31 @@ export function parseSelectionResponse(response, candidates) {
  * "model ran but found nothing" (empty array) from "couldn't reach model"
  * (throw) — both lead to fallback, but the caller may log them differently.
  */
-export async function llmSelectFiles(task, candidatePaths, projectRoot, opts) {
-    const candidates = candidatePaths.map(p => ({
+/**
+ * Backend-agnostic file selection: builds the prompt, calls the provided
+ * generate function (Ollama or Gemini or any text model), parses + validates.
+ * The empty-file filter and hallucination guard apply regardless of backend.
+ */
+export async function selectFilesWithGenerate(task, candidatePaths, projectRoot, count, generateFn) {
+    const meaningful = candidatePaths.filter(p => {
+        try {
+            return fs.readFileSync(p, 'utf-8').trim().length >= 10;
+        }
+        catch {
+            return false;
+        }
+    });
+    const candidates = meaningful.map(p => ({
         path: path.relative(projectRoot, p),
         signature: buildSignature(p),
     }));
-    const prompt = buildSelectionPrompt(task, candidates, opts.count);
-    const response = await generate(opts.host, opts.model, prompt, {
-        timeoutMs: opts.timeoutMs,
-    });
+    const prompt = buildSelectionPrompt(task, candidates, count);
+    const response = await generateFn(prompt);
     return parseSelectionResponse(response, candidates);
 }
+export async function llmSelectFiles(task, candidatePaths, projectRoot, opts) {
+    return selectFilesWithGenerate(task, candidatePaths, projectRoot, opts.count, (prompt) => generate(opts.host, opts.model, prompt, { timeoutMs: opts.timeoutMs }));
+}
 // Re-export for callers that want to detect transport errors specifically.
 export { OllamaError };
 //# sourceMappingURL=llmSelector.js.map

package/dist/src/core/llmSelector.js.map

@@ -1 +1 @@
-{"version":3,"file":"llmSelector.js","sourceRoot":"","sources":["../../../src/core/llmSelector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"llmSelector.js","sourceRoot":"","sources":["../../../src/core/llmSelector.ts"],"names":[],"mappings":"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"}

package/dist/src/core/providers.d.ts

@@ -0,0 +1,60 @@
+/**
+ * OpenAI-compatible remote sous-chef providers (v0.3.5).
+ *
+ * Kimi (Moonshot), Grok (xAI), and ChatGPT (OpenAI) all expose the same
+ * OpenAI chat-completions API shape, so they share ONE client
+ * (openaiCompatGenerate) and differ only in configuration: base URL, default
+ * model, env var, and free-tier data-policy note. To users they're three
+ * distinct providers (three panels, three keys); under the hood, one code path.
+ *
+ * Gemini stays separate (core/gemini.ts) because its REST shape differs.
+ *
+ * PRIVACY: every provider here is a free tier that MAY train on inputs (Grok's
+ * free credits are explicitly a data-sharing program; Gemini likewise; Kimi
+ * verify per current terms). So all are governed by the same privacy gate in
+ * core/souschef.ts — decomposition by default, code only with allowRemoteCode.
+ * The freeTierNote is surfaced so the user sees the tradeoff per provider.
+ */
+export interface ProviderConfig {
+    id: string;
+    /** Human label for the cockpit. */
+    label: string;
+    /** OpenAI-compatible base URL (without the /chat/completions suffix). */
+    baseUrl: string;
+    /** Default model id for this provider's free/cheap tier. */
+    defaultModel: string;
+    /** Env var that holds this provider's API key. */
+    envVar: string;
+    /** One-line note on the free-tier data/training policy. */
+    freeTierNote: string;
+}
+/**
+ * The registry. Models/URLs verified around mid-2026; they drift, so they're
+ * config, not hardcoded logic — easy to bump. Pick exact models at use time if
+ * a default is deprecated.
+ */
+export declare const PROVIDERS: ProviderConfig[];
+export declare function getProvider(id: string): ProviderConfig | null;
+export declare class OpenAICompatError extends Error {
+    readonly quotaExhausted: boolean;
+    constructor(message: string, quotaExhausted?: boolean);
+}
+type FetchImpl = (url: string, init?: RequestInit) => Promise<Response>;
+export interface OpenAICompatCall {
+    baseUrl: string;
+    model: string;
+    apiKey: string;
+    timeoutMs: number;
+}
+export interface OpenAICompatDeps {
+    fetchImpl?: FetchImpl;
+}
+/** Extract the assistant message content from a chat-completions body. */
+export declare function parseChatCompletion(body: any): string;
+/**
+ * Call any OpenAI-compatible chat-completions endpoint. Returns the text on
+ * success; throws OpenAICompatError on any failure (quotaExhausted set for
+ * 429s) so callers fall back to a cheaper worker.
+ */
+export declare function openaiCompatGenerate(prompt: string, call: OpenAICompatCall, deps?: OpenAICompatDeps): Promise<string>;
+export {};

package/dist/src/core/providers.js

@@ -0,0 +1,117 @@
+/**
+ * OpenAI-compatible remote sous-chef providers (v0.3.5).
+ *
+ * Kimi (Moonshot), Grok (xAI), and ChatGPT (OpenAI) all expose the same
+ * OpenAI chat-completions API shape, so they share ONE client
+ * (openaiCompatGenerate) and differ only in configuration: base URL, default
+ * model, env var, and free-tier data-policy note. To users they're three
+ * distinct providers (three panels, three keys); under the hood, one code path.
+ *
+ * Gemini stays separate (core/gemini.ts) because its REST shape differs.
+ *
+ * PRIVACY: every provider here is a free tier that MAY train on inputs (Grok's
+ * free credits are explicitly a data-sharing program; Gemini likewise; Kimi
+ * verify per current terms). So all are governed by the same privacy gate in
+ * core/souschef.ts — decomposition by default, code only with allowRemoteCode.
+ * The freeTierNote is surfaced so the user sees the tradeoff per provider.
+ */
+/**
+ * The registry. Models/URLs verified around mid-2026; they drift, so they're
+ * config, not hardcoded logic — easy to bump. Pick exact models at use time if
+ * a default is deprecated.
+ */
+export const PROVIDERS = [
+    {
+        id: 'kimi',
+        label: 'Kimi',
+        baseUrl: 'https://api.moonshot.ai/v1',
+        defaultModel: 'kimi-k2.5',
+        envVar: 'MOONSHOT_API_KEY',
+        freeTierNote: 'Moonshot free tier (~1000 req/day); verify current training policy.',
+    },
+    {
+        id: 'grok',
+        label: 'Grok',
+        baseUrl: 'https://api.x.ai/v1',
+        defaultModel: 'grok-4.1-fast',
+        envVar: 'XAI_API_KEY',
+        freeTierNote: 'xAI free credits via data-sharing — inputs MAY train xAI models.',
+    },
+    {
+        id: 'openai',
+        label: 'ChatGPT',
+        baseUrl: 'https://api.openai.com/v1',
+        defaultModel: 'gpt-5.4-mini',
+        envVar: 'OPENAI_API_KEY',
+        freeTierNote: 'OpenAI API — check whether your account/tier trains on inputs.',
+    },
+];
+export function getProvider(id) {
+    return PROVIDERS.find(p => p.id === id) ?? null;
+}
+// --- the shared OpenAI-compatible client ---------------------------------
+export class OpenAICompatError extends Error {
+    quotaExhausted;
+    constructor(message, quotaExhausted = false) {
+        super(message);
+        this.name = 'OpenAICompatError';
+        this.quotaExhausted = quotaExhausted;
+    }
+}
+const DEFAULT_TIMEOUT = 30000;
+/** Extract the assistant message content from a chat-completions body. */
+export function parseChatCompletion(body) {
+    const choice = body?.choices?.[0];
+    const content = choice?.message?.content;
+    return typeof content === 'string' ? content : '';
+}
+/**
+ * Call any OpenAI-compatible chat-completions endpoint. Returns the text on
+ * success; throws OpenAICompatError on any failure (quotaExhausted set for
+ * 429s) so callers fall back to a cheaper worker.
+ */
+export async function openaiCompatGenerate(prompt, call, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+    const timeoutMs = call.timeoutMs ?? DEFAULT_TIMEOUT;
+    const url = `${call.baseUrl.replace(/\/$/, '')}/chat/completions`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${call.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: call.model,
+                messages: [{ role: 'user', content: prompt }],
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch (e) {
+        clearTimeout(timer);
+        const why = e?.name === 'AbortError' ? 'timed out' : e.message;
+        throw new OpenAICompatError(`request failed: ${why}`);
+    }
+    clearTimeout(timer);
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        throw new OpenAICompatError(`bad response (status ${response.status}, non-JSON)`);
+    }
+    if (!response.ok) {
+        const msg = body?.error?.message ?? `HTTP ${response.status}`;
+        const isQuota = response.status === 429;
+        throw new OpenAICompatError(`API error: ${msg}`, isQuota);
+    }
+    const text = parseChatCompletion(body).trim();
+    if (!text)
+        throw new OpenAICompatError('provider returned no usable text');
+    return text;
+}
+//# sourceMappingURL=providers.js.map

package/dist/src/core/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../../src/core/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAgBH;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAqB;IACzC;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,MAAM;QACb,OAAO,EAAE,4BAA4B;QACrC,YAAY,EAAE,WAAW;QACzB,MAAM,EAAE,kBAAkB;QAC1B,YAAY,EAAE,qEAAqE;KACpF;IACD;QACE,EAAE,EAAE,MAAM;QACV,KAAK,EAAE,MAAM;QACb,OAAO,EAAE,qBAAqB;QAC9B,YAAY,EAAE,eAAe;QAC7B,MAAM,EAAE,aAAa;QACrB,YAAY,EAAE,kEAAkE;KACjF;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,SAAS;QAChB,OAAO,EAAE,2BAA2B;QACpC,YAAY,EAAE,cAAc;QAC5B,MAAM,EAAE,gBAAgB;QACxB,YAAY,EAAE,gEAAgE;KAC/E;CACF,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,IAAI,IAAI,CAAC;AAClD,CAAC;AAED,4EAA4E;AAE5E,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,cAAc,CAAU;IACjC,YAAY,OAAe,EAAE,cAAc,GAAG,KAAK;QACjD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;IACvC,CAAC;CACF;AAeD,MAAM,eAAe,GAAG,KAAK,CAAC;AAE9B,0EAA0E;AAC1E,MAAM,UAAU,mBAAmB,CAAC,IAAS;IAC3C,MAAM,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;IAClC,MAAM,OAAO,GAAG,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC;IACzC,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,MAAc,EACd,IAAsB,EACtB,OAAyB,EAAE;IAE3B,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAK,UAAU,CAAC,KAAmB,CAAC;IACpE,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,eAAe,CAAC;IACpD,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,CAAC;IAElE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;IAE9D,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;YAC9B,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;aACvC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;aAC9C,CAAC;YACF,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,MAAM,GAAG,GAAI,CAAW,EAAE,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAE,CAAW,CAAC,OAAO,CAAC;QACrF,MAAM,IAAI,iBAAiB,CAAC,mBAAmB,GAAG,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,YAAY,CAAC,KAAK,CAAC,CAAC;IAEpB,IAAI,IAAS,CAAC;IACd,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,iBAAiB,CAAC,wBAAwB,QAAQ,CAAC,MAAM,aAAa,CAAC,CAAC;IACpF,CAAC;IAED,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,GAAG,GAAG,IAAI,EAAE,KAAK,EAAE,OAAO,IAAI,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC9D,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,KAAK,GAAG,CAAC;QACxC,MAAM,IAAI,iBAAiB,CAAC,cAAc,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,IAAI,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,iBAAiB,CAAC,kCAAkC,CAAC,CAAC;IAC3E,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/src/core/remoteRouter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Remote provider routing (v0.3.5).
+ *
+ * Picks which remote sous-chef to use among the configured providers, based on
+ * which one has a key available. Unifies the two client shapes — Gemini (its
+ * own REST) and the OpenAI-compatible trio (Kimi, Grok, ChatGPT) — behind one
+ * `generate(prompt)` function so callers (plan, selection, triage) don't care
+ * which provider answered.
+ *
+ * Priority order: Gemini first (the original, most-tested), then Kimi, Grok,
+ * ChatGPT. A caller may pass a preferred id to override the order when that
+ * provider has a key.
+ */
+export interface ResolvedProvider {
+    id: string;
+    label: string;
+    model: string;
+    key: string;
+    freeTierNote: string;
+    /** Run a prompt through this provider's client. Throws on failure. */
+    generate: (prompt: string, timeoutMs?: number) => Promise<string>;
+}
+/**
+ * Find the first remote provider that has a key. If `preferred` is given and
+ * that provider has a key, it wins; otherwise fall back to priority order.
+ */
+export declare function firstAvailableProvider(env?: Record<string, string | undefined>, preferred?: string, cwd?: string): ResolvedProvider | null;

package/dist/src/core/remoteRouter.js

@@ -0,0 +1,71 @@
+/**
+ * Remote provider routing (v0.3.5).
+ *
+ * Picks which remote sous-chef to use among the configured providers, based on
+ * which one has a key available. Unifies the two client shapes — Gemini (its
+ * own REST) and the OpenAI-compatible trio (Kimi, Grok, ChatGPT) — behind one
+ * `generate(prompt)` function so callers (plan, selection, triage) don't care
+ * which provider answered.
+ *
+ * Priority order: Gemini first (the original, most-tested), then Kimi, Grok,
+ * ChatGPT. A caller may pass a preferred id to override the order when that
+ * provider has a key.
+ */
+import { PROVIDERS, openaiCompatGenerate } from './providers.js';
+import { geminiGenerate } from './gemini.js';
+import { loadGeminiKey, loadProviderKey } from './keys.js';
+const GEMINI_MODEL = 'gemini-2.5-flash-lite';
+/** Priority order for auto-selection (Gemini first, then the OAI-compat trio). */
+const PRIORITY = ['gemini', 'kimi', 'grok', 'openai'];
+function makeGemini(key) {
+    return {
+        id: 'gemini',
+        label: 'Gemini',
+        model: GEMINI_MODEL,
+        key,
+        freeTierNote: 'Gemini free tier — inputs may train Google models.',
+        generate: (prompt, timeoutMs = 30000) => geminiGenerate(prompt, { apiKey: key, model: GEMINI_MODEL, timeoutMs }),
+    };
+}
+function makeOpenAICompat(p, key) {
+    return {
+        id: p.id,
+        label: p.label,
+        model: p.defaultModel,
+        key,
+        freeTierNote: p.freeTierNote,
+        generate: (prompt, timeoutMs = 30000) => openaiCompatGenerate(prompt, {
+            baseUrl: p.baseUrl, model: p.defaultModel, apiKey: key, timeoutMs,
+        }),
+    };
+}
+/** Resolve a single provider by id, if it has a key. */
+function resolveById(id, env, cwd) {
+    if (id === 'gemini') {
+        const key = loadGeminiKey(cwd, env);
+        return key ? makeGemini(key) : null;
+    }
+    const p = PROVIDERS.find(x => x.id === id);
+    if (!p)
+        return null;
+    const key = loadProviderKey(p.envVar, p.id, cwd, env);
+    return key ? makeOpenAICompat(p, key) : null;
+}
+/**
+ * Find the first remote provider that has a key. If `preferred` is given and
+ * that provider has a key, it wins; otherwise fall back to priority order.
+ */
+export function firstAvailableProvider(env = process.env, preferred, cwd = process.cwd()) {
+    if (preferred) {
+        const p = resolveById(preferred, env, cwd);
+        if (p)
+            return p;
+    }
+    for (const id of PRIORITY) {
+        const p = resolveById(id, env, cwd);
+        if (p)
+            return p;
+    }
+    return null;
+}
+//# sourceMappingURL=remoteRouter.js.map

package/dist/src/core/remoteRouter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remoteRouter.js","sourceRoot":"","sources":["../../../src/core/remoteRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,SAAS,EAAE,oBAAoB,EAAkB,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAY3D,MAAM,YAAY,GAAG,uBAAuB,CAAC;AAE7C,kFAAkF;AAClF,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEtD,SAAS,UAAU,CAAC,GAAW;IAC7B,OAAO;QACL,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,QAAQ;QACf,KAAK,EAAE,YAAY;QACnB,GAAG;QACH,YAAY,EAAE,oDAAoD;QAClE,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,GAAG,KAAK,EAAE,EAAE,CACtC,cAAc,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,CAAC;KAC1E,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,CAAiB,EAAE,GAAW;IACtD,OAAO;QACL,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,KAAK,EAAE,CAAC,CAAC,YAAY;QACrB,GAAG;QACH,YAAY,EAAE,CAAC,CAAC,YAAY;QAC5B,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,GAAG,KAAK,EAAE,EAAE,CACtC,oBAAoB,CAAC,MAAM,EAAE;YAC3B,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS;SAClE,CAAC;KACL,CAAC;AACJ,CAAC;AAED,wDAAwD;AACxD,SAAS,WAAW,CAClB,EAAU,EACV,GAAuC,EACvC,GAAW;IAEX,IAAI,EAAE,KAAK,QAAQ,EAAE,CAAC;QACpB,MAAM,GAAG,GAAG,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACpC,OAAO,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtC,CAAC;IACD,MAAM,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAC3C,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,GAAG,GAAG,eAAe,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACtD,OAAO,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,MAA0C,OAAO,CAAC,GAAG,EACrD,SAAkB,EAClB,MAAc,OAAO,CAAC,GAAG,EAAE;IAE3B,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,CAAC,GAAG,WAAW,CAAC,SAAS,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QAC3C,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;IAClB,CAAC;IACD,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,WAAW,CAAC,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;QACpC,IAAI,CAAC;YAAE,OAAO,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}