@shadowforge0/aquifer-memory 1.0.3 → 1.2.1

package/consumers/shared/llm-autodetect.js

@@ -0,0 +1,137 @@
+'use strict';
+
+// Aquifer v1.2.0: LLM provider autodetect from env for install-and-go.
+//
+// Precedence:
+//   1. config.llm.fn (explicit function — host supplies)
+//   2. AQUIFER_LLM_PROVIDER env + provider-specific api key + optional model
+//
+// We do NOT silently pick a provider from multiple keys (ambiguous). Hosts
+// must opt in by setting AQUIFER_LLM_PROVIDER explicitly when they want env
+// autowiring.
+//
+// Two response shapes in flight:
+//   - Anthropic-shape: { content: [{ type:'text', text:'...' }] }
+//     Used by: minimax, opencode
+//   - OpenAI-shape:    { choices:[{ message:{ content:'...' } }] }
+//     Used by: openai, openrouter
+
+const { createLlmFn } = require('./llm');
+
+const ANTHROPIC_PROVIDERS = {
+  minimax: {
+    envKey: 'MINIMAX_API_KEY',
+    baseUrl: 'https://api.minimax.io/anthropic/v1/messages',
+    defaultModel: 'MiniMax-M2.7',
+    extraHeaders: { 'anthropic-version': '2023-06-01' },
+  },
+  opencode: {
+    envKey: 'OPENCODE_API_KEY',
+    baseUrl: 'https://opencode.ai/zen/go/v1/messages',
+    defaultModel: 'minimax-m2.5',
+    extraHeaders: { 'anthropic-version': '2023-06-01' },
+  },
+};
+
+const OPENAI_PROVIDERS = {
+  openai: {
+    envKey: 'OPENAI_API_KEY',
+    baseUrl: 'https://api.openai.com/v1',
+    defaultModel: 'gpt-4o-mini',
+  },
+  openrouter: {
+    envKey: 'OPENROUTER_API_KEY',
+    baseUrl: 'https://openrouter.ai/api/v1',
+    defaultModel: 'openai/gpt-4o-mini',
+  },
+};
+
+function createAnthropicShapeFn({ baseUrl, apiKey, model, extraHeaders, timeoutMs, maxTokens }) {
+  const timeout = timeoutMs || 120000;
+  const mt = maxTokens || 4096;
+  return async function llmFn(prompt) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+      const res = await fetch(baseUrl, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${apiKey}`,
+          ...(extraHeaders || {}),
+        },
+        body: JSON.stringify({
+          model,
+          messages: [{ role: 'user', content: prompt }],
+          max_tokens: mt,
+        }),
+        signal: controller.signal,
+      });
+      if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        const err = new Error(`LLM ${res.status}: ${body.slice(0, 200).replace(/[\n\r]/g, ' ')}`);
+        err.statusCode = res.status;
+        throw err;
+      }
+      const data = await res.json();
+      let raw = '';
+      if (data.content && Array.isArray(data.content)) {
+        raw = data.content.map((c) => c.text || '').join('');
+      } else if (data.choices && Array.isArray(data.choices)) {
+        raw = data.choices[0]?.message?.content || '';
+      }
+      return raw.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}
+
+function resolveLlmFn(llmConfig, env) {
+  if (llmConfig && typeof llmConfig.fn === 'function') {
+    return llmConfig.fn;
+  }
+  const provider = env.AQUIFER_LLM_PROVIDER;
+  if (!provider) return null;
+
+  const model = env.AQUIFER_LLM_MODEL || null;
+  const timeoutMs = env.AQUIFER_LLM_TIMEOUT ? Number(env.AQUIFER_LLM_TIMEOUT) : undefined;
+
+  if (ANTHROPIC_PROVIDERS[provider]) {
+    const p = ANTHROPIC_PROVIDERS[provider];
+    const apiKey = env[p.envKey];
+    if (!apiKey) {
+      throw new Error(`AQUIFER_LLM_PROVIDER=${provider} requires ${p.envKey}`);
+    }
+    return createAnthropicShapeFn({
+      baseUrl: p.baseUrl,
+      apiKey,
+      model: model || p.defaultModel,
+      extraHeaders: p.extraHeaders,
+      timeoutMs,
+    });
+  }
+
+  if (OPENAI_PROVIDERS[provider]) {
+    const p = OPENAI_PROVIDERS[provider];
+    const apiKey = env[p.envKey];
+    if (!apiKey) {
+      throw new Error(`AQUIFER_LLM_PROVIDER=${provider} requires ${p.envKey}`);
+    }
+    return createLlmFn({
+      baseUrl: p.baseUrl,
+      model: model || p.defaultModel,
+      apiKey,
+      timeoutMs,
+    });
+  }
+
+  throw new Error(
+    `AQUIFER_LLM_PROVIDER=${provider} not supported. Valid: ${[
+      ...Object.keys(ANTHROPIC_PROVIDERS),
+      ...Object.keys(OPENAI_PROVIDERS),
+    ].join(', ')}`
+  );
+}
+
+module.exports = { resolveLlmFn };

package/consumers/shared/normalize.js

@@ -0,0 +1,129 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Shared normalize — turns raw host entries into commit-ready messages plus
+// session-level metadata. Wraps pipeline/normalize so consumers don't each
+// reinvent their own role/content extraction.
+//
+// Supported adapters: 'gateway' | 'cc' (alias of 'claude-code'). The OpenCode
+// consumer reads from SQLite and constructs the output shape directly; it is
+// not expected to route through here.
+//
+// Output shape is the one commit() + enrich() expect:
+//   { messages:[{role,content,timestamp}], userCount, assistantCount,
+//     model, tokensIn, tokensOut, startedAt, lastMessageAt,
+//     skipStats, boundaries, toolsUsed }
+// ---------------------------------------------------------------------------
+
+const { normalizeSession } = require('../../pipeline/normalize');
+
+const ADAPTER_ALIASES = {
+    'cc': 'claude-code',
+    'claude-code': 'claude-code',
+    'gateway': 'gateway',
+};
+
+function resolveAdapter(adapter) {
+    if (!adapter) return null;  // auto-detect
+    const name = ADAPTER_ALIASES[adapter];
+    if (!name) {
+        throw new Error(`Unknown adapter: "${adapter}". Supported: gateway, cc (alias claude-code).`);
+    }
+    return name;
+}
+
+function extractRawMeta(rawEntries) {
+    let model = null;
+    let tokensIn = 0;
+    let tokensOut = 0;
+
+    for (const entry of rawEntries || []) {
+        if (!entry || typeof entry !== 'object') continue;
+        const msg = entry.message || entry;
+        if (msg && typeof msg === 'object') {
+            if (msg.model && !model) model = msg.model;
+            if (msg.usage) {
+                tokensIn += msg.usage.input_tokens || msg.usage.input || 0;
+                tokensOut += msg.usage.output_tokens || msg.usage.output || 0;
+            }
+        }
+    }
+
+    return { model, tokensIn, tokensOut };
+}
+
+/**
+ * Normalize raw host entries to Aquifer-commit shape + session metadata.
+ *
+ * @param {any[]} rawEntries
+ * @param {object} [opts]
+ * @param {'gateway'|'cc'|'claude-code'} [opts.adapter] — host adapter; auto-detected if omitted
+ * @returns {{
+ *   messages: {role:string,content:string,timestamp:string|null}[],
+ *   userCount: number, assistantCount: number,
+ *   model: string|null, tokensIn: number, tokensOut: number,
+ *   startedAt: string|null, lastMessageAt: string|null,
+ *   skipStats: object, boundaries: object[], toolsUsed: string[]
+ * }}
+ */
+function normalizeMessages(rawEntries, opts = {}) {
+    const safeEntries = Array.isArray(rawEntries) ? rawEntries : [];
+
+    if (safeEntries.length === 0) {
+        return {
+            messages: [],
+            userCount: 0,
+            assistantCount: 0,
+            model: null,
+            tokensIn: 0,
+            tokensOut: 0,
+            startedAt: null,
+            lastMessageAt: null,
+            skipStats: { total: 0, nonMessage: 0, noRole: 0, meta: 0, caveat: 0,
+                empty: 0, toolOnly: 0, narration: 0, toolResult: 0, routine: 0, command: 0 },
+            boundaries: [],
+            toolsUsed: [],
+        };
+    }
+
+    const client = resolveAdapter(opts.adapter);
+    const { normalized, skipStats, boundaries, toolsUsed } = normalizeSession(
+        safeEntries,
+        client ? { client } : {},
+    );
+
+    const messages = normalized.map(m => ({
+        role: m.role,
+        content: m.text || '',
+        timestamp: m.timestamp || null,
+    }));
+
+    let userCount = 0, assistantCount = 0;
+    let startedAt = null, lastMessageAt = null;
+    for (const m of messages) {
+        if (m.role === 'user') userCount++;
+        else if (m.role === 'assistant') assistantCount++;
+        if (m.timestamp) {
+            if (!startedAt) startedAt = m.timestamp;
+            lastMessageAt = m.timestamp;
+        }
+    }
+
+    const { model, tokensIn, tokensOut } = extractRawMeta(safeEntries);
+
+    return {
+        messages,
+        userCount,
+        assistantCount,
+        model,
+        tokensIn,
+        tokensOut,
+        startedAt,
+        lastMessageAt,
+        skipStats,
+        boundaries,
+        toolsUsed,
+    };
+}
+
+module.exports = { normalizeMessages, extractRawMeta };

package/consumers/shared/recall-format.js

@@ -0,0 +1,110 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Shared recall formatter — turns aquifer.recall() rows into human-readable
+// text. The default is English and markdown-ish; consumers with a persona
+// (Miranda: zh-TW narrative) can override individual renderers.
+// ---------------------------------------------------------------------------
+
+function truncate(s, n) {
+    if (!s) return '';
+    const str = String(s);
+    return str.length > n ? `${str.slice(0, n)}...` : str;
+}
+
+function formatDateIso(value) {
+    if (!value) return 'unknown';
+    const d = new Date(value);
+    return Number.isNaN(d.getTime()) ? 'unknown' : d.toISOString().slice(0, 10);
+}
+
+// Default English renderers --------------------------------------------------
+
+const defaultRenderers = {
+    header({ results, query }) {
+        if (!query) return null;
+        return `Found ${results.length} result(s) for "${query}":`;
+    },
+    empty({ query }) {
+        return query ? `No results found for "${query}".` : 'No matching sessions found.';
+    },
+    title(result, index) {
+        const ss = result.structuredSummary || {};
+        const title = ss.title || truncate(result.summaryText, 60) || '(untitled)';
+        const date = formatDateIso(result.startedAt);
+        const agent = result.agentId || 'default';
+        return `### ${index + 1}. ${title} (${date}, ${agent})`;
+    },
+    body(result) {
+        const ss = result.structuredSummary || {};
+        const text = ss.overview || result.summaryText || '';
+        return text ? truncate(text, 300) : null;
+    },
+    matched(result) {
+        return result.matchedTurnText ? `Matched turn: ${truncate(result.matchedTurnText, 200)}` : null;
+    },
+    score(result, { showScore }) {
+        if (!showScore) return null;
+        return `Score: ${typeof result.score === 'number' ? result.score.toFixed(3) : '?'}`;
+    },
+    separator() {
+        return '';
+    },
+};
+
+/**
+ * Create a formatter with optional per-renderer overrides.
+ *
+ * @param {object} [overrides] — renderers to override: header/empty/title/body/matched/score/separator
+ * @returns {(results: any[], opts?: object) => string}
+ */
+function createRecallFormatter(overrides = {}) {
+    const r = { ...defaultRenderers, ...overrides };
+
+    return function format(results, opts = {}) {
+        const safeResults = Array.isArray(results) ? results : [];
+        const ctx = { query: opts.query || null, results: safeResults };
+
+        if (safeResults.length === 0) {
+            return r.empty(ctx);
+        }
+
+        const lines = [];
+        const header = r.header(ctx);
+        if (header) { lines.push(header); lines.push(''); }
+
+        for (let i = 0; i < safeResults.length; i++) {
+            const res = safeResults[i];
+            const title = r.title(res, i, ctx);
+            if (title) lines.push(title);
+            const body = r.body(res, i, ctx);
+            if (body) lines.push(body);
+            const matched = r.matched(res, i, ctx);
+            if (matched) lines.push(matched);
+            const score = r.score(res, { showScore: !!opts.showScore, ...ctx });
+            if (score) lines.push(score);
+            const sep = r.separator(i, ctx);
+            if (sep !== null && sep !== undefined) lines.push(sep);
+        }
+
+        // Trim trailing empty separator
+        while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+
+        return lines.join('\n');
+    };
+}
+
+// Pre-built default English formatter
+const defaultFormatter = createRecallFormatter();
+
+function formatRecallResults(results, opts = {}) {
+    return defaultFormatter(results, opts);
+}
+
+module.exports = {
+    createRecallFormatter,
+    formatRecallResults,
+    truncate,
+    formatDateIso,
+    defaultRenderers,
+};