@hasna/mementos 0.14.86 → 0.14.88

package/dist/storage.js

@@ -152,11 +152,119 @@ var init_retired_storage_mode = __esm(() => {
   ];
 });
 
-// src/storage.ts
-import { Database } from "bun:sqlite";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+// ../../node_modules/.bun/@hasna+paths@0.1.0/node_modules/@hasna/paths/dist/index.js
 import { homedir } from "os";
 import { join } from "path";
+function assertApp(app) {
+  if (typeof app !== "string" || app.length === 0) {
+    throw new TypeError("paths: app must be a non-empty string");
+  }
+  if (!APP_SLUG_RE.test(app)) {
+    throw new TypeError(`paths: invalid app slug "${app}" \u2014 expected lowercase kebab-case ([a-z0-9]+(-[a-z0-9]+)*)`);
+  }
+}
+function envOf(options) {
+  return options.env ?? process.env;
+}
+function envValue(options, kind) {
+  const value = envOf(options)[KIND_ENV[kind]];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function isMacOS(platform) {
+  return platform === "darwin";
+}
+function baseDir(kind, options) {
+  const override = envValue(options, kind);
+  if (override)
+    return override;
+  const home = options.home ?? homedir();
+  const platform = options.platform ?? process.platform;
+  if (isMacOS(platform)) {
+    switch (kind) {
+      case "config":
+      case "data":
+        return join(home, "Library", "Application Support", "Hasna");
+      case "cache":
+        return join(home, "Library", "Caches", "Hasna");
+      case "state":
+        return join(home, "Library", "Logs", "Hasna");
+    }
+  }
+  switch (kind) {
+    case "config":
+      return join(home, ".config", "hasna");
+    case "data":
+      return join(home, ".local", "share", "hasna");
+    case "state":
+      return join(home, ".local", "state", "hasna");
+    case "cache":
+      return join(home, ".cache", "hasna");
+  }
+}
+function resolvePath(kind, options) {
+  assertApp(options.app);
+  const appSegment = options.internal === true ? join("internal", options.app) : options.app;
+  return join(baseDir(kind, options), appSegment);
+}
+function dataDir(options) {
+  return resolvePath("data", options);
+}
+var KIND_ENV, APP_SLUG_RE;
+var init_dist = __esm(() => {
+  KIND_ENV = {
+    config: "HASNA_CONFIG_HOME",
+    data: "HASNA_DATA_HOME",
+    state: "HASNA_STATE_HOME",
+    cache: "HASNA_CACHE_HOME"
+  };
+  APP_SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+});
+
+// src/lib/paths.ts
+import { existsSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2, resolve } from "path";
+function effectiveHome() {
+  return process.env["HOME"] || process.env["USERPROFILE"] || homedir2() || "/tmp";
+}
+function legacyDataRoot() {
+  return join2(effectiveHome(), ".hasna", "mementos");
+}
+function resolverDataRoot() {
+  return dataDir({
+    app: "mementos",
+    home: process.env["HOME"] || process.env["USERPROFILE"] || undefined
+  });
+}
+function adoptResolverDataRoot(resolved, env = process.env) {
+  const dataOverride = env.HASNA_DATA_HOME;
+  if (typeof dataOverride === "string" && dataOverride.trim().length > 0)
+    return true;
+  return existsSync(join2(resolved, "mementos.db"));
+}
+function exactDataRoot() {
+  for (const key of ["HASNA_MEMENTOS_HOME", "MEMENTOS_HOME"]) {
+    const dir = process.env[key]?.trim();
+    if (dir)
+      return resolve(dir);
+  }
+  return;
+}
+function getDataRoot() {
+  const exact = exactDataRoot();
+  if (exact)
+    return exact;
+  const resolved = resolverDataRoot();
+  return adoptResolverDataRoot(resolved) ? resolve(resolved) : resolve(legacyDataRoot());
+}
+var init_paths = __esm(() => {
+  init_dist();
+});
+
+// src/storage.ts
+import { Database } from "bun:sqlite";
+import { existsSync as existsSync2, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join as join3 } from "path";
 import { fileURLToPath } from "url";
 import { Worker } from "worker_threads";
 import pg from "pg";
@@ -415,7 +523,7 @@ function readEnv(name) {
   return value ? value : null;
 }
 function readConfigFile() {
-  if (!existsSync(STORAGE_CONFIG_PATH)) {
+  if (!existsSync2(STORAGE_CONFIG_PATH)) {
     return {};
   }
   try {
@@ -677,11 +785,7 @@ function saveStorageConfig(config) {
 function getConfiguredConnectionString() {
   return getStorageDatabaseUrl() ?? undefined;
 }
-function getStorageConnectionString(dbName = "mementos") {
-  assertNoLegacyStorageMode2();
-  if (!isServerContext()) {
-    throw new Error("Refusing to construct an RDS Postgres DSN outside the mementos-serve server. " + "The raw database DSN is NEVER distributed to client machines. " + "Clients must use the HTTP API: set HASNA_MEMENTOS_API_URL and " + "HASNA_MEMENTOS_API_KEY (and unset HASNA_MEMENTOS_DATABASE_URL).");
-  }
+function resolveConfiguredConnectionString(dbName) {
   const envConnectionString = getConfiguredConnectionString();
   if (envConnectionString) {
     const validation = validatePostgresConnectionString(envConnectionString);
@@ -700,7 +804,7 @@ function getStorageConnectionString(dbName = "mementos") {
     missing.push("storage.rds.username");
   }
   if (missing.length > 0) {
-    throw new Error(`Remote storage database is not configured. Missing ${missing.join(", ")}. Set HASNA_MEMENTOS_DATABASE_URL or configure ~/.hasna/mementos/storage/config.json.`);
+    throw new Error(`Remote storage database is not configured. Missing ${missing.join(", ")}. Set HASNA_MEMENTOS_DATABASE_URL or configure ${STORAGE_CONFIG_PATH}.`);
   }
   const password = process.env[password_env];
   if (!password) {
@@ -709,6 +813,17 @@ function getStorageConnectionString(dbName = "mementos") {
   const sslParam = ssl ? "?sslmode=require" : "";
   return `postgres://${username}:${encodeURIComponent(password)}@${host}:${port}/${dbName}${sslParam}`;
 }
+function getStorageConnectionString(dbName = "mementos") {
+  assertNoLegacyStorageMode2();
+  if (!isServerContext()) {
+    throw new Error("Refusing to construct an RDS Postgres DSN outside the mementos-serve server. " + "The raw database DSN is NEVER distributed to client machines. " + "Clients must use the HTTP API: set HASNA_MEMENTOS_API_URL and " + "HASNA_MEMENTOS_API_KEY (and unset HASNA_MEMENTOS_DATABASE_URL).");
+  }
+  return resolveConfiguredConnectionString(dbName);
+}
+function getStorageConnectionStringForOperator(dbName = "mementos") {
+  assertNoLegacyStorageMode2();
+  return resolveConfiguredConnectionString(dbName);
+}
 function isSyncExcludedTable(table) {
   return SYNC_EXCLUDED_TABLE_PATTERNS.some((pattern) => pattern.test(table));
 }
@@ -878,6 +993,7 @@ CREATE TABLE IF NOT EXISTS _sync_meta (
 var init_storage = __esm(() => {
   init_backend();
   init_retired_storage_mode();
+  init_paths();
   PgSyncPool = class PgSyncPool {
     worker;
     status;
@@ -895,12 +1011,12 @@ var init_storage = __esm(() => {
       const ext = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
       const here = fileURLToPath(new URL(".", import.meta.url));
       const candidates = [
-        join(here, `pg-sync-worker${ext}`),
-        join(here, "..", `pg-sync-worker${ext}`),
-        join(here, "..", "..", `pg-sync-worker${ext}`)
+        join3(here, `pg-sync-worker${ext}`),
+        join3(here, "..", `pg-sync-worker${ext}`),
+        join3(here, "..", "..", `pg-sync-worker${ext}`)
       ];
       for (const candidate of candidates) {
-        if (existsSync(candidate))
+        if (existsSync2(candidate))
           return candidate;
       }
       return candidates[0];
@@ -988,7 +1104,7 @@ var init_storage = __esm(() => {
   MEMENTOS_STORAGE_FALLBACK_ENV = {
     databaseUrl: "MEMENTOS_DATABASE_URL"
   };
-  LOCAL_DATA_DIR = join(homedir(), ".hasna", "mementos");
+  LOCAL_DATA_DIR = getDataRoot();
   DEFAULT_STORAGE_CONFIG = {
     rds: {
       host: "",
@@ -1003,8 +1119,8 @@ var init_storage = __esm(() => {
       schedule_minutes: 0
     }
   };
-  STORAGE_CONFIG_DIR = join(LOCAL_DATA_DIR, "storage");
-  STORAGE_CONFIG_PATH = join(STORAGE_CONFIG_DIR, "config.json");
+  STORAGE_CONFIG_DIR = join3(LOCAL_DATA_DIR, "storage");
+  STORAGE_CONFIG_PATH = join3(STORAGE_CONFIG_DIR, "config.json");
   DATABASE_ENV_NAMES = [
     { name: MEMENTOS_STORAGE_ENV.databaseUrl, deprecated: false },
     { name: MEMENTOS_STORAGE_FALLBACK_ENV.databaseUrl, deprecated: false }
@@ -1051,6 +1167,7 @@ export {
   getStorageDatabaseUrl,
   getStorageDatabaseEnvName,
   getStorageDatabaseEnv,
+  getStorageConnectionStringForOperator,
   getStorageConnectionString,
   getStorageConfig,
   getStorageBackendDatabaseUrl,

package/dist/test-support/memories-page-stub-server.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=memories-page-stub-server.d.ts.map

package/dist/test-support/memories-page-stub-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memories-page-stub-server.d.ts","sourceRoot":"","sources":["../../src/test-support/memories-page-stub-server.ts"],"names":[],"mappings":"AA8CA,OAAO,EAAE,CAAC"}

package/dist/test-support/memories-page-stub.d.ts

@@ -0,0 +1,28 @@
+export interface MemoriesPageStub {
+    server: ReturnType<typeof Bun.serve>;
+    baseUrl: string;
+    stop(): void;
+}
+/** Start a stub GET /v1/memories serving `rowCount` rows on capped pages. */
+export declare function startMemoriesPageStub(rowCount: number): MemoriesPageStub;
+/**
+ * A process env for API mode pointed at a loopback stub. All store selectors
+ * are stripped first (the ambient environment on fleet machines carries the
+ * production API selectors), then the stub URL + a dummy key are set.
+ */
+export declare function apiModeTestEnv(baseUrl: string): Record<string, string>;
+export interface MemoriesPageStubProcess {
+    port: number;
+    baseUrl: string;
+    stop(): void;
+}
+/**
+ * Start the stub as a SEPARATE process. Required whenever the caller under
+ * test runs in the same process that would host the stub: the CLI's cloud
+ * reads are SYNCHRONOUS curl children (Bun.spawnSync), which deadlock against
+ * an in-process server whose event loop the spawn blocks.
+ */
+export declare function startMemoriesPageStubProcess(rowCount: number): MemoriesPageStubProcess;
+/** Poll the stub until it serves a page, or throw after ~5s. */
+export declare function waitForMemoriesPageStub(baseUrl: string): Promise<void>;
+//# sourceMappingURL=memories-page-stub.d.ts.map

package/dist/test-support/memories-page-stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memories-page-stub.d.ts","sourceRoot":"","sources":["../../src/test-support/memories-page-stub.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,IAAI,IAAI,CAAC;CACd;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAqCxE;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CActE;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,GACf,uBAAuB,CAuBzB;AAED,gEAAgE;AAChE,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAW5E"}

package/dist/test-support/pg-sync-stub-worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pg-sync-stub-worker.d.ts.map

package/dist/test-support/pg-sync-stub-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-sync-stub-worker.d.ts","sourceRoot":"","sources":["../../src/test-support/pg-sync-stub-worker.ts"],"names":[],"mappings":""}

package/dist/test-support/preload-local-store.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=preload-local-store.d.ts.map

package/dist/test-support/preload-local-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preload-local-store.d.ts","sourceRoot":"","sources":["../../src/test-support/preload-local-store.ts"],"names":[],"mappings":""}

package/dist/test-support/project-authority-identity.d.ts

@@ -0,0 +1,8 @@
+export declare const TEST_MEMENTOS_PROJECT_AUTHORITY_IDENTITY: {
+    readonly authority_id: "mementos";
+    readonly tenant_id: "default";
+    readonly corpus_id: "default";
+};
+export declare function projectAuthorityTestEnv(): Record<string, string>;
+export declare function configureProjectAuthorityTestIdentity(): void;
+//# sourceMappingURL=project-authority-identity.d.ts.map

package/dist/test-support/project-authority-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-authority-identity.d.ts","sourceRoot":"","sources":["../../src/test-support/project-authority-identity.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wCAAwC;;;;CAI3C,CAAC;AAEX,wBAAgB,uBAAuB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAShE;AAED,wBAAgB,qCAAqC,IAAI,IAAI,CAE5D"}

package/dist/test-support/store-isolation.d.ts

@@ -0,0 +1,108 @@
+import type { StoreBackendReport } from "../db/store-backend.js";
+/**
+ * Every env var that can move the store off local SQLite, plus the store
+ * credential. Derived from the resolver's own exported key lists rather than
+ * retyped, so adding a selector in src/db/api-mode.ts or src/storage.ts
+ * automatically widens what the harnesses neutralize.
+ *
+ * The retired storage-mode keys stay in the set even though the ratchet turns
+ * them into errors: a harness child that inherits a stale variable from the
+ * operator shell must have it DELETED (a blank value would still throw), and
+ * the preload must keep the suite runnable on a machine that still exports one.
+ *
+ * `MEMENTOS_DATABASE_PASSWORD` is not a selector but is the store credential;
+ * removing it can only make the child more local, never less.
+ */
+export declare const STORE_SELECTOR_ENV_KEYS: readonly string[];
+/** The two env vars that point the CLI at a specific SQLite file. */
+export declare const DB_PATH_ENV_KEYS: readonly ["MEMENTOS_DB_PATH", "HASNA_MEMENTOS_DB_PATH"];
+export interface IsolatedStoreEnvOptions {
+    /**
+     * Extra vars to set in the child, applied last. Harnesses use this to blank
+     * LLM provider keys so no test can make a billed call. Kept opt-in because
+     * blanking them changes what commands like `doctor` report.
+     */
+    extra?: Record<string, string>;
+}
+/**
+ * Build a child-process env that is pinned to a local SQLite file at `dbPath`.
+ *
+ * Selectors are DELETED rather than set to `""` — the resolver treats empty as
+ * unset either way, but deleting leaves no ambiguity for a human reading the
+ * child's environment during a postmortem.
+ *
+ * Building the env is necessary but NOT sufficient: pair it with
+ * {@link assertLocalStoreBackend} before the suite performs any write.
+ */
+export declare function isolatedStoreEnv(dbPath: string, options?: IsolatedStoreEnvOptions): Record<string, string>;
+export interface StubApiEnvOptions {
+    /** Stub bearer token. Never a real credential — the stub does not check it. */
+    apiKey?: string;
+}
+/**
+ * Build a child env for a suite that *deliberately* runs in API mode against a
+ * local stub server.
+ *
+ * Such a suite still must not inherit the operator's production API URL or key:
+ * it overrides the URL, but if that override were ever empty or renamed, the
+ * ambient value would take over and the suite would drive the real store. So
+ * start from a fully de-selected env and add back only the stub's own values.
+ *
+ * @param baseUrl the stub's origin, e.g. `http://127.0.0.1:<port>/<mode>`
+ */
+export declare function stubApiEnv(baseUrl: string, options?: StubApiEnvOptions): Record<string, string>;
+/**
+ * Build a child env that DOES resolve to the cloud API — the negative case the
+ * isolation guards are proved against.
+ *
+ * This exists because of the 2026-08-03 precedence-1 fix. Before it, a cloud
+ * case could be built by taking any env and adding an API url+key, and several
+ * tests did exactly that on top of {@link isolatedStoreEnv}. An explicit
+ * `MEMENTOS_DB_PATH` now DEFEATS the API selectors (see getApiConfig in
+ * src/db/api-mode.ts), so that recipe silently produces a LOCAL backend — which
+ * would leave the isolation guards' positive controls unable to observe the bad
+ * state they exist to detect, and `assertLocalStoreBackend`'s own self-test
+ * unable to fail. Both would still be green.
+ *
+ * So the DB_PATH keys are removed here explicitly, and that removal is the
+ * load-bearing line rather than an afterthought: it is the only way to reach the
+ * cloud backend now. They are NOT in STORE_SELECTOR_ENV_KEYS because that set
+ * means "moves the store OFF local SQLite", and DB_PATH does the opposite.
+ *
+ * @param baseUrl  point this at a closed loopback port, never a real endpoint
+ * @param apiKey   never a real credential
+ */
+export declare function cloudSelectingEnv(baseUrl: string, apiKey?: string): Record<string, string>;
+/** LLM provider keys most harnesses blank so no test can make a billed call. */
+export declare const LLM_PROVIDER_ENV_KEYS: readonly ["ANTHROPIC_API_KEY", "OPENAI_API_KEY", "CEREBRAS_API_KEY", "XAI_API_KEY"];
+/** `{ ANTHROPIC_API_KEY: "", ... }` — pass as `extra` to blank LLM providers. */
+export declare function blankLlmProviderEnv(): Record<string, string>;
+/**
+ * Ask the child process which store it resolved, and THROW if it is not local.
+ *
+ * This is the guard that turns an unknown future selector into a red suite
+ * rather than a silent production write. It asks the CLI itself
+ * (`storage mode --json`) rather than recomputing the answer here, so the
+ * verdict comes from the same resolution code the writes will use — and it runs
+ * as a real child process with the real env, so an env var that fails to cross
+ * the process boundary is caught rather than assumed away.
+ *
+ * `storage mode` opens no database and makes no network request, so this is
+ * safe to call even when the ambient env points at production.
+ *
+ * @param cliPath  path to src/cli/index.tsx
+ * @param env      the env produced by {@link isolatedStoreEnv}
+ * @param expectedDbPath  when given, also assert the child resolved this path
+ */
+export declare function assertLocalStoreBackend(cliPath: string, env: Record<string, string>, expectedDbPath?: string): Promise<StoreBackendReport>;
+/**
+ * Assert the scratch SQLite file now exists on disk.
+ *
+ * This is the second half of the proof and it is not redundant with
+ * {@link assertLocalStoreBackend}: the mode report says where the child INTENDS
+ * to write, whereas this says a write actually landed there. The reported
+ * incident's signature was precisely a correct-looking path with no file ever
+ * created, so call this AFTER the suite's first write.
+ */
+export declare function assertScratchDbCreated(dbPath: string, context?: string): void;
+//# sourceMappingURL=store-isolation.d.ts.map

package/dist/test-support/store-isolation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-isolation.d.ts","sourceRoot":"","sources":["../../src/test-support/store-isolation.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAIjE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAUpD,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,yDAA0D,CAAC;AAExF,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,uBAA4B,GACpC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKxB;AASD,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CAUjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQnG;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,MAAM,SAAmB,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAED,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,qFAKxB,CAAC;AAEX,iFAAiF;AACjF,wBAAgB,mBAAmB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAE5D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,kBAAkB,CAAC,CAsD7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,SAA0B,GAAG,IAAI,CAQ9F"}

package/dist/test-support/strip-ansi.d.ts

@@ -0,0 +1,3 @@
+/** Remove ANSI/VT100 SGR escape sequences from CLI output before asserting on content. */
+export declare function stripAnsi(input: string): string;
+//# sourceMappingURL=strip-ansi.d.ts.map

package/dist/test-support/strip-ansi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strip-ansi.d.ts","sourceRoot":"","sources":["../../src/test-support/strip-ansi.ts"],"names":[],"mappings":"AAyBA,0FAA0F;AAC1F,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/types/hooks.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Hook system types for mementos lifecycle events.
+ *
+ * Blocking hooks: handler returns false → operation is cancelled.
+ * Non-blocking hooks: fire-and-forget, never delay the caller.
+ */
+import type { Memory, CreateMemoryInput, UpdateMemoryInput } from "./index.js";
+export type HookType = "PreMemorySave" | "PostMemorySave" | "PreMemoryUpdate" | "PostMemoryUpdate" | "PreMemoryDelete" | "PostMemoryDelete" | "PreEntityCreate" | "PostEntityCreate" | "PreRelationCreate" | "PostRelationCreate" | "OnSessionStart" | "OnSessionEnd" | "PreMemoryInject" | "PostMemoryInject";
+export interface BaseHookContext {
+    agentId?: string;
+    projectId?: string;
+    sessionId?: string;
+    timestamp: number;
+}
+export interface PreMemorySaveContext extends BaseHookContext {
+    input: CreateMemoryInput;
+}
+export interface PostMemorySaveContext extends BaseHookContext {
+    memory: Memory;
+    wasUpdated: boolean;
+}
+export interface PreMemoryUpdateContext extends BaseHookContext {
+    memoryId: string;
+    input: UpdateMemoryInput;
+    existing: Memory;
+}
+export interface PostMemoryUpdateContext extends BaseHookContext {
+    memory: Memory;
+    previousValue: string;
+}
+export interface PreMemoryDeleteContext extends BaseHookContext {
+    memoryId: string;
+    memory: Memory;
+}
+export interface PostMemoryDeleteContext extends BaseHookContext {
+    memoryId: string;
+}
+export interface PreEntityCreateContext extends BaseHookContext {
+    name: string;
+    entityType: string;
+}
+export interface PostEntityCreateContext extends BaseHookContext {
+    entityId: string;
+    name: string;
+    entityType: string;
+}
+export interface PreRelationCreateContext extends BaseHookContext {
+    sourceEntityId: string;
+    targetEntityId: string;
+    relationType: string;
+}
+export interface PostRelationCreateContext extends BaseHookContext {
+    relationId: string;
+    sourceEntityId: string;
+    targetEntityId: string;
+    relationType: string;
+}
+export interface OnSessionStartContext extends BaseHookContext {
+    agentId: string;
+    projectId?: string;
+}
+export interface OnSessionEndContext extends BaseHookContext {
+    agentId: string;
+    projectId?: string;
+    /** Optional session summary for memory extraction */
+    summary?: string;
+}
+export interface PreMemoryInjectContext extends BaseHookContext {
+    /** Memories about to be injected — hook can mutate this array */
+    memories: Memory[];
+    format: string;
+}
+export interface PostMemoryInjectContext extends BaseHookContext {
+    memoriesCount: number;
+    format: string;
+    contextLength: number;
+}
+/** Union of all hook contexts keyed by type */
+export type HookContextMap = {
+    PreMemorySave: PreMemorySaveContext;
+    PostMemorySave: PostMemorySaveContext;
+    PreMemoryUpdate: PreMemoryUpdateContext;
+    PostMemoryUpdate: PostMemoryUpdateContext;
+    PreMemoryDelete: PreMemoryDeleteContext;
+    PostMemoryDelete: PostMemoryDeleteContext;
+    PreEntityCreate: PreEntityCreateContext;
+    PostEntityCreate: PostEntityCreateContext;
+    PreRelationCreate: PreRelationCreateContext;
+    PostRelationCreate: PostRelationCreateContext;
+    OnSessionStart: OnSessionStartContext;
+    OnSessionEnd: OnSessionEndContext;
+    PreMemoryInject: PreMemoryInjectContext;
+    PostMemoryInject: PostMemoryInjectContext;
+};
+/**
+ * Blocking hook: return false to cancel the operation.
+ * Non-blocking hook: return value is ignored.
+ */
+export type HookHandler<T extends HookType = HookType> = (context: HookContextMap[T]) => Promise<boolean | void>;
+export interface Hook<T extends HookType = HookType> {
+    id: string;
+    type: T;
+    handler: HookHandler<T>;
+    /** Lower number = runs first. Default: 50 */
+    priority: number;
+    /**
+     * If true: operation waits for handler result. Return false = cancel.
+     * If false: runs async in background, return value ignored.
+     */
+    blocking: boolean;
+    /** Scope: only fire for this agent (undefined = all agents) */
+    agentId?: string;
+    /** Scope: only fire for this project (undefined = all projects) */
+    projectId?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Whether this is a built-in system hook (can't be unregistered) */
+    builtin?: boolean;
+}
+export type HookRegistration<T extends HookType = HookType> = Omit<Hook<T>, "id">;
+export interface WebhookHook {
+    id: string;
+    type: HookType;
+    /** HTTP endpoint to POST the context to */
+    handlerUrl: string;
+    priority: number;
+    blocking: boolean;
+    agentId?: string;
+    projectId?: string;
+    description?: string;
+    enabled: boolean;
+    createdAt: string;
+    invocationCount: number;
+    failureCount: number;
+}
+//# sourceMappingURL=hooks.d.ts.map

package/dist/types/hooks.d.ts.map

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