hippo-memory 1.66.0 → 1.68.0

package/README.md

@@ -844,6 +844,8 @@ For Codex, it adds two hooks to `$CODEX_HOME/hooks.json` (else `~/.codex/hooks.j
 
 **Codex runs a new or changed hook only after you trust it, so open `/hooks` in Codex once and trust both;** `hippo doctor` reminds you. The per-prompt hook was checked against a real Codex request; the compaction hook follows Codex's documented `compact` start source and has not been watched end to end in Codex. Each hook also carries a `commandWindows` form (`hippo.cmd ...`), because Codex runs hooks through PowerShell on Windows, where the execution policy can block npm's `hippo.ps1`. hippo only ever appends these two entries and never rewrites one, since Codex treats a changed command as a new hook to trust. To remove: `hippo hook uninstall codex`, which takes out only hippo's exact commands and leaves every other hook, including one of yours that runs hippo.
 
+For GitHub Copilot, once `$COPILOT_HOME` (else `~/.copilot`) exists, `hippo setup` writes hippo's own `hooks/hippo.json`, adds a `hippo` server to `mcp-config.json` and puts a block in `copilot-instructions.md` that asks the agent to call `hippo_recall` and `hippo_remember`. The Copilot CLI, including its sessions inside VS Code, uses all four hooks, the server and the block. VS Code's Local agent runs only the session-start hook and reads neither of the other files, so it gets no pre-compact snapshot or end-of-session capture yet, and its recall tools need hippo added to VS Code's own `mcp.json`. The hooks, that `mcp.json` recipe and how to remove it all: [integrations/copilot.md](integrations/copilot.md).
+
 ### What the hook adds (Claude Code example)
 
 ````markdown

package/dist/api/auth.d.ts

@@ -1,6 +1,6 @@
 import { type ApiKeyListItem, type ApiKeyListRow } from '../auth.js';
 import type { KeysetPosition } from '../keyset.js';
-import type { Context } from './types.js';
+import type { Context, StoreReply } from './types.js';
 export interface AuthCreateOpts {
     label?: string;
     /**
@@ -29,7 +29,7 @@ export interface AuthCreateResult {
  * Only an admin actor can mint (ForbiddenError otherwise), and a key never
  * outranks its minter: a resolver admin is tenant-only, so it mints members.
  */
-export declare function authCreate(ctx: Context, opts: AuthCreateOpts): AuthCreateResult;
+export declare function authCreate<C extends Context>(ctx: C, opts: AuthCreateOpts): StoreReply<C, AuthCreateResult>;
 export interface AuthCreateSelfOpts {
     label?: string;
     /** Days until the new key expires. */
@@ -41,8 +41,9 @@ export interface AuthCreateSelfResult extends AuthCreateResult {
     /** ISO time the key stops working. */
     expiresAt: string;
 }
-/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the binary floor, the cap's revokes, the mint and its audit rows commit or fail together. */
-export declare function authCreateSelf(ctx: Context, opts: AuthCreateSelfOpts): AuthCreateSelfResult;
+/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the binary floor, the cap's revokes, the mint and its audit rows commit or fail together.
+ *  With `ctx.store`, its keyWrites group runs that transaction; hippo.db is opened only when there is no store. */
+export declare function authCreateSelf<C extends Context>(ctx: C, opts: AuthCreateSelfOpts): StoreReply<C, AuthCreateSelfResult>;
 /**
  * List API keys visible to the calling tenant.
  *
@@ -51,22 +52,25 @@ export declare function authCreateSelf(ctx: Context, opts: AuthCreateSelfOpts):
  * scoped because future multi-tenant deployments will share a hippoRoot, and
  * tenant A must not see tenant B's keys. Read-only, so no audit emit.
  */
-export declare function authList(ctx: Context, opts: {
+export declare function authList<C extends Context>(ctx: C, opts: {
     active: boolean;
-}): ApiKeyListItem[];
-/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from. */
-export declare function authListRows(ctx: Context, opts: {
+}): StoreReply<C, ApiKeyListItem[]>;
+type KeyListOpts = {
     active: boolean;
     limit?: number;
     after?: KeysetPosition;
-}): ApiKeyListRow[];
+};
+/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from.
+ *  With `ctx.store`, its keyWrites group reads them; hippo.db is opened only when there is no store. */
+export declare function authListRows<C extends Context>(ctx: C, opts: KeyListOpts): StoreReply<C, ApiKeyListRow[]>;
 export interface AuthRevokeResult {
     ok: true;
     revokedAt: string;
 }
+export type AuthRevokeReply<C extends Context> = StoreReply<C, AuthRevokeResult>;
 /** Revoke a key in the caller's tenant: a member API key may revoke only itself, a resolver member only the keys it minted.
- *  The auth_revoke row carries the KEY ROW's tenant, as cmdAuthRevoke does, and is skipped for an already-revoked key. */
-export declare function authRevoke(ctx: Context, keyId: string): AuthRevokeResult;
+ *  With `ctx.store`, its keyAudit group revokes and writes the auth_revoke row; hippo.db is opened only when there is no store. */
+export declare function authRevoke<C extends Context>(ctx: C, keyId: string): AuthRevokeReply<C>;
 /**
  * The tenant that owns `keyId`, or undefined for an unknown key. Host admin only: it reads across tenants,
  * so the local CLI can run revoke and grant in the key's own tenant.
@@ -80,4 +84,5 @@ export interface AuthGrantResult {
 export declare function authGrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
 /** Revoke `keyId`'s grant on `scope`. Same authorization and lookup rules as authGrant. */
 export declare function authUngrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
+export {};
 //# sourceMappingURL=auth.d.ts.map

package/dist/api/auth.js

@@ -2,30 +2,17 @@
 import { openHippoDb, closeHippoDb } from '../db.js';
 import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from '../api-errors.js';
 import { appendAuditEvent, reportAuditWriteFailure } from '../audit.js';
-import { createApiKey, listApiKeyRows, listLiveOwnedKeyIds, revokeApiKey, grantScope, ungrantScope } from '../auth.js';
+import { forgetVerifiedKey, insertApiKey, listApiKeyRows, mintApiKey, revokeApiKey, grantScope, ungrantScope, } from '../auth.js';
 import { DAY_MS } from '../dashboard-snapshot.js';
 import { isRestrictedScope } from '../recall-scope.js';
+import { requireGroup } from '../store-port.js';
+import { createAuditOf, createKeyAt, createSelfKeyAt } from '../store/key-writes.js';
 import { selectApiKeyOwner } from '../store/tenant-lookup.js';
 const API_KEY_SUBJECT = 'api_key:';
 /** The key id an API-key actor's subject names, or null for any other actor. */
 function keyIdOfSubject(subject) {
     return subject.startsWith(API_KEY_SUBJECT) ? subject.slice(API_KEY_SUBJECT.length) : null;
 }
-function inTransaction(db, fn) {
-    db.exec('BEGIN IMMEDIATE');
-    try {
-        const out = fn();
-        db.exec('COMMIT');
-        return out;
-    }
-    catch (err) {
-        try {
-            db.exec('ROLLBACK');
-        }
-        catch { /* keep the original error */ }
-        throw err;
-    }
-}
 /**
  * Mint a new API key. The new key is ALWAYS bound to `ctx.tenantId`. Callers
  * cannot override the tenant via the opts bag — a previous `tenantId` field
@@ -38,38 +25,56 @@ function inTransaction(db, fn) {
  * outranks its minter: a resolver admin is tenant-only, so it mints members.
  */
 export function authCreate(ctx, opts) {
+    // With a store, its keyWrites group stores the key and its auth_create row together, and hippo.db is never opened.
+    const reply = ctx.store ? createThroughStore(ctx, ctx.store, opts) : createOnHippoDb(ctx, opts);
+    // SAFETY: as in authRevoke, a C typed with a store gets the promise its path returns and a C that hides one gets the union.
+    return reply;
+}
+/** A key row in the caller's tenant, made here so only its hash ever reaches a store. */
+function newKey(ctx, fields) {
+    const { keyId, plaintext, keyHash } = mintApiKey();
+    return { plaintext, key: { ...fields, keyId, keyHash, tenantId: ctx.tenantId, createdAt: new Date().toISOString() } };
+}
+function adminKeyMint(ctx, opts) {
     if (ctx.actor.role !== 'admin') {
         throw new ForbiddenError('Only an admin key can create API keys');
     }
     if (ctx.actor.viaAuthResolver && opts.role === 'admin') {
         throw new ForbiddenError('A key minted through the auth resolver can only be a member key');
     }
+    const role = opts.role ?? (ctx.actor.viaAuthResolver ? 'member' : 'admin');
+    const label = opts.label ?? null;
+    const { plaintext, key } = newKey(ctx, { label, role, ownerSubject: null, expiresAt: null });
+    // The plaintext is NEVER logged; metadata carries label + role, keyId is non-secret.
+    return { plaintext, mint: { key, actor: ctx.actor.subject, metadata: { label, role } } };
+}
+function createResult({ key }, plaintext) {
+    return { keyId: key.keyId, plaintext, tenantId: key.tenantId, role: key.role };
+}
+async function createThroughStore(ctx, store, opts) {
+    const keyWrites = requireGroup(store, 'keyWrites');
+    const { plaintext, mint } = adminKeyMint(ctx, opts);
+    await keyWrites.createApiKey(mint);
+    return createResult(mint, plaintext);
+}
+function createOnHippoDb(ctx, opts) {
+    const { plaintext, mint } = adminKeyMint(ctx, opts);
     const db = openHippoDb(ctx.hippoRoot);
     try {
-        const role = opts.role ?? (ctx.actor.viaAuthResolver ? 'member' : 'admin');
-        const mint = () => createApiKey(db, { tenantId: ctx.tenantId, label: opts.label, role });
-        // The plaintext is NEVER logged; metadata carries label + role, keyId is non-secret.
-        const audit = (keyId) => appendAuditEvent(db, {
-            tenantId: ctx.tenantId, actor: ctx.actor.subject, op: 'auth_create', targetId: keyId, metadata: { label: opts.label ?? null, role },
-        });
         // A resolver admin's keys are found again only through their audit rows, so the key and its row commit together.
         if (ctx.actor.viaAuthResolver) {
-            const result = inTransaction(db, () => {
-                const minted = mint();
-                audit(minted.keyId);
-                return minted;
-            });
-            return { keyId: result.keyId, plaintext: result.plaintext, tenantId: ctx.tenantId, role };
+            createKeyAt(db, mint);
+            return createResult(mint, plaintext);
         }
-        const result = mint();
+        insertApiKey(db, mint.key);
         try {
-            audit(result.keyId);
+            appendAuditEvent(db, createAuditOf(mint));
         }
         catch (error) {
             // Audit must not crash a successful mint.
-            reportAuditWriteFailure('auth_create', String(error), result.keyId);
+            reportAuditWriteFailure('auth_create', String(error), mint.key.keyId);
         }
-        return { keyId: result.keyId, plaintext: result.plaintext, tenantId: ctx.tenantId, role };
+        return createResult(mint, plaintext);
     }
     finally {
         closeHippoDb(db);
@@ -85,34 +90,43 @@ function assertSelfMintOpts({ ttlDays, perSubject }) {
         throw new RangeError(`authCreateSelf: perSubject must be a whole number of at least 1, got ${String(perSubject)}`);
     }
 }
-/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the binary floor, the cap's revokes, the mint and its audit rows commit or fail together. */
+/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the binary floor, the cap's revokes, the mint and its audit rows commit or fail together.
+ *  With `ctx.store`, its keyWrites group runs that transaction; hippo.db is opened only when there is no store. */
 export function authCreateSelf(ctx, opts) {
+    const reply = ctx.store ? createSelfThroughStore(ctx, ctx.store, opts) : createSelfOnHippoDb(ctx, opts);
+    // SAFETY: as in authRevoke, a C typed with a store gets the promise its path returns and a C that hides one gets the union.
+    return reply;
+}
+function selfKeyMint(ctx, opts) {
     if (!ctx.actor.viaAuthResolver) {
         throw new ForbiddenError('Only a caller signed in through the auth resolver can mint its own key');
     }
     assertSelfMintOpts(opts);
-    const { tenantId, actor: { subject } } = ctx;
-    const now = Date.now();
-    const expiresAt = new Date(now + opts.ttlDays * DAY_MS).toISOString();
+    const { subject } = ctx.actor;
+    const label = opts.label ?? null;
+    const expiresAt = new Date(Date.now() + opts.ttlDays * DAY_MS).toISOString();
+    // Not destructured: a binding pattern makes TypeScript infer F as KeyFields and lose ownerSubject's string type.
+    const made = newKey(ctx, { label, role: 'member', ownerSubject: subject, expiresAt });
+    // Same op and actor as an admin mint, so a lookup by audit row finds this key too.
+    return { plaintext: made.plaintext, mint: { key: made.key, actor: subject, metadata: { label, role: 'member', self: true, expiresAt }, perSubject: opts.perSubject } };
+}
+function selfResult({ key }, plaintext) {
+    return { keyId: key.keyId, plaintext, tenantId: key.tenantId, role: 'member', expiresAt: key.expiresAt };
+}
+/** The store revokes the replaced keys without this process's verified-key cache, so they leave it here once the mint commits. */
+async function createSelfThroughStore(ctx, store, opts) {
+    const keyWrites = requireGroup(store, 'keyWrites');
+    const { plaintext, mint } = selfKeyMint(ctx, opts);
+    for (const keyId of await keyWrites.createSelfApiKey(mint))
+        forgetVerifiedKey(keyId);
+    return selfResult(mint, plaintext);
+}
+function createSelfOnHippoDb(ctx, opts) {
+    const { plaintext, mint } = selfKeyMint(ctx, opts);
     const db = openHippoDb(ctx.hippoRoot);
     try {
-        // IMMEDIATE takes the write lock before the count, so two mints for one subject cannot both see room under the cap.
-        const result = inTransaction(db, () => {
-            const live = listLiveOwnedKeyIds(db, tenantId, subject, now);
-            const replaced = live.slice(0, Math.max(0, live.length - opts.perSubject + 1));
-            const minted = createApiKey(db, { tenantId, label: opts.label, role: 'member', ownerSubject: subject, expiresAt });
-            for (const keyId of replaced) {
-                revokeApiKey(db, keyId);
-                appendAuditEvent(db, { tenantId, actor: subject, op: 'auth_revoke', targetId: keyId, metadata: { replacedBy: minted.keyId } });
-            }
-            // Same op and actor as an admin mint, so a lookup by audit row finds this key too.
-            appendAuditEvent(db, {
-                tenantId, actor: subject, op: 'auth_create', targetId: minted.keyId,
-                metadata: { label: opts.label ?? null, role: 'member', self: true, expiresAt },
-            });
-            return minted;
-        });
-        return { keyId: result.keyId, plaintext: result.plaintext, tenantId, role: 'member', expiresAt };
+        createSelfKeyAt(db, mint);
+        return selfResult(mint, plaintext);
     }
     finally {
         closeHippoDb(db);
@@ -127,30 +141,50 @@ export function authCreateSelf(ctx, opts) {
  * tenant A must not see tenant B's keys. Read-only, so no audit emit.
  */
 export function authList(ctx, opts) {
-    return authListRows(ctx, opts).map((r) => r.key);
+    const keysOf = (rows) => rows.map((r) => r.key);
+    const rows = listRows(ctx, opts);
+    // SAFETY: the promise comes back exactly when ctx has a store, as StoreReply says.
+    return (rows instanceof Promise ? rows.then(keysOf) : keysOf(rows));
 }
-/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from. */
+/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from.
+ *  With `ctx.store`, its keyWrites group reads them; hippo.db is opened only when there is no store. */
 export function authListRows(ctx, opts) {
+    // SAFETY: the promise comes back exactly when ctx has a store, as StoreReply says.
+    return listRows(ctx, opts);
+}
+function listRows(ctx, opts) {
+    return ctx.store ? listThroughStore(ctx, ctx.store, opts) : listOnHippoDb(ctx, opts);
+}
+async function listThroughStore(ctx, store, opts) {
+    const keyWrites = requireGroup(store, 'keyWrites');
+    const keyId = memberKeyIdOf(ctx.actor);
+    const filter = memberListFilter(ctx.actor, keyId === null ? undefined : (await store.findApiKey(keyId))?.ownerSubject);
+    return filter === null ? [] : keyWrites.listApiKeys({ ...opts, tenantId: ctx.tenantId, ...filter });
+}
+function listOnHippoDb(ctx, opts) {
     const db = openHippoDb(ctx.hippoRoot);
     try {
-        const filter = memberListFilter(db, ctx);
+        const keyId = memberKeyIdOf(ctx.actor);
+        const filter = memberListFilter(ctx.actor, keyId === null ? undefined : selectApiKeyOwner(db, keyId)?.ownerSubject);
         return filter === null ? [] : listApiKeyRows(db, { ...opts, tenantId: ctx.tenantId, ...filter });
     }
     finally {
         closeHippoDb(db);
     }
 }
+/** The key id of a member API key caller, whose owner decides what it lists; null for any other caller. */
+function memberKeyIdOf(actor) {
+    return actor.role === 'admin' || actor.viaAuthResolver ? null : keyIdOfSubject(actor.subject);
+}
 /** A member sees only the keys its person minted, or just its own key when that has no owner; an admin sees the whole tenant; null means no keys. */
-function memberListFilter(db, ctx) {
-    const { actor } = ctx;
+function memberListFilter(actor, owner) {
     if (actor.role === 'admin')
         return {};
     if (actor.viaAuthResolver)
         return { ownerSubject: actor.subject };
-    const keyId = keyIdOfSubject(actor.subject);
+    const keyId = memberKeyIdOf(actor);
     if (keyId === null)
         return null;
-    const owner = selectApiKeyOwner(db, keyId)?.ownerSubject;
     return owner ? { ownerSubject: owner } : { keyId };
 }
 /** Throws unless `ctx` may revoke `keyId`; a member gets one answer for a missing, foreign or unowned key, so it cannot probe key ids. */
@@ -168,11 +202,33 @@ function assertMayRevoke(ctx, keyId, row) {
     }
 }
 /** Revoke a key in the caller's tenant: a member API key may revoke only itself, a resolver member only the keys it minted.
- *  The auth_revoke row carries the KEY ROW's tenant, as cmdAuthRevoke does, and is skipped for an already-revoked key. */
+ *  With `ctx.store`, its keyAudit group revokes and writes the auth_revoke row; hippo.db is opened only when there is no store. */
 export function authRevoke(ctx, keyId) {
+    const reply = ctx.store ? revokeThroughStore(ctx, ctx.store, keyId) : revokeOnHippoDb(ctx, keyId);
+    // SAFETY: a C typed with a store gets the promise its path returns; a C whose type hides a runtime store (a Pick of
+    // Context) is typed as the union, which a caller has to await anyway.
+    return reply;
+}
+function assertMemberKeyRevokesSelf(ctx, keyId) {
     if (ctx.actor.role !== 'admin' && !ctx.actor.viaAuthResolver && keyIdOfSubject(ctx.actor.subject) !== keyId) {
         throw new ForbiddenError('A member key can revoke only itself');
     }
+}
+function keyOwnerOf(record) {
+    return record ? { tenantId: record.tenantId, revokedAt: record.revokedAt, role: record.role, ownerSubject: record.ownerSubject ?? null } : undefined;
+}
+/** The store keeps no handle on this process's verified-key cache, so the key leaves it here once the revoke commits. */
+async function revokeThroughStore(ctx, store, keyId) {
+    const keyAudit = requireGroup(store, 'keyAudit');
+    assertMemberKeyRevokesSelf(ctx, keyId);
+    assertMayRevoke(ctx, keyId, keyOwnerOf(await store.findApiKey(keyId)));
+    const revokedAt = await keyAudit.revokeApiKey({ tenantId: ctx.tenantId, keyId, actor: ctx.actor.subject, at: new Date().toISOString() });
+    forgetVerifiedKey(keyId);
+    return { ok: true, revokedAt };
+}
+/** The auth_revoke row carries the KEY ROW's tenant, as cmdAuthRevoke does, and is skipped for an already-revoked key. */
+function revokeOnHippoDb(ctx, keyId) {
+    assertMemberKeyRevokesSelf(ctx, keyId);
     const db = openHippoDb(ctx.hippoRoot);
     try {
         const row = selectApiKeyOwner(db, keyId);

package/dist/api/types.d.ts

@@ -25,6 +25,15 @@ export interface Context {
     actor: Actor;
     store?: HippoStore;
 }
+export type HippoDbContext = Context & {
+    store?: undefined;
+};
+export type StoreReply<C extends Context, R> = C extends {
+    readonly store: HippoStore;
+} ? Promise<R> : C extends {
+    readonly hippoRoot: string;
+    readonly store?: undefined;
+} ? R : R | Promise<R>;
 /**
  * Helper for building process-local Actor values (admin and host admin),
  * used by CLI and CLI-run connector Context constructors so the role

package/dist/auth.d.ts

@@ -23,6 +23,25 @@ export interface CreateApiKeyResult {
     keyId: string;
     plaintext: string;
 }
+/** A fresh key: the plaintext its caller sees once, and the scrypt hash a store keeps in its place. */
+export interface MintedApiKey extends CreateApiKeyResult {
+    keyHash: string;
+}
+export declare function mintApiKey(): MintedApiKey;
+/** One api_keys row as core hands it to a store: the hash of the secret, never the secret. */
+export interface NewApiKey {
+    readonly keyId: string;
+    readonly keyHash: string;
+    readonly tenantId: string;
+    readonly label: string | null;
+    readonly role: 'admin' | 'member';
+    readonly createdAt: string;
+    /** The auth-resolver subject a self-service key belongs to; null for a key an admin or the CLI mints. */
+    readonly ownerSubject: string | null;
+    /** ISO time the key stops working; null means it never expires. */
+    readonly expiresAt: string | null;
+}
+export declare function insertApiKey(db: DatabaseSyncLike, key: NewApiKey): void;
 export declare function createApiKey(db: DatabaseSyncLike, opts: CreateApiKeyOpts): CreateApiKeyResult;
 export interface ValidateResult {
     valid: boolean;
@@ -84,7 +103,9 @@ export declare class VerifiedKeyCache {
 }
 /** Verify a bearer API key against `store`, served at `hippoRoot`; a cache hit skips both scrypt and the store. Null when invalid. A token whose cache entry lapsed re-reads its record without scrypt; a throw from `beforeScrypt` refuses before scrypt runs. */
 export declare function verifyApiKeyCached(hippoRoot: string, plaintext: string, store: HippoStore, beforeScrypt?: () => void): Promise<VerifiedApiKey | null>;
-export declare function revokeApiKey(db: DatabaseSyncLike, keyId: string): void;
+export declare function revokeApiKey(db: DatabaseSyncLike, keyId: string, at?: string): void;
+/** A store other than hippo.db revokes without this process's cache, so its caller drops the key here once the revoke commits. */
+export declare function forgetVerifiedKey(keyId: string): void;
 /** Grant `keyId` read access to one restricted `scope`. Idempotent. */
 export declare function grantScope(db: DatabaseSyncLike, keyId: string, scope: string): void;
 /** Revoke `keyId`'s grant on `scope`. Not an error when no such grant exists. */

package/dist/auth.js

@@ -36,17 +36,25 @@ function verifyKey(plaintext, stored) {
     const actual = scryptSync(plaintext, salt, expected.length);
     return expected.length === actual.length && timingSafeEqual(expected, actual);
 }
-export function createApiKey(db, opts) {
+export function mintApiKey() {
     const keyId = `${API_KEY_PREFIX}${randBase32(ID_LEN)}`;
-    const secret = randBase32(SECRET_LEN);
-    const plaintext = `${keyId}.${secret}`;
-    const hash = hashKey(plaintext);
+    const plaintext = `${keyId}.${randBase32(SECRET_LEN)}`;
+    return { keyId, plaintext, keyHash: hashKey(plaintext) };
+}
+export function insertApiKey(db, key) {
     // openHippoDb runs runMigrations synchronously before returning the db handle,
     // so migration v26 (adds role column) is in place before this INSERT runs.
     // An older binary ignores expires_at and would honour an expired key, so the store shuts it out before the first one exists.
-    if (opts.expiresAt !== undefined)
+    if (key.expiresAt !== null)
         raiseMinBinary(db, EXPIRING_KEYS_MIN_BINARY);
-    db.prepare(`INSERT INTO api_keys (key_id, key_hash, tenant_id, label, created_at, role, owner_subject, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(keyId, hash, opts.tenantId, opts.label ?? null, new Date().toISOString(), opts.role ?? 'admin', opts.ownerSubject ?? null, opts.expiresAt ?? null);
+    db.prepare(`INSERT INTO api_keys (key_id, key_hash, tenant_id, label, created_at, role, owner_subject, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(key.keyId, key.keyHash, key.tenantId, key.label, key.createdAt, key.role, key.ownerSubject, key.expiresAt);
+}
+export function createApiKey(db, opts) {
+    const { keyId, plaintext, keyHash } = mintApiKey();
+    insertApiKey(db, {
+        keyId, keyHash, tenantId: opts.tenantId, label: opts.label ?? null, role: opts.role ?? 'admin', createdAt: new Date().toISOString(),
+        ownerSubject: opts.ownerSubject ?? null, expiresAt: opts.expiresAt ?? null,
+    });
     return { keyId, plaintext };
 }
 /** The api_keys row for `keyId` with its scope grants; null when no row matches. */
@@ -187,9 +195,13 @@ export async function verifyApiKeyCached(hippoRoot, plaintext, store, beforeScry
         verifiedKeys.set(hippoRoot, keyId, plaintext, found, Date.now());
     return found?.key ?? null;
 }
-export function revokeApiKey(db, keyId) {
+export function revokeApiKey(db, keyId, at = new Date().toISOString()) {
     db.prepare(`UPDATE api_keys SET revoked_at = ? WHERE key_id = ? AND revoked_at IS NULL`)
-        .run(new Date().toISOString(), keyId);
+        .run(at, keyId);
+    verifiedKeys.delete(keyId);
+}
+/** A store other than hippo.db revokes without this process's cache, so its caller drops the key here once the revoke commits. */
+export function forgetVerifiedKey(keyId) {
     verifiedKeys.delete(keyId);
 }
 /** Grant `keyId` read access to one restricted `scope`. Idempotent. */

package/dist/capture/compact.d.ts

@@ -1,3 +1,4 @@
+import { type HookRuntime } from '../capture-contract.js';
 /**
  * Log-forgery guard: messages here interpolate payload-controlled values
  * (transcript paths, session ids). Strip C0 control chars — newlines above
@@ -11,6 +12,7 @@ export interface PreCompactOptions {
     stdinText?: string;
     stdinTimedOut?: boolean;
     logFile?: string;
+    runtime?: HookRuntime;
 }
 /**
  * PreCompact hook entry point. Exit code 2 on PreCompact BLOCKS compaction,

package/dist/capture/compact.js

@@ -59,7 +59,8 @@ function printPreCompactInstruction(logFile) {
     }
 }
 /** Runs the PreCompact producer: records the compaction, asks the summariser for memories, saves a working-state snapshot. Never extracts memories itself; SessionEnd capture owns that. */
-function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile) {
+function runPreCompact(hippoRoot, options, logFile) {
+    const { stdinText, stdinTimedOut = false, runtime = 'claude-code' } = options;
     // The PreCompact hook fires in every Claude Code project, including
     // ones that never ran `hippo init`, so gate before any store-opening call
     // (saveActiveTaskSnapshot etc. call initStore, which would create one).
@@ -67,19 +68,20 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile) {
         appendPreCompactLog(logFile, 'skip: store not initialized');
         return;
     }
-    const receipt = readClaudeCodePreCompact(stdinText, stdinTimedOut);
+    const receipt = readClaudeCodePreCompact(stdinText, stdinTimedOut, runtime);
     if (receipt.status !== 'received') {
         appendPreCompactLog(logFile, `skip: ${receipt.reason}`);
         return;
     }
     const { sessionId, transcriptPath: payloadTranscriptPath, cwd: payloadCwd, trigger: payloadTrigger } = receipt.input;
     // The record is the "something saved before every compaction", so it lands even when no snapshot is derivable below.
+    // Copilot has no PostCompact hook to close a record, so its compactions get the snapshot alone.
     let recordId = null;
-    if (sessionId !== null && sessionId !== '') {
+    if (runtime === 'claude-code' && sessionId !== null && sessionId !== '') {
         recordId = recordCompactionStart(hippoRoot, { sessionId, trigger: payloadTrigger, cwd: payloadCwd, transcriptPath: payloadTranscriptPath }, (message) => appendPreCompactLog(logFile, message));
         printPreCompactInstruction(logFile);
     }
-    const transcriptPath = resolvePreCompactTranscript(payloadTranscriptPath, stdinText, logFile);
+    const transcriptPath = resolvePreCompactTranscript(payloadTranscriptPath, stdinText, logFile, runtime);
     if (!transcriptPath)
         return;
     // Nothing derivable skips the write, so a user-authored active snapshot is never clobbered with junk.
@@ -89,7 +91,7 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile) {
     saveDerivedSnapshot(hippoRoot, logFile, sessionId, recordId, derived);
 }
 /** The transcript to snapshot, or null after logging why there is none. */
-function resolvePreCompactTranscript(payloadTranscriptPath, stdinText, logFile) {
+function resolvePreCompactTranscript(payloadTranscriptPath, stdinText, logFile, runtime) {
     // A payload transcript_path is EXCLUSIVE: auto-discovery would snapshot a DIFFERENT session's
     // transcript under THIS payload's session_id, so it runs only on a manual invocation (no payload).
     let transcriptPath;
@@ -102,6 +104,10 @@ function resolvePreCompactTranscript(payloadTranscriptPath, stdinText, logFile)
             return null;
         }
     }
+    else if (runtime === 'copilot') {
+        // The scan only knows Claude Code's folders, so a manual Copilot run would snapshot a Claude session.
+        transcriptPath = null;
+    }
     else {
         transcriptPath = resolveLastSessionTranscript(undefined, stdinText, { mayScan: true });
     }
@@ -147,7 +153,7 @@ function saveDerivedSnapshot(hippoRoot, logFile, sessionId, recordId, derived) {
 export async function cmdPreCompact(hippoRoot, options) {
     const logFile = options.logFile ?? defaultPreCompactLogPath();
     try {
-        runPreCompact(hippoRoot, options.stdinText, options.stdinTimedOut ?? false, logFile);
+        runPreCompact(hippoRoot, options, logFile);
     }
     catch (err) {
         appendPreCompactLog(logFile, `pre-compact failed: ${errorMessage(err)}`);

package/dist/capture/copilot-transcript.d.ts

@@ -0,0 +1,15 @@
+/** The envelope fields a Copilot event-log line is read by; any may be absent. */
+export interface CopilotEventLine {
+    type?: unknown;
+    data?: unknown;
+    agentId?: unknown;
+}
+export interface CopilotTurn {
+    role: 'user' | 'assistant';
+    text: string;
+}
+/** The Copilot CLI log for a session, `<copilotHome>/session-state/<id>/events.jsonl`; null for an unsafe id or a missing file. */
+export declare function copilotTranscriptFor(sessionId: string): string | null;
+/** The turn one Copilot event-log line carries: the text of a human user.message or of an assistant.message; null for any other line, a sub-agent's included. */
+export declare function copilotTurn(line: CopilotEventLine): CopilotTurn | null;
+//# sourceMappingURL=copilot-transcript.d.ts.map

package/dist/capture/copilot-transcript.js

@@ -0,0 +1,40 @@
+// The Copilot event log: one `{type, data, id, timestamp, parentId}` object per line, written by the Copilot CLI and VS Code Local alike.
+// Matched line by line, since the tail readers start mid-file and never see the session.start line.
+import * as fs from 'fs';
+import * as path from 'path';
+import { copilotHomeDir } from '../hooks/shared.js';
+import { isObjectLike, isStringValue } from '../capture-contract.js';
+// A session id becomes a folder name, so anything beyond word characters and hyphens could climb out of session-state.
+const SESSION_ID_RE = /^[\w-]+$/;
+// user.message sources that mark text hippo did not get from the human: a hidden skill injection or another agent's prompt.
+const INJECTED_SOURCE_PREFIXES = ['skill-', 'agent-'];
+/** The Copilot CLI log for a session, `<copilotHome>/session-state/<id>/events.jsonl`; null for an unsafe id or a missing file. */
+export function copilotTranscriptFor(sessionId) {
+    if (!SESSION_ID_RE.test(sessionId))
+        return null;
+    const file = path.join(copilotHomeDir(), 'session-state', sessionId, 'events.jsonl');
+    return fs.existsSync(file) ? file : null;
+}
+function isSubagentLine(line, data) {
+    if (isStringValue(line.agentId) && line.agentId !== '')
+        return true;
+    return isStringValue(data.parentToolCallId) && data.parentToolCallId !== '';
+}
+function isInjectedUserMessage(data) {
+    if (data.isAutopilotContinuation === true)
+        return true;
+    const source = data.source;
+    return isStringValue(source) && INJECTED_SOURCE_PREFIXES.some((prefix) => source.startsWith(prefix));
+}
+/** The turn one Copilot event-log line carries: the text of a human user.message or of an assistant.message; null for any other line, a sub-agent's included. */
+export function copilotTurn(line) {
+    const role = line.type === 'user.message' ? 'user' : line.type === 'assistant.message' ? 'assistant' : null;
+    const data = isObjectLike(line.data) ? line.data : null;
+    if (role === null || data === null || isSubagentLine(line, data))
+        return null;
+    if (role === 'user' && isInjectedUserMessage(data))
+        return null;
+    const text = isStringValue(data.content) ? data.content.trim() : '';
+    return text ? { role, text } : null;
+}
+//# sourceMappingURL=copilot-transcript.js.map

package/dist/capture/failure-reading.js

@@ -14,6 +14,9 @@ const LEADING_CD = /^\s*(?:(?:cd|pushd)\b[^;&|]*(?:&&|\|\||;)\s*)+/;
 const NO_MATCH = /\bno (?:matches|files|results) found\b/i;
 /** Shell commands whose exit code 1 means "nothing found" or "differs", not an error. */
 const QUIET_EXIT_1 = /^\s*(?:grep|rg|egrep|fgrep|find|test|\[|diff|cmp|git diff|git grep)\b/;
+// Claude Code's tool names, then the Copilot CLI's and VS Code's; tests/copilot-failure-reading.test.ts cites where each comes from.
+const SEARCH_TOOLS = new Set(['Grep', 'Glob', 'grep', 'glob', 'rg', 'grep_search', 'file_search', 'semantic_search']);
+const SHELL_TOOLS = new Set(['Bash', 'bash', 'powershell', 'run_in_terminal']);
 function isString(v) {
     return v !== undefined && v !== null && v.constructor === String;
 }
@@ -58,9 +61,9 @@ export function lessonFromFailure(payload, scrub = (text) => text) {
         return routine('os-permission');
     if (NO_MATCH.test(error))
         return routine('no-match');
-    if (tool === 'Grep' || tool === 'Glob')
+    if (SEARCH_TOOLS.has(tool))
         return routine('search-tool');
-    if (tool === 'Bash' && QUIET_EXIT_1.test(command) && /exit code 1\b/i.test(error))
+    if (SHELL_TOOLS.has(tool) && QUIET_EXIT_1.test(command) && /exit code 1\b/i.test(error))
         return routine('quiet-exit');
     return { text, detail };
 }

package/dist/capture/transcript.js

@@ -3,8 +3,9 @@ import { claudeConfigDir } from '../hooks/shared.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { isObjectLike, isStringValue } from '../capture-contract.js';
+import { copilotTurn } from './copilot-transcript.js';
 /**
- * Build a compact text summary from a Claude Code / OpenCode JSONL transcript.
+ * Build a compact text summary from a Claude Code / OpenCode / Copilot JSONL transcript.
  * Keeps plain user messages and the final chunk of assistant text, drops
  * thinking blocks, tool_use, and tool_result noise. Capture reads the same
  * turns through `sessionTail`, one text per turn.
@@ -53,6 +54,11 @@ export function collectSessionTurns(jsonl, visit) {
         if (!isObjectLike(entry) || !('type' in entry))
             continue;
         visit?.(entry);
+        const copilot = copilotTurn(entry);
+        if (copilot !== null) {
+            turns.push(copilot);
+            continue;
+        }
         if (entry.type === 'user' || entry.type === 'assistant') {
             const message = 'message' in entry && isObjectLike(entry.message) ? entry.message : undefined;
             if (!message)