@illuma-ai/agents 1.1.28 → 1.3.1

package/dist/esm/memory/pgvectorStore.mjs

@@ -0,0 +1,223 @@
+import { DEFAULT_MEMORY_TABLE, DEFAULT_MAX_SEARCH_RESULTS, DEFAULT_MIN_SCORE, HYBRID_VECTOR_WEIGHT, HYBRID_TEXT_WEIGHT } from './constants.mjs';
+import { getMemoryEmbedder } from './embeddings.mjs';
+import { applyMMRToMemoryHits } from './mmr.mjs';
+import { applyTemporalDecayToHits } from './temporalDecay.mjs';
+import { shouldIncludeCitations, decorateCitations } from './citations.mjs';
+import { getTierForPath, assertWritablePath } from './paths.mjs';
+
+function assertScope(scope) {
+    if (!scope || !scope.agentId) {
+        throw new Error('MemoryScope { agentId } is required — agentId must be non-empty');
+    }
+}
+/** pgvector literal format: "[0.1,0.2,...]". */
+function toVectorLiteral(vec) {
+    return `[${vec.join(',')}]`;
+}
+/**
+ * Normalize caller userId for the layered read filter.
+ *
+ * The SQL filter is `(user_id IS NULL OR user_id = $2)`, so an empty
+ * string from the caller must not match rows whose user_id was set.
+ * We coerce empty/null/undefined to `null`, and pg treats `$2 = null`
+ * as `false` — which is exactly what we want for isolated callers:
+ * they see only agent-tier rows and nothing in the user tier.
+ */
+function normalizeCallerId(scope) {
+    const raw = scope.userId;
+    if (raw == null || raw === '')
+        return null;
+    return String(raw);
+}
+class PgvectorMemoryStore {
+    kind = 'vector';
+    pool;
+    table;
+    embedder;
+    constructor(opts) {
+        this.pool = opts.pool;
+        this.table = opts.table ?? DEFAULT_MEMORY_TABLE;
+        this.embedder = opts.embedder ?? getMemoryEmbedder();
+    }
+    async search(scope, query, opts = {}) {
+        assertScope(scope);
+        const trimmed = query.trim();
+        if (!trimmed)
+            return [];
+        const maxResults = Math.max(1, opts.maxResults ?? DEFAULT_MAX_SEARCH_RESULTS);
+        const minScore = opts.minScore ?? DEFAULT_MIN_SCORE;
+        const vector = await this.embedder.embed(trimmed);
+        const vectorLiteral = toVectorLiteral(vector);
+        const callerId = normalizeCallerId(scope);
+        // [memory-layered-search] debug: layered scope filter
+        //   agent-tier rows (user_id IS NULL) + this caller's user-tier rows.
+        //   Another user's rows are invisible at the SQL layer.
+        const sql = `
+      WITH scored AS (
+        SELECT
+          id,
+          path,
+          content,
+          created_at,
+          user_id,
+          (1 - (embedding <=> $1::vector)) AS vector_score,
+          ts_rank(tsv, plainto_tsquery('english', $2)) AS text_score
+        FROM ${this.table}
+        WHERE agent_id = $3
+          AND (user_id IS NULL OR user_id = $4)
+      )
+      SELECT
+        id,
+        path,
+        content,
+        created_at,
+        user_id,
+        (${HYBRID_VECTOR_WEIGHT} * vector_score + ${HYBRID_TEXT_WEIGHT} * text_score) AS score
+      FROM scored
+      WHERE (${HYBRID_VECTOR_WEIGHT} * vector_score + ${HYBRID_TEXT_WEIGHT} * text_score) >= $5
+      ORDER BY score DESC
+      LIMIT $6
+    `;
+        const { rows } = await this.pool.query(sql, [
+            vectorLiteral,
+            trimmed,
+            scope.agentId,
+            callerId,
+            minScore,
+            maxResults,
+        ]);
+        let hits = rows.map((row) => ({
+            id: String(row.id),
+            path: row.path,
+            content: row.content,
+            createdAt: new Date(row.created_at),
+            score: Number(row.score),
+            source: 'vector',
+            tier: getTierForPath(row.path),
+        }));
+        // Phase 2: temporal decay (before MMR so diversity sees post-decay ranks)
+        if (opts.temporalDecay?.enabled) {
+            hits = applyTemporalDecayToHits(hits, opts.temporalDecay);
+            hits.sort((a, b) => b.score - a.score);
+        }
+        // Phase 2: MMR reranking
+        if (opts.mmr?.enabled) {
+            hits = applyMMRToMemoryHits(hits, opts.mmr);
+        }
+        // Phase 2: citations (decorate last — mutates content with Source: trailer)
+        const citationsMode = opts.citations ?? 'auto';
+        if (shouldIncludeCitations(citationsMode)) {
+            hits = decorateCitations(hits, true);
+        }
+        return hits;
+    }
+    async get(scope, opts) {
+        assertScope(scope);
+        if (!opts.path)
+            return null;
+        const callerId = normalizeCallerId(scope);
+        const tier = getTierForPath(opts.path);
+        // Agent-tier rows always live under user_id=NULL. User-tier rows
+        // always carry the caller's id. Querying with a precise predicate
+        // is faster than leaving it open AND guarantees a user cannot
+        // read another user's row even if they know the path by heart.
+        const userClause = tier === 'agent' ? 'user_id IS NULL' : 'user_id = $3';
+        const params = [scope.agentId, opts.path];
+        if (tier === 'user')
+            params.push(callerId);
+        const sql = `
+      SELECT content
+      FROM ${this.table}
+      WHERE agent_id = $1 AND path = $2 AND ${userClause}
+      ORDER BY updated_at DESC
+      LIMIT 1
+    `;
+        const { rows } = await this.pool.query(sql, params);
+        if (rows.length === 0)
+            return null;
+        const text = String(rows[0].content ?? '');
+        if (opts.from == null && opts.lines == null) {
+            return { path: opts.path, text };
+        }
+        const allLines = text.split('\n');
+        const fromIdx = Math.max(0, (opts.from ?? 1) - 1);
+        const count = Math.max(0, opts.lines ?? allLines.length - fromIdx);
+        const slice = allLines.slice(fromIdx, fromIdx + count).join('\n');
+        return { path: opts.path, text: slice };
+    }
+    async append(scope, input) {
+        assertScope(scope);
+        // Whitelist + tier + scope-compatibility check in one call. Throws
+        // with an actionable message for each failure mode.
+        const descriptor = assertWritablePath(input.path, scope);
+        const content = input.content.trim();
+        if (!content) {
+            throw new Error('memory_append content must be non-empty');
+        }
+        // Tier determines the row's user_id:
+        //   agent tier → NULL (shared across all users)
+        //   user tier  → the caller's id (assertWritablePath guarantees non-empty)
+        const rowUserId = descriptor.tier === 'agent' ? null : String(scope.userId);
+        const provenance = scope.userId != null ? String(scope.userId) : null;
+        // Read the existing row (if any) for THIS tier so we can embed the
+        // merged content. Agent-tier merges regardless of caller; user-tier
+        // merges only within the caller's own row.
+        const lookupSql = `
+      SELECT content FROM ${this.table}
+      WHERE agent_id = $1 AND path = $2 AND ${rowUserId === null ? 'user_id IS NULL' : 'user_id = $3'}
+      LIMIT 1
+    `;
+        const lookupParams = rowUserId === null
+            ? [scope.agentId, input.path]
+            : [scope.agentId, input.path, rowUserId];
+        const existing = await this.pool.query(lookupSql, lookupParams);
+        const priorContent = existing.rows.length > 0 ? String(existing.rows[0].content ?? '') : '';
+        const mergedContent = priorContent
+            ? `${priorContent.replace(/\s+$/, '')}\n\n${content}`
+            : content;
+        const vector = await this.embedder.embed(mergedContent);
+        const vectorLiteral = toVectorLiteral(vector);
+        // UPSERT on (agent_id, user_id, path) with NULLS NOT DISTINCT so
+        // two NULL user_ids collide on the same agent+path (exactly one
+        // agent-tier row) while per-user rows on the same path coexist.
+        //
+        // Provenance note: `last_user_id` always records WHO wrote the
+        // latest append, even for agent-tier rows where the row's own
+        // `user_id` stays NULL. That gives the admin UI an audit trail
+        // ("agent-tier row last updated by Alice") without changing the
+        // scoping semantics.
+        const upsertSql = `
+      INSERT INTO ${this.table} (agent_id, user_id, path, content, embedding, last_user_id, updated_at)
+      VALUES ($1, $2, $3, $4, $5::vector, $6, NOW())
+      ON CONFLICT (agent_id, user_id, path) DO UPDATE
+      SET content      = EXCLUDED.content,
+          embedding    = EXCLUDED.embedding,
+          last_user_id = EXCLUDED.last_user_id,
+          updated_at   = NOW()
+    `;
+        await this.pool.query(upsertSql, [
+            scope.agentId,
+            rowUserId,
+            input.path,
+            mergedContent,
+            vectorLiteral,
+            provenance,
+        ]);
+    }
+    async health() {
+        try {
+            await this.pool.query('SELECT 1');
+            return { ok: true, backend: 'vector' };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                backend: 'vector',
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+}
+
+export { PgvectorMemoryStore };
+//# sourceMappingURL=pgvectorStore.mjs.map

package/dist/esm/memory/pgvectorStore.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pgvectorStore.mjs","sources":["../../../src/memory/pgvectorStore.ts"],"sourcesContent":["/**\n * Postgres + pgvector implementation of {@link MemoryBackend}.\n *\n * ## Scoping model (two-tier, layered)\n *\n * Every read query applies the layered filter\n *\n *   WHERE agent_id = $1 AND (user_id IS NULL OR user_id = $2)\n *\n * so the caller sees:\n *   - agent-tier rows (`user_id IS NULL`) — shared operational knowledge,\n *     visible to every user of the agent\n *   - their own user-tier rows (`user_id = <caller>`) — private per-user\n *     personalization\n *\n * Another user's user-tier rows are invisible — the privacy boundary is\n * enforced in SQL, not just in the UI or route layer.\n *\n * ## Writes\n *\n * `append()` routes to a row based on the path's tier, resolved via\n * {@link assertWritablePath}:\n *\n *   - `memory/agent/*` → stored with `user_id = NULL` regardless of\n *     what scope the caller passed. Agent-tier content is inherently\n *     shared; scoping it per-user would defeat the point.\n *   - `memory/user/*`  → stored with `user_id = scope.userId`. A missing\n *     `scope.userId` throws — user-tier paths cannot be written from\n *     isolated/autonomous contexts.\n *\n * UPSERT key is `(agent_id, user_id, path)` with `NULLS NOT DISTINCT`,\n * so each user gets their own `user/preferences.md` row and there is\n * exactly one `agent/playbook.md` row shared across the whole user base.\n * Content accumulates via `\\n\\n` concatenation on conflict, with the\n * embedding regenerated over the merged content so search stays\n * consistent.\n */\nimport type { Pool } from 'pg';\nimport {\n  DEFAULT_MAX_SEARCH_RESULTS,\n  DEFAULT_MEMORY_TABLE,\n  DEFAULT_MIN_SCORE,\n  HYBRID_TEXT_WEIGHT,\n  HYBRID_VECTOR_WEIGHT,\n} from './constants';\nimport { getMemoryEmbedder, type EmbeddingProvider } from './embeddings';\nimport { applyMMRToMemoryHits } from './mmr';\nimport { applyTemporalDecayToHits } from './temporalDecay';\nimport { decorateCitations, shouldIncludeCitations } from './citations';\nimport { assertWritablePath, getTierForPath } from './paths';\nimport type {\n  MemoryAppendInput,\n  MemoryBackend,\n  MemoryEntry,\n  MemoryGetOptions,\n  MemoryHealth,\n  MemoryReadResult,\n  MemoryScope,\n  MemorySearchOptions,\n} from './types';\n\nexport interface PgvectorStoreOptions {\n  pool: Pool;\n  table?: string;\n  embedder?: EmbeddingProvider;\n}\n\nfunction assertScope(scope: MemoryScope): void {\n  if (!scope || !scope.agentId) {\n    throw new Error(\n      'MemoryScope { agentId } is required — agentId must be non-empty'\n    );\n  }\n}\n\n/** pgvector literal format: \"[0.1,0.2,...]\". */\nfunction toVectorLiteral(vec: number[]): string {\n  return `[${vec.join(',')}]`;\n}\n\n/**\n * Normalize caller userId for the layered read filter.\n *\n * The SQL filter is `(user_id IS NULL OR user_id = $2)`, so an empty\n * string from the caller must not match rows whose user_id was set.\n * We coerce empty/null/undefined to `null`, and pg treats `$2 = null`\n * as `false` — which is exactly what we want for isolated callers:\n * they see only agent-tier rows and nothing in the user tier.\n */\nfunction normalizeCallerId(scope: MemoryScope): string | null {\n  const raw = scope.userId;\n  if (raw == null || raw === '') return null;\n  return String(raw);\n}\n\nexport class PgvectorMemoryStore implements MemoryBackend {\n  readonly kind = 'vector' as const;\n  private pool: Pool;\n  private table: string;\n  private embedder: EmbeddingProvider;\n\n  constructor(opts: PgvectorStoreOptions) {\n    this.pool = opts.pool;\n    this.table = opts.table ?? DEFAULT_MEMORY_TABLE;\n    this.embedder = opts.embedder ?? getMemoryEmbedder();\n  }\n\n  async search(\n    scope: MemoryScope,\n    query: string,\n    opts: MemorySearchOptions = {}\n  ): Promise<MemoryEntry[]> {\n    assertScope(scope);\n    const trimmed = query.trim();\n    if (!trimmed) return [];\n\n    const maxResults = Math.max(\n      1,\n      opts.maxResults ?? DEFAULT_MAX_SEARCH_RESULTS\n    );\n    const minScore = opts.minScore ?? DEFAULT_MIN_SCORE;\n\n    const vector = await this.embedder.embed(trimmed);\n    const vectorLiteral = toVectorLiteral(vector);\n    const callerId = normalizeCallerId(scope);\n\n    // [memory-layered-search] debug: layered scope filter\n    //   agent-tier rows (user_id IS NULL) + this caller's user-tier rows.\n    //   Another user's rows are invisible at the SQL layer.\n    const sql = `\n      WITH scored AS (\n        SELECT\n          id,\n          path,\n          content,\n          created_at,\n          user_id,\n          (1 - (embedding <=> $1::vector)) AS vector_score,\n          ts_rank(tsv, plainto_tsquery('english', $2)) AS text_score\n        FROM ${this.table}\n        WHERE agent_id = $3\n          AND (user_id IS NULL OR user_id = $4)\n      )\n      SELECT\n        id,\n        path,\n        content,\n        created_at,\n        user_id,\n        (${HYBRID_VECTOR_WEIGHT} * vector_score + ${HYBRID_TEXT_WEIGHT} * text_score) AS score\n      FROM scored\n      WHERE (${HYBRID_VECTOR_WEIGHT} * vector_score + ${HYBRID_TEXT_WEIGHT} * text_score) >= $5\n      ORDER BY score DESC\n      LIMIT $6\n    `;\n\n    const { rows } = await this.pool.query(sql, [\n      vectorLiteral,\n      trimmed,\n      scope.agentId,\n      callerId,\n      minScore,\n      maxResults,\n    ]);\n\n    let hits: MemoryEntry[] = rows.map(\n      (row: {\n        id: string | number;\n        path: string;\n        content: string;\n        created_at: Date;\n        user_id: string | null;\n        score: string | number;\n      }): MemoryEntry => ({\n        id: String(row.id),\n        path: row.path,\n        content: row.content,\n        createdAt: new Date(row.created_at),\n        score: Number(row.score),\n        source: 'vector',\n        tier: getTierForPath(row.path),\n      })\n    );\n\n    // Phase 2: temporal decay (before MMR so diversity sees post-decay ranks)\n    if (opts.temporalDecay?.enabled) {\n      hits = applyTemporalDecayToHits(hits, opts.temporalDecay);\n      hits.sort((a, b) => b.score - a.score);\n    }\n\n    // Phase 2: MMR reranking\n    if (opts.mmr?.enabled) {\n      hits = applyMMRToMemoryHits(hits, opts.mmr);\n    }\n\n    // Phase 2: citations (decorate last — mutates content with Source: trailer)\n    const citationsMode = opts.citations ?? 'auto';\n    if (shouldIncludeCitations(citationsMode)) {\n      hits = decorateCitations(hits, true);\n    }\n\n    return hits;\n  }\n\n  async get(\n    scope: MemoryScope,\n    opts: MemoryGetOptions\n  ): Promise<MemoryReadResult | null> {\n    assertScope(scope);\n    if (!opts.path) return null;\n\n    const callerId = normalizeCallerId(scope);\n    const tier = getTierForPath(opts.path);\n\n    // Agent-tier rows always live under user_id=NULL. User-tier rows\n    // always carry the caller's id. Querying with a precise predicate\n    // is faster than leaving it open AND guarantees a user cannot\n    // read another user's row even if they know the path by heart.\n    const userClause = tier === 'agent' ? 'user_id IS NULL' : 'user_id = $3';\n\n    const params: unknown[] = [scope.agentId, opts.path];\n    if (tier === 'user') params.push(callerId);\n\n    const sql = `\n      SELECT content\n      FROM ${this.table}\n      WHERE agent_id = $1 AND path = $2 AND ${userClause}\n      ORDER BY updated_at DESC\n      LIMIT 1\n    `;\n    const { rows } = await this.pool.query(sql, params);\n    if (rows.length === 0) return null;\n\n    const text = String(rows[0].content ?? '');\n    if (opts.from == null && opts.lines == null) {\n      return { path: opts.path, text };\n    }\n\n    const allLines = text.split('\\n');\n    const fromIdx = Math.max(0, (opts.from ?? 1) - 1);\n    const count = Math.max(0, opts.lines ?? allLines.length - fromIdx);\n    const slice = allLines.slice(fromIdx, fromIdx + count).join('\\n');\n    return { path: opts.path, text: slice };\n  }\n\n  async append(scope: MemoryScope, input: MemoryAppendInput): Promise<void> {\n    assertScope(scope);\n    // Whitelist + tier + scope-compatibility check in one call. Throws\n    // with an actionable message for each failure mode.\n    const descriptor = assertWritablePath(input.path, scope);\n    const content = input.content.trim();\n    if (!content) {\n      throw new Error('memory_append content must be non-empty');\n    }\n\n    // Tier determines the row's user_id:\n    //   agent tier → NULL (shared across all users)\n    //   user tier  → the caller's id (assertWritablePath guarantees non-empty)\n    const rowUserId = descriptor.tier === 'agent' ? null : String(scope.userId);\n    const provenance = scope.userId != null ? String(scope.userId) : null;\n\n    // Read the existing row (if any) for THIS tier so we can embed the\n    // merged content. Agent-tier merges regardless of caller; user-tier\n    // merges only within the caller's own row.\n    const lookupSql = `\n      SELECT content FROM ${this.table}\n      WHERE agent_id = $1 AND path = $2 AND ${rowUserId === null ? 'user_id IS NULL' : 'user_id = $3'}\n      LIMIT 1\n    `;\n    const lookupParams: unknown[] =\n      rowUserId === null\n        ? [scope.agentId, input.path]\n        : [scope.agentId, input.path, rowUserId];\n    const existing = await this.pool.query(lookupSql, lookupParams);\n    const priorContent: string =\n      existing.rows.length > 0 ? String(existing.rows[0].content ?? '') : '';\n    const mergedContent = priorContent\n      ? `${priorContent.replace(/\\s+$/, '')}\\n\\n${content}`\n      : content;\n\n    const vector = await this.embedder.embed(mergedContent);\n    const vectorLiteral = toVectorLiteral(vector);\n\n    // UPSERT on (agent_id, user_id, path) with NULLS NOT DISTINCT so\n    // two NULL user_ids collide on the same agent+path (exactly one\n    // agent-tier row) while per-user rows on the same path coexist.\n    //\n    // Provenance note: `last_user_id` always records WHO wrote the\n    // latest append, even for agent-tier rows where the row's own\n    // `user_id` stays NULL. That gives the admin UI an audit trail\n    // (\"agent-tier row last updated by Alice\") without changing the\n    // scoping semantics.\n    const upsertSql = `\n      INSERT INTO ${this.table} (agent_id, user_id, path, content, embedding, last_user_id, updated_at)\n      VALUES ($1, $2, $3, $4, $5::vector, $6, NOW())\n      ON CONFLICT (agent_id, user_id, path) DO UPDATE\n      SET content      = EXCLUDED.content,\n          embedding    = EXCLUDED.embedding,\n          last_user_id = EXCLUDED.last_user_id,\n          updated_at   = NOW()\n    `;\n    await this.pool.query(upsertSql, [\n      scope.agentId,\n      rowUserId,\n      input.path,\n      mergedContent,\n      vectorLiteral,\n      provenance,\n    ]);\n  }\n\n  async health(): Promise<MemoryHealth> {\n    try {\n      await this.pool.query('SELECT 1');\n      return { ok: true, backend: 'vector' };\n    } catch (err) {\n      return {\n        ok: false,\n        backend: 'vector',\n        error: err instanceof Error ? err.message : String(err),\n      };\n    }\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/memory/recallTracking.mjs

@@ -0,0 +1,94 @@
+import { createHash } from 'crypto';
+
+/**
+ * Recall tracking — Phase 2.
+ *
+ * Lightweight adaptation of upstream
+ * `extensions/memory-core/src/short-term-promotion.ts::recordShortTermRecalls`.
+ * Upstream stores recalls in a JSON file under `memory/.dreams/`; we store
+ * them in a Postgres table `agent_memory_recalls`. Schema captures what the
+ * future Phase 3 dreaming/promotion algorithm will need:
+ *   - which memory row was surfaced (`memory_id`)
+ *   - the query that surfaced it (raw + SHA-256 hash for dedupe)
+ *   - hybrid score at the time of recall
+ *   - the day bucket (for per-day dedupe / frequency counting)
+ *   - the recorded timestamp
+ *
+ * Best-effort: failures never block memory_search. The caller fires
+ * {@link RecallTracker.record} without awaiting the result and ignores errors.
+ */
+const RECALL_TABLE = 'agent_memory_recalls';
+function hashQuery(query) {
+    return createHash('sha256')
+        .update(query.trim().toLowerCase())
+        .digest('hex')
+        .slice(0, 32);
+}
+function dayBucket(nowMs) {
+    const d = new Date(nowMs);
+    const y = d.getUTCFullYear();
+    const m = String(d.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(d.getUTCDate()).padStart(2, '0');
+    return `${y}-${m}-${day}`;
+}
+class PgvectorRecallTracker {
+    pool;
+    table;
+    constructor(pool, table = RECALL_TABLE) {
+        this.pool = pool;
+        this.table = table;
+    }
+    async migrate() {
+        // [recall-tracking] debug: create table + indexes if missing
+        await this.pool.query(`
+      CREATE TABLE IF NOT EXISTS ${this.table} (
+        id           BIGSERIAL   PRIMARY KEY,
+        agent_id     TEXT        NOT NULL,
+        memory_id    TEXT        NOT NULL,
+        memory_path  TEXT        NOT NULL,
+        query        TEXT        NOT NULL,
+        query_hash   TEXT        NOT NULL,
+        score        DOUBLE PRECISION NOT NULL,
+        day_bucket   TEXT        NOT NULL,
+        recorded_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
+      )
+    `);
+        await this.pool.query(`CREATE INDEX IF NOT EXISTS ${this.table}_agent_day_idx ON ${this.table} (agent_id, day_bucket)`);
+        await this.pool.query(`CREATE INDEX IF NOT EXISTS ${this.table}_memory_idx ON ${this.table} (agent_id, memory_id)`);
+        await this.pool.query(`CREATE UNIQUE INDEX IF NOT EXISTS ${this.table}_dedupe_idx
+       ON ${this.table} (agent_id, memory_id, query_hash, day_bucket)`);
+    }
+    async record(params) {
+        if (!params.agentId || !params.query.trim() || params.hits.length === 0)
+            return;
+        const nowMs = params.nowMs ?? Date.now();
+        const qhash = hashQuery(params.query);
+        const bucket = dayBucket(nowMs);
+        // [recall-tracking] debug: upsert one row per (agent, memory, query, day)
+        // Upstream dedupes per-day per-query so repeated searches don't inflate counts.
+        const values = [];
+        const args = [];
+        let i = 1;
+        for (const hit of params.hits) {
+            values.push(`($${i++}, $${i++}, $${i++}, $${i++}, $${i++}, $${i++}, $${i++}, NOW())`);
+            args.push(params.agentId, hit.id, hit.path, params.query, qhash, hit.score, bucket);
+        }
+        const sql = `
+      INSERT INTO ${this.table}
+        (agent_id, memory_id, memory_path, query, query_hash, score, day_bucket, recorded_at)
+      VALUES ${values.join(', ')}
+      ON CONFLICT (agent_id, memory_id, query_hash, day_bucket) DO UPDATE
+      SET score       = GREATEST(${this.table}.score, EXCLUDED.score),
+          recorded_at = NOW()
+    `;
+        await this.pool.query(sql, args);
+    }
+}
+/** No-op tracker — used when recall tracking is disabled or the backend isn't pgvector. */
+class NullRecallTracker {
+    async record() { }
+    async migrate() { }
+}
+
+export { NullRecallTracker, PgvectorRecallTracker, RECALL_TABLE };
+//# sourceMappingURL=recallTracking.mjs.map

package/dist/esm/memory/recallTracking.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"recallTracking.mjs","sources":["../../../src/memory/recallTracking.ts"],"sourcesContent":["/**\n * Recall tracking — Phase 2.\n *\n * Lightweight adaptation of upstream\n * `extensions/memory-core/src/short-term-promotion.ts::recordShortTermRecalls`.\n * Upstream stores recalls in a JSON file under `memory/.dreams/`; we store\n * them in a Postgres table `agent_memory_recalls`. Schema captures what the\n * future Phase 3 dreaming/promotion algorithm will need:\n *   - which memory row was surfaced (`memory_id`)\n *   - the query that surfaced it (raw + SHA-256 hash for dedupe)\n *   - hybrid score at the time of recall\n *   - the day bucket (for per-day dedupe / frequency counting)\n *   - the recorded timestamp\n *\n * Best-effort: failures never block memory_search. The caller fires\n * {@link RecallTracker.record} without awaiting the result and ignores errors.\n */\nimport { createHash } from 'crypto';\nimport type { Pool } from 'pg';\n\nexport interface RecallTracker {\n  /** Record that the given memory ids were surfaced to the model for a query. */\n  record(params: RecallRecordParams): Promise<void>;\n  /** Backend-specific schema migration. Idempotent. */\n  migrate(): Promise<void>;\n}\n\nexport interface RecallRecordParams {\n  agentId: string;\n  query: string;\n  hits: Array<{ id: string; path: string; score: number }>;\n  nowMs?: number;\n}\n\nexport const RECALL_TABLE = 'agent_memory_recalls';\n\nfunction hashQuery(query: string): string {\n  return createHash('sha256')\n    .update(query.trim().toLowerCase())\n    .digest('hex')\n    .slice(0, 32);\n}\n\nfunction dayBucket(nowMs: number): string {\n  const d = new Date(nowMs);\n  const y = d.getUTCFullYear();\n  const m = String(d.getUTCMonth() + 1).padStart(2, '0');\n  const day = String(d.getUTCDate()).padStart(2, '0');\n  return `${y}-${m}-${day}`;\n}\n\nexport class PgvectorRecallTracker implements RecallTracker {\n  constructor(\n    private readonly pool: Pool,\n    private readonly table: string = RECALL_TABLE\n  ) {}\n\n  async migrate(): Promise<void> {\n    // [recall-tracking] debug: create table + indexes if missing\n    await this.pool.query(`\n      CREATE TABLE IF NOT EXISTS ${this.table} (\n        id           BIGSERIAL   PRIMARY KEY,\n        agent_id     TEXT        NOT NULL,\n        memory_id    TEXT        NOT NULL,\n        memory_path  TEXT        NOT NULL,\n        query        TEXT        NOT NULL,\n        query_hash   TEXT        NOT NULL,\n        score        DOUBLE PRECISION NOT NULL,\n        day_bucket   TEXT        NOT NULL,\n        recorded_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()\n      )\n    `);\n    await this.pool.query(\n      `CREATE INDEX IF NOT EXISTS ${this.table}_agent_day_idx ON ${this.table} (agent_id, day_bucket)`\n    );\n    await this.pool.query(\n      `CREATE INDEX IF NOT EXISTS ${this.table}_memory_idx ON ${this.table} (agent_id, memory_id)`\n    );\n    await this.pool.query(\n      `CREATE UNIQUE INDEX IF NOT EXISTS ${this.table}_dedupe_idx\n       ON ${this.table} (agent_id, memory_id, query_hash, day_bucket)`\n    );\n  }\n\n  async record(params: RecallRecordParams): Promise<void> {\n    if (!params.agentId || !params.query.trim() || params.hits.length === 0)\n      return;\n    const nowMs = params.nowMs ?? Date.now();\n    const qhash = hashQuery(params.query);\n    const bucket = dayBucket(nowMs);\n\n    // [recall-tracking] debug: upsert one row per (agent, memory, query, day)\n    // Upstream dedupes per-day per-query so repeated searches don't inflate counts.\n    const values: string[] = [];\n    const args: unknown[] = [];\n    let i = 1;\n    for (const hit of params.hits) {\n      values.push(\n        `($${i++}, $${i++}, $${i++}, $${i++}, $${i++}, $${i++}, $${i++}, NOW())`\n      );\n      args.push(\n        params.agentId,\n        hit.id,\n        hit.path,\n        params.query,\n        qhash,\n        hit.score,\n        bucket\n      );\n    }\n    const sql = `\n      INSERT INTO ${this.table}\n        (agent_id, memory_id, memory_path, query, query_hash, score, day_bucket, recorded_at)\n      VALUES ${values.join(', ')}\n      ON CONFLICT (agent_id, memory_id, query_hash, day_bucket) DO UPDATE\n      SET score       = GREATEST(${this.table}.score, EXCLUDED.score),\n          recorded_at = NOW()\n    `;\n    await this.pool.query(sql, args);\n  }\n}\n\n/** No-op tracker — used when recall tracking is disabled or the backend isn't pgvector. */\nexport class NullRecallTracker implements RecallTracker {\n  async record(): Promise<void> {}\n  async migrate(): Promise<void> {}\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/memory/schema.sql

@@ -0,0 +1,51 @@
+-- Autonomous memory — Postgres schema (v2: layered tier scoping).
+--
+-- Two-tier canonical-document model:
+--
+--   memory/agent/*   → shared across every user of the agent (user_id = NULL)
+--   memory/user/*    → private to a specific caller (user_id = <callerId>)
+--
+-- Uniqueness key is `(agent_id, user_id, path)` with NULLS NOT DISTINCT
+-- so two NULL user_id rows on the same path collide (exactly-one
+-- agent-tier row per path) while per-user rows on the same path coexist
+-- (one row per user for user-tier paths).
+--
+-- The read path filters with `(user_id IS NULL OR user_id = $caller)`,
+-- so callers see agent-tier rows + only their own user-tier rows —
+-- never another user's private memory. Enforcement is in SQL, not just
+-- the UI.
+--
+-- NULLS NOT DISTINCT requires PostgreSQL 15+. Host's production
+-- pgvector image is PG16, so this is safe. The migration in
+-- `migrate.ts` will drop the legacy `(agent_id, path)` constraint
+-- before creating the new one if it exists on an older database.
+
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE IF NOT EXISTS agent_memories (
+  id           BIGSERIAL   PRIMARY KEY,
+  agent_id     TEXT        NOT NULL,
+  user_id      TEXT,                                -- NULL = agent-tier, shared
+  path         TEXT        NOT NULL,
+  content      TEXT        NOT NULL,
+  embedding    VECTOR(1024),
+  tsv          TSVECTOR    GENERATED ALWAYS AS (to_tsvector('english', content)) STORED,
+  created_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at   TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  last_user_id TEXT,                                -- latest session to append
+  CONSTRAINT agent_memories_agent_user_path_uq
+    UNIQUE NULLS NOT DISTINCT (agent_id, user_id, path)
+);
+
+-- Primary lookup index for list/search/generate-prompt — matches the
+-- exact filter shape of every read query.
+CREATE INDEX IF NOT EXISTS agent_memories_scope_idx
+  ON agent_memories (agent_id, user_id, path);
+
+-- Vector ANN index — untouched by the scoping change.
+CREATE INDEX IF NOT EXISTS agent_memories_vector_idx
+  ON agent_memories USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
+
+-- Full-text GIN index — untouched.
+CREATE INDEX IF NOT EXISTS agent_memories_tsv_idx
+  ON agent_memories USING GIN (tsv);

package/dist/esm/memory/temporalDecay.mjs

@@ -0,0 +1,110 @@
+/**
+ * Temporal decay — Phase 2.
+ *
+ * Ported from upstream `extensions/memory-core/src/memory/temporal-decay.ts`.
+ * Ages dated memory files (`memory/YYYY-MM-DD.md`) using exponential decay
+ * `multiplier = exp(-ln(2) / halfLifeDays * ageInDays)`. At half-life, the
+ * score is exactly halved.
+ *
+ * Evergreen files (MEMORY.md, memory/topics.md, any non-dated file inside
+ * memory/) do NOT decay — they represent durable knowledge and should stay
+ * hot regardless of age. This mirrors upstream's `isEvergreenMemoryPath`.
+ *
+ * Since our pgvector rows carry `createdAt`, we don't need filesystem stat
+ * fallback — the row timestamp is authoritative for any file without a
+ * date in the path.
+ */
+const DEFAULT_TEMPORAL_DECAY_CONFIG = {
+    enabled: false,
+    halfLifeDays: 30,
+};
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DATED_MEMORY_PATH_RE = /(?:^|\/)memory\/(\d{4})-(\d{2})-(\d{2})\.md$/;
+function toDecayLambda(halfLifeDays) {
+    if (!Number.isFinite(halfLifeDays) || halfLifeDays <= 0)
+        return 0;
+    return Math.LN2 / halfLifeDays;
+}
+function calculateTemporalDecayMultiplier(params) {
+    const lambda = toDecayLambda(params.halfLifeDays);
+    const age = Math.max(0, params.ageInDays);
+    if (lambda <= 0 || !Number.isFinite(age))
+        return 1;
+    return Math.exp(-lambda * age);
+}
+function applyTemporalDecayToScore(params) {
+    return params.score * calculateTemporalDecayMultiplier(params);
+}
+function normalizePath(p) {
+    return (p ?? '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+/** Parse a date out of `memory/YYYY-MM-DD.md` — returns null on non-match or invalid date. */
+function parseMemoryDateFromPath(filePath) {
+    const m = DATED_MEMORY_PATH_RE.exec(normalizePath(filePath));
+    if (!m)
+        return null;
+    const y = Number(m[1]);
+    const mo = Number(m[2]);
+    const d = Number(m[3]);
+    if (!Number.isInteger(y) || !Number.isInteger(mo) || !Number.isInteger(d))
+        return null;
+    const ts = Date.UTC(y, mo - 1, d);
+    const parsed = new Date(ts);
+    if (parsed.getUTCFullYear() !== y ||
+        parsed.getUTCMonth() !== mo - 1 ||
+        parsed.getUTCDate() !== d) {
+        return null;
+    }
+    return parsed;
+}
+/**
+ * Evergreen = durable knowledge file that should not decay.
+ * - `MEMORY.md` / `memory.md` at root
+ * - anything inside `memory/` that is NOT a dated `YYYY-MM-DD.md` file
+ */
+function isEvergreenMemoryPath(filePath) {
+    const n = normalizePath(filePath);
+    if (n === 'MEMORY.md' || n === 'memory.md')
+        return true;
+    if (!n.startsWith('memory/'))
+        return false;
+    return !DATED_MEMORY_PATH_RE.test(n);
+}
+function ageInDays(timestamp, nowMs) {
+    return Math.max(0, nowMs - timestamp.getTime()) / DAY_MS;
+}
+/**
+ * Apply temporal decay to a list of memory hits.
+ *
+ * Priority for the effective timestamp:
+ *   1. Dated path (`memory/YYYY-MM-DD.md`) — use the date in the path
+ *   2. Otherwise, if the path is evergreen — NO decay
+ *   3. Otherwise, use the row's `createdAt`
+ */
+function applyTemporalDecayToHits(hits, config = {}, nowMs = Date.now()) {
+    const merged = { ...DEFAULT_TEMPORAL_DECAY_CONFIG, ...config };
+    if (!merged.enabled)
+        return [...hits];
+    return hits.map((h) => {
+        const datedTs = parseMemoryDateFromPath(h.path);
+        let ts = datedTs;
+        if (!ts) {
+            if (isEvergreenMemoryPath(h.path))
+                return h;
+            ts = h.createdAt ?? null;
+        }
+        if (!ts)
+            return h;
+        return {
+            ...h,
+            score: applyTemporalDecayToScore({
+                score: h.score,
+                ageInDays: ageInDays(ts, nowMs),
+                halfLifeDays: merged.halfLifeDays,
+            }),
+        };
+    });
+}
+
+export { DEFAULT_TEMPORAL_DECAY_CONFIG, applyTemporalDecayToHits, applyTemporalDecayToScore, calculateTemporalDecayMultiplier, isEvergreenMemoryPath, parseMemoryDateFromPath, toDecayLambda };
+//# sourceMappingURL=temporalDecay.mjs.map

package/dist/esm/memory/temporalDecay.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporalDecay.mjs","sources":["../../../src/memory/temporalDecay.ts"],"sourcesContent":["/**\n * Temporal decay — Phase 2.\n *\n * Ported from upstream `extensions/memory-core/src/memory/temporal-decay.ts`.\n * Ages dated memory files (`memory/YYYY-MM-DD.md`) using exponential decay\n * `multiplier = exp(-ln(2) / halfLifeDays * ageInDays)`. At half-life, the\n * score is exactly halved.\n *\n * Evergreen files (MEMORY.md, memory/topics.md, any non-dated file inside\n * memory/) do NOT decay — they represent durable knowledge and should stay\n * hot regardless of age. This mirrors upstream's `isEvergreenMemoryPath`.\n *\n * Since our pgvector rows carry `createdAt`, we don't need filesystem stat\n * fallback — the row timestamp is authoritative for any file without a\n * date in the path.\n */\n\nexport interface TemporalDecayConfig {\n  enabled: boolean;\n  halfLifeDays: number;\n}\n\nexport const DEFAULT_TEMPORAL_DECAY_CONFIG: TemporalDecayConfig = {\n  enabled: false,\n  halfLifeDays: 30,\n};\n\nconst DAY_MS = 24 * 60 * 60 * 1000;\nconst DATED_MEMORY_PATH_RE = /(?:^|\\/)memory\\/(\\d{4})-(\\d{2})-(\\d{2})\\.md$/;\n\nexport function toDecayLambda(halfLifeDays: number): number {\n  if (!Number.isFinite(halfLifeDays) || halfLifeDays <= 0) return 0;\n  return Math.LN2 / halfLifeDays;\n}\n\nexport function calculateTemporalDecayMultiplier(params: {\n  ageInDays: number;\n  halfLifeDays: number;\n}): number {\n  const lambda = toDecayLambda(params.halfLifeDays);\n  const age = Math.max(0, params.ageInDays);\n  if (lambda <= 0 || !Number.isFinite(age)) return 1;\n  return Math.exp(-lambda * age);\n}\n\nexport function applyTemporalDecayToScore(params: {\n  score: number;\n  ageInDays: number;\n  halfLifeDays: number;\n}): number {\n  return params.score * calculateTemporalDecayMultiplier(params);\n}\n\nfunction normalizePath(p: string): string {\n  return (p ?? '').replace(/\\\\/g, '/').replace(/^\\.\\//, '');\n}\n\n/** Parse a date out of `memory/YYYY-MM-DD.md` — returns null on non-match or invalid date. */\nexport function parseMemoryDateFromPath(filePath: string): Date | null {\n  const m = DATED_MEMORY_PATH_RE.exec(normalizePath(filePath));\n  if (!m) return null;\n  const y = Number(m[1]);\n  const mo = Number(m[2]);\n  const d = Number(m[3]);\n  if (!Number.isInteger(y) || !Number.isInteger(mo) || !Number.isInteger(d))\n    return null;\n  const ts = Date.UTC(y, mo - 1, d);\n  const parsed = new Date(ts);\n  if (\n    parsed.getUTCFullYear() !== y ||\n    parsed.getUTCMonth() !== mo - 1 ||\n    parsed.getUTCDate() !== d\n  ) {\n    return null;\n  }\n  return parsed;\n}\n\n/**\n * Evergreen = durable knowledge file that should not decay.\n * - `MEMORY.md` / `memory.md` at root\n * - anything inside `memory/` that is NOT a dated `YYYY-MM-DD.md` file\n */\nexport function isEvergreenMemoryPath(filePath: string): boolean {\n  const n = normalizePath(filePath);\n  if (n === 'MEMORY.md' || n === 'memory.md') return true;\n  if (!n.startsWith('memory/')) return false;\n  return !DATED_MEMORY_PATH_RE.test(n);\n}\n\nfunction ageInDays(timestamp: Date, nowMs: number): number {\n  return Math.max(0, nowMs - timestamp.getTime()) / DAY_MS;\n}\n\nexport interface DecayCandidate {\n  path: string;\n  score: number;\n  createdAt?: Date;\n}\n\n/**\n * Apply temporal decay to a list of memory hits.\n *\n * Priority for the effective timestamp:\n *   1. Dated path (`memory/YYYY-MM-DD.md`) — use the date in the path\n *   2. Otherwise, if the path is evergreen — NO decay\n *   3. Otherwise, use the row's `createdAt`\n */\nexport function applyTemporalDecayToHits<T extends DecayCandidate>(\n  hits: T[],\n  config: Partial<TemporalDecayConfig> = {},\n  nowMs: number = Date.now()\n): T[] {\n  const merged = { ...DEFAULT_TEMPORAL_DECAY_CONFIG, ...config };\n  if (!merged.enabled) return [...hits];\n\n  return hits.map((h) => {\n    const datedTs = parseMemoryDateFromPath(h.path);\n    let ts: Date | null = datedTs;\n    if (!ts) {\n      if (isEvergreenMemoryPath(h.path)) return h;\n      ts = h.createdAt ?? null;\n    }\n    if (!ts) return h;\n    return {\n      ...h,\n      score: applyTemporalDecayToScore({\n        score: h.score,\n        ageInDays: ageInDays(ts, nowMs),\n        halfLifeDays: merged.halfLifeDays,\n      }),\n    };\n  });\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/nodes/ApprovalGateNode.mjs

@@ -23,7 +23,7 @@ import { safeDispatchCustomEvent } from '../utils/events.mjs';
  * @param destinationAgentId - The agent that follows this gate
  */
 function createApprovalGateNode(config, sourceAgentId, destinationAgentId) {
-    const { gateId, channel = 'chat', prompt, approver, timeoutMs, } = config;
+    const { gateId, channel = 'chat', prompt, approver, timeoutMs } = config;
     /**
      * The gate node function. Receives the current graph state,
      * dispatches a notification, calls interrupt(), and returns

package/dist/esm/nodes/ApprovalGateNode.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ApprovalGateNode.mjs","sources":["../../../src/nodes/ApprovalGateNode.ts"],"sourcesContent":["import { interrupt } from '@langchain/langgraph';\nimport type { RunnableConfig } from '@langchain/core/runnables';\nimport type { ApprovalGateConfig, BaseGraphState } from '@/types/graph';\nimport type { ToolApprovalResponse } from '@/types/tools';\nimport { GraphEvents } from '@/common';\nimport { safeDispatchCustomEvent } from '@/utils/events';\n\n/**\n * Interrupt payload for approval gate nodes.\n * Passed to interrupt() and persisted in the checkpoint.\n */\nexport interface ApprovalGateInterrupt {\n  /** Discriminator to distinguish from tool approval interrupts */\n  type: 'approval_gate';\n  /** Unique gate identifier */\n  gateId: string;\n  /** Approval channel (chat, outlook, telegram) */\n  channel: string;\n  /** Human-readable prompt for the approver */\n  prompt?: string;\n  /** Approver identifier */\n  approver?: string;\n  /** Timeout in ms */\n  timeoutMs?: number;\n  /** Source agent ID (who just finished) */\n  sourceAgentId?: string;\n  /** Destination agent ID (who will run next if approved) */\n  destinationAgentId?: string;\n}\n\n/**\n * Creates a graph node function that acts as an approval gate.\n *\n * Unlike tool approval (which respects ExecutionContext and can be auto-approved\n * in scheduled/handoff modes), approval gates ALWAYS fire. They are placed by\n * the builder between agents in a sequence and represent explicit human\n * checkpoints that cannot be bypassed.\n *\n * Flow:\n * 1. Dispatch ON_APPROVAL_GATE notification (for SSE/persistence)\n * 2. Call interrupt() — graph pauses, state is checkpointed\n * 3. On resume, interrupt() returns the ToolApprovalResponse\n * 4. If approved, pass state through (next agent runs)\n * 5. If denied, return state as-is (routing handled by conditional edge)\n *\n * @param config - The approval gate configuration from the edge definition\n * @param sourceAgentId - The agent that precedes this gate\n * @param destinationAgentId - The agent that follows this gate\n */\nexport function createApprovalGateNode(\n  config: ApprovalGateConfig,\n  sourceAgentId: string,\n  destinationAgentId: string,\n) {\n  const {\n    gateId,\n    channel = 'chat',\n    prompt,\n    approver,\n    timeoutMs,\n  } = config;\n\n  /**\n   * The gate node function. Receives the current graph state,\n   * dispatches a notification, calls interrupt(), and returns\n   * the state with an approval result annotation.\n   */\n  return async function approvalGateNode(\n    state: BaseGraphState,\n    runnableConfig?: RunnableConfig,\n  ): Promise<Partial<BaseGraphState>> {\n    const interruptPayload: ApprovalGateInterrupt = {\n      type: 'approval_gate',\n      gateId,\n      channel,\n      prompt,\n      approver,\n      timeoutMs,\n      sourceAgentId,\n      destinationAgentId,\n    };\n\n    // Dispatch notification event so the host can:\n    // 1. Persist the approval request to MongoDB\n    // 2. Route to the appropriate channel adapter\n    // 3. Emit SSE event for chat UI\n    safeDispatchCustomEvent(\n      GraphEvents.ON_APPROVAL_GATE,\n      interruptPayload,\n      runnableConfig,\n    );\n\n    // Pause the graph — state is checkpointed by the MongoDBSaver.\n    // On resume via Command({ resume: ToolApprovalResponse }), interrupt()\n    // returns the response value.\n    const response = interrupt(interruptPayload) as ToolApprovalResponse;\n\n    // Return empty state update — the graph structure (conditional edges)\n    // handles routing based on the approval result. We store the response\n    // in a message so downstream nodes can access it if needed.\n    if (response.approved) {\n      return {};\n    }\n\n    // On denial, we could add a system message noting the denial.\n    // The conditional edge after this node will route to END or skip.\n    return {};\n  };\n}\n\n/**\n * Node ID for an approval gate, derived from the gate configuration.\n * Used by MultiAgentGraph when inserting gate nodes into the graph.\n */\nexport function getApprovalGateNodeId(gateId: string): string {\n  return `approval_gate_${gateId}`;\n}\n"],"names":[],"mappings":";;;;;AA8BA;;;;;;;;;;;;;;;;;;AAkBG;SACa,sBAAsB,CACpC,MAA0B,EAC1B,aAAqB,EACrB,kBAA0B,EAAA;AAE1B,IAAA,MAAM,EACJ,MAAM,EACN,OAAO,GAAG,MAAM,EAChB,MAAM,EACN,QAAQ,EACR,SAAS,GACV,GAAG,MAAM;AAEV;;;;AAIG;AACH,IAAA,OAAO,eAAe,gBAAgB,CACpC,KAAqB,EACrB,cAA+B,EAAA;AAE/B,QAAA,MAAM,gBAAgB,GAA0B;AAC9C,YAAA,IAAI,EAAE,eAAe;YACrB,MAAM;YACN,OAAO;YACP,MAAM;YACN,QAAQ;YACR,SAAS;YACT,aAAa;YACb,kBAAkB;SACnB;;;;;QAMD,uBAAuB,CACrB,WAAW,CAAC,gBAAgB,EAC5B,gBAAgB,EAChB,cAAc,CACf;;;;AAKD,QAAA,MAAM,QAAQ,GAAG,SAAS,CAAC,gBAAgB,CAAyB;;;;AAKpE,QAAA,IAAI,QAAQ,CAAC,QAAQ,EAAE;AACrB,YAAA,OAAO,EAAE;QACX;;;AAIA,QAAA,OAAO,EAAE;AACX,IAAA,CAAC;AACH;AAEA;;;AAGG;AACG,SAAU,qBAAqB,CAAC,MAAc,EAAA;IAClD,OAAO,CAAA,cAAA,EAAiB,MAAM,CAAA,CAAE;AAClC;;;;"}
+{"version":3,"file":"ApprovalGateNode.mjs","sources":["../../../src/nodes/ApprovalGateNode.ts"],"sourcesContent":["import { interrupt } from '@langchain/langgraph';\nimport type { RunnableConfig } from '@langchain/core/runnables';\nimport type { ApprovalGateConfig, BaseGraphState } from '@/types/graph';\nimport type { ToolApprovalResponse } from '@/types/tools';\nimport { GraphEvents } from '@/common';\nimport { safeDispatchCustomEvent } from '@/utils/events';\n\n/**\n * Interrupt payload for approval gate nodes.\n * Passed to interrupt() and persisted in the checkpoint.\n */\nexport interface ApprovalGateInterrupt {\n  /** Discriminator to distinguish from tool approval interrupts */\n  type: 'approval_gate';\n  /** Unique gate identifier */\n  gateId: string;\n  /** Approval channel (chat, outlook, telegram) */\n  channel: string;\n  /** Human-readable prompt for the approver */\n  prompt?: string;\n  /** Approver identifier */\n  approver?: string;\n  /** Timeout in ms */\n  timeoutMs?: number;\n  /** Source agent ID (who just finished) */\n  sourceAgentId?: string;\n  /** Destination agent ID (who will run next if approved) */\n  destinationAgentId?: string;\n}\n\n/**\n * Creates a graph node function that acts as an approval gate.\n *\n * Unlike tool approval (which respects ExecutionContext and can be auto-approved\n * in scheduled/handoff modes), approval gates ALWAYS fire. They are placed by\n * the builder between agents in a sequence and represent explicit human\n * checkpoints that cannot be bypassed.\n *\n * Flow:\n * 1. Dispatch ON_APPROVAL_GATE notification (for SSE/persistence)\n * 2. Call interrupt() — graph pauses, state is checkpointed\n * 3. On resume, interrupt() returns the ToolApprovalResponse\n * 4. If approved, pass state through (next agent runs)\n * 5. If denied, return state as-is (routing handled by conditional edge)\n *\n * @param config - The approval gate configuration from the edge definition\n * @param sourceAgentId - The agent that precedes this gate\n * @param destinationAgentId - The agent that follows this gate\n */\nexport function createApprovalGateNode(\n  config: ApprovalGateConfig,\n  sourceAgentId: string,\n  destinationAgentId: string\n) {\n  const { gateId, channel = 'chat', prompt, approver, timeoutMs } = config;\n\n  /**\n   * The gate node function. Receives the current graph state,\n   * dispatches a notification, calls interrupt(), and returns\n   * the state with an approval result annotation.\n   */\n  return async function approvalGateNode(\n    state: BaseGraphState,\n    runnableConfig?: RunnableConfig\n  ): Promise<Partial<BaseGraphState>> {\n    const interruptPayload: ApprovalGateInterrupt = {\n      type: 'approval_gate',\n      gateId,\n      channel,\n      prompt,\n      approver,\n      timeoutMs,\n      sourceAgentId,\n      destinationAgentId,\n    };\n\n    // Dispatch notification event so the host can:\n    // 1. Persist the approval request to MongoDB\n    // 2. Route to the appropriate channel adapter\n    // 3. Emit SSE event for chat UI\n    safeDispatchCustomEvent(\n      GraphEvents.ON_APPROVAL_GATE,\n      interruptPayload,\n      runnableConfig\n    );\n\n    // Pause the graph — state is checkpointed by the MongoDBSaver.\n    // On resume via Command({ resume: ToolApprovalResponse }), interrupt()\n    // returns the response value.\n    const response = interrupt(interruptPayload) as ToolApprovalResponse;\n\n    // Return empty state update — the graph structure (conditional edges)\n    // handles routing based on the approval result. We store the response\n    // in a message so downstream nodes can access it if needed.\n    if (response.approved) {\n      return {};\n    }\n\n    // On denial, we could add a system message noting the denial.\n    // The conditional edge after this node will route to END or skip.\n    return {};\n  };\n}\n\n/**\n * Node ID for an approval gate, derived from the gate configuration.\n * Used by MultiAgentGraph when inserting gate nodes into the graph.\n */\nexport function getApprovalGateNodeId(gateId: string): string {\n  return `approval_gate_${gateId}`;\n}\n"],"names":[],"mappings":";;;;;AA8BA;;;;;;;;;;;;;;;;;;AAkBG;SACa,sBAAsB,CACpC,MAA0B,EAC1B,aAAqB,EACrB,kBAA0B,EAAA;AAE1B,IAAA,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM;AAExE;;;;AAIG;AACH,IAAA,OAAO,eAAe,gBAAgB,CACpC,KAAqB,EACrB,cAA+B,EAAA;AAE/B,QAAA,MAAM,gBAAgB,GAA0B;AAC9C,YAAA,IAAI,EAAE,eAAe;YACrB,MAAM;YACN,OAAO;YACP,MAAM;YACN,QAAQ;YACR,SAAS;YACT,aAAa;YACb,kBAAkB;SACnB;;;;;QAMD,uBAAuB,CACrB,WAAW,CAAC,gBAAgB,EAC5B,gBAAgB,EAChB,cAAc,CACf;;;;AAKD,QAAA,MAAM,QAAQ,GAAG,SAAS,CAAC,gBAAgB,CAAyB;;;;AAKpE,QAAA,IAAI,QAAQ,CAAC,QAAQ,EAAE;AACrB,YAAA,OAAO,EAAE;QACX;;;AAIA,QAAA,OAAO,EAAE;AACX,IAAA,CAAC;AACH;AAEA;;;AAGG;AACG,SAAU,qBAAqB,CAAC,MAAc,EAAA;IAClD,OAAO,CAAA,cAAA,EAAiB,MAAM,CAAA,CAAE;AAClC;;;;"}

package/dist/esm/prompts/memoryFlushPrompt.mjs

@@ -0,0 +1,44 @@
+import { DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT, FLUSH_PROMPT_RUBRIC_PLACEHOLDER, DEFAULT_MEMORY_FLUSH_PROMPT } from '../memory/constants.mjs';
+import { renderPathsRubric } from '../memory/paths.mjs';
+
+/**
+ * Memory-flush prompt resolver.
+ *
+ * The raw prompt strings live in `src/memory/constants.ts` and contain a
+ * single `{{MEMORY_PATHS_RUBRIC}}` placeholder. This module substitutes
+ * the caller-scoped rubric (produced by `renderPathsRubric()` in
+ * `src/memory/paths.ts`) into that placeholder at flush time, so:
+ *
+ *   - a collaborative agent with a real caller sees all 8 paths
+ *   - an isolated/autonomous agent sees only the 4 agent-tier paths
+ *     (user-tier rows are physically omitted from the rubric the LLM
+ *      sees, so it cannot route writes there even by mistake)
+ *
+ * ## Why this lives in prompts/ and not memory/constants.ts
+ *
+ * The constants file is pure strings — no imports, no runtime work.
+ * Injecting the rubric needs access to `renderPathsRubric()` which
+ * needs `MemoryScope`, so the substitution has to happen one layer up.
+ * Keeping the placeholder in constants and the substitution here means
+ * tests of the raw prompt (no scope) and tests of the rendered prompt
+ * (scope-aware) stay independent.
+ */
+/** Back-compat alias so existing callers keep working. */
+const MEMORY_FLUSH_SYSTEM_PROMPT = DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT;
+/**
+ * Substitutes the paths rubric into the raw prompts for a given scope.
+ *
+ * Idempotent (calling it twice on already-resolved strings is a no-op
+ * because the placeholder will have been replaced already). Safe to
+ * call per-flush; no caching needed — the string concat is microseconds.
+ */
+function resolveFlushPrompts(options) {
+    const rubric = renderPathsRubric(options.scope);
+    return {
+        prompt: DEFAULT_MEMORY_FLUSH_PROMPT.replaceAll(FLUSH_PROMPT_RUBRIC_PLACEHOLDER, rubric),
+        systemPrompt: DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT.replaceAll(FLUSH_PROMPT_RUBRIC_PLACEHOLDER, rubric),
+    };
+}
+
+export { DEFAULT_MEMORY_FLUSH_PROMPT, DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT, MEMORY_FLUSH_SYSTEM_PROMPT, resolveFlushPrompts };
+//# sourceMappingURL=memoryFlushPrompt.mjs.map

package/dist/esm/prompts/memoryFlushPrompt.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryFlushPrompt.mjs","sources":["../../../src/prompts/memoryFlushPrompt.ts"],"sourcesContent":["/**\n * Memory-flush prompt resolver.\n *\n * The raw prompt strings live in `src/memory/constants.ts` and contain a\n * single `{{MEMORY_PATHS_RUBRIC}}` placeholder. This module substitutes\n * the caller-scoped rubric (produced by `renderPathsRubric()` in\n * `src/memory/paths.ts`) into that placeholder at flush time, so:\n *\n *   - a collaborative agent with a real caller sees all 8 paths\n *   - an isolated/autonomous agent sees only the 4 agent-tier paths\n *     (user-tier rows are physically omitted from the rubric the LLM\n *      sees, so it cannot route writes there even by mistake)\n *\n * ## Why this lives in prompts/ and not memory/constants.ts\n *\n * The constants file is pure strings — no imports, no runtime work.\n * Injecting the rubric needs access to `renderPathsRubric()` which\n * needs `MemoryScope`, so the substitution has to happen one layer up.\n * Keeping the placeholder in constants and the substitution here means\n * tests of the raw prompt (no scope) and tests of the rendered prompt\n * (scope-aware) stay independent.\n */\nimport {\n  DEFAULT_MEMORY_FLUSH_PROMPT,\n  DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT,\n  FLUSH_PROMPT_RUBRIC_PLACEHOLDER,\n} from '@/memory/constants';\nimport { renderPathsRubric } from '@/memory/paths';\nimport type { MemoryScope } from '@/memory/types';\n\nexport { DEFAULT_MEMORY_FLUSH_PROMPT, DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT };\n\n/** Back-compat alias so existing callers keep working. */\nexport const MEMORY_FLUSH_SYSTEM_PROMPT = DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT;\n\n/** Minimum scope shape needed to render the rubric. */\nexport interface ResolveFlushPromptsOptions {\n  /**\n   * The scope the memory tools were built with. Only `userId` matters\n   * for rubric rendering — if absent, the user-tier paths are filtered\n   * out of the rubric the LLM sees.\n   */\n  scope: Pick<MemoryScope, 'userId'>;\n}\n\n/**\n * Result shape returned to `runMemoryFlush`. `prompt` goes in the\n * HumanMessage, `systemPrompt` goes in the SystemMessage. Both already\n * have the rubric substituted — the caller should pass them through\n * verbatim.\n */\nexport interface ResolvedFlushPrompts {\n  prompt: string;\n  systemPrompt: string;\n}\n\n/**\n * Substitutes the paths rubric into the raw prompts for a given scope.\n *\n * Idempotent (calling it twice on already-resolved strings is a no-op\n * because the placeholder will have been replaced already). Safe to\n * call per-flush; no caching needed — the string concat is microseconds.\n */\nexport function resolveFlushPrompts(\n  options: ResolveFlushPromptsOptions\n): ResolvedFlushPrompts {\n  const rubric = renderPathsRubric(options.scope);\n  return {\n    prompt: DEFAULT_MEMORY_FLUSH_PROMPT.replaceAll(\n      FLUSH_PROMPT_RUBRIC_PLACEHOLDER,\n      rubric\n    ),\n    systemPrompt: DEFAULT_MEMORY_FLUSH_SYSTEM_PROMPT.replaceAll(\n      FLUSH_PROMPT_RUBRIC_PLACEHOLDER,\n      rubric\n    ),\n  };\n}\n"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;AAqBG;AAWH;AACO,MAAM,0BAA0B,GAAG;AAuB1C;;;;;;AAMG;AACG,SAAU,mBAAmB,CACjC,OAAmC,EAAA;IAEnC,MAAM,MAAM,GAAG,iBAAiB,CAAC,OAAO,CAAC,KAAK,CAAC;IAC/C,OAAO;QACL,MAAM,EAAE,2BAA2B,CAAC,UAAU,CAC5C,+BAA+B,EAC/B,MAAM,CACP;QACD,YAAY,EAAE,kCAAkC,CAAC,UAAU,CACzD,+BAA+B,EAC/B,MAAM,CACP;KACF;AACH;;;;"}