vault-go 0.11.0 → 0.13.0

package/README.md

@@ -89,6 +89,9 @@ bunx --bun vault-go@latest setup
 bunx --bun vault-go@latest setup --clients codex,claude,copilot
 bunx --bun vault-go@latest login --force
 bunx --bun vault-go@latest serve
+bunx --bun vault-go@latest engine list
+bunx --bun vault-go@latest engine use openrouter
+bunx --bun vault-go@latest engine key openrouter
 ```
 
 As credenciais são gravadas em `~/.memvault/auth.json` com permissão `0600`;
@@ -159,6 +162,11 @@ limitados.
 - `vault_go_knowledge_query`: recupera contexto fundamentado e citações dentro da base.
 - `vault_go_knowledge_delete`: remove a base e preserva as memórias originais.
 - `vault_go_forget`: exclusão explícita de uma memória.
+- `vault_go_engines`: lista motores de contexto (Vault AI, Claude, OpenRouter, Gemini, ChatGPT/Codex) sem revelar chaves.
+- `vault_go_engine_select`: escolhe o motor local (`vault-ai-resume`, `claude-subscription`, `openai-subscription`, `openrouter`, `gemini`).
+- `vault_go_generate_context`: gera título, fatos e conceitos com o motor escolhido; não persiste memória sozinho.
+
+O seletor de motor segue o mesmo modelo do claude-mem: Claude (CLI da assinatura), OpenRouter (chave), Gemini (chave) ou o Vault AI Resume da conta. Grave chaves com `vault-go engine key openrouter|gemini` ou no painel local; as ferramentas MCP não aceitam segredos.
 
 O recurso `vault-go://status` fornece o resumo sanitizado em JSON.
 
@@ -241,6 +249,8 @@ local, atividade MCP recente, projetos e memórias consultados na nuvem.
 Atualiza a interface a cada 5 segundos enquanto visível e consulta a nuvem
 a cada 15 segundos. Sem conexão, conserva o último cache da mesma conta.
 
+Abra http://localhost:38850 e clique em **Conectar ao Vault** para entrar pelo navegador. A senha permanece no portal; o painel libera a sessão somente após confirmar o retorno OAuth com PKCE. A tela oferece próximos passos para configurar clientes e registrar a primeira memória. A logo e as cores são as mesmas do portal.
+
 O serviço escuta exclusivamente em 127.0.0.1:38850. `local open` verifica
 uma prova criptográfica do serviço e abre uma sessão privada no navegador;
 o segredo local é removido do fragmento imediatamente e trocado por cookie
@@ -259,3 +269,32 @@ pelo MCP Vault, sem argumentos, consultas ou credenciais. Não captura toda a
 atividade da máquina nem importa automaticamente o banco do claude-mem em
 37701. A sincronização deste painel é de leitura da nuvem; as ferramentas
 MCP continuam responsáveis pelas gravações na API.
+
+### Sessões, dispositivos e proteção local
+
+**Sair** encerra a sessão desta página e cancela suas prévias de contexto.
+**Desconectar dispositivo** pede confirmação, revoga as credenciais do agente
+na nuvem e remove a autenticação e o cache local após sucesso. Os arquivos
+pessoais permanecem intactos. Para reconectar, entre novamente pelo navegador.
+O portal mostra último contato, permissões e permite revogar cada agente.
+
+O cache e a credencial de monitoramento usam AES-256-GCM. No macOS, a chave
+fica no Keychain; nos demais sistemas, em arquivo privado `0600`. Os tokens
+MCP existentes continuam em arquivo privado. O painel informa essas diferenças:
+cache cifrado não significa que todas as memórias sejam criptografadas ponta a
+ponta. O cofre de arquivos e o canal do terminal têm seus próprios protocolos.
+
+### Motor de contexto
+
+Escolha **Vault AI Resume**, **Claude Subscription** ou **OpenAI Subscription**
+no painel local. A disponibilidade é verificada antes da geração. Claude usa
+`claude auth login`; OpenAI usa `codex login` com uma conta ChatGPT. O agente
+não pede nem copia credenciais desses provedores. O modelo gerenciado depende
+de configuração e quota no servidor Vault.
+
+A geração exige texto e consentimento explícito, usa diretório temporário,
+limites de entrada/saída e timeout, e permite cancelamento. CLIs recebem apenas
+o texto informado, com ferramentas/configurações locais desativadas conforme
+os recursos suportados. O resultado é uma prévia privada da sessão, disponível
+para copiar; não é salvo automaticamente como memória. Os planos e limites do
+provedor escolhido se aplicam. Cancelar não garante estorno de uso já iniciado.

package/dist/activity.js

@@ -1,29 +1,44 @@
-import { appendFileSync, chmodSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { randomUUID } from 'node:crypto';
+import { appendFileSync, chmodSync, mkdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
 export function recordActivity(home, operation, ok, durationMs) {
     try {
         mkdirSync(home, { recursive: true, mode: 0o700 });
-        const file = join(home, 'local-activity.jsonl');
+        const file = join(home, "local-activity.jsonl");
         // Bounded journal contains metadata only: never arguments, content or credentials.
         try {
             if (statSync(file).size > 2 * 1024 * 1024)
-                writeFileSync(file, '', { mode: 0o600 });
+                writeFileSync(file, "", { mode: 0o600 });
         }
         catch { }
-        appendFileSync(file, JSON.stringify({ id: randomUUID(), time: new Date().toISOString(), operation: operation.slice(0, 180), ok, durationMs: Math.round(durationMs) }) + '\n', { mode: 0o600 });
+        appendFileSync(file, JSON.stringify({
+            id: randomUUID(),
+            time: new Date().toISOString(),
+            operation: operation.slice(0, 180),
+            ok,
+            durationMs: Math.round(durationMs),
+        }) + "\n", { mode: 0o600 });
         chmodSync(file, 0o600);
     }
-    catch { /* Observability must never prevent an MCP operation. */ }
+    catch {
+        /* Observability must never prevent an MCP operation. */
+    }
 }
 export function readActivity(home) {
     try {
-        return readFileSync(join(home, 'local-activity.jsonl'), 'utf8').split('\n').filter(Boolean).slice(-100).flatMap(line => { try {
-            return [JSON.parse(line)];
-        }
-        catch {
-            return [];
-        } }).reverse();
+        return readFileSync(join(home, "local-activity.jsonl"), "utf8")
+            .split("\n")
+            .filter(Boolean)
+            .slice(-100)
+            .flatMap((line) => {
+            try {
+                return [JSON.parse(line)];
+            }
+            catch {
+                return [];
+            }
+        })
+            .reverse();
     }
     catch {
         return [];

package/dist/auth.d.ts

@@ -10,6 +10,8 @@ export declare function validateExistingAuthentication(home: string, fetcher?: F
 export declare function openVaultBrowser(url: string): Promise<void>;
 export declare function authenticateWithBrowser(home: string, options?: {
     locale?: Locale;
+    callbackHtml?: string;
+    signal?: AbortSignal;
     fetcher?: Fetcher;
     openBrowser?: (url: string) => Promise<void>;
     timeoutMs?: number;

package/dist/auth.js

@@ -128,7 +128,7 @@ export async function authenticateWithBrowser(home, options = {}) {
     const server = createServer((req, res) => {
         res.setHeader('Cache-Control', 'no-store');
         res.setHeader('Referrer-Policy', 'no-referrer');
-        res.setHeader('Content-Security-Policy', "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'");
+        res.setHeader('Content-Security-Policy', "default-src 'none'; img-src data:; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'");
         let url;
         try {
             url = new URL(req.url ?? '/', `http://127.0.0.1:${port}`);
@@ -160,11 +160,15 @@ export async function authenticateWithBrowser(home, options = {}) {
         }
         accepted = true;
         res.setHeader('Content-Type', 'text/html; charset=utf-8');
-        res.end(callbackPage(locale));
+        res.end(options.callbackHtml ?? callbackPage(locale));
         claim?.(code);
     });
     let timer;
+    const abort = () => rejectClaim?.(new Error(t.denied));
+    options.signal?.addEventListener('abort', abort, { once: true });
     try {
+        if (options.signal?.aborted)
+            throw new Error(t.denied);
         await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
         const address = server.address();
         if (!address || typeof address === 'string')
@@ -197,6 +201,7 @@ export async function authenticateWithBrowser(home, options = {}) {
         return { email: account.email, method: 'browser' };
     }
     finally {
+        options.signal?.removeEventListener('abort', abort);
         if (timer)
             clearTimeout(timer);
         server.closeAllConnections();

package/dist/callback-page.d.ts

@@ -1,3 +1,3 @@
-import { type Locale } from './locale.js';
+import { type Locale } from "./locale.js";
 /** All interpolated content is from the static locale catalog, never the callback URL. */
-export declare function callbackPage(locale: Locale): string;
+export declare function callbackPage(locale: Locale, dashboardUrl?: string): string;

package/dist/callback-page.js

@@ -1,8 +1,33 @@
-import { copy } from './locale.js';
+import { readFileSync } from "node:fs";
+import { copy } from "./locale.js";
 /** All interpolated content is from the static locale catalog, never the callback URL. */
-export function callbackPage(locale) {
-    const t = copy[locale];
+export function callbackPage(locale, dashboardUrl) {
+    const base = copy[locale];
+    const local = {
+        pt: {
+            body: "Sua conexão está sendo concluída. Volte ao painel local para acompanhar suas memórias.",
+            step2: "Retorno seguro recebido nesta máquina",
+            step3: "Abra o painel para acompanhar a conexão",
+            back: "Voltar ao painel local",
+        },
+        en: {
+            body: "Your connection is being completed. Return to the local dashboard to follow your memories.",
+            step2: "Secure callback received on this machine",
+            step3: "Open the dashboard to follow the connection",
+            back: "Return to local dashboard",
+        },
+        es: {
+            body: "Tu conexión se está completando. Vuelve al panel local para consultar tus memorias.",
+            step2: "Retorno seguro recibido en esta máquina",
+            step3: "Abre el panel para consultar la conexión",
+            back: "Volver al panel local",
+        },
+    };
+    const t = dashboardUrl ? { ...base, ...local[locale] } : base;
+    if (dashboardUrl && !/^http:\/\/localhost:\d+\/$/.test(dashboardUrl))
+        throw new Error("Invalid dashboard callback");
+    const logo = readFileSync(new URL("../assets/vault-logo-glass.png", import.meta.url)).toString("base64");
     return `<!doctype html><html lang="${locale}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="color-scheme" content="dark"><title>AI Vault Memory · ${t.received}</title><style>
 *{box-sizing:border-box}body{margin:0;min-height:100svh;display:grid;place-items:center;padding:24px;color:#f1f3fc;background:radial-gradient(ellipse at 20% 10%,#38305a60,transparent 50%),radial-gradient(ellipse at 90% 90%,#20394c40,transparent 55%),#080b12;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif}.panel{width:min(100%,520px);padding:44px;border:1px solid #cdd8ff26;border-radius:32px;background:linear-gradient(135deg,#272c3edb,#131724ed);box-shadow:0 32px 100px #0008,inset 0 1px #ffffff10;animation:arrive .6s cubic-bezier(.2,.8,.2,1) both}.mark{display:block;margin:0 auto 28px;width:92px;height:92px;filter:drop-shadow(0 8px 25px #9990ff40)}.ribbon{stroke-dasharray:180;animation:draw 1.1s ease both}.ribbon:nth-child(2){animation-delay:.12s}.ribbon:nth-child(3){animation-delay:.24s}.brand{text-align:center;color:#b9b6ff;font-size:10px;letter-spacing:.22em;font-weight:650}h1{text-align:center;font-size:34px;letter-spacing:-.045em;line-height:1.1;margin:16px 0}.intro{text-align:center;color:#acb4cb;font-size:15px;line-height:1.7;margin:0 0 30px}.steps{list-style:none;padding:0;margin:0;border-top:1px solid #cdd8ff20}.steps li{display:flex;align-items:center;gap:14px;padding:15px 0;border-bottom:1px solid #cdd8ff15;font-size:13px;animation:arrive .5s both}.steps li:nth-child(2){animation-delay:.15s}.steps li:nth-child(3){animation-delay:.3s}.step{display:grid;place-items:center;flex-shrink:0;width:28px;height:28px;border:1px solid #b9b6ff40;background:#b9b6ff12;border-radius:9px;color:#c8c5ff;font-size:11px}.return{margin:26px 0 0;padding:16px 18px;background:#b9b6ff14;border:1px solid #b9b6ff30;border-radius:16px;color:#d4d1ff;font-size:14px;line-height:1.6}.privacy{margin:22px 0 0;color:#929db6;font-size:11px;line-height:1.7;text-align:center}@keyframes arrive{from{opacity:0;transform:translateY(12px)}to{opacity:1;transform:translateY(0)}}@keyframes draw{from{stroke-dashoffset:180;opacity:0}to{stroke-dashoffset:0;opacity:1}}@media(max-width:480px){.panel{padding:30px 24px}h1{font-size:30px}}@media(prefers-reduced-motion:reduce){*,*::before,*::after{animation:none!important}}@media(forced-colors:active){.panel,.step,.return{border:1px solid CanvasText}svg{stroke:CanvasText}}
-</style></head><body><main class="panel"><svg class="mark" viewBox="0 0 100 100" fill="none" aria-hidden="true"><defs><linearGradient id="glass" x1="10" y1="10" x2="85" y2="90" gradientUnits="userSpaceOnUse"><stop stop-color="#e2edff"/><stop offset=".48" stop-color="#8b88df"/><stop offset="1" stop-color="#c4e6ff"/></linearGradient></defs><g stroke="url(#glass)" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"><path class="ribbon" d="M12 20 50 84 88 20"/><path class="ribbon" d="M25 20 50 63 75 20"/><path class="ribbon" d="M38 20 50 41 62 20"/></g></svg><p class="brand">AI VAULT MEMORY</p><h1>${t.received}</h1><p class="intro">${t.body}</p><ol class="steps"><li><span class="step">01</span>${t.step1}</li><li><span class="step">02</span>${t.step2}</li><li><span class="step">03</span>${t.step3}</li></ol><p class="return">↗ ${t.back}</p><p class="privacy">${t.privacy}</p></main></body></html>`;
+</style></head><body><main class="panel"><img class="mark" src="data:image/png;base64,${logo}" alt="AI Vault Memory"><p class="brand">AI VAULT MEMORY</p><h1>${t.received}</h1><p class="intro">${t.body}</p><ol class="steps"><li><span class="step">01</span>${t.step1}</li><li><span class="step">02</span>${t.step2}</li><li><span class="step">03</span>${t.step3}</li></ol><div class="return">${dashboardUrl ? `<a style="color:inherit" href="${dashboardUrl}">↗ ${t.back}</a>` : `↗ ${t.back}`}</div><p class="privacy">${t.privacy}</p></main></body></html>`;
 }

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 import { type McpClient } from './installer.js';
-export type CliMode = 'help' | 'version' | 'setup' | 'login' | 'serve' | 'local' | 'invalid';
+export type CliMode = 'help' | 'version' | 'setup' | 'login' | 'serve' | 'local' | 'engine' | 'invalid';
 export declare function resolveCliMode(argument: string | undefined, stdinIsTTY: boolean, stderrIsTTY: boolean): CliMode;
 export declare function parseNumberedClients(value: string): McpClient[];
 export declare function cliArguments(args: string[]): {
@@ -10,3 +10,4 @@ export declare function runLocal(args: string[]): Promise<number>;
 export declare function runLogin(args: string[]): Promise<number>;
 export declare function runSetup(args: string[]): Promise<number>;
 export declare function helpText(version: string): string;
+export declare function runEngine(args: string[]): Promise<number>;

package/dist/cli.js

@@ -2,6 +2,8 @@ import { authenticateWithApiKey, authenticateWithBrowser, validateExistingAuthen
 import { vaultHome } from './config.js';
 import { detectMcpClients, installMcpClient, MCP_CLIENTS, parseClientSelection, } from './installer.js';
 import { promptSecret, promptText } from './prompt.js';
+import { CONTEXT_ENGINE_IDS, isApiEngine, listContextEngines, saveEngineKey, selectContextEngine, } from './context-engines.js';
+import { VaultCloudClient } from './cloud.js';
 import { copy, resolveLocale } from './locale.js';
 import { installLocal, localStatus, localUrl, openLocal, startLocal, stopLocal, uninstallLocal } from './local-install.js';
 export function resolveCliMode(argument, stdinIsTTY, stderrIsTTY) {
@@ -17,6 +19,8 @@ export function resolveCliMode(argument, stdinIsTTY, stderrIsTTY) {
         return 'serve';
     if (argument === 'local')
         return 'local';
+    if (argument === 'engine')
+        return 'engine';
     if (argument === undefined)
         return stdinIsTTY && stderrIsTTY ? 'setup' : 'serve';
     return 'invalid';
@@ -221,6 +225,10 @@ Uso:
   vault-go local [install|start|open|status|stop|uninstall|serve]
       Painel local em http://localhost:38850; install ativa início automático no macOS.
 
+  vault-go engine list|use <motor>|key openrouter|gemini
+      Escolhe o motor de contexto: vault-ai-resume, claude-subscription,
+      openai-subscription, openrouter ou gemini. key grava a chave em prompt oculto.
+
   --lang pt|en|es
       Idioma do assistente (padrão: idioma do sistema).
 
@@ -231,5 +239,53 @@ Variáveis:
   VAULT_GO_HOME         Diretório de configuração (padrão: ~/.memvault)
   MEMVAULT_CONFIG_DIR   Diretório compartilhado com o agente MemVault
   VAULT_GO_API_URL      Endpoint alternativo da API Vault
+  VAULT_GO_OPENROUTER_API_KEY / OPENROUTER_API_KEY
+  VAULT_GO_GEMINI_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY
 `;
 }
+async function managedStatus(home) {
+    try {
+        const status = (await new VaultCloudClient(home).observerStatus());
+        return {
+            available: status.configured === true && status.entitlement?.allowed === true,
+            reason: status.configured
+                ? 'Provider readiness is checked when generating.'
+                : 'Managed observer is not configured.',
+            billing: 'Uses the Vault observer allowance.',
+        };
+    }
+    catch {
+        return {
+            available: false,
+            reason: 'Vault AI Resume is not configured or unavailable for this account.',
+            billing: 'Uses the Vault observer allowance.',
+        };
+    }
+}
+export async function runEngine(args) {
+    const home = vaultHome();
+    const positional = args.filter((item) => !item.startsWith('--'));
+    const action = positional[0] ?? 'list';
+    if (action === 'list') {
+        const listed = await listContextEngines(home, await managedStatus(home));
+        process.stdout.write(`${JSON.stringify(listed, null, 2)}\n`);
+        return 0;
+    }
+    if (action === 'use') {
+        const engine = positional[1];
+        if (!engine || !CONTEXT_ENGINE_IDS.includes(engine)) {
+            throw new Error(`Motor inválido. Use: ${CONTEXT_ENGINE_IDS.join(', ')}`);
+        }
+        process.stdout.write(`${selectContextEngine(home, engine)}\n`);
+        return 0;
+    }
+    if (action === 'key') {
+        const engine = positional[1];
+        if (!isApiEngine(engine))
+            throw new Error('Use vault-go engine key openrouter|gemini');
+        saveEngineKey(home, engine, await promptSecret(`Chave ${engine}: `));
+        process.stderr.write(`Chave ${engine} gravada com permissão privada.\n`);
+        return 0;
+    }
+    throw new Error('vault-go engine list|use <motor>|key openrouter|gemini');
+}

package/dist/cloud.d.ts

@@ -1,4 +1,6 @@
 export interface VaultMemoryApi {
+    observerStatus?(): Promise<unknown>;
+    observerGenerate?(text: string, signal?: AbortSignal): Promise<unknown>;
     health(): Promise<unknown>;
     projects(): Promise<unknown>;
     createProject(input: Record<string, unknown>): Promise<unknown>;
@@ -35,6 +37,11 @@ export declare class VaultCloudClient implements VaultMemoryApi {
     private readonly journal;
     constructor(home?: string, cloudFetch?: typeof fetch, journal?: boolean);
     health(): Promise<unknown>;
+    observerStatus(): Promise<unknown>;
+    observerGenerate(text: string, signal?: AbortSignal): Promise<unknown>;
+    registerDevice(input: Record<string, unknown>): Promise<unknown>;
+    rotateDevice(id: string): Promise<unknown>;
+    deviceAction(id: string, token: string, action: 'heartbeat' | 'disconnect', body?: Record<string, unknown>): Promise<unknown>;
     projects(): Promise<unknown>;
     createProject(input: Record<string, unknown>): Promise<unknown>;
     startSession(input: Record<string, unknown>): Promise<unknown>;
@@ -68,3 +75,7 @@ export declare class VaultCloudClient implements VaultMemoryApi {
     private request;
     private performRequest;
 }
+export declare class VaultCloudError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}

package/dist/cloud.js

@@ -12,6 +12,26 @@ export class VaultCloudClient {
     async health() {
         return this.request('/health', { authenticated: false });
     }
+    async observerStatus() { return this.request('/memory/observer/status'); }
+    async observerGenerate(text, signal) {
+        return this.request('/memory/observer/generate', { method: 'POST', body: { text }, timeoutMs: 60_000, ...(signal ? { signal } : {}) });
+    }
+    async registerDevice(input) {
+        return this.request('/devices/register', { method: 'POST', body: input });
+    }
+    async rotateDevice(id) {
+        if (!/^[a-f0-9-]{36}$/.test(id))
+            throw new Error('Invalid device identifier.');
+        return this.request(`/devices/${id}/rotate`, { method: 'POST', body: {} });
+    }
+    async deviceAction(id, token, action, body = {}) {
+        if (!/^[a-f0-9-]{36}$/.test(id) || !/^vg_device_[a-f0-9]{64}$/.test(token))
+            throw new Error('Invalid device credential.');
+        const response = await this.cloudFetch(this.endpoint(`/devices/${id}/${action}`), { method: 'POST', redirect: 'error', headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' }, body: JSON.stringify(body), signal: AbortSignal.timeout(10_000) });
+        if (!response.ok)
+            throw new VaultCloudError(response.status, 'device_request_failed');
+        return response.status === 204 ? null : response.json();
+    }
     async projects() {
         return this.request('/memory/projects');
     }
@@ -146,6 +166,12 @@ export class VaultCloudClient {
             throw new Error('Sessão expirada. Execute `bunx --bun vault-go@latest login --force`.');
         }
         const refreshed = (await response.json());
+        // A refresh already in flight must not overwrite a newer login or logout.
+        const latest = loadTokens(this.home);
+        if (!latest)
+            throw new Error('Vault session was disconnected.');
+        if (latest.accessToken !== tokens.accessToken || latest.refreshToken !== tokens.refreshToken)
+            return latest.accessToken;
         const stored = {
             ...refreshed,
             expiresAt: Date.now() + (refreshed.expiresIn ?? 900) * 1000,
@@ -177,7 +203,7 @@ export class VaultCloudClient {
             method: options.method ?? 'GET',
             redirect: 'error',
             headers,
-            signal: AbortSignal.timeout(15_000),
+            signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(options.timeoutMs ?? 15_000)]) : AbortSignal.timeout(options.timeoutMs ?? 15_000),
         };
         if (options.body)
             request.body = JSON.stringify(options.body);
@@ -197,11 +223,19 @@ export class VaultCloudClient {
             const message = payload && typeof payload === 'object' && 'error' in payload
                 ? String(payload.error)
                 : `Vault respondeu HTTP ${response.status}`;
-            throw new Error(message);
+            throw new VaultCloudError(response.status, message);
         }
         return payload;
     }
 }
+export class VaultCloudError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'VaultCloudError';
+    }
+}
 function safeJson(text) {
     try {
         return JSON.parse(text);

package/dist/context-engines.d.ts

@@ -0,0 +1,60 @@
+export declare const CONTEXT_ENGINE_IDS: readonly ["vault-ai-resume", "claude-subscription", "openai-subscription", "openrouter", "gemini"];
+export declare const API_ENGINE_IDS: readonly ["openrouter", "gemini"];
+export type ContextEngineId = (typeof CONTEXT_ENGINE_IDS)[number];
+export type ApiEngineId = (typeof API_ENGINE_IDS)[number];
+export interface ContextResult {
+    title: string;
+    content: string;
+    facts: string[];
+    concepts: string[];
+    engine: ContextEngineId;
+}
+export interface EngineAvailability {
+    available: boolean;
+    reason?: string;
+    billing?: string;
+}
+export interface ContextEngine extends EngineAvailability {
+    id: ContextEngineId;
+    name: string;
+}
+export interface CommandRequest {
+    command: "claude" | "codex";
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    input?: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}
+export type CommandRunner = (request: CommandRequest) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export declare function isContextEngine(value: unknown): value is ContextEngineId;
+export declare function isApiEngine(value: unknown): value is ApiEngineId;
+export declare function selectedContextEngine(home: string): ContextEngineId;
+export declare function selectContextEngine(home: string, engine: unknown): ContextEngineId;
+export declare function saveEngineKey(home: string, engine: unknown, key: unknown): ApiEngineId;
+export declare function loadEngineKey(home: string, engine: ApiEngineId, environment?: NodeJS.ProcessEnv): string | undefined;
+export declare function contextEnvironment(source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** Never includes process stderr or model input in an error message. */
+export declare const runContextCommand: CommandRunner;
+export declare function listContextEngines(home: string, managedStatus?: EngineAvailability, options?: {
+    runner?: CommandRunner;
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    selected: ContextEngineId;
+    engines: ContextEngine[];
+}>;
+export declare function validateContextResult(value: unknown, engine: ContextEngineId): ContextResult;
+export interface GenerateContextOptions {
+    signal?: AbortSignal;
+    runner?: CommandRunner;
+    httpFetch?: (input: string, init?: RequestInit) => Promise<Response>;
+    env?: NodeJS.ProcessEnv;
+    managedGenerate?: (text: string, options: {
+        signal?: AbortSignal;
+    }) => Promise<unknown>;
+}
+export declare function generateContext(home: string, engine: unknown, text: unknown, options?: GenerateContextOptions): Promise<ContextResult>;