@mercury-fw/core 0.25.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# @mercury-fw/core
+
+## 0.25.0
+
+### Minor Changes
+
+- c114e34: - Mercury is published on npm as `@mercury-fw/*`: the framework packages move together under one version, plugins and channels have versions of their own.
+  - `bun create mercury-agent my-agent` scaffolds an app, and the CLI command is now `mfw` (`@mercury-fw/cli`).
+  - Packages ship type declarations, so a new app type-checks against the framework without re-checking its source.
+  - External dependencies use version ranges instead of exact pins, so an app shares them with the framework.
+  - Every package has its own README, and the repo README describes the framework.
+  - MIT license.
+
+### Patch Changes
+
+- @mercury-fw/plugin-types@0.25.0
+- @mercury-fw/channel-types@0.25.0
+- @mercury-fw/cli-engine@0.25.0
+- @mercury-fw/confirm-engine@0.25.0

package/README.md

@@ -0,0 +1,38 @@
+# @mercury-fw/core
+
+The runtime of [Mercury](https://github.com/lucabro81/mercury-fw): it builds an agent from the config an app gives it and runs it, from the conversation loop to the channels. An app depends on it; a plugin doesn't (plugins build on [`@mercury-fw/kit`](https://www.npmjs.com/package/@mercury-fw/kit)).
+
+The usual way to get it is scaffolding an app, which wires it up for you:
+
+```bash
+bun create mercury-agent my-agent
+```
+
+## What it exports
+
+- `defineMercuryConfig(config)` types the app's `mercury.config.ts`: `plugins`, `channels`, `persona`.
+- `composeMercury(config)` builds the agent from that config and the environment, and returns what the entrypoints start: `handleTurn`, the declared channels with their runtime, and the background jobs (`startCrons`, `startAdmin`).
+- `loadChannels(channels, { runtime })` turns the declared channels into started providers, and `createTerminalProvider(...)` opens the dev REPL on `handleTurn`.
+- `DEFAULT_PERSONA_IDENTITY`, `DEFAULT_PERSONA_TONE` are the persona an app gets when its config sets none.
+
+A scaffolded app's `src/index.ts` (the service) and `src/repl.ts` (the REPL) are the reference for using them.
+
+## Environment
+
+| Variable | |
+|---|---|
+| `OLLAMA_HOST` | The Ollama-compatible endpoint. Required. |
+| `OLLAMA_MODEL` | The chat model. Required. |
+| `OLLAMA_EMBEDDING_MODEL` | The embedding model for the episodic memory (default `nomic-embed-text`). |
+| `OLLAMA_THINK` | `false` for a model that doesn't support thinking. |
+| `QDRANT_URL` | Qdrant, for the episodic memory (default `http://qdrant:6333`). |
+| `WIKI_VAULT_PATH` | Where the wiki lives. Required. |
+| `MERCURY_CLIS` | The tool plugins this deployment turns on, by name, comma-separated. |
+
+Qdrant being unreachable degrades memory, it doesn't stop the agent.
+
+## Requirements
+
+Bun: the package ships its TypeScript source, which Bun runs as is, plus type declarations for your editor and `tsc`.
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The public surface of `@mercury-fw/core` — the framework runtime a Mercury
+ * instance consumes. Everything else under `src/` is internal: an app depends on
+ * this barrel, never on a deep path.
+ *
+ * What's exported, and who uses it:
+ * - `composeMercury` builds the instance from a config it is *given* (the
+ *   config is never imported by the core — that's what keeps it app-agnostic).
+ *   `ComposedApp`/`ConfirmDeps` are its result and confirm-binding types.
+ * - `loadChannels`/`LoadedChannel` — the service entrypoint starts the declared
+ *   channels with these.
+ * - `createTerminalProvider` — the dev REPL entrypoint opens the terminal with it.
+ * - `defineMercuryConfig`/`MercuryConfig` — the app's `mercury.config.ts` declares
+ *   its composition through these; `Persona` types its `persona` field.
+ * - `DEFAULT_PERSONA_IDENTITY`/`DEFAULT_PERSONA_TONE` — the persona an instance
+ *   gets when its config sets none; the scaffolder writes them as a new app's
+ *   starting persona.
+ */
+export { composeMercury, type ComposedApp, type ConfirmDeps } from "./src/compose.ts";
+export { loadChannels, type LoadedChannel } from "./src/router/channel-loader.ts";
+export { createTerminalProvider } from "./src/router/terminal-provider.ts";
+export { defineMercuryConfig, type MercuryConfig } from "./src/config/define-config.ts";
+export { DEFAULT_PERSONA_IDENTITY, DEFAULT_PERSONA_TONE, type Persona } from "./src/session/system-prompt.ts";

package/dist/src/admin/cli-routes.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Admin panel's CLI status tab: lists each active CLI's allowlisted
+ * commands straight from the same `CliConfig` `src/index.ts` already
+ * built at startup (`activeCliConfigs`), and — where a CLI declares a
+ * plain, non-mutating `auth whoami`-shaped prefix — runs it through the
+ * exact same `runCli` used for real tool calls. Never constructs or runs
+ * anything else; this is read-only status, not a command console.
+ */
+import type { CliConfig } from "@mercury-fw/cli-engine";
+import type { runCli } from "@mercury-fw/cli-engine";
+export type CliStatusEntry = {
+    binary: string;
+    allowedPrefixes: CliConfig["allowedPrefixes"];
+    whoami: {
+        available: false;
+    } | {
+        available: true;
+        ok: boolean;
+        output: string;
+    };
+};
+export declare function getCliStatus(configs: Record<string, CliConfig>, runCliFn: typeof runCli): Promise<CliStatusEntry[]>;

package/dist/src/admin/env-file.d.ts

@@ -0,0 +1 @@
+export declare function setEnvValue(content: string, key: string, value: string): string;

package/dist/src/admin/model-routes.d.ts

@@ -0,0 +1,26 @@
+/** Live model names Ollama actually has pulled, or `null` if the host isn't reachable. */
+export declare function getAvailableModels(host: string, fetchFn?: typeof fetch): Promise<string[] | null>;
+export type ModelStatus = {
+    host: string;
+    model: string;
+    contextLength: number | null;
+    availableModels: string[] | null;
+};
+export declare function getModelStatus(host: string, model: string, fetchFn?: typeof fetch): Promise<ModelStatus>;
+export type SelfHealth = {
+    uptimeSeconds: number;
+    memory: {
+        rss: number;
+        heapUsed: number;
+        heapTotal: number;
+    };
+    qdrantReachable: boolean;
+    ollamaReachable: boolean;
+};
+export declare function getSelfHealth(deps: {
+    qdrant: {
+        getCollections(): Promise<unknown>;
+    };
+    ollamaHost: string;
+    fetchFn?: typeof fetch;
+}): Promise<SelfHealth>;

package/dist/src/admin/qdrant-scroll.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Read-only point enumeration for the admin panel's Qdrant inspection tab —
+ * `episodic-store.ts`/`semantic-facts-store.ts` only wrap similarity
+ * `search`, there's no existing way to just list what's in a collection.
+ * One page per call (not an auto-paging fetch-everything loop): a real
+ * collection can be arbitrarily large, so the caller decides whether to
+ * request another page via the returned `nextOffset`.
+ */
+type ScrollOffset = string | number | Record<string, unknown> | null;
+export type ScrollableQdrantClient = {
+    scroll(collection: string, params: {
+        limit: number;
+        offset?: ScrollOffset;
+        with_payload: boolean;
+    }): Promise<{
+        points: Array<{
+            id: string | number;
+            payload?: Record<string, unknown> | null;
+        }>;
+        next_page_offset?: ScrollOffset;
+    }>;
+};
+export type ScrollPage = {
+    points: Array<{
+        id: string | number;
+        payload: Record<string, unknown> | null;
+    }>;
+    nextOffset: ScrollOffset;
+};
+export declare function scrollCollection(client: ScrollableQdrantClient, collectionName: string, opts: {
+    limit: number;
+    offset?: ScrollOffset;
+}): Promise<ScrollPage>;
+export {};

package/dist/src/admin/server.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Admin panel POC — a separate `Bun.serve()` instance running inside the
+ * same Mercury process (see plan: reuses the already-constructed `qdrant`
+ * client, `activeCliConfigs`, model, and vault path directly, no IPC).
+ * Dev-only, unauthenticated by design (see docs/DECISIONS.md-adjacent
+ * scoping conversation) — never started unless `ADMIN_PANEL_ENABLED` is
+ * set (see `src/index.ts`).
+ */
+import type { LanguageModel } from "ai";
+import type { CliConfig } from "@mercury-fw/cli-engine";
+import type { runCli } from "@mercury-fw/cli-engine";
+import { type ScrollableQdrantClient } from "./qdrant-scroll.ts";
+type QdrantDeps = ScrollableQdrantClient & {
+    getCollections(): Promise<{
+        collections: Array<{
+            name: string;
+        }>;
+    }>;
+};
+export type AdminServerDeps = {
+    port: number;
+    vaultPath: string;
+    model: LanguageModel;
+    qdrant: QdrantDeps;
+    qdrantCollections: {
+        episodic: string;
+        semanticFacts: string;
+    };
+    activeCliConfigs: Record<string, CliConfig>;
+    runCliFn: typeof runCli;
+    ollamaHost: string;
+    ollamaModel: string;
+    systemPrompts: {
+        terminal: string;
+        googleChat: string;
+    };
+    envFilePath: string;
+};
+export declare function startAdminServer(deps: AdminServerDeps): ReturnType<typeof Bun.serve>;
+export {};

package/dist/src/admin/wiki-routes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Admin panel's Wiki tab. `list`/`read`/`grep` walk the whole vault
+ * directly (same trusted-admin-context choice `vault-cli.ts` already
+ * makes — bypassing `wiki-read.ts`'s per-user `allowedRoots` scoping,
+ * which exists to isolate what the MODEL can see per caller, not what an
+ * operator running this panel can see).
+ *
+ * Curated edits go through a real, short-lived agent turn instead of
+ * calling `writeCuratedNote` directly — see `editWikiViaModel`. Raw
+ * writes and deletes have no model-facing tool today, so they stay
+ * direct calls into `wiki-note.ts`, same as `vault-cli.ts`.
+ */
+import type { LanguageModel } from "ai";
+import type { WikiGrepMatch } from "../wiki/wiki-read.ts";
+export declare function listWikiVault(vaultPath: string): Promise<string[]>;
+export declare function readWikiVaultFile(vaultPath: string, relativePath: string): Promise<string>;
+export declare function grepWikiVault(vaultPath: string, pattern: string): Promise<WikiGrepMatch[]>;
+/** `vaultRelativePath` must start with `raw/`, matching `vault-cli.ts`'s `write-raw`. */
+export declare function writeRawWikiEntry(vaultPath: string, vaultRelativePath: string, body: string): Promise<void>;
+/** `vaultRelativePath` must start with `curated/` or `raw/` — nothing else is deletable from here. */
+export declare function deleteWikiEntry(vaultPath: string, vaultRelativePath: string): Promise<void>;
+/**
+ * Sends `instruction` through a real, short-lived agent turn scoped
+ * ONLY to the four wiki tools (`createWikiTools`) — never the full
+ * toolset a normal channel gets, so this box can't touch Jira/Bitbucket.
+ * Reuses the exact commit path a real conversation would take
+ * (`write_file` -> `writeCuratedNote` -> git commit, D-16); this
+ * function has no write logic of its own. History is fresh per call,
+ * never persisted — this isn't a real session.
+ */
+export declare function editWikiViaModel(model: LanguageModel, vaultPath: string, instruction: string): Promise<string>;

package/dist/src/compose.d.ts

@@ -0,0 +1,42 @@
+import { type ConfirmationStore } from "@mercury-fw/confirm-engine";
+import type { MercuryConfig } from "./config/define-config.ts";
+import type { HandleTurn, ChannelRuntimeContext, ChannelPlugin } from "@mercury-fw/channel-types";
+import { writeConfirmationNote } from "./wiki/wiki-note.ts";
+/** A stoppable subsystem (cron, server). */
+type Stoppable = {
+    stop: () => void;
+};
+/** The confirm capability's binding to this instance's store/vault/note-writer, shared by the terminal and the channel runtime. */
+export type ConfirmDeps = {
+    store: ConfirmationStore;
+    vaultPath: string;
+    writeConfirmationNoteFn: typeof writeConfirmationNote;
+};
+/**
+ * The built Mercury instance. `build`, not `start`: the channels, crons and
+ * admin are not running until an entrypoint starts them.
+ */
+export type ComposedApp = {
+    /** The turn driver every channel funnels through (see `turn-runner.ts`). */
+    handleTurn: HandleTurn;
+    /** The declared channel plugins (from `mercury.config.ts`). */
+    channels: ChannelPlugin[];
+    /** The runtime context each channel's `build()` gets — confirm + in-process reads injected by the core. */
+    channelRuntime: ChannelRuntimeContext;
+    /** The confirm binding, for a caller (the terminal) that intercepts tokens directly. */
+    confirmDeps: ConfirmDeps;
+    ollamaHost: string;
+    ollamaModel: string;
+    /** Starts the Layer-3 idle-capture and self-review crons; returns a single stopper for shutdown. */
+    startCrons: () => Stoppable;
+    /** Starts the POC admin panel if `ADMIN_PANEL_ENABLED`; returns it (to stop on shutdown), or undefined. */
+    startAdmin: () => Stoppable | undefined;
+};
+/**
+ * Builds a Mercury instance from the composition `config` it is given + env. The
+ * config is a parameter, never imported here: that's what makes the core
+ * app-agnostic — an entrypoint (the service, the dev REPL, a future scaffolded
+ * app) reads its own `mercury.config.ts` and passes it in. See {@link ComposedApp}.
+ */
+export declare function composeMercury(config: MercuryConfig): Promise<ComposedApp>;
+export {};

package/dist/src/config/define-config.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The instance composition config contract and its `defineMercuryConfig`
+ * helper. A Mercury instance is composed by declaring, in one place, which
+ * plugins it runs — the way a Nuxt/Vite project declares its config through a
+ * `defineConfig` call in a `*.config.ts` file. `defineMercuryConfig` adds no
+ * runtime behavior; it exists purely so the app-root `mercury.config.ts` gets
+ * editor/compiler support (the argument is checked against `MercuryConfig`) and
+ * so there is a single, stable seam the composition root reads from.
+ *
+ * This is the minimal foundational slice of a broader composition rethink: for
+ * now the config carries only the plugin list. Per-plugin configuration and the
+ * eventual retirement of the file-based cli-configs are deliberately not here.
+ */
+import type { Plugin } from "@mercury-fw/plugin-types";
+import type { ChannelPlugin } from "@mercury-fw/channel-types";
+import type { Persona } from "../session/system-prompt.ts";
+/** The shape of a Mercury instance's composition config: the tool plugins
+ * (gated by MERCURY_CLIS) and the channel plugins (enabled by being declared
+ * here — declared = active), each loaded by its own loader, plus the
+ * assistant's persona (its identity and tone; the defaults when left out). */
+export type MercuryConfig = {
+    plugins: Plugin[];
+    channels?: ChannelPlugin[];
+    persona?: Persona;
+};
+/**
+ * Identity + typing helper for `mercury.config.ts`. Returns its argument
+ * unchanged; its only job is to type the config literal against `MercuryConfig`
+ * at the call site, exactly like `defineConfig` in the Vite/Nuxt ecosystem.
+ */
+export declare function defineMercuryConfig(config: MercuryConfig): MercuryConfig;

package/dist/src/cron/idle-session-cron.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The session-persistence cron loop: periodically sweeps for sessions idle past the
+ * configured timeout, summarizes each one (episodic-summarizer.ts),
+ * writes the result to Qdrant (episodic-store.ts), and discards the raw
+ * transcript (`deps.closeSession`). Every dependency is injected — this
+ * file owns only the sweep/interval mechanics, not session storage, the
+ * LLM call, or Qdrant itself.
+ */
+import type { IdleSessionScanner } from "./idle-session-scanner.ts";
+import type { Message } from "../session/history.ts";
+import type { EpisodicSummary } from "../memory/episodic-store.ts";
+import type { SemanticFact } from "../session/semantic-fact-extractor.ts";
+import type { SemanticFactEntry } from "../memory/semantic-facts-store.ts";
+export type IdleSession = {
+    key: string;
+    userId: string;
+    messages: Message[];
+};
+/**
+ * Dependencies for `captureSessionToMemory` — a subset of
+ * `IdleSessionSweepDeps`, without `getSession`/`closeSession`: this
+ * function never decides *whether* a session should be captured or
+ * whether it should be closed afterwards, only *how* to capture a given
+ * slice of messages. Reused by the idle sweep below (final capture +
+ * close) and, without touching this file's own tests, by the two
+ * mid-conversation triggers wired in `index.ts` (message-count threshold,
+ * Layer 1 compression) — neither of which closes the session.
+ */
+export type CaptureDeps = {
+    summarize: (messages: Message[]) => Promise<string>;
+    store: (entry: EpisodicSummary) => Promise<void>;
+    /**
+     * Semantic fact extraction/consolidation (D-22/D-34) — an enrichment on
+     * top of the episodic summary above, not a required part of it: omit
+     * all three and capture behaves exactly as before. When present, a
+     * failure here is logged and never propagates — the episodic write
+     * already succeeded and is the source of truth being preserved, same
+     * "system must work when this enrichment is absent" boundary as every
+     * other Layer 2/3 store in Mercury.
+     */
+    extractFacts?: (messages: Message[]) => Promise<SemanticFact[]>;
+    storeFact?: (entry: SemanticFactEntry) => Promise<void>;
+    consolidateFact?: (userId: string, topic: string) => Promise<void>;
+    log?: (msg: string) => void;
+};
+/**
+ * Summarizes+stores an episodic entry for `messages`, then (when the
+ * semantic deps are provided) extracts and consolidates semantic facts —
+ * the one place this logic lives, shared by every capture trigger. A
+ * failure summarizing/storing propagates to the caller (it decides what
+ * "capture failed" means for its own trigger — e.g. the idle sweep below
+ * leaves the session tracked for retry and skips `closeSession`); a
+ * failure in the semantic enrichment layer is caught and logged here,
+ * never propagated, since it must never undo an episodic write that
+ * already succeeded.
+ */
+export declare function captureSessionToMemory(userId: string, sessionKey: string, messages: Message[], now: number, deps: CaptureDeps): Promise<void>;
+export type IdleSessionSweepDeps = CaptureDeps & {
+    /** Looks up a session's current content by key; `undefined` if it's already gone (e.g. closed by something else in the meantime). */
+    getSession: (key: string) => IdleSession | undefined;
+    /** Discards the session's raw transcript — called only after a successful summarize+store. */
+    closeSession: (key: string) => void;
+};
+/**
+ * Runs one sweep at `now`: every session `scanner` reports idle (past
+ * `idleTimeoutMs`) gets captured (`captureSessionToMemory`) and closed,
+ * then cleared from `scanner`. A failure capturing is logged and leaves
+ * that session's tracking untouched (retried on the next sweep) — it must
+ * never stop the sweep from processing the others (hard-won convention:
+ * one bad tick can't take down the rest of Mercury).
+ */
+export declare function runIdleSessionSweep(scanner: IdleSessionScanner, now: number, idleTimeoutMs: number, deps: IdleSessionSweepDeps): Promise<void>;
+export type IdleSessionCron = {
+    stop: () => void;
+};
+/** Starts the periodic sweep on `opts.checkIntervalMs`, gated on `opts.idleTimeoutMs`. `stop()` halts it. */
+export declare function startIdleSessionCron(scanner: IdleSessionScanner, deps: IdleSessionSweepDeps, opts: {
+    idleTimeoutMs: number;
+    checkIntervalMs: number;
+}): IdleSessionCron;

package/dist/src/cron/idle-session-scanner.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pure idle-tracking for session persistence: remembers the last
+ * activity time per session key and reports which are idle at a given
+ * moment. Time is always passed in, never read internally (`Date.now()`
+ * lives in the caller, e.g. `src/index.ts`/`idle-session-cron.ts`) — this
+ * is what makes `scanIdle`'s threshold behavior exactly testable.
+ */
+export type IdleSessionScanner = {
+    /** Records activity for `key` at `now`, resetting its idle clock. */
+    touch(key: string, now: number): void;
+    /** Returns every tracked key whose last activity is at least `idleTimeoutMs` before `now`. */
+    scanIdle(now: number, idleTimeoutMs: number): string[];
+    /** Stops tracking `key` — call after a session has been consolidated and its raw transcript discarded. */
+    clear(key: string): void;
+};
+export declare function createIdleSessionScanner(): IdleSessionScanner;

package/dist/src/cron/self-review-cron.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The wiki self-review cron: runs once nightly (a fixed local hour,
+ * hardcoded, no env override — deliberately different from every other
+ * interval in this codebase, per an explicit request to keep this one
+ * out of runtime configurability), running raw/ triage, index.md/orphan
+ * maintenance, and a contradiction check as three independent sub-passes
+ * (see `self-review-runner.ts` for why they're independent, not one
+ * multi-step call). Raw-triage and index/orphan each skip when their own
+ * cheap pre-check finds nothing to do; the contradiction check has no
+ * such pre-check and always runs on a triggered tick — running the whole
+ * thing at night, when nothing else contends for the shared local model,
+ * is what makes that affordable.
+ *
+ * This file owns only the scheduling/orchestration mechanics — vault
+ * access and the actual LLM calls are injected, same separation
+ * `idle-session-cron.ts` uses for session storage and the LLM summarizer.
+ */
+export type SelfReviewTickDeps = {
+    listRawEntries: () => Promise<string[]>;
+    findOrphans: () => Promise<string[]>;
+    runRawTriage: (rawEntries: string[]) => Promise<void>;
+    runIndexAndOrphan: (orphans: string[]) => Promise<void>;
+    runContradictionCheck: () => Promise<void>;
+    log?: (msg: string) => void;
+};
+/**
+ * Runs one nightly pass: raw-triage and index/orphan each run only if
+ * their own cheap signal found something; the contradiction check always
+ * runs, since nothing cheap can tell it whether there's anything to find.
+ * Each sub-pass is wrapped in its own try/catch — one failing must not
+ * stop the other two from running in the same pass (hard-won convention:
+ * one bad tick can't take down the rest of Mercury).
+ */
+export declare function runSelfReviewTick(deps: SelfReviewTickDeps): Promise<void>;
+/** 3 AM local time — hardcoded on purpose, see file header. */
+export declare const SELF_REVIEW_HOUR = 3;
+/** How often to check whether it's time to run — mirrors idle-session-cron's
+ * check-vs-timeout split, hardcoded for the same reason as the hour above. */
+export declare const SELF_REVIEW_CHECK_INTERVAL_MS: number;
+export type SelfReviewCron = {
+    stop: () => void;
+};
+/**
+ * Checks every `opts.checkIntervalMs` whether the current local hour
+ * matches `opts.hour` and today hasn't run yet; if so, runs one tick.
+ * `lastRunDate` is in-memory only — if the process restarts mid-window it
+ * just waits for tomorrow's, which is fine, nothing here needs to survive
+ * a restart. `opts.now`/`opts.hour`/`opts.checkIntervalMs` exist purely as
+ * test seams; production (`index.ts`) never overrides them.
+ */
+export declare function startSelfReviewCron(deps: SelfReviewTickDeps, opts?: {
+    hour?: number;
+    checkIntervalMs?: number;
+    now?: () => Date;
+}): SelfReviewCron;

package/dist/src/cron/semantic-consolidation.d.ts

@@ -0,0 +1,71 @@
+import type { readWikiFile } from "../wiki/wiki-read.ts";
+import type { writeInferredNote, writeToolCorrectionNote } from "../wiki/wiki-note.ts";
+import type { SemanticFactEntry } from "../memory/semantic-facts-store.ts";
+import type { ToolCorrectionEntry } from "../memory/tool-corrections-store.ts";
+type ClusterFn = (userId: string, topic: string, limit: number) => Promise<SemanticFactEntry[]>;
+type Confidence = "low" | "medium" | "high";
+export type ConsolidationDeps = {
+    vaultPath: string;
+    clusterFn: ClusterFn;
+    readWikiFileFn: typeof readWikiFile;
+    writeInferredNoteFn: typeof writeInferredNote;
+    k?: number;
+    confidenceForCount?: (dominantCount: number, k: number) => Confidence;
+    now?: () => string;
+};
+type ToolCorrectionClusterFn = (tool: string, topic: string, limit: number) => Promise<ToolCorrectionEntry[]>;
+/**
+ * Same shape as `ConsolidationDeps`, keyed by `tool` instead of `userId` —
+ * `readNoteFn`/`writeNoteFn` deliberately don't take a userId at all
+ * (unlike `readWikiFileFn`/`writeInferredNoteFn` above): a procedural
+ * correction lives under `curated/standards/`, visible to every session
+ * regardless of who asks, never scoped to one user's own
+ * `inferred/users/<userId>/`.
+ */
+export type ToolCorrectionConsolidationDeps = {
+    vaultPath: string;
+    clusterFn: ToolCorrectionClusterFn;
+    readNoteFn: (vaultPath: string, relativePath: string) => Promise<string>;
+    writeNoteFn: typeof writeToolCorrectionNote;
+    k?: number;
+    confidenceForCount?: (dominantCount: number, k: number) => Confidence;
+    now?: () => string;
+};
+/** Window size for consolidation — how many recent occurrences of a topic to consider. Uncalibrated: chosen without real usage data, to revisit once there's actual traffic to tune against. */
+export declare const DEFAULT_CONSOLIDATION_K = 3;
+/**
+ * Uncalibrated confidence bands, count relative to `k`: a single
+ * occurrence is unconfirmed (low); repeated but not unanimous within the
+ * tracked window is medium; the dominant value filling the whole window
+ * is high. Same "revisit with real usage" caveat as `DEFAULT_CONSOLIDATION_K`.
+ */
+export declare function defaultConfidenceForCount(dominantCount: number, k: number): Confidence;
+/**
+ * Re-clusters `topic` for `userId`, and promotes the dominant value to a
+ * wiki note if it beats the current incumbent's count. No-op if the
+ * cluster is empty or has no single dominant value.
+ *
+ * `userId` here is Qdrant's own storage form (e.g. `"users/42"`, a raw
+ * Google Chat resource name) — `clusterFn` above searches with it as-is,
+ * matching how `storeSemanticFact` wrote it. The wiki's
+ * `inferred/users/<userId>/` convention expects a different,
+ * `encodeURIComponent`-encoded form instead (the same one the model's
+ * own wiki tools already use) — a raw userId containing "/" would
+ * otherwise be rejected outright by
+ * `writeInferredNote`'s own path-separator guard, and even without that
+ * guard would land in a directory the model's wiki tools never look at.
+ * Two different representations of the same identity, for two different
+ * purposes — `wikiUserId` below is used only for the wiki-facing calls,
+ * never for `clusterFn`.
+ */
+export declare function consolidateSemanticFact(userId: string, topic: string, deps: ConsolidationDeps): Promise<void>;
+/**
+ * Same promotion logic as `consolidateSemanticFact` — re-clusters `topic`
+ * for `tool`, promotes the dominant value if it beats the incumbent's
+ * count — but keyed by `tool` (a CLI, not a person) and writing to
+ * `curated/standards/<tool>-<topic>.md` (global) instead of
+ * `inferred/users/<userId>/<topic>.md` (per-user). No userId encoding
+ * needed here: a tool name (e.g. "jira") never contains a path separator.
+ */
+export declare function consolidateToolCorrection(tool: string, topic: string, deps: ToolCorrectionConsolidationDeps): Promise<void>;
+export {};

package/dist/src/memory/embedder.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Thin glue turning an embedding model into the `(text) => Promise<number[]>`
+ * shape `episodic-store.ts`'s `storeEpisodicSummary` expects. Same "not
+ * worth mocking deeply" reasoning as `session/summarizer.ts` — one line
+ * of glue around the AI SDK's `embed`, no dedicated test file.
+ */
+import { type EmbeddingModel } from "ai";
+/** Returns a function that embeds a string using `model`. */
+export declare function createEmbedder(model: EmbeddingModel): (text: string) => Promise<number[]>;