bare-agent 0.16.2 → 0.18.0

package/src/provider-gemini.d.ts

@@ -0,0 +1,70 @@
+export type Message = import("../types").Message;
+export type ToolDef = import("../types").ToolDef;
+export type ToolCall = import("../types").ToolCall;
+export type GenerateResult = import("../types").GenerateResult;
+export type GeminiOptions = {
+    /**
+     * - Google AI Studio (Gemini) API key.
+     */
+    apiKey?: string | undefined;
+    /**
+     * - Model ID.
+     */
+    model?: string | undefined;
+    /**
+     * - API base (override for proxies; posts to `${baseUrl}/models/${model}:generateContent`).
+     */
+    baseUrl?: string | undefined;
+    /**
+     * - Attach the full upstream response to `err.body` on HTTP errors (off by default; `err.message` still carries the API error).
+     */
+    exposeErrorBody?: boolean | undefined;
+};
+/**
+ * @typedef {object} GeminiOptions
+ * @property {string} [apiKey] - Google AI Studio (Gemini) API key.
+ * @property {string} [model='gemini-2.5-flash'] - Model ID.
+ * @property {string} [baseUrl='https://generativelanguage.googleapis.com/v1beta'] - API base (override for proxies; posts to `${baseUrl}/models/${model}:generateContent`).
+ * @property {boolean} [exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default; `err.message` still carries the API error).
+ */
+/**
+ * Google Gemini provider (native `generateContent` API, NOT the OpenAI-compat endpoint — that endpoint
+ * omits the cache token tier, so it can't feed the cost meter; verified by POC). Converts the Loop's
+ * OpenAI-format messages to Gemini `contents`, declares tools as `functionDeclarations`, and normalizes
+ * `usageMetadata` to the neutral Usage shape. Gemini auto-caches (implicit caching on 2.5 models), so the
+ * cache-read tier populates with no opt-in.
+ */
+export class GeminiProvider {
+    /** @param {GeminiOptions} [options] */
+    constructor(options?: GeminiOptions);
+    apiKey: string | undefined;
+    model: string;
+    baseUrl: string;
+    exposeErrorBody: boolean;
+    /**
+     * Generate a response from the Gemini API.
+     * @param {Message[]} messages - Conversation messages (OpenAI format, auto-converted).
+     * @param {ToolDef[]} [tools=[]] - Tool definitions.
+     * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens).
+     * @returns {Promise<GenerateResult>}
+     * @throws {Error} `[GeminiProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
+     */
+    generate(messages: Message[], tools?: ToolDef[], options?: Record<string, any>): Promise<GenerateResult>;
+    /**
+     * Normalize Gemini `usageMetadata` to the neutral {@link Usage} shape. Like OpenAI, `promptTokenCount`
+     * INCLUDES the cached tokens (`cachedContentTokenCount`), so subtract for the uncached remainder
+     * (verified live). Gemini bills "thinking" (`thoughtsTokenCount`) as output, so fold it into output
+     * (total = prompt + candidates + thoughts — confirmed against live usageMetadata). Implicit caching
+     * has no separate write tier → cacheCreationTokens 0.
+     * @param {any} u - raw `data.usageMetadata`
+     * @returns {import('../types').Usage}
+     */
+    _normalizeUsage(u: any): import("../types").Usage;
+    /**
+     * @param {string} path
+     * @param {Record<string, any>} body
+     * @returns {Promise<any>}
+     */
+    _request(path: string, body: Record<string, any>): Promise<any>;
+    _warnedInsecure: boolean | undefined;
+}

package/src/provider-gemini.js

@@ -0,0 +1,197 @@
+'use strict';
+
+const https = require('https');
+const http = require('http');
+const { ProviderError } = require('./errors');
+
+/** @typedef {import('../types').Message} Message */
+/** @typedef {import('../types').ToolDef} ToolDef */
+/** @typedef {import('../types').ToolCall} ToolCall */
+/** @typedef {import('../types').GenerateResult} GenerateResult */
+
+/** @param {string} hostname @returns {boolean} */
+function isLoopbackHost(hostname) {
+  const h = hostname.replace(/^\[|\]$/g, ''); // strip IPv6 brackets
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h.startsWith('127.');
+}
+
+/**
+ * @typedef {object} GeminiOptions
+ * @property {string} [apiKey] - Google AI Studio (Gemini) API key.
+ * @property {string} [model='gemini-2.5-flash'] - Model ID.
+ * @property {string} [baseUrl='https://generativelanguage.googleapis.com/v1beta'] - API base (override for proxies; posts to `${baseUrl}/models/${model}:generateContent`).
+ * @property {boolean} [exposeErrorBody=false] - Attach the full upstream response to `err.body` on HTTP errors (off by default; `err.message` still carries the API error).
+ */
+
+/**
+ * Google Gemini provider (native `generateContent` API, NOT the OpenAI-compat endpoint — that endpoint
+ * omits the cache token tier, so it can't feed the cost meter; verified by POC). Converts the Loop's
+ * OpenAI-format messages to Gemini `contents`, declares tools as `functionDeclarations`, and normalizes
+ * `usageMetadata` to the neutral Usage shape. Gemini auto-caches (implicit caching on 2.5 models), so the
+ * cache-read tier populates with no opt-in.
+ */
+class GeminiProvider {
+  /** @param {GeminiOptions} [options] */
+  constructor(options = {}) {
+    this.apiKey = options.apiKey?.trim();
+    this.model = options.model || 'gemini-2.5-flash';
+    this.baseUrl = options.baseUrl || 'https://generativelanguage.googleapis.com/v1beta';
+    this.exposeErrorBody = options.exposeErrorBody === true;
+  }
+
+  /**
+   * Generate a response from the Gemini API.
+   * @param {Message[]} messages - Conversation messages (OpenAI format, auto-converted).
+   * @param {ToolDef[]} [tools=[]] - Tool definitions.
+   * @param {Record<string, any>} [options={}] - Options (temperature, maxTokens).
+   * @returns {Promise<GenerateResult>}
+   * @throws {Error} `[GeminiProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
+   */
+  async generate(messages, tools = [], options = {}) {
+    const systemParts = [];
+    /** @type {any[]} */
+    const contents = [];
+    // Gemini matches a functionResponse to its call by NAME, but OpenAI tool results carry only the
+    // tool_call_id. Track id→name from assistant tool_calls so a following tool message can name itself.
+    /** @type {Map<string,string>} */
+    const toolNames = new Map();
+
+    for (const m of messages) {
+      if (m.role === 'system') {
+        if (typeof m.content === 'string' && m.content) systemParts.push({ text: m.content });
+        continue;
+      }
+      if (m.role === 'tool') {
+        const id = m.tool_call_id || '';
+        const name = toolNames.get(id) || id || 'tool';
+        contents.push({ role: 'user', parts: [{ functionResponse: { name, response: { content: m.content } } }] });
+        continue;
+      }
+      if (m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length > 0) {
+        /** @type {any[]} */
+        const parts = [];
+        if (m.content) parts.push({ text: m.content });
+        for (const tc of m.tool_calls) {
+          toolNames.set(tc.id, tc.function.name);
+          let args = tc.function.arguments;
+          if (typeof args === 'string') { try { args = JSON.parse(args); } catch { args = {}; } }
+          parts.push({ functionCall: { name: tc.function.name, args: args || {} } });
+        }
+        contents.push({ role: 'model', parts });
+        continue;
+      }
+      // plain user / assistant text
+      const role = m.role === 'assistant' ? 'model' : 'user';
+      contents.push({ role, parts: [{ text: typeof m.content === 'string' ? m.content : JSON.stringify(m.content) }] });
+    }
+
+    /** @type {Record<string, any>} */
+    const body = { contents };
+    if (systemParts.length) body.systemInstruction = { parts: systemParts };
+    if (tools.length > 0) {
+      body.tools = [{
+        functionDeclarations: tools.map(t => ({
+          name: t.name,
+          description: t.description,
+          ...(t.parameters && { parameters: t.parameters }),
+        })),
+      }];
+    }
+    /** @type {Record<string, any>} */
+    const genConfig = {};
+    if (options.maxTokens) genConfig.maxOutputTokens = options.maxTokens;
+    if (options.temperature != null) genConfig.temperature = options.temperature;
+    if (Object.keys(genConfig).length) body.generationConfig = genConfig;
+
+    const data = await this._request(`/models/${this.model}:generateContent`, body);
+
+    let text = '';
+    /** @type {ToolCall[]} */
+    const toolCalls = [];
+    let fnSeq = 0;
+    const parts = data.candidates?.[0]?.content?.parts || [];
+    for (const part of parts) {
+      if (typeof part.text === 'string') text += part.text;
+      if (part.functionCall) {
+        // Gemini gives no call id; synthesize a stable one so the Loop can pair the tool result.
+        toolCalls.push({ id: `gemini_call_${fnSeq++}`, name: part.functionCall.name, arguments: part.functionCall.args || {} });
+      }
+    }
+
+    return {
+      text,
+      toolCalls,
+      model: data.modelVersion || this.model,
+      usage: this._normalizeUsage(data.usageMetadata),
+    };
+  }
+
+  /**
+   * Normalize Gemini `usageMetadata` to the neutral {@link Usage} shape. Like OpenAI, `promptTokenCount`
+   * INCLUDES the cached tokens (`cachedContentTokenCount`), so subtract for the uncached remainder
+   * (verified live). Gemini bills "thinking" (`thoughtsTokenCount`) as output, so fold it into output
+   * (total = prompt + candidates + thoughts — confirmed against live usageMetadata). Implicit caching
+   * has no separate write tier → cacheCreationTokens 0.
+   * @param {any} u - raw `data.usageMetadata`
+   * @returns {import('../types').Usage}
+   */
+  _normalizeUsage(u) {
+    const cacheRead = u?.cachedContentTokenCount || 0;
+    return {
+      inputTokens: Math.max(0, (u?.promptTokenCount || 0) - cacheRead),
+      outputTokens: (u?.candidatesTokenCount || 0) + (u?.thoughtsTokenCount || 0),
+      cacheReadTokens: cacheRead,
+      cacheCreationTokens: 0,
+    };
+  }
+
+  /**
+   * @param {string} path
+   * @param {Record<string, any>} body
+   * @returns {Promise<any>}
+   */
+  _request(path, body) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(this.baseUrl + path);
+      const transport = url.protocol === 'https:' ? https : http;
+      const payload = JSON.stringify(body);
+
+      // Plaintext key to a remote host exposes it on the wire; loopback is the legitimate http case.
+      if (this.apiKey && url.protocol === 'http:' && !isLoopbackHost(url.hostname) && !this._warnedInsecure) {
+        this._warnedInsecure = true;
+        console.warn(`[GeminiProvider] sending x-goog-api-key over PLAINTEXT http to ${url.hostname} — key exposed on the wire. Use https.`);
+      }
+
+      const req = transport.request(url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(payload),
+          ...(this.apiKey && { 'x-goog-api-key': this.apiKey }),
+        },
+      }, (res) => {
+        let chunks = '';
+        res.on('data', d => (chunks += d));
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(chunks);
+            if ((res.statusCode ?? 0) >= 400) {
+              return reject(new ProviderError(
+                `[GeminiProvider] ${parsed.error?.message || `HTTP ${res.statusCode}`}`,
+                /** @type {any} */ ({ status: res.statusCode, body: this.exposeErrorBody ? parsed : undefined })
+              ));
+            }
+            resolve(parsed);
+          } catch (e) {
+            reject(new Error(`[GeminiProvider] Invalid JSON response: ${chunks.slice(0, 200)}`));
+          }
+        });
+      });
+      req.on('error', reject);
+      req.write(payload);
+      req.end();
+    });
+  }
+}
+
+module.exports = { GeminiProvider };

package/src/provider-openai.d.ts

@@ -44,6 +44,16 @@ export class OpenAIProvider {
      * @throws {Error} `[OpenAIProvider] ...` — on HTTP errors (4xx/5xx) or invalid JSON response.
      */
     generate(messages: Message[], tools?: ToolDef[], options?: Record<string, any>): Promise<GenerateResult>;
+    /**
+     * Normalize OpenAI usage to the neutral {@link Usage} shape. OpenAI auto-caches prompt prefixes
+     * (>=1024 tokens) and reports the cached portion in `prompt_tokens_details.cached_tokens` —
+     * crucially, `prompt_tokens` INCLUDES those cached tokens, so we subtract them to get the uncached
+     * remainder (else the cached tokens are double-counted and priced at the full input rate, a ~2x
+     * over-charge on a warm prompt). OpenAI has no separate cache-write tier → cacheCreationTokens 0.
+     * @param {any} u - raw `data.usage`
+     * @returns {import('../types').Usage}
+     */
+    _normalizeUsage(u: any): import("../types").Usage;
     /**
      * @param {string} path
      * @param {Record<string, any>} body

package/src/provider-openai.js

@@ -73,10 +73,26 @@ class OpenAIProvider {
         arguments: JSON.parse(tc.function.arguments),
       })),
       model: data.model || this.model,
-      usage: {
-        inputTokens: data.usage?.prompt_tokens || 0,
-        outputTokens: data.usage?.completion_tokens || 0,
-      },
+      usage: this._normalizeUsage(data.usage),
+    };
+  }
+
+  /**
+   * Normalize OpenAI usage to the neutral {@link Usage} shape. OpenAI auto-caches prompt prefixes
+   * (>=1024 tokens) and reports the cached portion in `prompt_tokens_details.cached_tokens` —
+   * crucially, `prompt_tokens` INCLUDES those cached tokens, so we subtract them to get the uncached
+   * remainder (else the cached tokens are double-counted and priced at the full input rate, a ~2x
+   * over-charge on a warm prompt). OpenAI has no separate cache-write tier → cacheCreationTokens 0.
+   * @param {any} u - raw `data.usage`
+   * @returns {import('../types').Usage}
+   */
+  _normalizeUsage(u) {
+    const cacheRead = u?.prompt_tokens_details?.cached_tokens || 0;
+    return {
+      inputTokens: Math.max(0, (u?.prompt_tokens || 0) - cacheRead),
+      outputTokens: u?.completion_tokens || 0,
+      cacheReadTokens: cacheRead,
+      cacheCreationTokens: 0,
     };
   }
 

package/src/providers.d.ts

@@ -1,6 +1,7 @@
 import { OpenAIProvider } from "./provider-openai";
 import { AnthropicProvider } from "./provider-anthropic";
+import { GeminiProvider } from "./provider-gemini";
 import { OllamaProvider } from "./provider-ollama";
 import { CLIPipeProvider } from "./provider-clipipe";
 import { FallbackProvider } from "./provider-fallback";
-export { OpenAIProvider as OpenAI, AnthropicProvider as Anthropic, OllamaProvider as Ollama, CLIPipeProvider as CLIPipe, FallbackProvider as Fallback, OpenAIProvider, AnthropicProvider, OllamaProvider, CLIPipeProvider, FallbackProvider };
+export { OpenAIProvider as OpenAI, AnthropicProvider as Anthropic, GeminiProvider as Gemini, OllamaProvider as Ollama, CLIPipeProvider as CLIPipe, FallbackProvider as Fallback, OpenAIProvider, AnthropicProvider, GeminiProvider, OllamaProvider, CLIPipeProvider, FallbackProvider };

package/src/providers.js

@@ -2,6 +2,7 @@
 
 const { OpenAIProvider } = require('./provider-openai');
 const { AnthropicProvider } = require('./provider-anthropic');
+const { GeminiProvider } = require('./provider-gemini');
 const { OllamaProvider } = require('./provider-ollama');
 const { CLIPipeProvider } = require('./provider-clipipe');
 const { FallbackProvider } = require('./provider-fallback');
@@ -10,6 +11,7 @@ module.exports = {
   // Short names (canonical — used throughout docs and the integration guide)
   OpenAI: OpenAIProvider,
   Anthropic: AnthropicProvider,
+  Gemini: GeminiProvider,
   Ollama: OllamaProvider,
   CLIPipe: CLIPipeProvider,
   Fallback: FallbackProvider,
@@ -17,6 +19,7 @@ module.exports = {
   // `const { OpenAIProvider } = require('bare-agent/providers')` also works.
   OpenAIProvider,
   AnthropicProvider,
+  GeminiProvider,
   OllamaProvider,
   CLIPipeProvider,
   FallbackProvider,

package/src/refine.d.ts

@@ -0,0 +1,86 @@
+export type Verdict = import("./evaluator").Verdict;
+export type RefineOptions = {
+    /**
+     *   Build one generation. On iteration 0, `lastResult`/`critique` are null. Fresh-feedback (D6/A1) is the
+     *   consumer's to realize here: seed a NEW Loop with `{goal + critique}` rather than continuing the failed
+     *   transcript — anchoring on a wrong answer defeats the independent verifier.
+     */
+    attempt: (args: {
+        iteration: number;
+        lastResult: any;
+        critique: string | null;
+        contract: string | null;
+    }) => any;
+    /**
+     *   Judge a result — typically `evaluator.evaluate(goal, result, { rubric, contract })`.
+     */
+    evaluate: (result: any, ctx: {
+        iteration: number;
+        contract: string | null;
+    }) => (Verdict | Promise<Verdict>);
+    /**
+     * - The shared definition of done (A3/D10), forwarded to BOTH `attempt` and
+     * `evaluate` so generator and critic agree on what success means.
+     */
+    contract?: string | undefined;
+    /**
+     * - Hard cap. The REAL bound is bareguard maxTurns / budget.
+     */
+    maxIterations?: number | undefined;
+    /**
+     * - Stop on the first satisfied verdict.
+     */
+    stopOnPass?: boolean | undefined;
+};
+export type RefineOutcome = {
+    /**
+     * - The last (best available) result.
+     */
+    result: any;
+    /**
+     * - Its verdict.
+     */
+    verdict: Verdict | null;
+    /**
+     * - How many attempts ran.
+     */
+    iterations: number;
+    /**
+     * - Every attempt + verdict, in order.
+     */
+    history: Array<{
+        result: any;
+        verdict: Verdict;
+    }>;
+};
+/** @typedef {import('./evaluator').Verdict} Verdict */
+/**
+ * @typedef {object} RefineOptions
+ * @property {(args: {iteration: number, lastResult: any, critique: string|null, contract: string|null}) => any} attempt
+ *   Build one generation. On iteration 0, `lastResult`/`critique` are null. Fresh-feedback (D6/A1) is the
+ *   consumer's to realize here: seed a NEW Loop with `{goal + critique}` rather than continuing the failed
+ *   transcript — anchoring on a wrong answer defeats the independent verifier.
+ * @property {(result: any, ctx: {iteration: number, contract: string|null}) => (Verdict | Promise<Verdict>)} evaluate
+ *   Judge a result — typically `evaluator.evaluate(goal, result, { rubric, contract })`.
+ * @property {string} [contract] - The shared definition of done (A3/D10), forwarded to BOTH `attempt` and
+ *   `evaluate` so generator and critic agree on what success means.
+ * @property {number} [maxIterations=3] - Hard cap. The REAL bound is bareguard maxTurns / budget.
+ * @property {boolean} [stopOnPass=true] - Stop on the first satisfied verdict.
+ */
+/**
+ * @typedef {object} RefineOutcome
+ * @property {any} result - The last (best available) result.
+ * @property {Verdict|null} verdict - Its verdict.
+ * @property {number} iterations - How many attempts ran.
+ * @property {Array<{result: any, verdict: Verdict}>} history - Every attempt + verdict, in order.
+ */
+/**
+ * Thin, Loop-agnostic generate → evaluate → regenerate loop (a port of Managed Agents "Outcomes":
+ * iterate → grade → revise, bounded). Knows nothing about providers or `loop.js`; it drives caller-supplied
+ * `attempt`/`evaluate` until a satisfied verdict, a terminal `failed`, or `maxIterations`. A `HaltError`
+ * thrown by either callback (e.g. a governance cap) propagates as a clean exit — never caught here.
+ *
+ * @param {RefineOptions} options
+ * @returns {Promise<RefineOutcome>}
+ */
+export function refine(options: RefineOptions): Promise<RefineOutcome>;

package/src/refine.js

@@ -0,0 +1,65 @@
+'use strict';
+
+/** @typedef {import('./evaluator').Verdict} Verdict */
+
+/**
+ * @typedef {object} RefineOptions
+ * @property {(args: {iteration: number, lastResult: any, critique: string|null, contract: string|null}) => any} attempt
+ *   Build one generation. On iteration 0, `lastResult`/`critique` are null. Fresh-feedback (D6/A1) is the
+ *   consumer's to realize here: seed a NEW Loop with `{goal + critique}` rather than continuing the failed
+ *   transcript — anchoring on a wrong answer defeats the independent verifier.
+ * @property {(result: any, ctx: {iteration: number, contract: string|null}) => (Verdict | Promise<Verdict>)} evaluate
+ *   Judge a result — typically `evaluator.evaluate(goal, result, { rubric, contract })`.
+ * @property {string} [contract] - The shared definition of done (A3/D10), forwarded to BOTH `attempt` and
+ *   `evaluate` so generator and critic agree on what success means.
+ * @property {number} [maxIterations=3] - Hard cap. The REAL bound is bareguard maxTurns / budget.
+ * @property {boolean} [stopOnPass=true] - Stop on the first satisfied verdict.
+ */
+
+/**
+ * @typedef {object} RefineOutcome
+ * @property {any} result - The last (best available) result.
+ * @property {Verdict|null} verdict - Its verdict.
+ * @property {number} iterations - How many attempts ran.
+ * @property {Array<{result: any, verdict: Verdict}>} history - Every attempt + verdict, in order.
+ */
+
+/**
+ * Thin, Loop-agnostic generate → evaluate → regenerate loop (a port of Managed Agents "Outcomes":
+ * iterate → grade → revise, bounded). Knows nothing about providers or `loop.js`; it drives caller-supplied
+ * `attempt`/`evaluate` until a satisfied verdict, a terminal `failed`, or `maxIterations`. A `HaltError`
+ * thrown by either callback (e.g. a governance cap) propagates as a clean exit — never caught here.
+ *
+ * @param {RefineOptions} options
+ * @returns {Promise<RefineOutcome>}
+ */
+async function refine(options) {
+  const { attempt, evaluate } = options;
+  if (typeof attempt !== 'function') throw new Error('[refine] requires an attempt(args) function');
+  if (typeof evaluate !== 'function') throw new Error('[refine] requires an evaluate(result, ctx) function');
+  const contract = typeof options.contract === 'string' ? options.contract : null;
+  const mi = options.maxIterations;
+  const maxIterations = typeof mi === 'number' && Number.isInteger(mi) && mi > 0 ? mi : 3;
+  const stopOnPass = options.stopOnPass !== false;
+
+  /** @type {Array<{result: any, verdict: Verdict}>} */
+  const history = [];
+  let lastResult = null;
+  /** @type {Verdict|null} */
+  let lastVerdict = null;
+
+  for (let iteration = 0; iteration < maxIterations; iteration++) {
+    const result = await attempt({ iteration, lastResult, critique: lastVerdict ? lastVerdict.critique : null, contract });
+    const verdict = await evaluate(result, { iteration, contract });
+    history.push({ result, verdict });
+    lastResult = result;
+    lastVerdict = verdict;
+
+    if (stopOnPass && verdict.pass) break;
+    if (verdict.status === 'failed') break; // terminal — revising a fundamentally-wrong approach burns budget
+  }
+
+  return { result: lastResult, verdict: lastVerdict, iterations: history.length, history };
+}
+
+module.exports = { refine };

package/src/remember.d.ts

@@ -0,0 +1,118 @@
+export type RememberOptions = {
+    /**
+     * - LLM provider implementing `generate(messages, tools, opts)`.
+     */
+    provider: Provider;
+    /**
+     * - The Store socket (or a `Memory` wrapper). remember writes through
+     * `.store(content, metadata)` ONLY — no other verb, no backend assumptions.
+     */
+    store: Pick<Store, "store">;
+    /**
+     * - Optional definition of what counts as durable for this task; appended to the
+     * distiller prompt to steer it (the A3 contract idea, reused on the write side).
+     */
+    contract?: string | undefined;
+    /**
+     * - Merged into every stored fact's metadata. `kind` is always `'fact'`
+     * (NOT overridable — `remember` writes facts; `fact` is litectx's canonical durable kind and harmless to other
+     * stores, so the stored label always matches the `facts` counter). Add ANY OTHER metadata here (tags, or litectx
+     * `format`/`scope` to differentiate facts). NEVER carries ctx — ctx rides in its own option, never persisted.
+     */
+    metadata?: Record<string, any> | undefined;
+    /**
+     * - The run ctx. If it carries
+     * the loop-lent `recordMemoryOp`, each fact write counts against `result.metrics.memory.facts`.
+     */
+    ctx?: ({
+        recordMemoryOp?: (kind: string) => void;
+    } & Record<string, any>) | undefined;
+    /**
+     * - Budget hook;
+     * each distill pass forwards usage so a bareguard gate keeps counting (mirror of Evaluator).
+     */
+    onLlmResult?: ((payload: {
+        usage: any;
+        model: string | null;
+        kind: "remember";
+    }) => any) | undefined;
+    /**
+     * - Override the distiller system prompt (defaults to the F5-validated one).
+     */
+    prompt?: string | undefined;
+};
+export type RememberOutcome = {
+    /**
+     * - The facts written, in order — deduplicated within this call by exact string
+     * (so `facts.length` is the count stored). Cross-run / semantic dedup is the store's/consumer's job.
+     */
+    facts: string[];
+    /**
+     * - How many non-empty spans were processed.
+     */
+    spans: number;
+};
+export type Provider = import("../types").Provider;
+export type Store = import("../types").Store;
+/**
+ * @typedef {object} RememberOptions
+ * @property {Provider} provider - LLM provider implementing `generate(messages, tools, opts)`.
+ * @property {Pick<Store, 'store'>} store - The Store socket (or a `Memory` wrapper). remember writes through
+ *   `.store(content, metadata)` ONLY — no other verb, no backend assumptions.
+ * @property {string} [contract] - Optional definition of what counts as durable for this task; appended to the
+ *   distiller prompt to steer it (the A3 contract idea, reused on the write side).
+ * @property {Record<string, any>} [metadata] - Merged into every stored fact's metadata. `kind` is always `'fact'`
+ *   (NOT overridable — `remember` writes facts; `fact` is litectx's canonical durable kind and harmless to other
+ *   stores, so the stored label always matches the `facts` counter). Add ANY OTHER metadata here (tags, or litectx
+ *   `format`/`scope` to differentiate facts). NEVER carries ctx — ctx rides in its own option, never persisted.
+ * @property {{ recordMemoryOp?: (kind: string) => void } & Record<string, any>} [ctx] - The run ctx. If it carries
+ *   the loop-lent `recordMemoryOp`, each fact write counts against `result.metrics.memory.facts`.
+ * @property {(payload: { usage: any, model: string|null, kind: 'remember' }) => any} [onLlmResult] - Budget hook;
+ *   each distill pass forwards usage so a bareguard gate keeps counting (mirror of Evaluator).
+ * @property {string} [prompt] - Override the distiller system prompt (defaults to the F5-validated one).
+ */
+/**
+ * @typedef {object} RememberOutcome
+ * @property {string[]} facts - The facts written, in order — deduplicated within this call by exact string
+ *   (so `facts.length` is the count stored). Cross-run / semantic dedup is the store's/consumer's job.
+ * @property {number} spans - How many non-empty spans were processed.
+ */
+/**
+ * Distill durable facts from harvested spans and persist them through the Store socket.
+ *
+ * @param {Array<string | { content?: string, text?: string }>} spans - The harvested spans (stash's feedstock).
+ *   Each is a transcript chunk — a raw string, or an object with `content`/`text`. Empty/blank spans are skipped.
+ * @param {RememberOptions} options
+ * @returns {Promise<RememberOutcome>}
+ */
+export function remember(spans: Array<string | {
+    content?: string;
+    text?: string;
+}>, options?: RememberOptions): Promise<RememberOutcome>;
+/**
+ * remember — the consolidation pass (eval-assist F5). The "future glue" the PRD parked: it turns the spans
+ * `stash` harvested out of the live transcript into durable facts, written back through the GENERIC four-verb
+ * `Store` socket (`store`/`search`/`get`/`delete`). Backend-agnostic by construction — works with the
+ * JsonFileStore, SQLite, litectx, or a custom store — so it carries NO litectx coupling (the reason the
+ * read-litectx's-promotion-count alternative was rejected: it reaches past the socket into one backend).
+ *
+ * One cheap LLM pass per span distills durable signal (decisions, config, identifiers, stable preferences)
+ * and DROPS ephemeral chatter, superseded values, and unanswered questions. The distiller prompt below is the
+ * one validated live on the real Anthropic wire in `poc/f5-remember-distill.mjs` (faithfulness + correction +
+ * discrimination, all falsifiable). A wrong distiller poisons Memory silently, so that POC must stay green.
+ *
+ * SECURITY — memory-poisoning surface: facts are model output distilled over UNTRUSTED transcript content and
+ * written to durable memory. The grounding prompt refuses a direct "record this fact" injection (validated in the
+ * F5 POC + integration test), but treat recalled facts as untrusted CONTEXT, never as authority — and never feed
+ * a recalled fact into a privileged action without the same gate you'd apply to any model output.
+ *
+ * Composes AROUND a Loop (like Evaluator/refine), never inside `loop.js`. Optional, flagged-and-deletable.
+ * Budget visibility: each distill pass forwards `usage` to `opts.onLlmResult` (mirror of Evaluator) so a wired
+ * bareguard gate keeps counting. A `HaltError` from the provider propagates clean. Metering: each fact write
+ * counts against `result.metrics.memory.facts` via the loop-lent `ctx.recordMemoryOp('facts')` hook — the
+ * honest producer that field waited for. `facts` is DISJOINT from `stored`: remember writes via `store.store`
+ * WITHOUT threading ctx, so it never also trips the generic-write counter.
+ */
+/** @typedef {import('../types').Provider} Provider */
+/** @typedef {import('../types').Store} Store */
+export const DISTILL_PROMPT: string;