@illuma-ai/agents 1.1.28 → 1.3.1

package/dist/cjs/memory/embeddings.cjs

@@ -0,0 +1,151 @@
+'use strict';
+
+var clientBedrockRuntime = require('@aws-sdk/client-bedrock-runtime');
+var constants = require('./constants.cjs');
+
+/**
+ * Provider-agnostic embedding client for autonomous memory.
+ *
+ * Factory pattern mirrors host's `getSharedSummaryBedrockClient()` in
+ * `api/server/controllers/agents/client.js` — lazy init, shared instance,
+ * testable reset. Same AWS credential chain as host's existing Bedrock
+ * calls, so no new IAM policy or secret.
+ */
+/**
+ * Read embedder config from environment. Called once per factory invocation;
+ * fresh reads make testing override-friendly via {@link resetMemoryEmbedder}.
+ */
+function resolveConfig() {
+    const rawProvider = (process.env.MEMORY_EMBEDDINGS_PROVIDER ?? constants.DEFAULT_MEMORY_PROVIDER).toLowerCase();
+    if (rawProvider !== 'bedrock' && rawProvider !== 'openai') {
+        throw new Error(`Unsupported MEMORY_EMBEDDINGS_PROVIDER: "${rawProvider}". Supported: bedrock, openai.`);
+    }
+    const model = process.env.MEMORY_EMBEDDINGS_MODEL ?? constants.DEFAULT_MEMORY_MODEL;
+    const dimensions = Number(process.env.MEMORY_EMBEDDINGS_DIMENSIONS) ||
+        constants.DEFAULT_MEMORY_DIMENSIONS;
+    return { provider: rawProvider, model, dimensions };
+}
+class BedrockEmbedder {
+    kind = 'bedrock';
+    model;
+    dimensions;
+    client;
+    constructor(params) {
+        this.model = params.model;
+        this.dimensions = params.dimensions;
+        const region = process.env.BEDROCK_AWS_DEFAULT_REGION ??
+            process.env.AWS_REGION ??
+            'us-east-1';
+        // Default credential provider chain — identical to host's existing
+        // Bedrock client. In ECS this resolves to the task role.
+        this.client = new clientBedrockRuntime.BedrockRuntimeClient({ region });
+    }
+    async embed(text) {
+        const input = text.trim();
+        if (!input) {
+            throw new Error('Cannot embed empty text');
+        }
+        const body = {
+            inputText: input,
+            dimensions: this.dimensions,
+            normalize: true,
+        };
+        const command = new clientBedrockRuntime.InvokeModelCommand({
+            modelId: this.model,
+            contentType: 'application/json',
+            accept: 'application/json',
+            body: new TextEncoder().encode(JSON.stringify(body)),
+        });
+        const response = await this.client.send(command);
+        const decoded = JSON.parse(new TextDecoder().decode(response.body));
+        if (!Array.isArray(decoded.embedding)) {
+            throw new Error('Bedrock embedding response missing `embedding` field');
+        }
+        return decoded.embedding;
+    }
+    async embedBatch(texts) {
+        // Titan embed v2 has no native batch API — sequential calls are the
+        // documented pattern. Parallelism here can trip per-account TPS ceilings,
+        // so we keep it serial. For Phase 4 we can introduce a bounded queue.
+        const out = [];
+        for (const text of texts) {
+            out.push(await this.embed(text));
+        }
+        return out;
+    }
+}
+class OpenAIEmbedder {
+    kind = 'openai';
+    model;
+    dimensions;
+    apiKey;
+    baseUrl;
+    constructor(params) {
+        this.model = params.model;
+        this.dimensions = params.dimensions;
+        const apiKey = process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new Error('OPENAI_API_KEY is not set — required when MEMORY_EMBEDDINGS_PROVIDER=openai');
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = process.env.OPENAI_BASEURL ?? 'https://api.openai.com/v1';
+    }
+    async call(texts) {
+        const res = await fetch(`${this.baseUrl}/embeddings`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({ model: this.model, input: texts }),
+        });
+        if (!res.ok) {
+            const errText = await res.text();
+            throw new Error(`OpenAI embeddings ${res.status}: ${errText}`);
+        }
+        const json = (await res.json());
+        return json.data.map((d) => d.embedding);
+    }
+    async embed(text) {
+        const [vec] = await this.call([text]);
+        return vec;
+    }
+    async embedBatch(texts) {
+        if (texts.length === 0)
+            return [];
+        return this.call(texts);
+    }
+}
+let sharedEmbedder = null;
+/**
+ * Lazy singleton accessor. Same idiom as host's
+ * `getSharedSummaryBedrockClient()`.
+ */
+function getMemoryEmbedder() {
+    if (sharedEmbedder)
+        return sharedEmbedder;
+    const cfg = resolveConfig();
+    switch (cfg.provider) {
+        case 'bedrock':
+            sharedEmbedder = new BedrockEmbedder({
+                model: cfg.model,
+                dimensions: cfg.dimensions,
+            });
+            break;
+        case 'openai':
+            sharedEmbedder = new OpenAIEmbedder({
+                model: cfg.model,
+                dimensions: cfg.dimensions,
+            });
+            break;
+    }
+    return sharedEmbedder;
+}
+/** Test hook — drops the cached embedder so the next call re-reads env. */
+function resetMemoryEmbedder() {
+    sharedEmbedder = null;
+}
+
+exports.getMemoryEmbedder = getMemoryEmbedder;
+exports.resetMemoryEmbedder = resetMemoryEmbedder;
+//# sourceMappingURL=embeddings.cjs.map

package/dist/cjs/memory/embeddings.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.cjs","sources":["../../../src/memory/embeddings.ts"],"sourcesContent":["/**\n * Provider-agnostic embedding client for autonomous memory.\n *\n * Factory pattern mirrors host's `getSharedSummaryBedrockClient()` in\n * `api/server/controllers/agents/client.js` — lazy init, shared instance,\n * testable reset. Same AWS credential chain as host's existing Bedrock\n * calls, so no new IAM policy or secret.\n */\nimport {\n  BedrockRuntimeClient,\n  InvokeModelCommand,\n} from '@aws-sdk/client-bedrock-runtime';\nimport {\n  DEFAULT_MEMORY_DIMENSIONS,\n  DEFAULT_MEMORY_MODEL,\n  DEFAULT_MEMORY_PROVIDER,\n} from './constants';\n\nexport type EmbeddingProviderKind = 'bedrock' | 'openai';\n\nexport interface EmbeddingProvider {\n  readonly kind: EmbeddingProviderKind;\n  readonly model: string;\n  readonly dimensions: number;\n  embed(text: string): Promise<number[]>;\n  embedBatch(texts: string[]): Promise<number[][]>;\n}\n\ninterface ResolvedEmbedderConfig {\n  provider: EmbeddingProviderKind;\n  model: string;\n  dimensions: number;\n}\n\n/**\n * Read embedder config from environment. Called once per factory invocation;\n * fresh reads make testing override-friendly via {@link resetMemoryEmbedder}.\n */\nfunction resolveConfig(): ResolvedEmbedderConfig {\n  const rawProvider = (\n    process.env.MEMORY_EMBEDDINGS_PROVIDER ?? DEFAULT_MEMORY_PROVIDER\n  ).toLowerCase();\n  if (rawProvider !== 'bedrock' && rawProvider !== 'openai') {\n    throw new Error(\n      `Unsupported MEMORY_EMBEDDINGS_PROVIDER: \"${rawProvider}\". Supported: bedrock, openai.`\n    );\n  }\n  const model = process.env.MEMORY_EMBEDDINGS_MODEL ?? DEFAULT_MEMORY_MODEL;\n  const dimensions =\n    Number(process.env.MEMORY_EMBEDDINGS_DIMENSIONS) ||\n    DEFAULT_MEMORY_DIMENSIONS;\n  return { provider: rawProvider, model, dimensions };\n}\n\nclass BedrockEmbedder implements EmbeddingProvider {\n  readonly kind = 'bedrock' as const;\n  readonly model: string;\n  readonly dimensions: number;\n  private client: BedrockRuntimeClient;\n\n  constructor(params: { model: string; dimensions: number }) {\n    this.model = params.model;\n    this.dimensions = params.dimensions;\n    const region =\n      process.env.BEDROCK_AWS_DEFAULT_REGION ??\n      process.env.AWS_REGION ??\n      'us-east-1';\n    // Default credential provider chain — identical to host's existing\n    // Bedrock client. In ECS this resolves to the task role.\n    this.client = new BedrockRuntimeClient({ region });\n  }\n\n  async embed(text: string): Promise<number[]> {\n    const input = text.trim();\n    if (!input) {\n      throw new Error('Cannot embed empty text');\n    }\n    const body = {\n      inputText: input,\n      dimensions: this.dimensions,\n      normalize: true,\n    };\n    const command = new InvokeModelCommand({\n      modelId: this.model,\n      contentType: 'application/json',\n      accept: 'application/json',\n      body: new TextEncoder().encode(JSON.stringify(body)),\n    });\n    const response = await this.client.send(command);\n    const decoded = JSON.parse(new TextDecoder().decode(response.body)) as {\n      embedding: number[];\n    };\n    if (!Array.isArray(decoded.embedding)) {\n      throw new Error('Bedrock embedding response missing `embedding` field');\n    }\n    return decoded.embedding;\n  }\n\n  async embedBatch(texts: string[]): Promise<number[][]> {\n    // Titan embed v2 has no native batch API — sequential calls are the\n    // documented pattern. Parallelism here can trip per-account TPS ceilings,\n    // so we keep it serial. For Phase 4 we can introduce a bounded queue.\n    const out: number[][] = [];\n    for (const text of texts) {\n      out.push(await this.embed(text));\n    }\n    return out;\n  }\n}\n\nclass OpenAIEmbedder implements EmbeddingProvider {\n  readonly kind = 'openai' as const;\n  readonly model: string;\n  readonly dimensions: number;\n  private apiKey: string;\n  private baseUrl: string;\n\n  constructor(params: { model: string; dimensions: number }) {\n    this.model = params.model;\n    this.dimensions = params.dimensions;\n    const apiKey = process.env.OPENAI_API_KEY;\n    if (!apiKey) {\n      throw new Error(\n        'OPENAI_API_KEY is not set — required when MEMORY_EMBEDDINGS_PROVIDER=openai'\n      );\n    }\n    this.apiKey = apiKey;\n    this.baseUrl = process.env.OPENAI_BASEURL ?? 'https://api.openai.com/v1';\n  }\n\n  private async call(texts: string[]): Promise<number[][]> {\n    const res = await fetch(`${this.baseUrl}/embeddings`, {\n      method: 'POST',\n      headers: {\n        'Content-Type': 'application/json',\n        Authorization: `Bearer ${this.apiKey}`,\n      },\n      body: JSON.stringify({ model: this.model, input: texts }),\n    });\n    if (!res.ok) {\n      const errText = await res.text();\n      throw new Error(`OpenAI embeddings ${res.status}: ${errText}`);\n    }\n    const json = (await res.json()) as { data: Array<{ embedding: number[] }> };\n    return json.data.map((d) => d.embedding);\n  }\n\n  async embed(text: string): Promise<number[]> {\n    const [vec] = await this.call([text]);\n    return vec;\n  }\n\n  async embedBatch(texts: string[]): Promise<number[][]> {\n    if (texts.length === 0) return [];\n    return this.call(texts);\n  }\n}\n\nlet sharedEmbedder: EmbeddingProvider | null = null;\n\n/**\n * Lazy singleton accessor. Same idiom as host's\n * `getSharedSummaryBedrockClient()`.\n */\nexport function getMemoryEmbedder(): EmbeddingProvider {\n  if (sharedEmbedder) return sharedEmbedder;\n  const cfg = resolveConfig();\n  switch (cfg.provider) {\n    case 'bedrock':\n      sharedEmbedder = new BedrockEmbedder({\n        model: cfg.model,\n        dimensions: cfg.dimensions,\n      });\n      break;\n    case 'openai':\n      sharedEmbedder = new OpenAIEmbedder({\n        model: cfg.model,\n        dimensions: cfg.dimensions,\n      });\n      break;\n  }\n  return sharedEmbedder;\n}\n\n/** Test hook — drops the cached embedder so the next call re-reads env. */\nexport function resetMemoryEmbedder(): void {\n  sharedEmbedder = null;\n}\n"],"names":["DEFAULT_MEMORY_PROVIDER","DEFAULT_MEMORY_MODEL","DEFAULT_MEMORY_DIMENSIONS","BedrockRuntimeClient","InvokeModelCommand"],"mappings":"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"}

package/dist/cjs/memory/factory.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+var pg = require('pg');
+var constants = require('./constants.cjs');
+var pgvectorStore = require('./pgvectorStore.cjs');
+var migrate = require('./migrate.cjs');
+var recallTracking = require('./recallTracking.cjs');
+
+/**
+ * Factory for building a memory backend from environment variables.
+ *
+ * Called once at startup by host's singleton (`api/server/services/memoryStore.js`).
+ * Returns `null` — never throws — when required env vars are missing, so
+ * agents with `memory_enabled=true` still run, just without memory. Host
+ * logs a single warning on boot instead of crashing.
+ */
+function readPgConfig() {
+    // Dev shortcut: single URL overrides discrete fields if present.
+    const url = process.env.MEMORY_DATABASE_URL;
+    if (url) {
+        try {
+            const u = new URL(url);
+            return {
+                host: u.hostname,
+                port: Number(u.port || 5432),
+                user: decodeURIComponent(u.username),
+                password: decodeURIComponent(u.password),
+                database: u.pathname.replace(/^\//, ''),
+                ssl: (process.env.MEMORY_POSTGRES_SSL ?? 'disable') === 'require',
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    const host = process.env.MEMORY_POSTGRES_HOST;
+    const user = process.env.MEMORY_POSTGRES_USER;
+    const password = process.env.MEMORY_POSTGRES_PASSWORD;
+    const database = process.env.MEMORY_POSTGRES_DB;
+    if (!host || !user || !password || !database) {
+        return null;
+    }
+    return {
+        host,
+        port: Number(process.env.MEMORY_POSTGRES_PORT ?? 5432),
+        user,
+        password,
+        database,
+        ssl: (process.env.MEMORY_POSTGRES_SSL ?? 'disable') === 'require',
+    };
+}
+/**
+ * Try to build a configured memory backend. Returns null when the required
+ * env vars are absent — caller should log a single "memory disabled" warning
+ * and continue. Never throws on missing config.
+ */
+async function buildMemoryBackendFromEnv() {
+    const cfg = readPgConfig();
+    if (!cfg)
+        return null;
+    const pool = new pg.Pool({
+        host: cfg.host,
+        port: cfg.port,
+        user: cfg.user,
+        password: cfg.password,
+        database: cfg.database,
+        ssl: cfg.ssl ? { rejectUnauthorized: false } : undefined,
+        max: 10,
+    });
+    const table = process.env.MEMORY_TABLE_NAME ?? constants.DEFAULT_MEMORY_TABLE;
+    try {
+        await migrate.runMemoryMigration({ pool, table });
+    }
+    catch (err) {
+        // Migration failures ARE fatal — they mean dimension mismatch or
+        // permissions wrong, and silently running past that would produce
+        // corrupt or missing memory reads.
+        await pool.end().catch(() => undefined);
+        throw err;
+    }
+    const backend = new pgvectorStore.PgvectorMemoryStore({ pool, table });
+    // Phase 2 — recall tracker migration is best-effort at boot. If it fails,
+    // tool wiring continues with a null tracker rather than crashing host.
+    const recallTracker = new recallTracking.PgvectorRecallTracker(pool);
+    try {
+        await recallTracker.migrate();
+    }
+    catch {
+        // [phase2-recall-tracking] debug: migration skipped — non-fatal
+    }
+    return { backend, pool, recallTracker };
+}
+
+exports.buildMemoryBackendFromEnv = buildMemoryBackendFromEnv;
+//# sourceMappingURL=factory.cjs.map

package/dist/cjs/memory/factory.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.cjs","sources":["../../../src/memory/factory.ts"],"sourcesContent":["/**\n * Factory for building a memory backend from environment variables.\n *\n * Called once at startup by host's singleton (`api/server/services/memoryStore.js`).\n * Returns `null` — never throws — when required env vars are missing, so\n * agents with `memory_enabled=true` still run, just without memory. Host\n * logs a single warning on boot instead of crashing.\n */\nimport { Pool } from 'pg';\nimport { DEFAULT_MEMORY_TABLE } from './constants';\nimport { PgvectorMemoryStore } from './pgvectorStore';\nimport { runMemoryMigration } from './migrate';\nimport { PgvectorRecallTracker, type RecallTracker } from './recallTracking';\nimport type { MemoryBackend } from './types';\n\nexport interface BuildMemoryBackendResult {\n  backend: MemoryBackend;\n  pool: Pool;\n  /** Phase 2 — shared recall tracker bound to the same pool/migration. */\n  recallTracker: RecallTracker;\n}\n\ninterface PgConfig {\n  host: string;\n  port: number;\n  user: string;\n  password: string;\n  database: string;\n  ssl: boolean;\n}\n\nfunction readPgConfig(): PgConfig | null {\n  // Dev shortcut: single URL overrides discrete fields if present.\n  const url = process.env.MEMORY_DATABASE_URL;\n  if (url) {\n    try {\n      const u = new URL(url);\n      return {\n        host: u.hostname,\n        port: Number(u.port || 5432),\n        user: decodeURIComponent(u.username),\n        password: decodeURIComponent(u.password),\n        database: u.pathname.replace(/^\\//, ''),\n        ssl: (process.env.MEMORY_POSTGRES_SSL ?? 'disable') === 'require',\n      };\n    } catch {\n      return null;\n    }\n  }\n\n  const host = process.env.MEMORY_POSTGRES_HOST;\n  const user = process.env.MEMORY_POSTGRES_USER;\n  const password = process.env.MEMORY_POSTGRES_PASSWORD;\n  const database = process.env.MEMORY_POSTGRES_DB;\n  if (!host || !user || !password || !database) {\n    return null;\n  }\n  return {\n    host,\n    port: Number(process.env.MEMORY_POSTGRES_PORT ?? 5432),\n    user,\n    password,\n    database,\n    ssl: (process.env.MEMORY_POSTGRES_SSL ?? 'disable') === 'require',\n  };\n}\n\n/**\n * Try to build a configured memory backend. Returns null when the required\n * env vars are absent — caller should log a single \"memory disabled\" warning\n * and continue. Never throws on missing config.\n */\nexport async function buildMemoryBackendFromEnv(): Promise<BuildMemoryBackendResult | null> {\n  const cfg = readPgConfig();\n  if (!cfg) return null;\n\n  const pool = new Pool({\n    host: cfg.host,\n    port: cfg.port,\n    user: cfg.user,\n    password: cfg.password,\n    database: cfg.database,\n    ssl: cfg.ssl ? { rejectUnauthorized: false } : undefined,\n    max: 10,\n  });\n\n  const table = process.env.MEMORY_TABLE_NAME ?? DEFAULT_MEMORY_TABLE;\n\n  try {\n    await runMemoryMigration({ pool, table });\n  } catch (err) {\n    // Migration failures ARE fatal — they mean dimension mismatch or\n    // permissions wrong, and silently running past that would produce\n    // corrupt or missing memory reads.\n    await pool.end().catch(() => undefined);\n    throw err;\n  }\n\n  const backend = new PgvectorMemoryStore({ pool, table });\n\n  // Phase 2 — recall tracker migration is best-effort at boot. If it fails,\n  // tool wiring continues with a null tracker rather than crashing host.\n  const recallTracker = new PgvectorRecallTracker(pool);\n  try {\n    await recallTracker.migrate();\n  } catch {\n    // [phase2-recall-tracking] debug: migration skipped — non-fatal\n  }\n\n  return { backend, pool, recallTracker };\n}\n"],"names":["Pool","DEFAULT_MEMORY_TABLE","runMemoryMigration","PgvectorMemoryStore","PgvectorRecallTracker"],"mappings":";;;;;;;;AAAA;;;;;;;AAOG;AAwBH,SAAS,YAAY,GAAA;;AAEnB,IAAA,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB;IAC3C,IAAI,GAAG,EAAE;AACP,QAAA,IAAI;AACF,YAAA,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC;YACtB,OAAO;gBACL,IAAI,EAAE,CAAC,CAAC,QAAQ;gBAChB,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC;AAC5B,gBAAA,IAAI,EAAE,kBAAkB,CAAC,CAAC,CAAC,QAAQ,CAAC;AACpC,gBAAA,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC,QAAQ,CAAC;gBACxC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;gBACvC,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,SAAS,MAAM,SAAS;aAClE;QACH;AAAE,QAAA,MAAM;AACN,YAAA,OAAO,IAAI;QACb;IACF;AAEA,IAAA,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB;AAC7C,IAAA,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB;AAC7C,IAAA,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB;AACrD,IAAA,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB;AAC/C,IAAA,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,EAAE;AAC5C,QAAA,OAAO,IAAI;IACb;IACA,OAAO;QACL,IAAI;QACJ,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,IAAI,CAAC;QACtD,IAAI;QACJ,QAAQ;QACR,QAAQ;QACR,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,SAAS,MAAM,SAAS;KAClE;AACH;AAEA;;;;AAIG;AACI,eAAe,yBAAyB,GAAA;AAC7C,IAAA,MAAM,GAAG,GAAG,YAAY,EAAE;AAC1B,IAAA,IAAI,CAAC,GAAG;AAAE,QAAA,OAAO,IAAI;AAErB,IAAA,MAAM,IAAI,GAAG,IAAIA,OAAI,CAAC;QACpB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,QAAQ,EAAE,GAAG,CAAC,QAAQ;AACtB,QAAA,GAAG,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,kBAAkB,EAAE,KAAK,EAAE,GAAG,SAAS;AACxD,QAAA,GAAG,EAAE,EAAE;AACR,KAAA,CAAC;IAEF,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAIC,8BAAoB;AAEnE,IAAA,IAAI;QACF,MAAMC,0BAAkB,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC3C;IAAE,OAAO,GAAG,EAAE;;;;AAIZ,QAAA,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,SAAS,CAAC;AACvC,QAAA,MAAM,GAAG;IACX;IAEA,MAAM,OAAO,GAAG,IAAIC,iCAAmB,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;;;AAIxD,IAAA,MAAM,aAAa,GAAG,IAAIC,oCAAqB,CAAC,IAAI,CAAC;AACrD,IAAA,IAAI;AACF,QAAA,MAAM,aAAa,CAAC,OAAO,EAAE;IAC/B;AAAE,IAAA,MAAM;;IAER;AAEA,IAAA,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE;AACzC;;;;"}

package/dist/cjs/memory/migrate.cjs

@@ -0,0 +1,81 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var url = require('url');
+var constants = require('./constants.cjs');
+var embeddings = require('./embeddings.cjs');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+function resolveSchemaSqlPath() {
+    // Works under both ESM (import.meta.url) and compiled CJS (fall back to __dirname).
+    const meta = ({ url: (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('memory/migrate.cjs', document.baseURI).href)) });
+    const metaUrl = typeof meta.url === 'string' ? meta.url : undefined;
+    if (metaUrl) {
+        return path.join(path.dirname(url.fileURLToPath(metaUrl)), 'schema.sql');
+    }
+    const globalDirname = globalThis
+        .__dirname;
+    return path.join(globalDirname ?? process.cwd(), 'schema.sql');
+}
+async function runMemoryMigration(opts) {
+    const table = opts.table ?? constants.DEFAULT_MEMORY_TABLE;
+    const schemaPath = resolveSchemaSqlPath();
+    const schemaSql = fs.readFileSync(schemaPath, 'utf8').replace(/agent_memories/g, table);
+    // Drop the legacy `(agent_id, path)` unique constraint BEFORE running
+    // the schema SQL. The schema creates the new
+    // `(agent_id, user_id, path)` NULLS-NOT-DISTINCT constraint, which
+    // must not collide with the old one. Dropping by the legacy name is a
+    // no-op on fresh installs where the constraint never existed, and on
+    // upgrades it cleanly frees the unique-index slot so the new
+    // constraint can be installed.
+    await opts.pool
+        .query(`ALTER TABLE ${table} DROP CONSTRAINT IF EXISTS ${table}_agent_path_uq`)
+        .catch(() => undefined);
+    await opts.pool.query(schemaSql);
+    // Adopt legacy rows if the table pre-existed with an older shape.
+    // Idempotent — every statement is no-op-safe on a fresh schema.
+    await opts.pool
+        .query(`ALTER TABLE ${table} ALTER COLUMN user_id DROP NOT NULL`)
+        .catch(() => undefined);
+    await opts.pool.query(`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`);
+    await opts.pool.query(`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS last_user_id TEXT`);
+    // Belt-and-suspenders: if the schema CREATE was skipped because the
+    // table already existed AND the new constraint was absent, add it
+    // explicitly. Swallow duplicate-object errors on happy-path re-runs.
+    await opts.pool
+        .query(`ALTER TABLE ${table}
+         ADD CONSTRAINT ${table}_agent_user_path_uq
+         UNIQUE NULLS NOT DISTINCT (agent_id, user_id, path)`)
+        .catch(() => undefined);
+    if (opts.skipEmbedderProbe)
+        return;
+    // Vector dimension sanity check — refuses to serve if the column width
+    // disagrees with the live embedder and the table has data. See plan §3.
+    const embedder = embeddings.getMemoryEmbedder();
+    const liveDim = embedder.dimensions || constants.DEFAULT_MEMORY_DIMENSIONS;
+    // pgvector stores the declared width directly in atttypmod (unlike varchar
+    // which uses atttypmod = N + VARHDRSZ). Reading it raw gives the true dim.
+    const dimResult = await opts.pool.query(`
+    SELECT atttypmod AS dim
+    FROM pg_attribute
+    WHERE attrelid = to_regclass($1)
+      AND attname = 'embedding'
+    `, [table]);
+    const columnDim = dimResult.rows[0]?.dim;
+    if (columnDim && Number(columnDim) !== liveDim) {
+        const countRes = await opts.pool.query(`SELECT COUNT(*)::int AS n FROM ${table}`);
+        const rowCount = Number(countRes.rows[0]?.n ?? 0);
+        if (rowCount === 0) {
+            await opts.pool.query(`ALTER TABLE ${table} ALTER COLUMN embedding TYPE VECTOR(${liveDim})`);
+        }
+        else {
+            throw new Error(`Memory vector dimension mismatch: column is VECTOR(${columnDim}) but ` +
+                `embedder "${embedder.model}" produces ${liveDim}-d vectors, and ${rowCount} ` +
+                `rows exist. Refusing to serve memory. Admin must run a reindex job.`);
+        }
+    }
+}
+
+exports.runMemoryMigration = runMemoryMigration;
+//# sourceMappingURL=migrate.cjs.map

package/dist/cjs/memory/migrate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.cjs","sources":["../../../src/memory/migrate.ts"],"sourcesContent":["/**\n * Idempotent schema install + vector-dimension safety check.\n *\n * Called once at agents-library startup by host's `memoryStore.js` singleton\n * factory. Safe to call multiple times — every statement is `IF NOT EXISTS`.\n */\nimport type { Pool } from 'pg';\nimport { readFileSync } from 'fs';\nimport { join, dirname } from 'path';\nimport { fileURLToPath } from 'url';\nimport { DEFAULT_MEMORY_DIMENSIONS, DEFAULT_MEMORY_TABLE } from './constants';\nimport { getMemoryEmbedder } from './embeddings';\n\nexport interface MigrationOptions {\n  pool: Pool;\n  table?: string;\n  /** If true, skip the live embedder probe (tests). */\n  skipEmbedderProbe?: boolean;\n}\n\nfunction resolveSchemaSqlPath(): string {\n  // Works under both ESM (import.meta.url) and compiled CJS (fall back to __dirname).\n  const meta = import.meta as unknown as { url?: string };\n  const metaUrl = typeof meta.url === 'string' ? meta.url : undefined;\n  if (metaUrl) {\n    return join(dirname(fileURLToPath(metaUrl)), 'schema.sql');\n  }\n  const globalDirname = (globalThis as unknown as { __dirname?: string })\n    .__dirname;\n  return join(globalDirname ?? process.cwd(), 'schema.sql');\n}\n\nexport async function runMemoryMigration(\n  opts: MigrationOptions\n): Promise<void> {\n  const table = opts.table ?? DEFAULT_MEMORY_TABLE;\n  const schemaPath = resolveSchemaSqlPath();\n  const schemaSql = readFileSync(schemaPath, 'utf8').replace(\n    /agent_memories/g,\n    table\n  );\n\n  // Drop the legacy `(agent_id, path)` unique constraint BEFORE running\n  // the schema SQL. The schema creates the new\n  // `(agent_id, user_id, path)` NULLS-NOT-DISTINCT constraint, which\n  // must not collide with the old one. Dropping by the legacy name is a\n  // no-op on fresh installs where the constraint never existed, and on\n  // upgrades it cleanly frees the unique-index slot so the new\n  // constraint can be installed.\n  await opts.pool\n    .query(\n      `ALTER TABLE ${table} DROP CONSTRAINT IF EXISTS ${table}_agent_path_uq`\n    )\n    .catch(() => undefined);\n\n  await opts.pool.query(schemaSql);\n\n  // Adopt legacy rows if the table pre-existed with an older shape.\n  // Idempotent — every statement is no-op-safe on a fresh schema.\n  await opts.pool\n    .query(`ALTER TABLE ${table} ALTER COLUMN user_id DROP NOT NULL`)\n    .catch(() => undefined);\n  await opts.pool.query(\n    `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()`\n  );\n  await opts.pool.query(\n    `ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS last_user_id TEXT`\n  );\n  // Belt-and-suspenders: if the schema CREATE was skipped because the\n  // table already existed AND the new constraint was absent, add it\n  // explicitly. Swallow duplicate-object errors on happy-path re-runs.\n  await opts.pool\n    .query(\n      `ALTER TABLE ${table}\n         ADD CONSTRAINT ${table}_agent_user_path_uq\n         UNIQUE NULLS NOT DISTINCT (agent_id, user_id, path)`\n    )\n    .catch(() => undefined);\n\n  if (opts.skipEmbedderProbe) return;\n\n  // Vector dimension sanity check — refuses to serve if the column width\n  // disagrees with the live embedder and the table has data. See plan §3.\n  const embedder = getMemoryEmbedder();\n  const liveDim = embedder.dimensions || DEFAULT_MEMORY_DIMENSIONS;\n\n  // pgvector stores the declared width directly in atttypmod (unlike varchar\n  // which uses atttypmod = N + VARHDRSZ). Reading it raw gives the true dim.\n  const dimResult = await opts.pool.query(\n    `\n    SELECT atttypmod AS dim\n    FROM pg_attribute\n    WHERE attrelid = to_regclass($1)\n      AND attname = 'embedding'\n    `,\n    [table]\n  );\n  const columnDim = dimResult.rows[0]?.dim;\n  if (columnDim && Number(columnDim) !== liveDim) {\n    const countRes = await opts.pool.query(\n      `SELECT COUNT(*)::int AS n FROM ${table}`\n    );\n    const rowCount = Number(countRes.rows[0]?.n ?? 0);\n    if (rowCount === 0) {\n      await opts.pool.query(\n        `ALTER TABLE ${table} ALTER COLUMN embedding TYPE VECTOR(${liveDim})`\n      );\n    } else {\n      throw new Error(\n        `Memory vector dimension mismatch: column is VECTOR(${columnDim}) but ` +\n          `embedder \"${embedder.model}\" produces ${liveDim}-d vectors, and ${rowCount} ` +\n          `rows exist. Refusing to serve memory. Admin must run a reindex job.`\n      );\n    }\n  }\n}\n"],"names":["join","dirname","fileURLToPath","DEFAULT_MEMORY_TABLE","readFileSync","getMemoryEmbedder","DEFAULT_MEMORY_DIMENSIONS"],"mappings":"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"}

package/dist/cjs/memory/mmr.cjs

@@ -0,0 +1,138 @@
+'use strict';
+
+/**
+ * Maximal Marginal Relevance (MMR) re-ranking — Phase 2.
+ *
+ * Ported from upstream `extensions/memory-core/src/memory/mmr.ts` with
+ * minor adaptation for our `MemoryEntry` shape (content vs snippet, id vs
+ * path+startLine). Behavior is identical: normalize scores, iteratively
+ * pick the item that maximizes `λ * relevance - (1-λ) * max_similarity`
+ * using Jaccard on tokenized content.
+ *
+ * @see Carbonell & Goldstein, "The Use of MMR, Diversity-Based Reranking" (1998)
+ */
+const DEFAULT_MMR_CONFIG = {
+    enabled: false,
+    lambda: 0.7,
+};
+/**
+ * CJK Unified Ideographs + Extension A, Hiragana/Katakana, Hangul.
+ * These lack whitespace boundaries so we must tokenize them differently.
+ */
+const CJK_RE = /[\u3040-\u309f\u30a0-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uac00-\ud7af\u1100-\u11ff]/;
+/**
+ * Tokenize content into a set for Jaccard similarity.
+ *
+ * ASCII: alphanumeric + underscore runs, lowercased.
+ * CJK: each char becomes a unigram; consecutive pairs become a bigram.
+ * Non-adjacent CJK chars (e.g. `我a好`) do NOT form a bigram.
+ */
+function tokenize(text) {
+    const lower = (text ?? '').toLowerCase();
+    const ascii = lower.match(/[a-z0-9_]+/g) ?? [];
+    const chars = Array.from(lower);
+    const cjkData = [];
+    for (let i = 0; i < chars.length; i++) {
+        if (CJK_RE.test(chars[i]))
+            cjkData.push({ char: chars[i], index: i });
+    }
+    const bigrams = [];
+    for (let i = 0; i < cjkData.length - 1; i++) {
+        if (cjkData[i + 1].index === cjkData[i].index + 1) {
+            bigrams.push(cjkData[i].char + cjkData[i + 1].char);
+        }
+    }
+    return new Set([...ascii, ...bigrams, ...cjkData.map((d) => d.char)]);
+}
+function jaccardSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    const [smaller, larger] = a.size <= b.size ? [a, b] : [b, a];
+    let intersection = 0;
+    for (const t of smaller)
+        if (larger.has(t))
+            intersection++;
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+function textSimilarity(a, b) {
+    return jaccardSimilarity(tokenize(a), tokenize(b));
+}
+function computeMMRScore(relevance, maxSimilarity, lambda) {
+    return lambda * relevance - (1 - lambda) * maxSimilarity;
+}
+/**
+ * Re-rank items using MMR. Returns a new array in MMR order.
+ */
+function mmrRerank(items, config = {}) {
+    const enabled = config.enabled ?? DEFAULT_MMR_CONFIG.enabled;
+    const rawLambda = config.lambda ?? DEFAULT_MMR_CONFIG.lambda;
+    if (!enabled || items.length <= 1)
+        return [...items];
+    const lambda = Math.max(0, Math.min(1, rawLambda));
+    if (lambda === 1)
+        return [...items].sort((a, b) => b.score - a.score);
+    const tokenCache = new Map();
+    for (const item of items)
+        tokenCache.set(item.id, tokenize(item.content));
+    const scores = items.map((i) => i.score);
+    const maxScore = Math.max(...scores);
+    const minScore = Math.min(...scores);
+    const range = maxScore - minScore;
+    const normalize = (s) => range === 0 ? 1 : (s - minScore) / range;
+    const selected = [];
+    const remaining = new Set(items);
+    while (remaining.size > 0) {
+        let best = null;
+        let bestMMR = -Infinity;
+        for (const cand of remaining) {
+            const rel = normalize(cand.score);
+            const candTokens = tokenCache.get(cand.id);
+            let maxSim = 0;
+            for (const sel of selected) {
+                const sim = jaccardSimilarity(candTokens, tokenCache.get(sel.id));
+                if (sim > maxSim)
+                    maxSim = sim;
+            }
+            const mmr = computeMMRScore(rel, maxSim, lambda);
+            if (mmr > bestMMR ||
+                (mmr === bestMMR && cand.score > (best?.score ?? -Infinity))) {
+                bestMMR = mmr;
+                best = cand;
+            }
+        }
+        if (!best)
+            break;
+        selected.push(best);
+        remaining.delete(best);
+    }
+    return selected;
+}
+/**
+ * Adapter: apply MMR to an array of MemoryEntry-shaped hits.
+ *
+ * Uses (path|id|index) as the stable ID so two hits from the same file at
+ * different content still get distinct MMR identities.
+ */
+function applyMMRToMemoryHits(results, config = {}) {
+    if (results.length <= 1)
+        return results;
+    const byId = new Map();
+    const items = results.map((r, i) => {
+        const id = `${r.path}#${r.id}#${i}`;
+        byId.set(id, r);
+        return { id, score: r.score, content: r.content };
+    });
+    return mmrRerank(items, config).map((m) => byId.get(m.id));
+}
+
+exports.DEFAULT_MMR_CONFIG = DEFAULT_MMR_CONFIG;
+exports.applyMMRToMemoryHits = applyMMRToMemoryHits;
+exports.computeMMRScore = computeMMRScore;
+exports.jaccardSimilarity = jaccardSimilarity;
+exports.mmrRerank = mmrRerank;
+exports.textSimilarity = textSimilarity;
+exports.tokenize = tokenize;
+//# sourceMappingURL=mmr.cjs.map

package/dist/cjs/memory/mmr.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mmr.cjs","sources":["../../../src/memory/mmr.ts"],"sourcesContent":["/**\n * Maximal Marginal Relevance (MMR) re-ranking — Phase 2.\n *\n * Ported from upstream `extensions/memory-core/src/memory/mmr.ts` with\n * minor adaptation for our `MemoryEntry` shape (content vs snippet, id vs\n * path+startLine). Behavior is identical: normalize scores, iteratively\n * pick the item that maximizes `λ * relevance - (1-λ) * max_similarity`\n * using Jaccard on tokenized content.\n *\n * @see Carbonell & Goldstein, \"The Use of MMR, Diversity-Based Reranking\" (1998)\n */\n\nexport interface MMRConfig {\n  /** Opt-in. Upstream default is false. */\n  enabled: boolean;\n  /** 0 = max diversity, 1 = max relevance. Upstream default 0.7. */\n  lambda: number;\n}\n\nexport const DEFAULT_MMR_CONFIG: MMRConfig = {\n  enabled: false,\n  lambda: 0.7,\n};\n\n/**\n * CJK Unified Ideographs + Extension A, Hiragana/Katakana, Hangul.\n * These lack whitespace boundaries so we must tokenize them differently.\n */\nconst CJK_RE =\n  /[\\u3040-\\u309f\\u30a0-\\u30ff\\u3400-\\u4dbf\\u4e00-\\u9fff\\uac00-\\ud7af\\u1100-\\u11ff]/;\n\n/**\n * Tokenize content into a set for Jaccard similarity.\n *\n * ASCII: alphanumeric + underscore runs, lowercased.\n * CJK: each char becomes a unigram; consecutive pairs become a bigram.\n * Non-adjacent CJK chars (e.g. `我a好`) do NOT form a bigram.\n */\nexport function tokenize(text: string): Set<string> {\n  const lower = (text ?? '').toLowerCase();\n  const ascii = lower.match(/[a-z0-9_]+/g) ?? [];\n\n  const chars = Array.from(lower);\n  const cjkData: Array<{ char: string; index: number }> = [];\n  for (let i = 0; i < chars.length; i++) {\n    if (CJK_RE.test(chars[i])) cjkData.push({ char: chars[i], index: i });\n  }\n\n  const bigrams: string[] = [];\n  for (let i = 0; i < cjkData.length - 1; i++) {\n    if (cjkData[i + 1].index === cjkData[i].index + 1) {\n      bigrams.push(cjkData[i].char + cjkData[i + 1].char);\n    }\n  }\n\n  return new Set([...ascii, ...bigrams, ...cjkData.map((d) => d.char)]);\n}\n\nexport function jaccardSimilarity(a: Set<string>, b: Set<string>): number {\n  if (a.size === 0 && b.size === 0) return 1;\n  if (a.size === 0 || b.size === 0) return 0;\n\n  const [smaller, larger] = a.size <= b.size ? [a, b] : [b, a];\n  let intersection = 0;\n  for (const t of smaller) if (larger.has(t)) intersection++;\n  const union = a.size + b.size - intersection;\n  return union === 0 ? 0 : intersection / union;\n}\n\nexport function textSimilarity(a: string, b: string): number {\n  return jaccardSimilarity(tokenize(a), tokenize(b));\n}\n\nexport function computeMMRScore(\n  relevance: number,\n  maxSimilarity: number,\n  lambda: number\n): number {\n  return lambda * relevance - (1 - lambda) * maxSimilarity;\n}\n\nexport interface MMRItem {\n  id: string;\n  score: number;\n  content: string;\n}\n\n/**\n * Re-rank items using MMR. Returns a new array in MMR order.\n */\nexport function mmrRerank<T extends MMRItem>(\n  items: T[],\n  config: Partial<MMRConfig> = {}\n): T[] {\n  const enabled = config.enabled ?? DEFAULT_MMR_CONFIG.enabled;\n  const rawLambda = config.lambda ?? DEFAULT_MMR_CONFIG.lambda;\n\n  if (!enabled || items.length <= 1) return [...items];\n\n  const lambda = Math.max(0, Math.min(1, rawLambda));\n  if (lambda === 1) return [...items].sort((a, b) => b.score - a.score);\n\n  const tokenCache = new Map<string, Set<string>>();\n  for (const item of items) tokenCache.set(item.id, tokenize(item.content));\n\n  const scores = items.map((i) => i.score);\n  const maxScore = Math.max(...scores);\n  const minScore = Math.min(...scores);\n  const range = maxScore - minScore;\n  const normalize = (s: number): number =>\n    range === 0 ? 1 : (s - minScore) / range;\n\n  const selected: T[] = [];\n  const remaining = new Set(items);\n\n  while (remaining.size > 0) {\n    let best: T | null = null;\n    let bestMMR = -Infinity;\n    for (const cand of remaining) {\n      const rel = normalize(cand.score);\n      const candTokens = tokenCache.get(cand.id)!;\n      let maxSim = 0;\n      for (const sel of selected) {\n        const sim = jaccardSimilarity(candTokens, tokenCache.get(sel.id)!);\n        if (sim > maxSim) maxSim = sim;\n      }\n      const mmr = computeMMRScore(rel, maxSim, lambda);\n      if (\n        mmr > bestMMR ||\n        (mmr === bestMMR && cand.score > (best?.score ?? -Infinity))\n      ) {\n        bestMMR = mmr;\n        best = cand;\n      }\n    }\n    if (!best) break;\n    selected.push(best);\n    remaining.delete(best);\n  }\n\n  return selected;\n}\n\n/**\n * Adapter: apply MMR to an array of MemoryEntry-shaped hits.\n *\n * Uses (path|id|index) as the stable ID so two hits from the same file at\n * different content still get distinct MMR identities.\n */\nexport function applyMMRToMemoryHits<\n  T extends { id: string; path: string; content: string; score: number },\n>(results: T[], config: Partial<MMRConfig> = {}): T[] {\n  if (results.length <= 1) return results;\n  const byId = new Map<string, T>();\n  const items: MMRItem[] = results.map((r, i) => {\n    const id = `${r.path}#${r.id}#${i}`;\n    byId.set(id, r);\n    return { id, score: r.score, content: r.content };\n  });\n  return mmrRerank(items, config).map((m) => byId.get(m.id)!);\n}\n"],"names":[],"mappings":"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"}