@mercury-fw/core 0.25.0

package/dist/src/session/summarizer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Thin glue that turns `createSessionHistory`'s injected `summarize`
+ * dependency into a real LLM call.
+ *
+ * Kept separate from `history.ts` on purpose: `history.ts`'s threshold/
+ * merge/replace logic is the substantial part and is fully unit-tested
+ * with a fake summarizer; this file's only job is producing the prompt
+ * and calling `generateText`, which isn't worth mocking deeply for one
+ * line of glue.
+ *
+ * Used by: `src/index.ts` (wiring), which passes the result into
+ * `createSessionHistory` (see `src/session/history.ts`).
+ */
+import { type LanguageModel } from "ai";
+import type { Message } from "./history.ts";
+/**
+ * Returns a function matching `createSessionHistory`'s `summarize`
+ * signature, backed by `model`. The returned function asks the model to
+ * condense the given messages into a short summary that preserves
+ * names, ticket keys, and decisions — the things a future turn would
+ * otherwise lose once the raw messages are cleared.
+ */
+export declare function createSummarizer(model: LanguageModel): (messages: Message[]) => Promise<string>;

package/dist/src/session/system-prompt.d.ts

@@ -0,0 +1,38 @@
+import type { Skill } from "@mercury-fw/plugin-types";
+/** The assistant's persona, set by the instance: `identity` opens the system
+ * prompt, `tone` closes it. Either one left out falls back to its default. */
+export type Persona = {
+    identity?: string;
+    tone?: string;
+};
+/** The identity an instance gets when its config sets none. */
+export declare const DEFAULT_PERSONA_IDENTITY = "You are Mercury, an internal assistant.";
+/** The tone an instance gets when its config sets none. */
+export declare const DEFAULT_PERSONA_TONE: string;
+/**
+ * Builds a system prompt that only describes tools actually present in
+ * `tools` (see `src/session/agent-turn.ts` for why a prompt mentioning
+ * an absent tool is a real bug, not a harmless no-op). The persona fills the
+ * first and last slots (see `personaSlot`).
+ */
+export declare function buildSystemPrompt(opts: {
+    pluginFragments: string[];
+    skills: Skill[];
+    multiUserChannel: boolean;
+    persona?: Persona;
+}): string;
+/**
+ * Builds the instance's two system prompts from the same plugins and persona:
+ * `system` for 1:1 channels (the terminal, the HTTP surface) and `chatSystem`
+ * for shared spaces, the only one that carries the multi-user clause — an
+ * operator typing normally must never get a NO_REPLY meant for a shared space.
+ */
+export declare function buildSystemPrompts(opts: {
+    pluginFragments: string[];
+    skills: Skill[];
+    /** Required even when undefined, so a caller can't silently drop the instance's persona. */
+    persona: Persona | undefined;
+}): {
+    system: string;
+    chatSystem: string;
+};

package/dist/src/session/tool-correction-extractor.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Detects, within a single turn's steps, a CLI command call that failed
+ * followed later by one for the same binary that succeeded — a candidate
+ * procedural correction, distinct from `semantic-fact-extractor.ts` (which
+ * is about the user, from `session.messages`) — this is about a *tool*,
+ * from the tool-call trace (`StepInfo`), true for whoever uses that
+ * command next, not just this user. Pairing is deterministic (pure
+ * string/status matching); describing *what* the correction actually was
+ * is delegated to the model, same `generateObject`-with-fixed-schema style
+ * as `semantic-fact-extractor.ts`.
+ *
+ * Wired per-turn (`onStepFinish`, see `index.ts`), not from
+ * `idle-session-cron.ts`'s idle sweep: the tool-call trace for a turn only
+ * exists in memory for the duration of that turn (`tool-log-buffer.ts` is a
+ * 200-entry ring buffer shared across every session — not a reliable place
+ * to reconstruct one turn's trace minutes or hours later).
+ */
+import { type LanguageModel } from "ai";
+import { z } from "zod";
+import type { StepInfo } from "./step-info.ts";
+export declare const ProceduralCorrectionCandidateSchema: z.ZodObject<{
+    topic: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strip>;
+export type ProceduralCorrection = {
+    tool: string;
+    topic: string;
+    value: string;
+};
+type GenerateObjectFn = (params: {
+    model: LanguageModel;
+    output: "array";
+    schema: typeof ProceduralCorrectionCandidateSchema;
+    instructions: string;
+    prompt: string;
+}) => Promise<{
+    object: z.infer<typeof ProceduralCorrectionCandidateSchema>[];
+}>;
+/** Returns a function that extracts candidate procedural corrections from a single turn's steps. */
+export declare function createToolCorrectionExtractor(model: LanguageModel, generateObjectFn?: GenerateObjectFn, deps?: {
+    log?: (msg: string) => void;
+}): (steps: StepInfo[]) => Promise<ProceduralCorrection[]>;
+export {};

package/dist/src/session/tool-log-buffer.d.ts

@@ -0,0 +1,24 @@
+import type { StepInfo } from "./step-info.ts";
+/**
+ * Whatever the provider that ran the turn calls itself — see
+ * `InboundTurn.channel` in `src/router/provider.ts`. Was a closed union
+ * ("terminal" | "google-chat") back when the set of providers was fixed in
+ * this file; widened so a new provider is a new `Provider` implementation,
+ * not an edit here.
+ */
+export type ToolLogChannel = string;
+export type ToolLogEntry = {
+    timestamp: string;
+    channel: ToolLogChannel;
+    sessionKey: string;
+    toolName: string;
+    input: string;
+    output: string;
+};
+export declare function recordStep(channel: ToolLogChannel, sessionKey: string, step: StepInfo): void;
+/** Most recent entries first, optionally restricted to one session. */
+export declare function getToolLog(filter?: {
+    sessionKey?: string;
+}): ToolLogEntry[];
+/** Test-only: clears the module-level buffer so tests don't leak into each other. */
+export declare function resetToolLogForTest(): void;

package/dist/src/session/tool-log-recall-tool.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Model-invocable recall of this conversation's own past tool calls —
+ * same split as `wiki-tools.ts` wrapping plain functions in `tool()`.
+ * Exists because `SessionHistory` (`history.ts`) only ever persists the
+ * final assistant text of a turn, never the tool-call trace: asked to
+ * recall exactly what it ran, the model otherwise has no ground truth in
+ * its own context and reconstructs a plausible-looking (and sometimes
+ * wrong) answer instead of quoting the real one. Backed by
+ * `tool-log-buffer.ts`, filtered to the calling session only — never
+ * another conversation's history.
+ */
+import type { ExecutableTool } from "@mercury-fw/plugin-types";
+export type ToolLogRecallDeps = {
+    sessionKey: string;
+};
+export declare function createToolLogRecallTool(deps: ToolLogRecallDeps): {
+    recall_tool_calls: ExecutableTool;
+};

package/dist/src/session/tool-start-hook.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Wraps every tool's `execute` so `onToolStart` fires the moment a call
+ * actually begins (before its result is ready), instead of the existing
+ * `onStepFinish` visibility (`tool-log.ts`) which only reports after a step
+ * already finished, and `onToolFinish` fires once it settles. Used by
+ * `src/index.ts`'s `buildTools` for every channel — both terminal and
+ * Google Chat always supply a real `onToolStart` (`TurnSink` in
+ * `router/provider.ts`), so both are always wrapped.
+ *
+ * Every wrapped tool's `execute` calls share one `chain` (below), so at
+ * most one tool call runs at a time turn-wide — the AI SDK otherwise runs
+ * a step's tool calls concurrently (`Promise.all`), which this codebase
+ * has never actually relied on; serializing keeps Google Chat's status
+ * card for a given `toolCallId` (see `google-chat-provider.ts`) from ever
+ * having to handle an overlapping in-flight card.
+ */
+import type { Tool } from "ai";
+/**
+ * Describes, in one short user-facing sentence, what a tool call is about to do
+ * — no arguments/queries shown. A tool a plugin contributed carries its own
+ * label via `toolStatusDescribers` (keyed by tool name), so the core never
+ * decides how a plugin's tool reads — it just looks the describer up. The other
+ * tools are core functionality (wiki, grep, memory) and keep their core-coined
+ * labels until they too become internal plugins.
+ */
+export declare function describeToolStart(toolName: string, input: unknown, toolStatusDescribers: Record<string, (input: unknown) => string>): string;
+/**
+ * The actual command/input behind a tool call, for display in a status
+ * card — `describeToolStart`'s label alone doesn't say *what* ran, only
+ * which service. No markdown decoration: Google Chat cards don't render
+ * backticks as monospace, so a plain string reads better. Named per-tool
+ * (path for a file, pattern for a search, ...) rather than dumping the raw
+ * input, since that's what a human actually wants to see; only a genuinely
+ * unmapped/future tool falls back to a bounded JSON dump.
+ */
+export declare function describeToolDetail(toolName: string, input: unknown): string;
+export type { ToolOutcome } from "@mercury-fw/channel-types";
+import type { ToolOutcome } from "@mercury-fw/channel-types";
+/**
+ * Every tool in this codebase returns a uniform `{ok: true, ...}` /
+ * `{ok: false, error, ...}` shape (confirmed across `wiki-tools.ts`,
+ * `tool-log-recall-tool.ts`, `cli-tool.ts`), with `cli-tool.ts`'s
+ * confirm-required staging additionally setting `pendingConfirmation: true`
+ * without having actually run the command yet — so this classifier works
+ * for any tool without per-tool special-casing. Defaults to `"success"` for
+ * an unrecognized result shape; nothing returned by a tool today hits that
+ * branch.
+ */
+export declare function classifyToolResult(result: unknown): ToolOutcome;
+/**
+ * Wraps every tool's `execute` to call `onToolStart` first, then run the
+ * original, then `onToolFinish` once it settles. `chain` serializes every
+ * wrapped tool sharing this one `withToolStartHook` call (i.e. one turn's
+ * worth of tools, since `buildTools` builds fresh tools per turn) — see
+ * this file's header comment for why.
+ */
+export declare function withToolStartHook(tools: Record<string, Tool>, onToolStart: (label: string, detail?: string, toolCallId?: string) => void, toolStatusDescribers: Record<string, (input: unknown) => string>, onToolFinish?: (toolCallId: string, outcome: ToolOutcome) => void): Record<string, Tool>;

package/dist/src/tools/display-store.d.ts

@@ -0,0 +1,36 @@
+/**
+ * In-memory staging area for the user-facing `display` artifacts a tool
+ * produces (see `ToolDisplay` and the formatter decorator), decoupling
+ * *producing* an artifact from *showing* it. A tool `stash`es its already-
+ * rendered artifact here and gets back a short `ref`; the model, and only
+ * the model, decides whether to actually surface it by calling the
+ * `present` tool (see `present-tool.ts`), which marks the ref via
+ * `surface`. At finalize the turn runner appends only what
+ * `takeSurfaced` returns — the artifacts the model explicitly asked to
+ * show — never the whole set unconditionally. The worst case becomes
+ * omission (the user says "show me"), never a garbled or force-appended
+ * list.
+ *
+ * Scoped by `sessionKey`, exactly like `confirmation-store.ts`: a ref
+ * minted for one session (terminal, or a given Google Chat space+sender)
+ * can't be surfaced by another. The store is created once and shared
+ * across turns, so a ref stays valid (until its TTL) for a later
+ * "show me that list again" follow-up — session-scoped, not turn-scoped.
+ */
+export type DisplayStore = {
+    /** Stashes `artifact` for `sessionKey` and returns a fresh ref. */
+    stash(sessionKey: string, artifact: string): string;
+    /** Marks `ref` to be shown at finalize. Returns `false` if it doesn't
+     * exist, belongs to a different session, or has expired. */
+    surface(sessionKey: string, ref: string): boolean;
+    /** The artifacts surfaced for `sessionKey`, in stash order. Consumes the
+     * surfaced flag (so the same artifact isn't re-appended on a later turn
+     * unless `surface` is called again) but keeps the entry until its TTL,
+     * so a still-valid ref can be surfaced again across turns. */
+    takeSurfaced(sessionKey: string): string[];
+};
+export declare function createDisplayStore(opts?: {
+    now?: () => number;
+    ttlMs?: number;
+    refFn?: () => string;
+}): DisplayStore;

package/dist/src/tools/present-tool.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The `present` tool: the model's explicit "show this artifact to the user"
+ * action. A tool that produced a user-facing `display` stashed it in the
+ * `DisplayStore` (see `display-store.ts`) and returned a `ref` on the model
+ * channel; the model never sees the rendered content, only the ref. Calling
+ * `present(ref)` marks that ref to be appended to the reply at finalize.
+ *
+ * This is what shrinks the model's job from "format this list correctly"
+ * (which small models garble) to "show this list? yes/no": the artifact is
+ * always the deterministic one the formatter produced, and the model only
+ * decides whether it appears. If the model never calls `present`, nothing is
+ * shown — the right outcome for a "how many are open?" question answered in
+ * prose. Scoped to the calling session, so it can only surface its own refs.
+ */
+import type { ExecutableTool } from "@mercury-fw/plugin-types";
+import type { DisplayStore } from "./display-store.ts";
+export type PresentToolDeps = {
+    sessionKey: string;
+    store: DisplayStore;
+};
+export declare function createPresentTool(deps: PresentToolDeps): {
+    present: ExecutableTool;
+};

package/dist/src/wiki/frontmatter-schema.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Frontmatter schema for wiki notes, based on Open Knowledge
+ * Format (OKF — https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing):
+ * `type` is the only field OKF mandates; `source`/`confidence`/
+ * `derived_from`/`last_reviewed` are Mercury-specific extensions, the
+ * kind OKF explicitly leaves to the producer. `curated` and `inferred`
+ * are validated as separate shapes (discriminated on `type`) because
+ * only `inferred` notes carry provenance — a curated doc has no
+ * meaningful `confidence` or `derived_from`.
+ */
+import { z } from "zod";
+export declare const CuratedFrontmatterSchema: z.ZodObject<{
+    type: z.ZodLiteral<"curated">;
+    author: z.ZodOptional<z.ZodString>;
+    last_updated: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const InferredFrontmatterSchema: z.ZodObject<{
+    type: z.ZodLiteral<"inferred">;
+    source: z.ZodLiteral<"agent">;
+    confidence: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>;
+    derived_from: z.ZodArray<z.ZodString>;
+    last_reviewed: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * A fourth category: the lifecycle of one confirm-required action, from
+ * staging through its eventual resolution — a deterministic instruction
+ * the user explicitly approved via the confirmation-token mechanism,
+ * never an autonomous LLM judgment call. Tracks a specific CLI action's
+ * own token, written once when staged (`status: "pending"`) and
+ * overwritten in place once resolved (`"confirmed"`/`"failed"`). Lives
+ * outside `inferred/users/<userId>/` (see `wiki-read.ts`'s
+ * `allowedRoots`) so it's structurally invisible to the model's own
+ * `list_files`/`grep` — reachable only via the narrow `resolve_reference`
+ * tool given the exact token (see `wiki-tools.ts`), never by browsing.
+ */
+export declare const ConfirmationFrontmatterSchema: z.ZodObject<{
+    type: z.ZodLiteral<"confirmation">;
+    status: z.ZodEnum<{
+        pending: "pending";
+        failed: "failed";
+        confirmed: "confirmed";
+    }>;
+    requested_at: z.ZodString;
+    resolved_at: z.ZodNullable<z.ZodString>;
+    command: z.ZodString;
+}, z.core.$strip>;
+export type CuratedFrontmatter = z.infer<typeof CuratedFrontmatterSchema>;
+export type InferredFrontmatter = z.infer<typeof InferredFrontmatterSchema>;
+export type ConfirmationFrontmatter = z.infer<typeof ConfirmationFrontmatterSchema>;

package/dist/src/wiki/index-entry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Deterministic index.md line management. Turns "this curated doc, with
+ * this description" into the exact `[[wikilink]]` line format
+ * `orphan-detector.ts`'s wikilink check recognizes — instead of trusting
+ * the model to freely author (and correctly reproduce, on every edit) the
+ * whole file's syntax by hand, which is what `write_index` used to do and
+ * how a doc could end up with an index.md line that still isn't
+ * recognized as a reference to it.
+ */
+/** Accepts any of "curated/x/y.md", "x/y.md", or "x/y" and normalizes to "x/y" — the form `[[wikilink]]`s use. */
+export declare function normalizeIndexKey(path: string): string;
+/** Adds a line for `key`, or replaces its existing one in place — never duplicates an entry. */
+export declare function upsertIndexEntry(content: string, key: string, description: string): string;
+/** Removes `key`'s line if present; no-op otherwise. */
+export declare function removeIndexEntry(content: string, key: string): string;

package/dist/src/wiki/orphan-detector.d.ts

@@ -0,0 +1 @@
+export declare function findOrphanCuratedDocs(vaultPath: string): Promise<string[]>;

package/dist/src/wiki/self-review-runner.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The nightly self-review job's three LLM passes. Each is a fresh,
+ * stateless `generateText` call — never a persisted conversation history
+ * like `agent-turn.ts`'s `runTurn` — so nothing carries over between
+ * passes or between nights except what actually landed on disk. Running
+ * all four checks as one giant multi-step call would let tool-call
+ * context accumulate across unrelated jobs at once; splitting into three
+ * independent calls keeps each one's context bounded to its own job.
+ *
+ * `generateText` comes from `ai-sdk-ollama`, matching `agent-turn.ts` —
+ * plain `ai`'s version is documented there to return empty text after a
+ * tool call on this codebase's Ollama setup, which applies here too
+ * since every pass uses tools.
+ */
+import { type LanguageModel, type Tool } from "ai";
+import type { Message } from "../session/history.ts";
+/** Empirical, tuned later — generous headroom for reading several docs and
+ * writing/deleting within one pass, well above a conversational turn's. */
+export declare const SELF_REVIEW_STEP_COUNT = 15;
+type GenerateTextFn = (params: {
+    model: LanguageModel;
+    messages: Message[];
+    tools: Record<string, Tool>;
+    instructions: string;
+}) => Promise<{
+    text: string;
+}>;
+export type RawTriagePassDeps = {
+    vaultPath: string;
+    model: LanguageModel;
+    rawEntries: string[];
+    generateTextFn?: GenerateTextFn;
+};
+export declare function runRawTriagePass(deps: RawTriagePassDeps): Promise<void>;
+export type IndexAndOrphanPassDeps = {
+    vaultPath: string;
+    model: LanguageModel;
+    orphans: string[];
+    generateTextFn?: GenerateTextFn;
+};
+export declare function runIndexAndOrphanPass(deps: IndexAndOrphanPassDeps): Promise<void>;
+export type ContradictionCheckPassDeps = {
+    vaultPath: string;
+    model: LanguageModel;
+    generateTextFn?: GenerateTextFn;
+};
+export declare function runContradictionCheckPass(deps: ContradictionCheckPassDeps): Promise<void>;
+export {};

package/dist/src/wiki/self-review-tools.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The nightly self-review job's own tool set — distinct from
+ * `wiki-tools.ts` (the model-invocable tools a normal conversation gets),
+ * same reasoning already applied to `writeInferredNote` never being
+ * wired into those: this is a separate trust context (a stateless admin
+ * batch job, not a live conversation), scoped via `selfReviewRoots`
+ * (curated/ + raw/, never inferred/ — reserved for deterministic,
+ * mechanically-written notes, not an LLM's own judgment call) and with
+ * capabilities no conversational tool
+ * has (deleting an entry, updating/removing an index.md entry — the
+ * model supplies a doc path and a description, never the file's raw text,
+ * so an update can't get the `[[wikilink]]` format wrong).
+ *
+ * All three nightly sub-passes (`self-review-runner.ts`) share this
+ * exact tool set — they differ only in system prompt and pre-computed
+ * input data, not in which tools they can call.
+ */
+import type { ExecutableTool } from "@mercury-fw/plugin-types";
+export type SelfReviewToolsDeps = {
+    vaultPath: string;
+};
+export declare function createSelfReviewTools(deps: SelfReviewToolsDeps): Record<"list_files" | "read_file" | "grep" | "write_curated" | "update_index_entry" | "remove_index_entry" | "delete_raw" | "delete_curated", ExecutableTool>;

package/dist/src/wiki/vault-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/src/wiki/vault-init.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Creates the vault's curated/inferred subdirectories and git-inits the
+ * vault if it isn't already a git repo. Safe to call on every startup:
+ * pre-existing directories/content are left untouched, and re-running
+ * `git init` on an already-initialized repo is a no-op.
+ */
+export declare function initVault(vaultPath: string): Promise<void>;

package/dist/src/wiki/wiki-note.d.ts

@@ -0,0 +1,62 @@
+/** Writes a curated doc at `curated/<relativePath>` (e.g. "standards/jira-fields.md"). */
+export declare function writeCuratedNote(vaultPath: string, relativePath: string, fields: {
+    author?: string;
+    last_updated?: string;
+}, body: string): Promise<void>;
+/** Writes a semantic note at `inferred/users/<userId>/<topic>.md`. */
+export declare function writeInferredNote(vaultPath: string, userId: string, topic: string, fields: {
+    confidence: "low" | "medium" | "high";
+    derived_from: string[];
+    last_reviewed: string | null;
+}, body: string): Promise<void>;
+/**
+ * Writes a deterministically-promoted procedural correction at
+ * `curated/standards/<tool>-<topic>.md` — one file per correction, not
+ * merged into a single per-tool doc (that would need safe section-level
+ * merging into whatever a human already wrote by hand there, e.g.
+ * `curated/standards/jira-cli.md`, deliberately out of scope here).
+ * Frontmatter is still `type: inferred, source: agent` (same provenance
+ * shape as `writeInferredNote` — probabilistic, consolidation-derived, not
+ * human-authored) even though the file lives under `curated/`: the path
+ * controls read visibility (every user's wiki tools expose `curated/`,
+ * only their own `inferred/users/<userId>/`), not authorship.
+ */
+export declare function writeToolCorrectionNote(vaultPath: string, tool: string, topic: string, fields: {
+    confidence: "low" | "medium" | "high";
+    derived_from: string[];
+    last_reviewed: string | null;
+}, body: string): Promise<void>;
+/**
+ * Writes (or overwrites) the deterministic lifecycle record for one
+ * confirm-required action at `inferred/confirmations/<encoded userId>/<token>.md`
+ * — see `ConfirmationFrontmatterSchema`'s own doc comment for why this
+ * subtree, not `inferred/users/<userId>/`. Called twice per action: once
+ * at staging (`status: "pending"`, `resolvedAt: null`), once at resolution
+ * (`"confirmed"`/`"failed"`, `resolvedAt` set) — the whole-file replace
+ * every writer here already does, not a partial update.
+ */
+export declare function writeConfirmationNote(vaultPath: string, userId: string, token: string, fields: {
+    status: "pending" | "confirmed" | "failed";
+    requestedAt: string;
+    resolvedAt: string | null;
+    command: string;
+}): Promise<void>;
+/** Writes a raw/ inbox entry verbatim at `raw/<relativePath>` — no
+ * frontmatter, content is whatever a human pasted as-is (see
+ * `vault-cli.ts`'s `write-raw`). Never called during a normal
+ * conversation; only the self-review job (`self-review-tools.ts`) reads
+ * this back to triage it into `curated/`. */
+export declare function writeRawEntry(vaultPath: string, relativePath: string, body: string): Promise<void>;
+/** Overwrites `index.md` at the vault root with `content` verbatim — no
+ * frontmatter, it's a generated Karpathy-pattern index, not a note.
+ * Whole-file replace: the caller (self-review) computes the full new
+ * text and passes the complete replacement, same as every writer here. */
+export declare function writeIndexFile(vaultPath: string, content: string): Promise<void>;
+/** Deletes a raw/ entry once self-review has resolved it (merged,
+ * promoted, or discarded). */
+export declare function deleteRawEntry(vaultPath: string, relativePath: string): Promise<void>;
+/** Deletes a curated/ doc — used only by the self-review job to retire a
+ * redundant/superseded doc (never during a normal conversation). Callers
+ * should also remove the doc's `index.md` line in the same pass, so a
+ * deletion doesn't leave a dangling index reference. */
+export declare function deleteCuratedEntry(vaultPath: string, relativePath: string): Promise<void>;

package/dist/src/wiki/wiki-read.d.ts

@@ -0,0 +1,27 @@
+/** curated/ + raw/ only — never inferred/, for the nightly self-review job.
+ * A distinct trust boundary from a per-user conversation's `allowedRoots`
+ * (which trades curated/ for one user's own inferred/ instead of raw/):
+ * inferred/ is meant to hold only deterministic, mechanically-written
+ * notes (never an LLM's own judgment call about what to remember) —
+ * off-limits here for the same reason it's off-limits to regular
+ * conversations, not a special exception for self-review. */
+export declare function selfReviewRoots(vaultPath: string): string[];
+/** Lists every `.md` file under `roots`. */
+export declare function listWikiFilesInRoots(vaultPath: string, roots: string[]): Promise<string[]>;
+/** Lists every `.md` file visible to `userId`: all of curated/, plus only their own inferred/users/<userId>/. */
+export declare function listWikiFiles(vaultPath: string, userId: string): Promise<string[]>;
+/** Reads a single wiki file. Throws if `relativePath` falls outside `roots`. */
+export declare function readWikiFileInRoots(vaultPath: string, roots: string[], relativePath: string): Promise<string>;
+/** Reads a single wiki file. Throws if `relativePath` falls outside the caller's allowed scope. */
+export declare function readWikiFile(vaultPath: string, userId: string, relativePath: string): Promise<string>;
+export type WikiGrepMatch = {
+    path: string;
+    line: number;
+    text: string;
+};
+/** Searches every file under `roots` for `pattern` (a regular expression), line by line. */
+export declare function grepWikiInRoots(vaultPath: string, roots: string[], pattern: string): Promise<WikiGrepMatch[]>;
+/** Searches every file visible to `userId` for `pattern` (a regular expression), line by line. */
+export declare function grepWiki(vaultPath: string, userId: string, pattern: string): Promise<WikiGrepMatch[]>;
+/** Reads index.md at the vault root; empty string if it doesn't exist yet (a brand-new vault, or one where self-review hasn't created it). */
+export declare function readIndexFile(vaultPath: string): Promise<string>;

package/dist/src/wiki/wiki-tools.d.ts

@@ -0,0 +1,7 @@
+import type { ExecutableTool } from "@mercury-fw/plugin-types";
+export type WikiToolsDeps = {
+    vaultPath: string;
+    userId: string;
+};
+/** Builds the four wiki tools scoped to `deps.userId` (curated/ fully, only their own inferred/users/<userId>/). */
+export declare function createWikiTools(deps: WikiToolsDeps): Record<"list_files" | "read_file" | "write_file" | "grep" | "resolve_reference", ExecutableTool>;

package/index.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/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@mercury-fw/core",
+  "version": "0.25.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucabro81/mercury-fw.git",
+    "directory": "packages/libs/core"
+  },
+  "files": [
+    "*.ts",
+    "dist",
+    "src",
+    "CHANGELOG.md",
+    "!**/*.test.ts",
+    "!**/__fixtures__"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "mercury-fw-source": "./index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./index.ts"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@mercury-fw/channel-types": "0.25.0",
+    "@mercury-fw/cli-engine": "0.25.0",
+    "@mercury-fw/confirm-engine": "0.25.0",
+    "@mercury-fw/plugin-types": "0.25.0",
+    "@qdrant/js-client-rest": "^1.19.0",
+    "ai": "^7.0.77",
+    "ai-sdk-ollama": "^4.2.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@mercury-fw/typescript-config": "*",
+    "@types/bun": "^1.4.0",
+    "typescript": "^6.0.3"
+  }
+}