hippo-memory 1.67.0 → 1.69.0

package/dist/embeddings.d.ts

@@ -4,8 +4,10 @@
  * Falls back silently if the library is not installed.
  */
 import { MemoryEntry } from './memory.js';
+import { type DatabaseSyncLike } from './db.js';
 import { EMBEDDING_MODEL_META_KEY } from './vector-store.js';
 import { type EmbeddingProvider } from './embedding-provider.js';
+import type { HippoStore } from './store-port.js';
 export { EMBEDDING_MODEL_META_KEY };
 /**
  * Bump whenever `embeddingInputText`'s composition changes in a way that
@@ -73,10 +75,13 @@ export interface EmbeddingIndexState {
 export declare function indexedModel(state: EmbeddingIndexState): string | null;
 /** The one rebuild rule every store applies to its indexed model. */
 export declare function indexNeedsRebuild(indexed: string | null, providerId: string): boolean;
+/** Whether a vector write under the index identity `model` first drops the stored index, which another model built. */
+export declare function replacesIndex(state: EmbeddingIndexState, model: string): boolean;
 export declare function resolveIndexedEmbeddingModel(hippoRoot: string, index?: Record<string, number[]>): string | null;
 export declare function embeddingModelRequiresReindex(hippoRoot: string, model: string, index?: Record<string, number[]>): boolean;
 /** hippo.db's index state, the meta row and the EXISTS on one handle. */
 export declare function embeddingIndexStateAt(hippoRoot: string): EmbeddingIndexState;
+export declare function embeddingIndexStateOn(db: DatabaseSyncLike): EmbeddingIndexState;
 /**
  * Cosine similarity between two vectors. Handles unnormalized vectors.
  * Returns 0 for empty or mismatched vectors.
@@ -88,14 +93,9 @@ export declare function loadEmbeddingIndex(hippoRoot: string): Record<string, nu
 export declare function loadStoredVectors(hippoRoot: string, ids: readonly string[]): Map<string, number[]>;
 /** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
 export declare function saveEmbeddingIndex(hippoRoot: string, index: Record<string, number[]>, model?: string): void;
-/**
- * Embed a single memory entry and cache the result in the embedding index.
- */
-export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model?: string): Promise<void>;
-/**
- * Embed all entries in hippoRoot that don't already have cached vectors.
- * Prunes orphaned embeddings for memories that no longer exist.
- * Returns the count of newly embedded entries. `provider` defaults to the store's configured one.
- */
-export declare function embedAll(hippoRoot: string, model?: string, provider?: EmbeddingProvider): Promise<number>;
+/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
+export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model?: string, store?: HippoStore): Promise<void>;
+/** Embeds every entry with no cached vector, prunes vectors of deleted memories, and returns how many it embedded; `provider` defaults to the
+ *  configured one. With `store`, every tenant's memories with no vector for the provider's model go through its `vectorWrites`, never hippo.db. */
+export declare function embedAll(hippoRoot: string, model?: string, provider?: EmbeddingProvider, store?: HippoStore): Promise<number>;
 //# sourceMappingURL=embeddings.d.ts.map

package/dist/embeddings.js

@@ -16,6 +16,7 @@ import { resolveEmbeddingProvider } from './embedding-provider.js';
 import { DEFAULT_EMBEDDING_MODEL } from './local-embedding.js';
 import { redactSecretsStrict } from './secret-detect.js';
 import { log } from './log.js';
+import { StoreNotPortedError } from './db/sqlite-blocked.js';
 export { EMBEDDING_MODEL_META_KEY };
 /**
  * Bump whenever `embeddingInputText`'s composition changes in a way that
@@ -109,6 +110,11 @@ export function indexedModel(state) {
 export function indexNeedsRebuild(indexed, providerId) {
     return indexed !== null && indexed !== embeddingIndexIdentity(providerId);
 }
+/** Whether a vector write under the index identity `model` first drops the stored index, which another model built. */
+export function replacesIndex(state, model) {
+    const indexed = indexedModel(state);
+    return indexed !== null && indexed !== model;
+}
 export function resolveIndexedEmbeddingModel(hippoRoot, index) {
     const storedModel = loadStoredEmbeddingModel(hippoRoot);
     if (storedModel)
@@ -120,10 +126,13 @@ export function embeddingModelRequiresReindex(hippoRoot, model, index) {
 }
 /** hippo.db's index state, the meta row and the EXISTS on one handle. */
 export function embeddingIndexStateAt(hippoRoot) {
-    return withVectorDb(hippoRoot, (db) => ({
+    return withVectorDb(hippoRoot, embeddingIndexStateOn);
+}
+export function embeddingIndexStateOn(db) {
+    return {
         storedModel: getMeta(db, EMBEDDING_MODEL_META_KEY, '').trim() || null,
         hasVectors: hasStoredVectors(db),
-    }));
+    };
 }
 async function rebuildEmbeddingIndex(entries, provider) {
     const rebuilt = {};
@@ -273,12 +282,7 @@ async function acquireEmbedFileLock(hippoRoot) {
     }
 }
 async function withEmbedLock(hippoRoot, fn) {
-    let resolve;
-    const next = new Promise(r => { resolve = r; });
-    const prev = _embedWriteLock;
-    _embedWriteLock = next;
-    await prev;
-    try {
+    return withProcessEmbedLock(async () => {
         const release = await acquireEmbedFileLock(hippoRoot);
         try {
             return await fn();
@@ -286,6 +290,17 @@ async function withEmbedLock(hippoRoot, fn) {
         finally {
             release();
         }
+    });
+}
+// A store keeps each write whole in its own transaction, and a lock file in hippoRoot would not reach a worker on another host.
+async function withProcessEmbedLock(fn) {
+    let resolve;
+    const next = new Promise(r => { resolve = r; });
+    const prev = _embedWriteLock;
+    _embedWriteLock = next;
+    await prev;
+    try {
+        return await fn();
     }
     finally {
         resolve();
@@ -301,10 +316,79 @@ function warnEmbedFailureOnce(source, rawMessage) {
     const message = redactSecretsStrict(rawMessage).replace(/\s+/g, ' ').replace(/\.+$/, '');
     log.warn(`embedding failed (${source}): ${message}. Memories are stored without embeddings until this is fixed.`);
 }
-/**
- * Embed a single memory entry and cache the result in the embedding index.
- */
-export async function embedMemory(hippoRoot, entry, model) {
+// store-port.ts imports this module, so its requireGroup would close an import cycle.
+function vectorGroups(store) {
+    if (store.vectors === undefined)
+        throw new StoreNotPortedError(store.kind, 'vectors');
+    if (store.vectorWrites === undefined)
+        throw new StoreNotPortedError(store.kind, 'vectorWrites');
+    return [store.vectors, store.vectorWrites];
+}
+/** Writes one page's vectors, one writeVectors per tenant, and stops at the first refused write; `withParticles` seeds each memory's particle. */
+async function writeVectorPage(writes, write, page, vectors, withParticles) {
+    const byTenant = new Map();
+    page.forEach((entry, i) => {
+        const vector = vectors[i];
+        if (!vector || vector.length === 0)
+            return noteSkippedEmbedding(entry.id);
+        const row = withParticles ? { memoryId: entry.id, vector, particle: initializeParticle(entry, vector) } : { memoryId: entry.id, vector };
+        byTenant.set(entry.tenantId, [...(byTenant.get(entry.tenantId) ?? []), row]);
+    });
+    let written = 0;
+    for (const [tenantId, rows] of byTenant) {
+        const result = await writes.writeVectors({ ...write, tenantId, rows });
+        if (result.modelMismatch)
+            return { written, modelMismatch: true };
+        written += result.written;
+    }
+    return { written, modelMismatch: false };
+}
+const STORE_PAGE = 64;
+const OTHER_MODEL_INDEX = "the vector index was built by another embedding model; run 'hippo embed' to rebuild it";
+/** Embeds every memory with no vector under `model`, page by page, so a provider failure keeps the pages written; a rebuild reseeds the particles it drops. */
+async function backfillInStore(writes, provider, model, rebuild) {
+    let count = 0;
+    let afterId;
+    for (;;) {
+        const page = await writes.entriesWithoutVector({ model, afterId, limit: STORE_PAGE });
+        if (page.length === 0)
+            return count;
+        afterId = page[page.length - 1].id;
+        const vectors = await provider.embed(page.map((e) => embeddingInputText(e)), 'passage');
+        const result = await writeVectorPage(writes, { model, replaceIndex: rebuild }, page, vectors, rebuild);
+        // Another process rebuilt the index mid-run; every later page would be refused too, after paying the provider for it.
+        if (result.modelMismatch)
+            throw new Error(OTHER_MODEL_INDEX);
+        count += result.written;
+    }
+}
+/** embedAll on a store: a model change re-embeds every memory, and the first page written drops the old index. */
+async function embedAllInStore(store, provider) {
+    const [reads, writes] = vectorGroups(store);
+    const rebuild = indexNeedsRebuild(indexedModel(await reads.embeddingIndexState()), provider.id);
+    return backfillInStore(writes, provider, embeddingIndexIdentity(provider.id), rebuild);
+}
+/** embedMemory on a store; like the hippo.db path it resolves whatever fails. Unlike it, it leaves a model change to embedAll, so a stale
+ *  read here never drops another process's rebuild; the read only saves a paid embed call, as the write refuses another model itself. */
+function embedMemoryInStore(store, provider, entry) {
+    return withProcessEmbedLock(async () => {
+        const [reads, writes] = vectorGroups(store);
+        const model = embeddingIndexIdentity(provider.id);
+        try {
+            const refused = replacesIndex(await reads.embeddingIndexState(), model)
+                || (await writeVectorPage(writes, { model, replaceIndex: false }, [entry], await provider.embed([embeddingInputText(entry)], 'passage'), true)).modelMismatch;
+            if (refused)
+                warnEmbedFailureOnce('index', OTHER_MODEL_INDEX);
+        }
+        catch (err) {
+            warnEmbedFailureOnce(provider.kind, err instanceof Error ? err.message : String(err));
+        }
+    }).catch((err) => {
+        log.warn(`skipped embedding ${entry.id} (${err instanceof Error ? err.message : String(err)})`);
+    });
+}
+/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
+export async function embedMemory(hippoRoot, entry, model, store) {
     let provider;
     try {
         provider = resolveEmbeddingProvider(hippoRoot, { model });
@@ -316,6 +400,8 @@ export async function embedMemory(hippoRoot, entry, model) {
     }
     if (!provider.isAvailable())
         return;
+    if (store)
+        return embedMemoryInStore(store, provider, entry);
     return withEmbedLock(hippoRoot, async () => {
         // embedMemory is best-effort: an embedding failure (API down / bad key / 5xx)
         // must not reject the caller's write — `getEmbedding` historically swallowed
@@ -418,16 +504,15 @@ async function backfillPending(hippoRoot, provider, pending, model) {
     }
     return { count, backfillError };
 }
-/**
- * Embed all entries in hippoRoot that don't already have cached vectors.
- * Prunes orphaned embeddings for memories that no longer exist.
- * Returns the count of newly embedded entries. `provider` defaults to the store's configured one.
- */
-export async function embedAll(hippoRoot, model, provider = resolveEmbeddingProvider(hippoRoot, { model })) {
+/** Embeds every entry with no cached vector, prunes vectors of deleted memories, and returns how many it embedded; `provider` defaults to the
+ *  configured one. With `store`, every tenant's memories with no vector for the provider's model go through its `vectorWrites`, never hippo.db. */
+export async function embedAll(hippoRoot, model, provider = resolveEmbeddingProvider(hippoRoot, { model }), store) {
     if (!provider.isAvailable()) {
         throwIfProviderKeyMissing(hippoRoot, provider);
         return 0;
     }
+    if (store)
+        return withProcessEmbedLock(() => embedAllInStore(store, provider));
     return withEmbedLock(hippoRoot, async () => {
         const identity = provider.id;
         // Host-wide by design. embedAll backfills vectors for all tenants'

package/dist/env.d.ts

@@ -41,6 +41,8 @@ export declare function envRequireSessionScopedFreshTail(): boolean;
 export declare function envStdinWaitMs(): number | undefined;
 export declare function envLogLevel(): string;
 export declare function envPort(): string | undefined;
+/** How long a client waits for a running server's /health before writing to the store directly; server-detect.ts holds the default. */
+export declare function envHealthProbeMs(): number | undefined;
 export declare function envRequireAuth(): boolean;
 export declare function envV1Rps(): string | undefined;
 export declare function envApiKey(): string | undefined;

package/dist/env.js

@@ -83,6 +83,8 @@ export function envStdinWaitMs() { return positiveInt('HIPPO_STDIN_WAIT_MS'); }
 export function envLogLevel() { return raw('HIPPO_LOG')?.trim().toLowerCase() ?? ''; }
 // Server.
 export function envPort() { return raw('HIPPO_PORT'); }
+/** How long a client waits for a running server's /health before writing to the store directly; server-detect.ts holds the default. */
+export function envHealthProbeMs() { return positiveInt('HIPPO_HEALTH_PROBE_MS'); }
 export function envRequireAuth() { return isOne('HIPPO_REQUIRE_AUTH'); }
 export function envV1Rps() { return raw('HIPPO_V1_RPS'); }
 export function envApiKey() { return raw('HIPPO_API_KEY'); }

package/dist/hooks/copilot.d.ts

@@ -1,21 +1,41 @@
+import type { JsonObject } from '../working-memory.js';
 /** Copilot drops what a per-prompt hook prints, so per-task recall goes through the MCP tool the block names. */
 export declare const COPILOT_INSTRUCTIONS: string;
-/** The three files hippo writes for Copilot. */
+export declare const VSCODE_INSTRUCTIONS: string;
+/** The files hippo writes in one VS Code User folder. */
+export interface VscodePaths {
+    readonly userDir: string;
+    readonly mcpConfig: string;
+    readonly instructions: string;
+    /** Profile folders, which keep their own mcp.json and prompts; hippo installs into the default profile only. */
+    readonly profiles: readonly string[];
+}
+/** The three files hippo writes for Copilot, plus the two it writes in each VS Code User folder. */
 export interface CopilotPaths {
     readonly hooks: string;
     readonly mcpConfig: string;
     readonly instructions: string;
+    readonly vscode: readonly VscodePaths[];
 }
 export declare function copilotPaths(): CopilotPaths;
-/** What to paste under "mcpServers" when hippo cannot edit the file itself. */
-export declare function copilotMcpSnippet(): string;
+/** The app that reads an MCP config: where it keeps its servers, and hippo's entry there. */
+export interface McpHost {
+    readonly key: 'mcpServers' | 'servers';
+    server(): JsonObject;
+}
+/** The Copilot CLI's mcp-config.json keeps servers under "mcpServers", each with an env and a tool list. */
+export declare const COPILOT_CLI_MCP: McpHost;
+/** VS Code's mcp.json keeps stdio servers under "servers"; it has no "mcpServers" key. */
+export declare const VSCODE_MCP: McpHost;
+/** What to paste under the host's key when hippo cannot edit the file itself. */
+export declare function copilotMcpSnippet(host?: McpHost): string;
 export type McpMergeStatus = 'added' | 'present' | 'user-owned' | 'unreadable';
 /** Adds hippo's server and keeps every other key; a file hippo cannot parse, or a "hippo" key it did not write, stays as it is. */
-export declare function mergeMcpServer(file: string): McpMergeStatus;
+export declare function mergeMcpServer(file: string, host?: McpHost): McpMergeStatus;
 export type McpRemoveStatus = 'removed' | 'absent' | 'user-owned' | 'unreadable';
 /** Removes the "hippo" key only when hippo wrote it. */
-export declare function removeMcpServer(file: string): McpRemoveStatus;
-/** A filesystem error on mcp-config.json (EACCES, EISDIR, EBUSY), kept as its own message so setup can report it and go on. */
+export declare function removeMcpServer(file: string, host?: McpHost): McpRemoveStatus;
+/** A filesystem error on an MCP config file (EACCES, EISDIR, EBUSY), kept as its own message so setup can report it and go on. */
 export interface McpFailure {
     readonly failed: string;
 }
@@ -27,19 +47,41 @@ export declare function ensureInstructionsBlock(file: string): InstructionsInsta
 export type InstructionsRemoveStatus = 'removed' | 'absent' | 'kept' | 'unclosed';
 /** Splices out only hippo's own Copilot block and keeps every other byte; a file left with nothing but whitespace goes. */
 export declare function removeInstructionsBlock(file: string): InstructionsRemoveStatus;
+/** `kept`: the file is there but is not the text hippo writes, so the user edited it or it is someone else's. */
+export type VscodeInstructionsInstallStatus = 'written' | 'present' | 'kept';
+/** The file is hippo's alone, so it is written whole; an earlier hippo text is upgraded, and any other text already there stays. */
+export declare function ensureVscodeInstructions(file: string): VscodeInstructionsInstallStatus;
+export type VscodeInstructionsRemoveStatus = 'removed' | 'absent' | 'kept';
+/** Deletes the file only when it still holds exactly what a hippo release wrote. */
+export declare function removeVscodeInstructions(file: string): VscodeInstructionsRemoveStatus;
+export interface VscodeInstallResult {
+    readonly paths: VscodePaths;
+    readonly mcp: McpMergeStatus | McpFailure;
+    readonly instructions: VscodeInstructionsInstallStatus;
+}
 export interface CopilotInstallResult {
     readonly paths: CopilotPaths;
     /** True when the hooks file was written; false when it already held hippo's current table. */
     readonly hooks: boolean;
-    readonly mcp: McpMergeStatus | McpFailure;
-    readonly instructions: InstructionsInstallStatus;
+    /** Null, like `instructions`, when the Copilot CLI is not installed, since only it reads these two files. */
+    readonly mcp: McpMergeStatus | McpFailure | null;
+    readonly instructions: InstructionsInstallStatus | null;
+    readonly vscode: readonly VscodeInstallResult[];
 }
+/** The CLI's folder holds more than the hooks folder setup makes for VS Code, so a rerun on a VS Code-only machine still finds no CLI. */
+export declare function isCopilotCliPresent(home?: string): boolean;
 export declare function installCopilot(): CopilotInstallResult;
+export interface VscodeUninstallResult {
+    readonly paths: VscodePaths;
+    readonly mcp: McpRemoveStatus | McpFailure;
+    readonly instructions: VscodeInstructionsRemoveStatus;
+}
 export interface CopilotUninstallResult {
     readonly paths: CopilotPaths;
     readonly hooks: boolean;
     readonly mcp: McpRemoveStatus | McpFailure;
     readonly instructions: InstructionsRemoveStatus;
+    readonly vscode: readonly VscodeUninstallResult[];
 }
 export declare function uninstallCopilot(): CopilotUninstallResult;
 //# sourceMappingURL=copilot.d.ts.map

package/dist/hooks/copilot.js

@@ -1,10 +1,11 @@
-// GitHub Copilot: hippo's hooks file, one MCP server key and an instructions block, all under the Copilot home folder.
+// GitHub Copilot: hippo's hooks file, one MCP server key and an instructions block under the Copilot home folder,
+// plus the MCP server and an instructions file in each VS Code User folder.
 import * as fs from 'fs';
 import * as path from 'path';
 import { isDeepStrictEqual } from 'node:util';
 import { readJsonFile } from '../json.js';
 import { HOOK_MARKERS, hippoBlock } from '../cli/hook-blocks.js';
-import { copilotHomeDir, isJsonObject } from './shared.js';
+import { copilotHomeDir, isJsonObject, vscodeUserDirs } from './shared.js';
 import { installJsonHooks, resolveJsonHookPaths, uninstallJsonHooks, writeSettingsFile } from './json-hooks.js';
 const MCP_KEY = 'hippo';
 /** Copilot drops what a per-prompt hook prints, so per-task recall goes through the MCP tool the block names. */
@@ -19,32 +20,75 @@ reason, a user preference, why something failed), call the \`hippo_remember\`
 tool right then, while you work, never as a closing step. Set \`error\` to true
 for a failure. Leave out secrets and personal details.
 
+The installed hooks load pinned memories when a session starts and capture
+the session as you work, so there is nothing to run before you finish.
+`.trim();
+/** Every Copilot text a release has written, so install upgrades an old block and uninstall still removes it; add the old text when the text changes. */
+const SHIPPED_COPILOT_INSTRUCTIONS = [
+    COPILOT_INSTRUCTIONS,
+    `
+## Project Memory (Hippo)
+
+At the start of each task, call the \`hippo_recall\` tool with a short query that
+names the task. Read the memories it returns before you write any code.
+
+When you learn something that should outlive this session (a decision and its
+reason, a user preference, why something failed), call the \`hippo_remember\`
+tool right then, while you work, never as a closing step. Set \`error\` to true
+for a failure. Leave out secrets and personal details.
+
 The installed hooks load pinned memories when a session starts, store failed
 tool calls and capture the session when it ends, so there is nothing to run
 before you finish.
-`.trim();
+`.trim(),
+];
+/** VS Code attaches a User `*.instructions.md` file to every chat request its `applyTo` glob matches. */
+const withApplyToAll = (text) => `---\napplyTo: "**"\n---\n${text}\n`;
+export const VSCODE_INSTRUCTIONS = withApplyToAll(COPILOT_INSTRUCTIONS);
+function isHipposVscodeInstructions(text) {
+    return SHIPPED_COPILOT_INSTRUCTIONS.some((shipped) => text === withApplyToAll(shipped));
+}
+function profileDirs(userDir) {
+    const dir = path.join(userDir, 'profiles');
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => path.join(dir, e.name)).sort();
+}
 export function copilotPaths() {
     const home = copilotHomeDir();
     return {
         hooks: resolveJsonHookPaths('copilot').settings,
         mcpConfig: path.join(home, 'mcp-config.json'),
         instructions: path.join(home, 'copilot-instructions.md'),
+        vscode: vscodeUserDirs().map((userDir) => ({
+            userDir,
+            mcpConfig: path.join(userDir, 'mcp.json'),
+            instructions: path.join(userDir, 'prompts', 'hippo.instructions.md'),
+            profiles: profileDirs(userDir),
+        })),
     };
 }
 /** Windows gets npm's .cmd shim, as the Codex hooks do, since a PowerShell execution policy can block hippo.ps1. */
-function hippoMcpServer() {
-    return { type: 'local', command: process.platform === 'win32' ? 'hippo.cmd' : 'hippo', args: ['mcp'], env: {}, tools: ['*'] };
+function hippoCommand() {
+    return process.platform === 'win32' ? 'hippo.cmd' : 'hippo';
 }
-/** Only a server hippo wrote counts as hippo's: a user's own "hippo" key with another command or args is never touched. */
-function isHipposServer(entry) {
-    return isJsonObject(entry) && (entry.command === 'hippo' || entry.command === 'hippo.cmd') && isDeepStrictEqual(entry.args, ['mcp']);
+/** The Copilot CLI's mcp-config.json keeps servers under "mcpServers", each with an env and a tool list. */
+export const COPILOT_CLI_MCP = { key: 'mcpServers', server: () => ({ type: 'local', command: hippoCommand(), args: ['mcp'], env: {}, tools: ['*'] }) };
+/** VS Code's mcp.json keeps stdio servers under "servers"; it has no "mcpServers" key. */
+export const VSCODE_MCP = { key: 'servers', server: () => ({ type: 'stdio', command: hippoCommand(), args: ['mcp'] }) };
+/** Only a server hippo wrote counts as hippo's: another command, other args, or any key or value setup does not write (an env you added) makes it the user's. */
+function isHipposServer(entry, host) {
+    if (!isJsonObject(entry) || !('command' in entry) || !('args' in entry))
+        return false;
+    const ours = host.server();
+    return Object.entries(entry).every(([key, value]) => (key === 'command' ? value === 'hippo' || value === 'hippo.cmd' : isDeepStrictEqual(value, ours[key])));
 }
-/** What to paste under "mcpServers" when hippo cannot edit the file itself. */
-export function copilotMcpSnippet() {
-    return `"${MCP_KEY}": ${JSON.stringify(hippoMcpServer())}`;
+/** What to paste under the host's key when hippo cannot edit the file itself. */
+export function copilotMcpSnippet(host = COPILOT_CLI_MCP) {
+    return `"${MCP_KEY}": ${JSON.stringify(host.server())}`;
 }
 /** Null for a file with comments, one that is not JSON, or one whose shape a merge would overwrite; a missing file reads as empty. */
-function readMcpConfig(file) {
+function readMcpConfig(file, host) {
     let config = {};
     if (fs.existsSync(file)) {
         try {
@@ -52,45 +96,47 @@ function readMcpConfig(file) {
         }
         catch (err) {
             // Only a parse failure means the text is not JSON hippo can merge; EACCES or EISDIR is thrown with its own message.
-            if (err instanceof SyntaxError)
+            if (!(err instanceof SyntaxError))
+                throw err;
+            // An empty file is a new one with no servers yet, not one with comments.
+            if (fs.readFileSync(file, 'utf8').trim() !== '')
                 return null;
-            throw err;
         }
     }
     if (!isJsonObject(config))
         return null;
-    if (config.mcpServers === undefined)
-        config.mcpServers = {};
-    const servers = config.mcpServers;
+    if (config[host.key] === undefined)
+        config[host.key] = {};
+    const servers = config[host.key];
     return isJsonObject(servers) ? { config, servers } : null;
 }
 /** Adds hippo's server and keeps every other key; a file hippo cannot parse, or a "hippo" key it did not write, stays as it is. */
-export function mergeMcpServer(file) {
-    const read = readMcpConfig(file);
+export function mergeMcpServer(file, host = COPILOT_CLI_MCP) {
+    const read = readMcpConfig(file, host);
     if (read === null)
         return 'unreadable';
     const existing = read.servers[MCP_KEY];
     if (existing !== undefined)
-        return isHipposServer(existing) ? 'present' : 'user-owned';
-    read.servers[MCP_KEY] = hippoMcpServer();
+        return isHipposServer(existing, host) ? 'present' : 'user-owned';
+    read.servers[MCP_KEY] = host.server();
     writeSettingsFile(file, read.config);
     return 'added';
 }
 /** Removes the "hippo" key only when hippo wrote it. */
-export function removeMcpServer(file) {
+export function removeMcpServer(file, host = COPILOT_CLI_MCP) {
     if (!fs.existsSync(file))
         return 'absent';
-    const read = readMcpConfig(file);
+    const read = readMcpConfig(file, host);
     if (read === null)
         return 'unreadable';
     const existing = read.servers[MCP_KEY];
     if (existing === undefined)
         return 'absent';
-    if (!isHipposServer(existing))
+    if (!isHipposServer(existing, host))
         return 'user-owned';
     delete read.servers[MCP_KEY];
     if (Object.keys(read.servers).length === 0)
-        delete read.config.mcpServers;
+        delete read.config[host.key];
     writeSettingsFile(file, read.config);
     return 'removed';
 }
@@ -100,7 +146,7 @@ export function isMcpFailure(status) {
 function hasErrnoCode(err) {
     return 'code' in err && typeof err.code === 'string';
 }
-/** One mcp-config.json step; a filesystem error comes back as a failure, so the hooks file and the block still install. */
+/** One MCP config step; a filesystem error comes back as a failure, so the hooks file and the instructions still install. */
 function mcpStep(step) {
     try {
         return step();
@@ -111,9 +157,8 @@ function mcpStep(step) {
         throw err;
     }
 }
-// A later release adds the hash of each earlier Copilot text here, as SHIPPED_HOOK_HASHES does for the other agents.
 function isCopilotBlock(inner) {
-    return inner === COPILOT_INSTRUCTIONS;
+    return SHIPPED_COPILOT_INSTRUCTIONS.includes(inner);
 }
 /** Replaces only the text between the markers, in the file's own line ending, or appends a block after the user's text. */
 function withCopilotBlock(text, found) {
@@ -166,13 +211,49 @@ export function removeInstructionsBlock(file) {
         fs.writeFileSync(file, left, 'utf8');
     return 'removed';
 }
+/** The file is hippo's alone, so it is written whole; an earlier hippo text is upgraded, and any other text already there stays. */
+export function ensureVscodeInstructions(file) {
+    if (fs.existsSync(file)) {
+        const old = fs.readFileSync(file, 'utf8');
+        if (old === VSCODE_INSTRUCTIONS)
+            return 'present';
+        if (!isHipposVscodeInstructions(old))
+            return 'kept';
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, VSCODE_INSTRUCTIONS, 'utf8');
+    return 'written';
+}
+/** Deletes the file only when it still holds exactly what a hippo release wrote. */
+export function removeVscodeInstructions(file) {
+    if (!fs.existsSync(file))
+        return 'absent';
+    if (!isHipposVscodeInstructions(fs.readFileSync(file, 'utf8')))
+        return 'kept';
+    fs.rmSync(file);
+    return 'removed';
+}
+/** The CLI's folder holds more than the hooks folder setup makes for VS Code, so a rerun on a VS Code-only machine still finds no CLI. */
+export function isCopilotCliPresent(home = copilotHomeDir()) {
+    if (fs.statSync(home, { throwIfNoEntry: false })?.isDirectory() !== true)
+        return false;
+    const entries = fs.readdirSync(home);
+    return entries.length !== 1 || entries[0] !== 'hooks';
+}
 export function installCopilot() {
     const paths = copilotPaths();
+    // Read before the hooks install, which makes the folder on a machine with only VS Code.
+    const cli = isCopilotCliPresent();
     return {
         paths,
         hooks: installJsonHooks('copilot').installedSessionStart,
-        mcp: mcpStep(() => mergeMcpServer(paths.mcpConfig)),
-        instructions: ensureInstructionsBlock(paths.instructions),
+        mcp: cli ? mcpStep(() => mergeMcpServer(paths.mcpConfig)) : null,
+        instructions: cli ? ensureInstructionsBlock(paths.instructions) : null,
+        vscode: paths.vscode.map((dir) => ({
+            paths: dir,
+            mcp: mcpStep(() => mergeMcpServer(dir.mcpConfig, VSCODE_MCP)),
+            instructions: ensureVscodeInstructions(dir.instructions),
+        })),
     };
 }
 export function uninstallCopilot() {
@@ -182,6 +263,11 @@ export function uninstallCopilot() {
         hooks: uninstallJsonHooks('copilot'),
         mcp: mcpStep(() => removeMcpServer(paths.mcpConfig)),
         instructions: removeInstructionsBlock(paths.instructions),
+        vscode: paths.vscode.map((dir) => ({
+            paths: dir,
+            mcp: mcpStep(() => removeMcpServer(dir.mcpConfig, VSCODE_MCP)),
+            instructions: removeVscodeInstructions(dir.instructions),
+        })),
     };
 }
 //# sourceMappingURL=copilot.js.map

package/dist/hooks/json-hooks.d.ts

@@ -63,6 +63,8 @@ export interface InstallResult {
 }
 /** The paths for `target` under the current home directory; reads and writes nothing. */
 export declare function resolveJsonHookPaths(target: JsonHookTarget): JsonHookPaths;
+/** The events in hippo's Copilot hooks file, in file order, for setup to name. */
+export declare function copilotHookEvents(): string[];
 /** Adds hippo's hooks to `target`'s settings file and migrates older hippo entries; a file that is not JSON stays untouched. */
 export declare function installJsonHooks(target: JsonHookTarget): InstallResult;
 /** Swaps the file in with one rename, so a crash mid-write cannot leave a truncated settings.json that Claude Code cannot parse. */

package/dist/hooks/json-hooks.js

@@ -35,7 +35,7 @@
  */
 import * as fs from 'fs';
 import * as path from 'path';
-import { isJsonObject, HIPPO_SLEEP_MARKER, HIPPO_LAST_SLEEP_MARKER, HIPPO_CAPTURE_MARKER, HIPPO_SESSION_END_MARKER, HIPPO_PINNED_INJECT_MARKER, HIPPO_PINNED_INJECT_COMMAND, HIPPO_PRE_COMPACT_MARKER, HIPPO_COMPACT_RESUME_MARKER, HIPPO_CAPTURE_ERROR_MARKER, HIPPO_POST_COMPACT_MARKER, homeDir, claudeConfigDir, codexHomeDir, copilotHomeDir, defaultPreCompactLogPath } from './shared.js';
+import { isJsonObject, HIPPO_SLEEP_MARKER, HIPPO_LAST_SLEEP_MARKER, HIPPO_CAPTURE_MARKER, HIPPO_SESSION_END_MARKER, HIPPO_PINNED_INJECT_MARKER, HIPPO_PINNED_INJECT_COMMAND, HIPPO_PRE_COMPACT_MARKER, HIPPO_COMPACT_RESUME_MARKER, HIPPO_CAPTURE_ERROR_MARKER, HIPPO_POST_COMPACT_MARKER, homeDir, claudeConfigDir, codexHomeDir, copilotHooksFile, defaultPreCompactLogPath } from './shared.js';
 import { isJsonString, readJsonFile } from '../json.js';
 import { escapeRegex } from '../escape.js';
 import { errorMessage, log } from '../log.js';
@@ -58,7 +58,7 @@ export function resolveJsonHookPaths(target) {
             };
         case 'copilot':
             return {
-                settings: path.join(copilotHomeDir(), 'hooks', 'hippo.json'),
+                settings: copilotHooksFile(),
                 logFile: path.join(logsDir, 'copilot-sleep.log'),
                 display: 'Copilot',
             };
@@ -214,10 +214,19 @@ function copilotHooksTable() {
             sessionStart: copilotCommandHook('context --pinned-only --include-recent 5 --format copilot', 10),
             postToolUseFailure: copilotCommandHook('capture-error --runtime copilot', 10),
             preCompact: copilotCommandHook('pre-compact --runtime copilot', 30),
+            // VS Code maps no camelCase preCompact. The Copilot CLI may run both names, so pre-compact skips a snapshot saved seconds before.
+            PreCompact: copilotCommandHook('pre-compact --runtime copilot', 30),
+            // VS Code's per-reply Stop. --turn acts on a VS Code payload only, so the Copilot CLI's agentStop does nothing.
+            agentStop: copilotCommandHook('session-end --runtime copilot --turn', 30),
             sessionEnd: copilotCommandHook('session-end --runtime copilot', 30),
         },
     };
 }
+/** The events in hippo's Copilot hooks file, in file order, for setup to name. */
+export function copilotHookEvents() {
+    const hooks = copilotHooksTable().hooks;
+    return isJsonObject(hooks) ? Object.keys(hooks) : [];
+}
 /** Hippo owns this whole file, so install writes the full table and a second install changes no byte. */
 function installCopilotHooks(settingsPath) {
     const result = nothingInstalled('copilot', settingsPath);

package/dist/hooks/shared.d.ts

@@ -30,7 +30,13 @@ export declare function copilotHomeDir(home?: string, env?: Readonly<Record<stri
 export declare function claudeConfigDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
 /** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
 export declare function isCodexPresent(home?: string): boolean;
-/** Copilot counts as installed only when its config folder exists, so setup never creates ~/.copilot on a machine without it. */
+/** hippo's own hooks file, in the hooks folder the Copilot CLI reads. */
+export declare function copilotHooksFile(): string;
+/** Where VS Code's agent finds hippo.json: its docs name ~/.copilot/hooks as the user hooks folder, whatever COPILOT_HOME says. */
+export declare function vscodeUserHooksFile(home?: string): string;
+/** The VS Code User folders that exist; Stable and Insiders keep their own, and only an edition the user has run has one. */
+export declare function vscodeUserDirs(env?: Readonly<Record<string, string | undefined>>, home?: string): string[];
+/** Copilot counts as installed only when its config folder or a VS Code User folder exists, so setup never creates ~/.copilot on a machine with neither. */
 export declare function isCopilotPresent(home?: string): boolean;
 /** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */
 export declare const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus up to 5 that match the prompt. Codex runs hippo's hooks only after you trust them once in `/hooks`.";