@vesk/agentic 0.2.11

package/README.md

@@ -0,0 +1,53 @@
+# @vesk/agentic
+
+Agentic AI plugin for Vesk — zero-deps agent loop, provider abstraction, permissions, tools, checkpoints. Vendored clone of `@narimangardi/agent-loop` (20.7kB, zero deps) — core Vesk ships no agent runtime.
+
+## Install
+
+```sh
+npm install @vesk/agentic
+```
+
+## Usage — add to `vesk.config.ts`
+
+```ts
+// vesk.config.ts
+import { defineConfig } from '@vesk/compiler';
+import agentic from '@vesk/agentic/src/plugin.js';
+
+export default defineConfig({
+  plugins: [
+    agentic({
+      provider: 'openai',          // 'openai' | 'openai-compatible' | 'anthropic' | 'google' | 'ollama'
+      model: 'gpt-4o-mini',
+      // apiKey: process.env.VESK_AGENTIC_API_KEY,
+      mode: 'explore',             // 'explore' | 'debug' | 'agent'
+      maxSteps: 10,
+    }),
+  ],
+});
+```
+
+- `provider`/`model`/`apiKey`/`baseUrl` are provider-agnostic — switching models never touches the agent implementation.
+- `mode` selects the default permission set (`explore`=read-only, `debug`=controlled fixes, `agent`=per-capability toggles). All checks are server-enforced via the Dev Server capability gate.
+- When the plugin is inactive (toggled off in the devtool or not listed), it is fully excluded from the build — zero bundle/build cost.
+
+## DevTools AI panel
+
+When `@vesk/agentic` is installed & active, `vesk dev` exposes the **AI** panel in the devtools overlay:
+
+- Provider / model / key config (shown only when the plugin is active)
+- Mode + granular permissions (`readFiles`, `writeFiles`, `deleteFiles`, `executeCommands`, `installPackages`, `modifyConfig`, `managePlugins`, `runBuild`, `runTests`, `modifyAgentsMd`, `createCheckpoint`, `rollback`)
+- Layered context (framework knowledge + project `agents.md` + live project state via Dev Server)
+- Vesk-native tools (`vesk.inspectProject`, `vesk.readConfig`, `vesk.runBuild`, `vesk.createCheckpoint`, etc.) gated by permissions
+- Checkpoints / history / rollback — every agent action checkpoints; rollback restores prior file state
+
+Inactive ⇒ the AI panel is hidden and no agent code is bundled.
+
+## Zero dependencies
+
+No runtime deps on `openai`, `@anthropic-ai/sdk`, `@google/genai`, or `@aws-sdk`. Each provider is a fetch-only adapter; bring your own key.
+
+## License
+
+MIT

package/dist/checkpoints.d.ts

@@ -0,0 +1,155 @@
+/**
+ * @vesk/agentic — checkpoints & transactions
+ *
+ * Zero-deps checkpoint system for agent operations.
+ *
+ * Two complementary surfaces in one module (both zero-deps):
+ *
+ *  1. `CheckpointManager` — in-memory, browser-safe manager for `Preview → Approve → Execute → Validate → Checkpoint`
+ *     flows inside the agent loop. Persists only metadata; caller restores files.
+ *
+ *  2. File-system store — `createCheckpoint(projectDir, message, changes, buildResult)` and friends
+ *     persisting to `<projectDir>/.vesk/agentic/history.json` + `checkpoints/{id}/checkpoint.json`.
+ *     Used by `@vesk/agentic` Dev Server router (`createAgentRouter`) and `vesk.*` tools (`createVeskTools`).
+ *
+ * Both surfaces share the same unified `Checkpoint` shape (superset of manager + file-system fields)
+ * so the Dev Server router and in-memory tests interoperate without type drift.
+ */
+export interface CheckpointFile {
+    path: string;
+    before: string | null;
+    after: string | null;
+}
+export interface CheckpointDeps {
+    installed: string[];
+    removed: string[];
+}
+export interface CheckpointBuild {
+    ok: boolean;
+    error?: string;
+    ms?: number;
+}
+export interface CheckpointTest {
+    ok: boolean;
+    error?: string;
+}
+export interface CheckpointCommand {
+    argv: string[];
+    stdout: string;
+    stderr: string;
+    code: number | null;
+}
+export interface CheckpointBuildResult {
+    success: boolean;
+    output?: string;
+    errors?: string[];
+    [k: string]: unknown;
+}
+export interface Checkpoint {
+    id: string;
+    timestamp: number;
+    createdAt: string;
+    message: string;
+    label?: string;
+    prompt?: string;
+    files: CheckpointFile[];
+    commands: string[][] | CheckpointCommand[];
+    deps: CheckpointDeps | string[];
+    build: CheckpointBuild | null;
+    test: CheckpointTest | null;
+    buildResult?: unknown;
+    parentId?: string;
+}
+export interface CreateCheckpointOptions {
+    id?: string;
+    label?: string;
+    message?: string;
+    prompt?: string;
+    files?: CheckpointFile[];
+    commands?: string[][] | CheckpointCommand[];
+    deps?: Partial<CheckpointDeps> | string[];
+    build?: CheckpointBuild | null;
+    test?: CheckpointTest | null;
+    buildResult?: unknown;
+    parentId?: string;
+    createdAt?: string;
+    timestamp?: number;
+}
+export interface CheckpointChanges {
+    files?: CheckpointFile[];
+    commands?: CheckpointCommand[] | string[][];
+    deps?: string[] | CheckpointDeps;
+    parentId?: string;
+    prompt?: string;
+}
+export interface TransactionPreview {
+    files: CheckpointFile[];
+    commands?: CheckpointCommand[] | string[][];
+    deps?: string[] | CheckpointDeps;
+    message?: string;
+    prompt?: string;
+}
+export interface TransactionOptions {
+    message: string;
+    prompt?: string;
+    parentId?: string;
+    preview: () => TransactionPreview | Promise<TransactionPreview>;
+    approve: (preview: TransactionPreview) => boolean | Promise<boolean>;
+    execute: () => {
+        files?: CheckpointFile[];
+        commands?: CheckpointCommand[] | string[][];
+        deps?: string[] | CheckpointDeps;
+    } | void | Promise<{
+        files?: CheckpointFile[];
+        commands?: CheckpointCommand[] | string[][];
+        deps?: string[] | CheckpointDeps;
+    } | void>;
+    validate?: () => unknown | Promise<unknown>;
+}
+export declare class CheckpointManager {
+    private store;
+    private order;
+    private readonly maxKeep;
+    constructor(opts?: {
+        maxKeep?: number;
+    });
+    create(opts?: CreateCheckpointOptions): Checkpoint;
+    list(): Checkpoint[];
+    listNewestFirst(): Checkpoint[];
+    get(id: string): Checkpoint | undefined;
+    has(id: string): boolean;
+    delete(id: string): boolean;
+    clear(): void;
+    size(): number;
+    /**
+     * Rollback plan for a checkpoint: returns the files that must be restored
+     * to their `before` state. Caller is responsible for actually writing/deleting files.
+     * Returns null if checkpoint does not exist.
+     */
+    rollback(id: string): {
+        id: string;
+        checkpoint: Checkpoint;
+        filesToRestore: CheckpointFile[];
+    } | null;
+    /**
+     * Helper: build a rollback summary describing what filesystem actions are required.
+     */
+    static describeRollback(files: CheckpointFile[]): {
+        writes: number;
+        deletes: number;
+        creates: number;
+    };
+}
+export declare function getAgenticDir(projectDir: string): string;
+export declare function getHistoryPath(projectDir: string): string;
+export declare function getCheckpointDir(projectDir: string, id: string): string;
+export declare function getCheckpointPath(projectDir: string, id: string): string;
+export declare function createCheckpoint(projectDir: string, message: string, changes?: CheckpointChanges, buildResult?: unknown): Checkpoint;
+export declare function listCheckpoints(projectDir: string): Checkpoint[];
+export declare function getCheckpoint(projectDir: string, id: string): Checkpoint | null;
+export declare function rollback(projectDir: string, id: string): Checkpoint | null;
+export declare function withTransaction(projectDir: string, options: TransactionOptions): Promise<Checkpoint | null>;
+export declare function deleteCheckpoint(projectDir: string, id: string): boolean;
+export declare function clearCheckpoints(projectDir: string): void;
+export declare function ensureAgenticStore(projectDir: string): void;
+//# sourceMappingURL=checkpoints.d.ts.map

package/dist/checkpoints.d.ts.map

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

package/dist/checkpoints.js

@@ -0,0 +1,394 @@
+/**
+ * @vesk/agentic — checkpoints & transactions
+ *
+ * Zero-deps checkpoint system for agent operations.
+ *
+ * Two complementary surfaces in one module (both zero-deps):
+ *
+ *  1. `CheckpointManager` — in-memory, browser-safe manager for `Preview → Approve → Execute → Validate → Checkpoint`
+ *     flows inside the agent loop. Persists only metadata; caller restores files.
+ *
+ *  2. File-system store — `createCheckpoint(projectDir, message, changes, buildResult)` and friends
+ *     persisting to `<projectDir>/.vesk/agentic/history.json` + `checkpoints/{id}/checkpoint.json`.
+ *     Used by `@vesk/agentic` Dev Server router (`createAgentRouter`) and `vesk.*` tools (`createVeskTools`).
+ *
+ * Both surfaces share the same unified `Checkpoint` shape (superset of manager + file-system fields)
+ * so the Dev Server router and in-memory tests interoperate without type drift.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync, unlinkSync, rmSync, renameSync } from 'node:fs';
+import { join, resolve, dirname, sep } from 'node:path';
+import { randomUUID as nodeRandomUUID } from 'node:crypto';
+function generateId() {
+    // Prefer crypto.randomUUID when available (Node 19+, browsers), fallback to Math.random.
+    try {
+        const c = globalThis.crypto;
+        if (c?.randomUUID)
+            return c.randomUUID();
+    }
+    catch { }
+    try {
+        return nodeRandomUUID();
+    }
+    catch { }
+    return `chk_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+export class CheckpointManager {
+    store = new Map();
+    order = [];
+    maxKeep;
+    constructor(opts) {
+        this.maxKeep = opts?.maxKeep;
+    }
+    create(opts = {}) {
+        const id = opts.id ?? generateId();
+        const createdAt = opts.createdAt ?? new Date().toISOString();
+        const timestamp = opts.timestamp ?? (Date.parse(createdAt) || Date.now());
+        // message/label are aliases — populate both from whichever is provided
+        const rawMessage = opts.message ?? opts.label ?? '';
+        const label = opts.label ?? (rawMessage || undefined);
+        const message = rawMessage || (opts.label ?? '');
+        // Normalize deps: object {installed, removed} or string[] → union kept as-is but object is canonical for manager
+        let deps = { installed: [], removed: [] };
+        if (Array.isArray(opts.deps))
+            deps = [...opts.deps];
+        else if (opts.deps && typeof opts.deps === 'object') {
+            const d = opts.deps;
+            deps = { installed: d.installed ? [...d.installed] : [], removed: d.removed ? [...d.removed] : [] };
+        }
+        // Normalize commands: keep as provided (string[][] or CheckpointCommand[])
+        let commands = [];
+        if (Array.isArray(opts.commands)) {
+            // Detect which shape by inspecting first element
+            const first = opts.commands[0];
+            if (first && typeof first === 'object' && !Array.isArray(first) && 'argv' in first) {
+                commands = opts.commands.map((c) => ({ ...c }));
+            }
+            else {
+                commands = opts.commands.map((c) => [...c]);
+            }
+        }
+        const checkpoint = {
+            id,
+            timestamp,
+            createdAt,
+            message,
+            label,
+            prompt: opts.prompt,
+            files: opts.files ? opts.files.map((f) => ({ ...f })) : [],
+            commands,
+            deps,
+            build: opts.build !== undefined ? (opts.build ? { ...opts.build } : null) : null,
+            test: opts.test !== undefined ? (opts.test ? { ...opts.test } : null) : null,
+            ...(opts.buildResult !== undefined ? { buildResult: opts.buildResult } : {}),
+            ...(opts.parentId ? { parentId: opts.parentId } : {}),
+        };
+        // If id already exists, remove old position (idempotent update)
+        if (this.store.has(id)) {
+            this.order = this.order.filter((x) => x !== id);
+        }
+        this.store.set(id, checkpoint);
+        this.order.push(id);
+        // Prune oldest when over maxKeep
+        if (this.maxKeep !== undefined && this.order.length > this.maxKeep) {
+            const excess = this.order.length - this.maxKeep;
+            for (let i = 0; i < excess; i++) {
+                const oldest = this.order.shift();
+                this.store.delete(oldest);
+            }
+        }
+        return checkpoint;
+    }
+    list() {
+        // Oldest-first (insertion order) — callers can reverse for newest-first UI.
+        return this.order.map((id) => this.store.get(id));
+    }
+    listNewestFirst() {
+        return [...this.list()].reverse();
+    }
+    get(id) {
+        return this.store.get(id);
+    }
+    has(id) {
+        return this.store.has(id);
+    }
+    delete(id) {
+        const ok = this.store.delete(id);
+        if (ok)
+            this.order = this.order.filter((x) => x !== id);
+        return ok;
+    }
+    clear() {
+        this.store.clear();
+        this.order = [];
+    }
+    size() {
+        return this.store.size;
+    }
+    /**
+     * Rollback plan for a checkpoint: returns the files that must be restored
+     * to their `before` state. Caller is responsible for actually writing/deleting files.
+     * Returns null if checkpoint does not exist.
+     */
+    rollback(id) {
+        const cp = this.store.get(id);
+        if (!cp)
+            return null;
+        return {
+            id,
+            checkpoint: cp,
+            filesToRestore: cp.files.map((f) => ({ ...f })),
+        };
+    }
+    /**
+     * Helper: build a rollback summary describing what filesystem actions are required.
+     */
+    static describeRollback(files) {
+        let writes = 0;
+        let deletes = 0;
+        let creates = 0;
+        for (const f of files) {
+            if (f.before === null && f.after !== null)
+                deletes++; // file was created → delete it
+            else if (f.before !== null && f.after === null)
+                creates++; // file was deleted → recreate
+            else if (f.before !== null)
+                writes++; // modified → overwrite
+            // before===null && after===null → no-op (should not happen)
+        }
+        return { writes, deletes, creates };
+    }
+}
+// ── File-system store (persisted) ────────────────────────────────────────────
+// Mirrors the original file-system implementation (now unified with Manager's shape)
+// so `createVeskTools` and `createAgentRouter` keep working.
+export function getAgenticDir(projectDir) {
+    return join(resolve(projectDir), '.vesk', 'agentic');
+}
+export function getHistoryPath(projectDir) {
+    return join(getAgenticDir(projectDir), 'history.json');
+}
+export function getCheckpointDir(projectDir, id) {
+    return join(getAgenticDir(projectDir), 'checkpoints', id);
+}
+export function getCheckpointPath(projectDir, id) {
+    return join(getCheckpointDir(projectDir, id), 'checkpoint.json');
+}
+function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true });
+}
+function readJson(filePath, fallback) {
+    try {
+        if (!existsSync(filePath))
+            return fallback;
+        const raw = readFileSync(filePath, 'utf-8');
+        if (raw.trim() === '')
+            return fallback;
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+function writeJsonAtomic(filePath, data) {
+    ensureDir(dirname(filePath));
+    const tmp = `${filePath}.tmp`;
+    writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf-8');
+    try {
+        renameSync(tmp, filePath);
+    }
+    catch {
+        try {
+            writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+            try {
+                unlinkSync(tmp);
+            }
+            catch { }
+        }
+        catch { }
+    }
+}
+function readHistory(projectDir) {
+    const p = getHistoryPath(projectDir);
+    const data = readJson(p, []);
+    return Array.isArray(data) ? data : [];
+}
+function writeHistory(projectDir, history) {
+    writeJsonAtomic(getHistoryPath(projectDir), history);
+}
+export function createCheckpoint(projectDir, message, changes = {}, buildResult) {
+    const id = generateId();
+    const timestamp = Date.now();
+    const createdAt = new Date(timestamp).toISOString();
+    const files = changes.files ? changes.files.map((f) => ({ ...f })) : [];
+    // Normalize commands/deps
+    let commands = [];
+    if (changes.commands) {
+        const first = changes.commands[0];
+        if (first && typeof first === 'object' && !Array.isArray(first) && 'argv' in first) {
+            commands = changes.commands.map((c) => ({ ...c }));
+        }
+        else {
+            commands = changes.commands.map((c) => [...c]);
+        }
+    }
+    let deps = [];
+    if (Array.isArray(changes.deps))
+        deps = [...changes.deps];
+    else if (changes.deps && typeof changes.deps === 'object') {
+        const d = changes.deps;
+        deps = { installed: d.installed ? [...d.installed] : [], removed: d.removed ? [...d.removed] : [] };
+    }
+    const checkpoint = {
+        id,
+        timestamp,
+        createdAt,
+        message,
+        label: message,
+        prompt: changes.prompt,
+        files,
+        commands,
+        deps,
+        build: null,
+        test: null,
+        ...(buildResult !== undefined ? { buildResult } : {}),
+        ...(changes.parentId ? { parentId: changes.parentId } : {}),
+    };
+    const agenticDir = getAgenticDir(projectDir);
+    ensureDir(agenticDir);
+    ensureDir(join(agenticDir, 'checkpoints'));
+    const cpDir = getCheckpointDir(projectDir, id);
+    ensureDir(cpDir);
+    writeJsonAtomic(getCheckpointPath(projectDir, id), checkpoint);
+    const history = readHistory(projectDir);
+    history.unshift(checkpoint);
+    writeHistory(projectDir, history);
+    return checkpoint;
+}
+export function listCheckpoints(projectDir) {
+    const history = readHistory(projectDir);
+    return [...history].sort((a, b) => (b.timestamp ?? 0) - (a.timestamp ?? 0));
+}
+export function getCheckpoint(projectDir, id) {
+    const cpPath = getCheckpointPath(projectDir, id);
+    const fromFile = readJson(cpPath, null);
+    if (fromFile && typeof fromFile === 'object' && fromFile.id === id)
+        return fromFile;
+    const history = readHistory(projectDir);
+    return history.find((c) => c.id === id) ?? null;
+}
+export function rollback(projectDir, id) {
+    const cp = getCheckpoint(projectDir, id);
+    if (!cp)
+        return null;
+    const projectRoot = resolve(projectDir);
+    for (const f of cp.files) {
+        if (!f.path || !f.path.trim())
+            continue;
+        const abs = resolve(projectRoot, f.path);
+        if (f.before === null) {
+            try {
+                if (existsSync(abs)) {
+                    const s = statSync(abs);
+                    if (s.isDirectory())
+                        rmSync(abs, { recursive: true, force: true });
+                    else
+                        unlinkSync(abs);
+                }
+            }
+            catch { }
+        }
+        else {
+            try {
+                ensureDir(dirname(abs));
+                writeFileSync(abs, f.before, 'utf-8');
+            }
+            catch { }
+        }
+    }
+    return cp;
+}
+export async function withTransaction(projectDir, options) {
+    const preview = await options.preview();
+    const approved = await options.approve(preview);
+    if (!approved)
+        return null;
+    const executedRaw = await options.execute();
+    const executed = (executedRaw ?? {});
+    const files = executed.files ?? preview.files ?? [];
+    const commands = executed.commands ?? preview.commands ?? [];
+    const deps = executed.deps ?? preview.deps ?? [];
+    let buildResult;
+    if (options.validate) {
+        const v = await options.validate();
+        buildResult = typeof v === 'boolean' ? { success: v } : v;
+    }
+    let parentId = options.parentId;
+    if (!parentId) {
+        const latest = listCheckpoints(projectDir)[0];
+        if (latest)
+            parentId = latest.id;
+    }
+    const message = options.message;
+    const changes = {
+        files,
+        commands: commands,
+        deps: deps,
+        ...(parentId ? { parentId } : {}),
+        ...(options.prompt ? { prompt: options.prompt } : {}),
+        ...(preview.prompt ? { prompt: preview.prompt } : {}),
+    };
+    return createCheckpoint(projectDir, message, changes, buildResult);
+}
+export function deleteCheckpoint(projectDir, id) {
+    const cpDir = getCheckpointDir(projectDir, id);
+    let existed = false;
+    try {
+        if (existsSync(cpDir)) {
+            rmSync(cpDir, { recursive: true, force: true });
+            existed = true;
+        }
+    }
+    catch { }
+    const history = readHistory(projectDir);
+    const next = history.filter((c) => c.id !== id);
+    if (next.length !== history.length) {
+        writeHistory(projectDir, next);
+        existed = true;
+    }
+    else {
+        const cpPath = getCheckpointPath(projectDir, id);
+        if (existsSync(cpPath)) {
+            try {
+                unlinkSync(cpPath);
+            }
+            catch { }
+            existed = true;
+        }
+    }
+    return existed;
+}
+export function clearCheckpoints(projectDir) {
+    const agenticDir = getAgenticDir(projectDir);
+    const historyPath = getHistoryPath(projectDir);
+    try {
+        if (existsSync(historyPath))
+            unlinkSync(historyPath);
+    }
+    catch { }
+    const checkpointsRoot = join(agenticDir, 'checkpoints');
+    try {
+        if (existsSync(checkpointsRoot))
+            rmSync(checkpointsRoot, { recursive: true, force: true });
+    }
+    catch { }
+}
+export function ensureAgenticStore(projectDir) {
+    const dir = getAgenticDir(projectDir);
+    ensureDir(dir);
+    ensureDir(join(dir, 'checkpoints'));
+    const hp = getHistoryPath(projectDir);
+    if (!existsSync(hp))
+        writeJsonAtomic(hp, []);
+}
+// Ensure sep is used (avoid unused import warning)
+void sep;

package/dist/config.d.ts

@@ -0,0 +1,57 @@
+export interface AgenticConfig {
+    provider: 'openai' | 'anthropic' | 'google' | 'ollama' | 'opencode' | 'opencode-go' | 'openrouter' | 'loopers' | 'custom';
+    model: string;
+    baseUrl?: string;
+    mode: 'explore' | 'debug' | 'agent';
+    maxSteps: number;
+}
+export declare const SUPPORTED_PROVIDERS: string[];
+export declare function providerDotenvVar(provider: string): string;
+export declare function dotenvPath(projectDir: string): string;
+/**
+ * Read a provider key from the project `.env.local` file.
+ * Note: normally `process.env` already reflects `.env.local` (loaded at CLI
+ * startup); this reads the file directly as a defensive fallback (e.g. when
+ * the file changed after startup, or callers didn't go through loadEnvFiles).
+ */
+export declare function readDotenvValue(projectDir: string, key: string, def?: string | null): string | null;
+/**
+ * Set a `KEY=VALUE` line in the project `.env.local`, creating the file if
+ * missing, updating in place if present. Also mirrors into `process.env` so
+ * the current process sees it immediately. Returns true on success.
+ */
+export declare function writeDotenvValue(projectDir: string, key: string, value: string): boolean;
+export declare function loadAgenticConfig(projectDir: string): AgenticConfig & {
+    hasKey: boolean;
+};
+export declare function saveAgenticConfig(projectDir: string, patch: Partial<AgenticConfig>): AgenticConfig;
+export declare function maskApiKey(apiKey: string | null | undefined): string | null;
+export declare const maskKey: typeof maskApiKey;
+export declare const maskedPreview: typeof maskApiKey;
+export declare function getMaskedKey(projectDir: string, provider: string): string | null;
+export declare function getApiKeyPreview(projectDir: string, provider: string): string | null;
+export declare function getMaskedPreview(projectDir: string, provider: string): string | null;
+export declare function getKeyPreview(projectDir: string, provider: string): string | null;
+/**
+ * Save an API key for a specific provider.
+ *
+ * Supports both new 3-arg form `saveApiKey(projectDir, provider, apiKey)`
+ * and legacy 2-arg form `saveApiKey(projectDir, apiKey)` for backward compat.
+ * Keys are stored in project `.env.local` as VK_{PROVIDER}_KEY (0600).
+ * The legacy 2-arg form targets the currently-configured provider.
+ */
+export declare function saveApiKey(projectDir: string, providerOrApiKey: string, apiKeyMaybe?: string): void;
+/**
+ * Get API key for a provider.
+ * Precedence:
+ *   1. .env.local VK_{PROVIDER}_KEY (primary store; reflected in process.env)
+ *   2. (fallback) legacy .vesk/agentic/keys/{provider}.key
+ * If `provider` is omitted, returns the key for the currently-configured
+ * provider, else null.
+ */
+export declare function getApiKey(projectDir: string, provider?: string): string | null;
+export declare function hasApiKey(projectDirOrProvider: string, providerMaybe?: string): boolean;
+export declare const hasKey: typeof hasApiKey;
+export declare const hasApiKeys: typeof hasApiKey;
+export declare function listApiKeys(projectDir: string): Record<string, boolean>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,aAAa,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC1H,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;CAClB;AASD,eAAO,MAAM,mBAAmB,EAAE,MAAM,EAGvC,CAAC;AAkCF,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAI1D;AACD,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,GAAG,IAAW,GAAG,MAAM,GAAG,IAAI,CAmBzG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CA4BxF;AAMD,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,GAAG;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAYzF;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CASlG;AAMD,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAM3E;AAGD,eAAO,MAAM,OAAO,mBAAa,CAAC;AAClC,eAAO,MAAM,aAAa,mBAAa,CAAC;AACxC,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEhF;AACD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEpF;AACD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEpF;AACD,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKjF;AA2BD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAyBnG;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA4B9E;AAID,wBAAgB,SAAS,CAAC,oBAAoB,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAmCvF;AAGD,eAAO,MAAM,MAAM,kBAAY,CAAC;AAEhC,eAAO,MAAM,UAAU,kBAAY,CAAC;AAIpC,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsCvE"}