@hasna/mementos 0.14.86 → 0.14.87

package/dist/storage.d.ts

@@ -0,0 +1,280 @@
+import { Database } from "bun:sqlite";
+import type { Pool, PoolClient } from "pg";
+import { type ServerDataBackend } from "./generated/storage-kit/backend.js";
+/** Called once by the mementos-serve entrypoint; enables the server-only DSN path. */
+export declare function markServerContext(): void;
+export declare function resetServerContextForTests(): void;
+/** True only inside the `mementos-serve` server process. */
+export declare function isServerContext(): boolean;
+export interface RunResult {
+    changes: number;
+    lastInsertRowid: number | bigint;
+}
+export interface PreparedStatement {
+    run(...params: any[]): RunResult;
+    get(...params: any[]): any;
+    all(...params: any[]): any[];
+    finalize(): void;
+}
+export interface DbAdapter {
+    run(sql: string, ...params: any[]): RunResult;
+    get(sql: string, ...params: any[]): any;
+    all(sql: string, ...params: any[]): any[];
+    exec(sql: string): void;
+    prepare(sql: string): PreparedStatement;
+    close(): void;
+    transaction<T>(fn: () => T): T;
+}
+export declare class SqliteAdapter implements DbAdapter {
+    private readonly db;
+    constructor(path: string);
+    run(sql: string, ...params: any[]): RunResult;
+    get(sql: string, ...params: any[]): any;
+    all(sql: string, ...params: any[]): any[];
+    exec(sql: string): void;
+    query(sql: string): import("bun:sqlite").Statement<unknown, import("bun:sqlite").SQLQueryBindings[] | [null] | [string] | [number] | [bigint] | [false] | [true] | [Uint8Array<ArrayBufferLike>] | [Uint8ClampedArray<ArrayBufferLike>] | [Uint16Array<ArrayBufferLike>] | [Uint32Array<ArrayBufferLike>] | [Int8Array<ArrayBufferLike>] | [Int16Array<ArrayBufferLike>] | [Int32Array<ArrayBufferLike>] | [BigUint64Array<ArrayBufferLike>] | [BigInt64Array<ArrayBufferLike>] | [Float16Array<ArrayBufferLike>] | [Float32Array<ArrayBufferLike>] | [Float64Array<ArrayBufferLike>] | [Record<string, string | number | bigint | boolean | NodeJS.TypedArray<ArrayBufferLike> | null>]>;
+    prepare(sql: string): PreparedStatement;
+    close(): void;
+    transaction<T>(fn: () => T): T;
+    get raw(): Database;
+}
+export declare function translateSql(sql: string): string;
+export declare function shouldUsePgSsl(connectionString: string): boolean;
+/** Build a pg Pool with adapter-controlled SSL from a connection string. */
+export declare function makePool(connectionString: string): Pool;
+interface SyncQueryResult {
+    rows: any[];
+    rowCount: number;
+}
+/**
+ * Synchronous Postgres access backed by a worker thread (see
+ * `pg-sync-worker.ts`). The worker owns one long-lived `pg.Client` and runs
+ * queries on its own event loop; the main thread blocks on `Atomics.wait`
+ * against a SharedArrayBuffer until the worker writes the response. This is the
+ * only way to expose a truly synchronous API (which the entire mementos data
+ * layer requires) over async pg I/O without deadlocking the main event loop.
+ *
+ * Every query carries a monotonic generation that the worker echoes back in
+ * the status word when the response is ready. When a query times out it is
+ * ABANDONED, not cancelled — the worker still finishes it and writes its
+ * response later — and the generation is what lets the caller tell that late
+ * response apart from the response to the query currently waiting, so a stale
+ * payload can never be consumed by a newer query (todos 027d17e9).
+ */
+export declare class PgSyncPool {
+    private readonly worker;
+    private readonly status;
+    private readonly data;
+    private closed;
+    private lastError;
+    private generation;
+    private static readonly DATA_BYTES;
+    /**
+     * Per-query timeout in milliseconds, overridable via
+     * `MEMENTOS_PGSYNC_QUERY_TIMEOUT_MS` (default 60_000). Read on every query()
+     * call so tests can shrink it without import-order games — the regression
+     * test in `pg-sync-race.test.ts` relies on this being a live read.
+     */
+    private static queryTimeoutMs;
+    /**
+     * Resolve the worker entry file. `storage` is bundled into several entry
+     * points at different depths (dist/cli, dist/mcp, dist/server) as well as run
+     * directly from source, so probe candidate locations relative to this module.
+     */
+    private static resolveWorkerPath;
+    constructor(connectionString: string, workerPath?: string);
+    query(sql: string, params: any[]): SyncQueryResult;
+    end(): void;
+}
+export declare class PgAdapter implements DbAdapter {
+    private readonly pool;
+    constructor(connectionString: string);
+    constructor(pool: PgSyncPool);
+    run(sql: string, ...params: any[]): RunResult;
+    get(sql: string, ...params: any[]): any;
+    all(sql: string, ...params: any[]): any[];
+    exec(sql: string): void;
+    prepare(sql: string): PreparedStatement;
+    /**
+     * Bun-sqlite-style `query()` shim so the CLI/MCP/server call sites that do
+     * `db.query(sql).get(...)` / `.all(...)` / `.run(...)` work unchanged against
+     * Postgres in the postgresql backend. Behaves like {@link prepare}.
+     */
+    query(sql: string): PreparedStatement;
+    close(): void;
+    transaction<T>(fn: () => T): T;
+    get raw(): PgSyncPool;
+}
+export declare class PgAdapterAsync {
+    private readonly pool;
+    constructor(connectionString: string);
+    constructor(pool: Pool);
+    run(sql: string, ...params: any[]): Promise<RunResult>;
+    get(sql: string, ...params: any[]): Promise<any>;
+    all(sql: string, ...params: any[]): Promise<any[]>;
+    exec(sql: string): Promise<void>;
+    close(): Promise<void>;
+    transaction<T>(fn: (client: PoolClient) => Promise<T>): Promise<T>;
+    get raw(): Pool;
+}
+export declare const MEMENTOS_STORAGE_TABLES: readonly ["projects", "agents", "machines", "sessions", "entities", "memories", "relations", "entity_memories", "memory_tags", "memory_versions", "memory_embeddings", "tool_events", "resource_locks", "memory_ratings"];
+export declare const STORAGE_TABLES: readonly ["projects", "agents", "machines", "sessions", "entities", "memories", "relations", "entity_memories", "memory_tags", "memory_versions", "memory_embeddings", "tool_events", "resource_locks", "memory_ratings"];
+export type MementosStorageTable = (typeof MEMENTOS_STORAGE_TABLES)[number];
+export declare const MEMENTOS_STORAGE_ENV: {
+    readonly databaseUrl: "HASNA_MEMENTOS_DATABASE_URL";
+};
+export declare const MEMENTOS_STORAGE_FALLBACK_ENV: {
+    readonly databaseUrl: "MEMENTOS_DATABASE_URL";
+};
+export interface StorageConfig {
+    rds: {
+        host: string;
+        port: number;
+        username: string;
+        password_env: string;
+        ssl: boolean;
+    };
+    auto_sync_interval_minutes: number;
+    feedback_endpoint: string;
+    sync: {
+        schedule_minutes: number;
+    };
+}
+export interface StorageEnv {
+    name: string;
+    deprecated: boolean;
+}
+export interface StorageEnvStatus {
+    name: string;
+    active_name: string;
+    configured: boolean;
+}
+/** The server data backend, from the shared storage kit: `sqlite | postgresql`. */
+export type StorageRuntimeKind = ServerDataBackend;
+export interface StorageRuntimeContract {
+    contract: "mementos-storage-runtime-v1";
+    kind: StorageRuntimeKind;
+    fail_closed: boolean;
+    local: {
+        adapter: "sqlite";
+        primary_runtime: boolean;
+        data_dir: string;
+        config_path: string;
+        local_file_sync: {
+            supported: false;
+            reason: string;
+        };
+    };
+    backend: {
+        adapter: "sqlite" | "postgres";
+        requested: boolean;
+        configured: boolean;
+        source: "env" | "config-file" | "none";
+        env_name: string | null;
+        redacted_url: string | null;
+        rds_compatible: boolean;
+        fail_closed: boolean;
+        missing: string[];
+    };
+    migrations: {
+        target: "postgres-rds-compatible";
+        command: "mementos storage migrate";
+        dry_run_command: "mementos storage migrate --dry-run";
+        configured: boolean;
+        mutates_remote_on_apply: true;
+        requires_approval_for_live_run: true;
+    };
+}
+export interface SafeStorageConfigSummary {
+    auto_sync_interval_minutes: number;
+    feedback_endpoint_configured: boolean;
+    sync: StorageConfig["sync"];
+    rds: {
+        host_configured: boolean;
+        port: number;
+        username_configured: boolean;
+        password_env: string;
+        password_configured: boolean;
+        ssl: boolean;
+    };
+}
+export interface NativeStorageStatus {
+    ok: boolean;
+    service: "mementos";
+    backend: StorageRuntimeKind;
+    local_default: boolean;
+    runtime: StorageRuntimeContract;
+    database: {
+        configured: boolean;
+        redacted_url: string | null;
+        source: "env" | "config-file" | "none";
+        env_name: string | null;
+        rds_compatible: boolean;
+    };
+    tables: readonly MementosStorageTable[];
+    env: {
+        databaseUrl: StorageEnvStatus;
+    };
+    issues: string[];
+    warnings: string[];
+    no_network: true;
+}
+export declare function getConfigDir(): string;
+export declare function getConfigPath(): string;
+export declare function getStorageDatabaseEnv(): StorageEnv | null;
+export declare function getStorageDatabaseUrl(): string | null;
+export declare function getStorageDatabaseEnvName(): string;
+/**
+ * The server data backend selected by the environment: `postgresql` when
+ * HASNA_MEMENTOS_DATABASE_URL is set, `sqlite` otherwise. Runs the fail-loud
+ * ratchet first, so a retired storage-mode variable throws here rather than
+ * being silently ignored. Delegated to the vendored storage kit so the key
+ * spec and the ratchet cannot drift from the shared contract.
+ */
+export declare function getStorageBackend(env?: NodeJS.ProcessEnv): ServerDataBackend;
+/** The database URL for the selected server backend, or `null` when sqlite. */
+export declare function getStorageBackendDatabaseUrl(env?: NodeJS.ProcessEnv): string | null;
+export declare function getStorageConfig(): StorageConfig;
+export declare function redactDatabaseUrl(value: string | null): string | null;
+export interface PostgresConnectionStringValidation {
+    ok: boolean;
+    redacted_url: string | null;
+    issues: string[];
+}
+export declare function validatePostgresConnectionString(value: string | null): PostgresConnectionStringValidation;
+export declare function getSafeStorageConfigSummary(config?: StorageConfig): SafeStorageConfigSummary;
+export declare function getStorageStatus(): NativeStorageStatus;
+export declare const getMementosStorageStatus: typeof getStorageStatus;
+export declare function saveStorageConfig(config: StorageConfig): void;
+export declare function getStorageConnectionString(dbName?: string): string;
+export declare const SYNC_EXCLUDED_TABLE_PATTERNS: RegExp[];
+export declare function isSyncExcludedTable(table: string): boolean;
+export declare function listSqliteTables(db: DbAdapter): string[];
+export interface IncrementalSyncStats {
+    table: string;
+    total_rows: number;
+    synced_rows: number;
+    skipped_rows: number;
+    errors: string[];
+    first_sync: boolean;
+}
+export interface SyncMeta {
+    table_name: string;
+    last_synced_at: string;
+    last_synced_row_count: number;
+    direction: "push" | "pull";
+}
+export interface IncrementalSyncOptions {
+    primaryKey?: string;
+    conflictColumn?: string;
+    batchSize?: number;
+}
+export declare function ensureSyncMetaTable(db: DbAdapter): void;
+export declare function incrementalSyncPush(local: DbAdapter, remote: DbAdapter, tables: string[], options?: IncrementalSyncOptions): IncrementalSyncStats[];
+export declare function incrementalSyncPull(remote: DbAdapter, local: DbAdapter, tables: string[], options?: IncrementalSyncOptions): IncrementalSyncStats[];
+export declare function getSyncMetaAll(db: DbAdapter): SyncMeta[];
+export declare function getSyncMetaForTable(db: DbAdapter, table: string): SyncMeta | null;
+export declare function resetSyncMeta(db: DbAdapter, table: string): void;
+export declare function resetAllSyncMeta(db: DbAdapter): void;
+export {};
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

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

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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"}