vault-go 0.29.2 → 0.31.0

package/dist/opencode-plugin.js

@@ -8,7 +8,7 @@ function owner(home) {
         process.env.VAULT_GO_TOKEN || loadTokens(home)?.accessToken || '',
     ])).digest('hex');
 }
-/** OpenCode 1.x plugin contract: context only; capture stays with the user's existing integrations. */
+/** OpenCode 1.x plugin: inject context and capture prompts, tool use and session end. */
 export function createOpenCodePlugin(input, options = {}) {
     const home = options.home ?? vaultHome();
     const pending = new Map();
@@ -54,6 +54,13 @@ export function createOpenCodePlugin(input, options = {}) {
             controller.abort();
         }
     }
+    async function capture(event, value) {
+        try {
+            const cloud = new VaultCloudClient(home, options.fetch ?? globalThis.fetch, false);
+            await executeHook('opencode', event, { cwd: input.directory, ...value }, cloud, home);
+        }
+        catch { /* capture must not stop the client */ }
+    }
     return {
         'experimental.chat.system.transform': async (request, output) => {
             if (!request.sessionID || !input.directory)
@@ -69,5 +76,33 @@ export function createOpenCodePlugin(input, options = {}) {
                 output.system.push(result.context);
             }
         },
+        'chat.message': async (_input, output) => {
+            const prompt = (output.parts ?? []).filter(part => part.type === 'text' || !part.type).map(part => part.text ?? '').join('\n').trim();
+            if (prompt)
+                await capture('session-init', { session_id: _input.sessionID, prompt });
+        },
+        'tool.execute.before': async (toolInput, output) => {
+            if (toolInput.tool === 'read') {
+                await capture('file-context', { session_id: toolInput.sessionID, tool_name: 'read', tool_input: output.args ?? {} });
+            }
+        },
+        'tool.execute.after': async (toolInput, output) => {
+            if (!toolInput.tool || /vault[_-]go|vault[_-]mem/i.test(toolInput.tool))
+                return;
+            await capture('observation', {
+                session_id: toolInput.sessionID,
+                tool_name: toolInput.tool,
+                tool_use_id: toolInput.callID,
+                tool_input: output.args ?? {},
+                tool_response: output.output ?? null,
+            });
+        },
+        event: async ({ event }) => {
+            if (event?.type !== 'session.idle')
+                return;
+            const info = event.properties?.info;
+            const sessionId = info && typeof info === 'object' ? String(info.id ?? '') : '';
+            await capture('session-end', { session_id: sessionId, last_assistant_message: '' });
+        },
     };
 }

package/dist/server.js

@@ -8,11 +8,14 @@ import { registerVaultModes } from './modes.js';
 import { registerCrystalTools } from './crystal-tools.js';
 import { registerModeIntegrations } from './mode-integrations.js';
 import { registerKnowledgeAgentTools } from './knowledge-tools.js';
+import { registerSkillTools } from './skill-tools.js';
 import { redact } from './hooks.js';
 import { createProjectScope } from './project-scope.js';
 import { VaultCloudClient } from './cloud.js';
 import { getStatus, vaultHome } from './config.js';
 import { createPrivateBackup, restorePrivateBackup } from './backup.js';
+import { estimateAgentCost } from './agent-cost.js';
+import { flattenArchive, groupArchive, recordsFromExport } from './memory-archive.js';
 import { CONTEXT_ENGINE_IDS, generateContext, listContextEngines, parseEngineModel, selectContextEngine, selectEngineModel, selectedContextEngine, selectedEngineModel, } from './context-engines.js';
 import packageJson from '../package.json' with { type: 'json' };
 export const VERSION = packageJson.version;
@@ -55,6 +58,7 @@ export function createVaultGoServer(home = vaultHome(), cloud = new VaultCloudCl
     registerVaultModes(server);
     registerCrystalTools(server, home);
     registerKnowledgeAgentTools(server, home, cloud);
+    registerSkillTools(server, home, cloud);
     server.registerTool('vault_go_engines', {
         title: 'Listar motores de contexto',
         description: 'Lista os motores disponíveis para preparar contexto: Vault AI, Claude, OpenRouter, Gemini e ChatGPT/Codex. Não revela chaves.',
@@ -484,6 +488,70 @@ export function createVaultGoServer(home = vaultHome(), cloud = new VaultCloudCl
         },
         annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
     }, async (input) => run(() => cloud.importMemories(input)));
+    const archiveRecord = z.object({
+        sourceId: z.string().trim().min(1).max(500),
+        kind: z.string().trim().min(1).max(100),
+        content: z.string().trim().min(1).max(200_000),
+        title: z.string().trim().max(500).optional(),
+        sessionId: z.string().uuid().optional(),
+        memoryType: z.string().trim().min(1).max(100).optional(),
+        facts: z.array(z.string().trim().min(1).max(2_000)).max(200).optional(),
+        concepts: z.array(z.string().trim().min(1).max(500)).max(200).optional(),
+        filesRead: z.array(z.string().trim().min(1).max(2_000)).max(500).optional(),
+        filesModified: z.array(z.string().trim().min(1).max(2_000)).max(500).optional(),
+        occurredAt: z.string().trim().max(40).optional(),
+    });
+    const archiveGroup = z.array(archiveRecord).max(1_000);
+    server.registerTool('vault_go_archive_export', {
+        title: 'Exportar arquivo em quatro grupos',
+        description: 'Exporta memórias da conta e as separa em observations, sessions, summaries e prompts.',
+        inputSchema: {
+            projectId: uuid.optional(),
+            limit: z.number().int().min(1).max(1_000).default(500),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (input) => run(async () => groupArchive(recordsFromExport(await cloud.exportMemories(input)))));
+    server.registerTool('vault_go_archive_import', {
+        title: 'Importar arquivo em quatro grupos',
+        description: 'Importa observations, sessions, summaries e prompts para um projeto existente.',
+        inputSchema: {
+            projectId: uuid,
+            observations: archiveGroup.default([]),
+            sessions: archiveGroup.default([]),
+            summaries: archiveGroup.default([]),
+            prompts: archiveGroup.default([]),
+        },
+        annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (input) => run(() => {
+        const records = flattenArchive({
+            version: 1,
+            format: 'vault-memory-groups',
+            observations: input.observations,
+            sessions: input.sessions,
+            summaries: input.summaries,
+            prompts: input.prompts,
+        }).map(record => ({
+            sourceId: record.sourceId,
+            kind: record.kind,
+            content: record.content,
+            memoryType: record.memoryType ?? 'discovery',
+            facts: record.facts ?? [],
+            concepts: record.concepts ?? [],
+            filesRead: record.filesRead ?? [],
+            filesModified: record.filesModified ?? [],
+            ...(record.title ? { title: record.title } : {}),
+            ...(record.sessionId ? { sessionId: record.sessionId } : {}),
+        }));
+        if (!records.length)
+            throw new Error('O arquivo não tem registros.');
+        return cloud.importMemories({ projectId: input.projectId, records });
+    }));
+    server.registerTool('vault_go_agent_cost_report', {
+        title: 'Estimar custo de transcripts',
+        description: 'Lê usage em JSONL locais e devolve tokens e um valor estimado. Sem usage, o valor fica indisponível.',
+        inputSchema: { root: z.string().trim().min(1).max(2_000) },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, async ({ root }) => run(async () => estimateAgentCost(root)));
     server.registerTool('vault_go_embedding_status', {
         title: 'Status da busca semântica',
         description: 'Mostra provedor, modelo e fila de vetores sem revelar a chave.',

package/dist/skill-context.d.ts

@@ -0,0 +1,4 @@
+import type { VaultMemoryApi } from './cloud.js';
+export declare const clip: (text: string, max?: number) => string;
+/** Seção curta para o contexto de início de sessão; vazia quando não há o que mostrar. */
+export declare function skillContextSection(cloud: VaultMemoryApi, projectId: string, max?: number): Promise<string>;

package/dist/skill-context.js

@@ -0,0 +1,16 @@
+export const clip = (text, max = 200) => (text.length > max ? `${text.slice(0, max - 1)}…` : text);
+/** Seção curta para o contexto de início de sessão; vazia quando não há o que mostrar. */
+export async function skillContextSection(cloud, projectId, max = 20) {
+    if (!cloud.skills)
+        return '';
+    const raw = await cloud.skills({ projectId, limit: max });
+    const result = raw && typeof raw === 'object' ? raw : {};
+    const skills = Array.isArray(result.skills) ? result.skills : [];
+    if (!skills.length)
+        return '';
+    return [
+        '## Skills privadas do Vault',
+        ...skills.map(s => `- ${s.name}${s.folderPath ? ` (${s.folderPath})` : ''} — ${clip(s.description, 160)}`),
+        'Use `vault_go_skill_read skill="<nome>"` para carregar uma skill quando ela se aplicar à tarefa.',
+    ].join('\n');
+}

package/dist/skill-download.d.ts

@@ -0,0 +1,6 @@
+import type { VaultMemoryApi } from './cloud.js';
+export declare function downloadSkillArchive(cloud: VaultMemoryApi, id: string, versionId?: string, fetcher?: typeof fetch): Promise<{
+    bytes: Uint8Array;
+    sha256: string;
+    versionId: string;
+}>;

package/dist/skill-download.js

@@ -0,0 +1,48 @@
+const MAX_ARCHIVE_BYTES = 40 * 1024 * 1024;
+function record(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Resposta de download inválida.');
+    return value;
+}
+export async function downloadSkillArchive(cloud, id, versionId, fetcher = globalThis.fetch) {
+    if (!cloud.skillDownloadGrant)
+        throw new Error('Este Vault não oferece download de skills.');
+    const grant = record(await cloud.skillDownloadGrant(id, versionId));
+    const link = record(grant.grant);
+    const version = record(grant.version);
+    if (typeof link.url !== 'string' || typeof version.id !== 'string' || typeof version.archiveSha256 !== 'string')
+        throw new Error('Resposta de download inválida.');
+    const url = new URL(link.url);
+    if (url.protocol !== 'https:')
+        throw new Error('Download inseguro da skill: HTTPS é obrigatório.');
+    const response = await fetcher(url, { redirect: 'error', signal: AbortSignal.timeout(60_000) });
+    if (!response.ok)
+        throw new Error(`Download da skill falhou (HTTP ${response.status}).`);
+    const declared = Number(response.headers.get('content-length'));
+    if (declared > MAX_ARCHIVE_BYTES) {
+        await response.body?.cancel();
+        throw new Error('Pacote acima de 40 MiB.');
+    }
+    if (!response.body)
+        throw new Error('Download vazio da skill.');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            total += next.value.byteLength;
+            if (total > MAX_ARCHIVE_BYTES) {
+                await reader.cancel();
+                throw new Error('Pacote acima de 40 MiB.');
+            }
+            chunks.push(next.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return { bytes: Buffer.concat(chunks, total), sha256: version.archiveSha256, versionId: version.id };
+}

package/dist/skill-library.d.ts

@@ -0,0 +1,8 @@
+import type { VaultMemoryApi } from './cloud.js';
+export type AccountSkillSummary = {
+    id: string;
+    name: string;
+    folderPath?: string | null;
+    [key: string]: unknown;
+};
+export declare function listAllSkillSummaries(cloud: VaultMemoryApi, query?: Record<string, unknown>): Promise<AccountSkillSummary[]>;

package/dist/skill-library.js

@@ -0,0 +1,32 @@
+export async function listAllSkillSummaries(cloud, query = {}) {
+    if (!cloud.skills)
+        throw new Error('Este Vault não oferece a biblioteca de skills.');
+    const output = [];
+    const cursors = new Set();
+    let cursor;
+    for (let page = 0; page < 20; page++) {
+        const response = await cloud.skills({ ...query, limit: 100, ...(cursor ? { cursor } : {}) });
+        if (!response || typeof response !== 'object' || Array.isArray(response))
+            throw new Error('Resposta inválida da biblioteca de skills.');
+        const body = response;
+        if (!Array.isArray(body.skills))
+            throw new Error('Resposta inválida da biblioteca de skills.');
+        for (const item of body.skills) {
+            if (!item || typeof item !== 'object' || Array.isArray(item))
+                throw new Error('Resposta inválida da biblioteca de skills.');
+            const skill = item;
+            if (typeof skill.id !== 'string' || typeof skill.name !== 'string' ||
+                (skill.folderPath !== null && skill.folderPath !== undefined && typeof skill.folderPath !== 'string')) {
+                throw new Error('Resposta inválida da biblioteca de skills.');
+            }
+            output.push(skill);
+        }
+        if (body.nextCursor == null)
+            return output;
+        if (typeof body.nextCursor !== 'string' || !body.nextCursor || cursors.has(body.nextCursor))
+            throw new Error('Paginação inválida da biblioteca de skills.');
+        cursor = body.nextCursor;
+        cursors.add(cursor);
+    }
+    throw new Error('Biblioteca de skills excedeu o limite de páginas.');
+}

package/dist/skill-local.d.ts

@@ -0,0 +1,53 @@
+export declare const SKILL_MARKER = ".vault-skill.json";
+export declare const SKILL_FILE_MAX_BYTES: number;
+export declare const SKILL_MAX_FILES = 512;
+export declare const SKILL_TOTAL_MAX_BYTES: number;
+/** Caminhos do manifesto de bundle (várias skills num tar): o Vault e o herdado. */
+export declare const SKILL_BUNDLE_MANIFEST_PATHS: readonly string[];
+export declare class SkillLocalError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export interface LocalSkillFile {
+    path: string;
+    content: string;
+    encoding: 'utf8' | 'base64';
+    executable: boolean;
+}
+export interface TarEntry {
+    path: string;
+    bytes: Buffer;
+    mode: number;
+}
+export interface InstalledSkill {
+    root: string;
+    dir: string;
+    skillId: string;
+    versionId: string;
+}
+export declare function inspectSkillDestination(root: string, dirName: string, skillId: string): {
+    status: 'missing' | 'managed' | 'conflict';
+    path: string;
+    reason?: 'unmanaged' | 'foreign';
+};
+/** name/description do frontmatter; valida só o formato mínimo (o servidor valida o resto). */
+export declare function frontmatter(md: string): {
+    name: string;
+    description: string;
+} | null;
+/** Lê uma pasta de skill para publicar; symlinks e pastas de ferramentas ficam de fora. */
+export declare function readSourceDir(directory: string): LocalSkillFile[];
+/** Leitor ustar mínimo: só arquivos regulares; link, dispositivo ou caminho perigoso recusa o pacote inteiro. */
+export declare function readTarGz(archive: Uint8Array): TarEntry[];
+export declare function installSkillArchive(input: {
+    bytes: Uint8Array;
+    expectedSha256: string;
+    dirName: string;
+    root: string;
+    skillId: string;
+    versionId: string;
+}): {
+    path: string;
+};
+/** Skills instaladas pelo Vault nas raízes informadas. */
+export declare function installedSkills(roots: string[]): InstalledSkill[];

package/dist/skill-local.js

@@ -0,0 +1,251 @@
+// Lado local da biblioteca de skills: ler uma pasta para publicar e instalar um
+// pacote baixado. A instalação confere sha256, cada arquivo e o digest do
+// manifesto, grava tudo numa pasta temporária irmã e só então troca de lugar.
+// Uma pasta que o Vault não instalou (sem .vault-skill.json) nunca é tocada.
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+import { LEGACY_SKILL_BUNDLE_MANIFEST_PATH } from './legacy-brand.js';
+export const SKILL_MARKER = '.vault-skill.json';
+export const SKILL_FILE_MAX_BYTES = 4 * 1024 * 1024;
+export const SKILL_MAX_FILES = 512;
+export const SKILL_TOTAL_MAX_BYTES = 32 * 1024 * 1024;
+const EXPANDED_MAX_BYTES = 40 * 1024 * 1024;
+const IGNORED = new Set(['.git', 'node_modules', '.DS_Store', SKILL_MARKER]);
+const NAME = /^[a-z0-9][a-z0-9.-]{0,63}$/;
+/** Caminhos do manifesto de bundle (várias skills num tar): o Vault e o herdado. */
+export const SKILL_BUNDLE_MANIFEST_PATHS = ['dev.vault.skill-sharing/manifest.json', LEGACY_SKILL_BUNDLE_MANIFEST_PATH];
+export class SkillLocalError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+const sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export function inspectSkillDestination(root, dirName, skillId) {
+    if (!NAME.test(dirName) || dirName.includes('..'))
+        throw new SkillLocalError('skill_install_invalid', `Nome de pasta inválido: ${dirName}`);
+    const path = join(resolve(root), dirName);
+    let target;
+    try {
+        target = lstatSync(path);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { status: 'missing', path };
+        throw error;
+    }
+    if (!target.isDirectory() || target.isSymbolicLink())
+        return { status: 'conflict', path, reason: 'unmanaged' };
+    const markerPath = join(path, SKILL_MARKER);
+    try {
+        const marker = lstatSync(markerPath);
+        if (!marker.isFile() || marker.isSymbolicLink())
+            return { status: 'conflict', path, reason: 'unmanaged' };
+        const data = JSON.parse(readFileSync(markerPath, 'utf8'));
+        if (!data || typeof data !== 'object' || Array.isArray(data))
+            return { status: 'conflict', path, reason: 'unmanaged' };
+        const skillIdInMarker = data.skillId;
+        return skillIdInMarker === skillId
+            ? { status: 'managed', path }
+            : { status: 'conflict', path, reason: typeof skillIdInMarker === 'string' ? 'foreign' : 'unmanaged' };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT' || error instanceof SyntaxError)
+            return { status: 'conflict', path, reason: 'unmanaged' };
+        throw error;
+    }
+}
+/** name/description do frontmatter; valida só o formato mínimo (o servidor valida o resto). */
+export function frontmatter(md) {
+    const block = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(md)?.[1];
+    if (!block)
+        return null;
+    const field = (key) => {
+        const raw = new RegExp(`^${key}:[ \\t]*(.+)$`, 'm').exec(block)?.[1]?.trim();
+        return raw ? raw.replace(/^(['"])(.*)\1$/, '$2').trim() : '';
+    };
+    const name = field('name'), description = field('description');
+    return name && description ? { name, description } : null;
+}
+function isText(bytes) {
+    if (bytes.includes(0))
+        return false;
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Lê uma pasta de skill para publicar; symlinks e pastas de ferramentas ficam de fora. */
+export function readSourceDir(directory) {
+    const base = resolve(directory);
+    if (!lstatSync(base).isDirectory())
+        throw new SkillLocalError('source_invalid', `Não é uma pasta: ${directory}`);
+    const files = [];
+    let total = 0;
+    const walk = (dir) => {
+        for (const name of readdirSync(dir).sort()) {
+            if (IGNORED.has(name))
+                continue;
+            const full = join(dir, name);
+            const stat = lstatSync(full);
+            if (stat.isSymbolicLink())
+                continue;
+            if (stat.isDirectory()) {
+                walk(full);
+                continue;
+            }
+            if (!stat.isFile())
+                continue;
+            if (files.length >= SKILL_MAX_FILES)
+                throw new SkillLocalError('payload_too_large', `A skill passa de ${SKILL_MAX_FILES} arquivos`);
+            if (stat.size > SKILL_FILE_MAX_BYTES)
+                throw new SkillLocalError('payload_too_large', `Arquivo acima de 4 MiB: ${relative(base, full)}`);
+            total += stat.size;
+            if (total > SKILL_TOTAL_MAX_BYTES)
+                throw new SkillLocalError('payload_too_large', 'Skill acima de 32 MiB');
+            const bytes = readFileSync(full);
+            const text = isText(bytes);
+            files.push({ path: relative(base, full).split(sep).join('/'), content: text ? bytes.toString('utf8') : bytes.toString('base64'), encoding: text ? 'utf8' : 'base64', executable: (stat.mode & 0o111) !== 0 });
+        }
+    };
+    walk(base);
+    return files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+function safePath(path) {
+    if (!path || path.startsWith('/') || path.includes('\\') || path.includes('\0') || /^[A-Za-z]:/.test(path))
+        throw new SkillLocalError('skill_package_invalid', `Caminho inválido no pacote: ${path}`);
+    const segments = path.split('/');
+    if (segments.some(s => s === '' || s === '.' || s === '..'))
+        throw new SkillLocalError('skill_package_invalid', `Caminho inválido no pacote: ${path}`);
+    return path;
+}
+/** Leitor ustar mínimo: só arquivos regulares; link, dispositivo ou caminho perigoso recusa o pacote inteiro. */
+export function readTarGz(archive) {
+    let tar;
+    try {
+        tar = gunzipSync(archive, { maxOutputLength: EXPANDED_MAX_BYTES });
+    }
+    catch {
+        throw new SkillLocalError('skill_package_invalid', 'Pacote corrompido');
+    }
+    const field = (block, offset, length) => { const raw = block.subarray(offset, offset + length); const end = raw.indexOf(0); return (end === -1 ? raw : raw.subarray(0, end)).toString('utf8'); };
+    const entries = [];
+    let offset = 0;
+    while (offset + 512 <= tar.length) {
+        const header = tar.subarray(offset, offset + 512);
+        if (header.every(b => b === 0))
+            break;
+        const type = String.fromCharCode(header[156]);
+        if (type !== '0' && type !== '\0')
+            throw new SkillLocalError('skill_package_invalid', 'Pacote contém entrada que não é arquivo regular');
+        const name = field(header, 0, 100), prefix = field(header, 345, 155);
+        const size = parseInt(field(header, 124, 12).trim() || '0', 8), mode = parseInt(field(header, 100, 8).trim() || '0', 8);
+        if (!Number.isSafeInteger(size) || size < 0 || offset + 512 + size > tar.length)
+            throw new SkillLocalError('skill_package_invalid', 'Pacote corrompido');
+        if (entries.length > SKILL_MAX_FILES + 2)
+            throw new SkillLocalError('skill_package_invalid', 'Pacote com entradas demais');
+        entries.push({ path: safePath(prefix ? `${prefix}/${name}` : name), bytes: Buffer.from(tar.subarray(offset + 512, offset + 512 + size)), mode });
+        offset += 512 + Math.ceil(size / 512) * 512;
+    }
+    return entries;
+}
+/** Confere o manifest.json do formato do Vault contra os bytes: nada fora dele, nada faltando, digest correto. */
+function verifiedFiles(entries) {
+    const integrity = (detail) => new SkillLocalError('skill_install_integrity', `Falha de integridade do pacote: ${detail}`);
+    const byPath = new Map(entries.map(e => [e.path, e]));
+    if (SKILL_BUNDLE_MANIFEST_PATHS.some(path => byPath.has(path)))
+        throw new SkillLocalError('skill_install_unsupported', 'Pacotes com várias skills (bundle) devem ser instalados pelo Vault Desktop');
+    const raw = byPath.get('manifest.json');
+    if (!raw)
+        throw integrity('manifest.json ausente');
+    let manifest;
+    try {
+        manifest = JSON.parse(raw.bytes.toString('utf8'));
+    }
+    catch {
+        throw integrity('manifest.json inválido');
+    }
+    const files = Array.isArray(manifest.files) ? manifest.files : [];
+    if (!files.some(f => f.path === 'SKILL.md'))
+        throw integrity('SKILL.md ausente');
+    const digest = createHash('sha256').update(JSON.stringify(files.map(f => ({ path: f.path, executable: f.executable, classification: f.classification, identitySha256: f.identitySha256 })))).digest('hex');
+    if (digest !== manifest.packageDigest)
+        throw integrity('digest do manifesto');
+    if (entries.length !== files.length + 1)
+        throw integrity('entradas fora do manifesto');
+    return files.map(file => {
+        const entry = byPath.get(safePath(file.path));
+        if (!entry || entry.bytes.length !== file.size || sha256(entry.bytes) !== file.sha256)
+            throw integrity(file.path);
+        return { file, entry };
+    });
+}
+export function installSkillArchive(input) {
+    if (sha256(input.bytes) !== input.expectedSha256)
+        throw new SkillLocalError('skill_install_integrity', 'Falha de integridade do pacote: sha256');
+    const files = verifiedFiles(readTarGz(input.bytes));
+    const root = resolve(input.root);
+    const destination = inspectSkillDestination(root, input.dirName, input.skillId);
+    const target = destination.path;
+    if (destination.status === 'conflict')
+        throw new SkillLocalError('skill_install_conflict', destination.reason === 'foreign'
+            ? `${target} pertence a outra skill Vault; nada foi alterado`
+            : `${target} já existe e não foi instalada pelo Vault; nada foi alterado`);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const token = `${process.pid}-${randomBytes(4).toString('hex')}`;
+    const staging = join(root, `.${input.dirName}.vault-tmp-${token}`);
+    const previous = join(root, `.${input.dirName}.vault-old-${token}`);
+    try {
+        for (const { file, entry } of files) {
+            const destination = resolve(staging, file.path);
+            if (!destination.startsWith(staging + sep))
+                throw new SkillLocalError('skill_package_invalid', `Caminho inválido no pacote: ${file.path}`);
+            mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+            writeFileSync(destination, entry.bytes, { mode: file.executable ? 0o755 : 0o644 });
+        }
+        writeFileSync(join(staging, SKILL_MARKER), `${JSON.stringify({ skillId: input.skillId, versionId: input.versionId, installedAt: new Date().toISOString() }, null, 2)}\n`, { mode: 0o644 });
+        const replacing = existsSync(target);
+        if (replacing)
+            renameSync(target, previous);
+        try {
+            renameSync(staging, target);
+        }
+        catch (error) {
+            if (replacing)
+                renameSync(previous, target);
+            throw error;
+        }
+        if (replacing)
+            rmSync(previous, { recursive: true, force: true });
+        return { path: target };
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+/** Skills instaladas pelo Vault nas raízes informadas. */
+export function installedSkills(roots) {
+    const out = [];
+    for (const root of roots) {
+        if (!existsSync(root))
+            continue;
+        for (const dir of readdirSync(root).sort()) {
+            const marker = join(root, dir, SKILL_MARKER);
+            if (dir.startsWith('.') || !existsSync(marker))
+                continue;
+            try {
+                const data = JSON.parse(readFileSync(marker, 'utf8'));
+                if (typeof data.skillId === 'string' && typeof data.versionId === 'string')
+                    out.push({ root, dir, skillId: data.skillId, versionId: data.versionId });
+            }
+            catch { /* marcador corrompido: tratado como não gerenciado */ }
+        }
+    }
+    return out;
+}

package/dist/skill-tools.d.ts

@@ -0,0 +1,52 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { VaultMemoryApi } from './cloud.js';
+import { skillContextSection } from './skill-context.js';
+export { skillContextSection };
+export declare const SKILL_TEXT_MAX: number;
+export interface SkillToolOptions {
+    cwd?: () => string;
+    fetch?: typeof fetch;
+    userHome?: string;
+    maxChars?: number;
+}
+type Folder = {
+    id: string;
+    parentId: string | null;
+    name: string;
+    path: string;
+    depth: number;
+    skillCount: number;
+};
+type Summary = {
+    id: string;
+    name: string;
+    description: string;
+    folderId: string | null;
+    folderPath: string | null;
+    projectIds: string[];
+    scope?: string;
+    latestVersion: {
+        id: string;
+    } | null;
+};
+export declare function page(text: string, offset?: number, max?: number): {
+    text: string;
+    offset: number;
+    nextOffset: number | null;
+    truncated: boolean;
+};
+export declare function loadFolders(cloud: VaultMemoryApi): Promise<Folder[]>;
+/** Caminho "a/b" → id da pasta ('' ou '/' = raiz → null). */
+export declare function folderByPath(folders: Folder[], path: string): Folder | null | undefined;
+/** Aceita o id da skill, `pasta/sub/nome` ou só `nome` (quando for único). */
+export declare function resolveSkill(cloud: VaultMemoryApi, ref: string): Promise<Summary | {
+    id: string;
+}>;
+export declare function currentProject(cloud: VaultMemoryApi, cwd: string): Promise<{
+    id: string;
+    name: string;
+} | null>;
+export declare const SKILL_TARGETS: readonly ["claude", "grok", "agents"];
+export type SkillTarget = typeof SKILL_TARGETS[number];
+export declare function targetRoot(target: SkillTarget, userHome?: string): string;
+export declare function registerSkillTools(server: McpServer, home: string, cloud: VaultMemoryApi, options?: SkillToolOptions): void;