bantamkit-mcp 0.29.2 → 0.31.0

package/dist/mcp/status.js

@@ -33,6 +33,8 @@ import { statSync } from 'node:fs';
 import { join } from 'node:path';
 import { AssetNotFound, assetsRoot } from '../assets.js';
 import { Memory } from '../memory/component.js';
+import { INDEX_PRESSURE_PERCENT } from '../memory/store.js';
+import { Undetermined, currentInstall, originStat } from './identity.js';
 /**
  * The tool AND the prompt answer to this one name. Deliberately the same word: the operator
  * who read `bantamkit_status` in a footer must find it in their prompt menu without
@@ -68,14 +70,13 @@ export const STATUS_PROMPT_TAIL = 'Show me that report as it stands. If it says
 export const SERVED_PROMPTS = 1;
 export const SERVED_RESOURCE_TEMPLATES = 2;
 /**
- * Percent of the index budget that has to be SPENT before the store is called degraded.
- *
- * 90 and not 100 because the useful moment is before the refusal, not after it: at 100% the
- * next `memory_save` has already failed and the operator has already seen the error. An
- * INTEGER percent, compared by cross-multiplication below, so the two runtimes cannot land
- * on opposite sides of the line through a float they rounded differently.
+ * `INDEX_PRESSURE_PERCENT` is re-exported here, where it used to be DEFINED, so that
+ * `import { INDEX_PRESSURE_PERCENT } from './mcp/status.js'` keeps resolving. It moved down
+ * to `memory/store.ts` in job46 (J46-5, mirroring the reference's J46-4):
+ * `MemoryStore.compact` is the remedy the sentence below names, and it cannot clear a warning
+ * whose line it cannot see. The comment that says why the number is 90 moved with it.
  */
-export const INDEX_PRESSURE_PERCENT = 90;
+export { INDEX_PRESSURE_PERCENT };
 /** `1 prompt` / `2 prompts`. Spelled once so the two runtimes cannot disagree twice. */
 export function plural(count, word) {
     return count === 1 ? `${count} ${word}` : `${count} ${word}s`;
@@ -221,6 +222,20 @@ export function unreadableLayerCondition(memory) {
  * not a divergence and is not fixed here; it is registered in `docs/porting.md`. The sentence
  * says "archive or shorten facts", which is what the operator has to do either way.
  *
+ * AMENDMENT (job46, J46-5): THE PARAGRAPH ABOVE IS A RECORD OF A DEFECT THAT IS NOW CLOSED,
+ * and it is left standing because it is the measurement that motivated the fix. What it says
+ * was true until this job: the band was real, and on this machine's own project store
+ * (101 facts, index.md 21819 bytes of a 24000-byte budget = 90.91%, largest index line 361
+ * bytes so the old target was 23639 = 98.50%) `compact()` answered `archived: []` with this
+ * very sentence on screen. What has changed is the second half — "is not fixed here". It is
+ * fixed now, in the layer that owns it: `MemoryStore.compact`'s default `reserve` is measured
+ * from `undegradedIndexCeiling(budget)` rather than from `budget`, so running the command
+ * this sentence names clears the condition this sentence reports. Both runtimes moved in the
+ * same job (the reference in `87cc1f7`), because a band that closed on one side only would be
+ * the divergence the paragraph above correctly said this was not. The register entry's own
+ * closure is not written here — that is a `docs/porting.md` edit, and it waits on a
+ * conformance case comparing the two answers.
+ *
  * THIS SENTENCE IS FOR THE OPERATOR; THE MODEL HAS ITS OWN REMEDY. Since job42 the model
  * can call `memory_compact` (the ninth served tool) when a save is actually refused, and
  * the refused-budget reply in `memory/component.ts` names it. That does not change this
@@ -261,13 +276,71 @@ export function eventLogCondition(log) {
             'whether its directory is writable.',
     };
 }
+/**
+ * This install came from a path on this machine, and that path is gone.
+ *
+ * THE ONE CONDITION THAT NAMES A PATH, and the exception is deliberate. Every other sentence
+ * here refuses one because `assetsRoot()` resolves differently in the two runtimes by
+ * construction, so a path would be an uncomparable value bought for nothing. This path is not
+ * the server's own location — it is the origin THE INSTALLER WROTE DOWN, it is the entire
+ * actionable content of the finding (AS-7's measured case is a tarball under a
+ * `/private/tmp/.../scratchpad` that no longer exists), and a sentence saying "something is
+ * missing" without saying what would be a sentence nobody can act on.
+ *
+ * THE REMEDY IS THE ONE THAT ACTUALLY MOVES SOMETHING. J46-4 spent a unit removing a condition
+ * whose remedy exited 0 having changed nothing, and this is exactly the shape that invites
+ * another: `npm update` where a dangling `file:` install lives is a no-op BY CONSTRUCTION. So
+ * the sentence sends the reader at a reinstall BY NAME from a registry, which replaces the
+ * install rather than trying to refresh it in place. `bantamkit` is the PRODUCT name and is
+ * copied verbatim from the reference — it is not the npm package id, and turning it into one
+ * is how `git_commit` diverged on a noun.
+ *
+ * THE DERIVED HALF IS MEMOISED AND THIS HALF IS NOT: the shape cannot change under a running
+ * process, the path's existence can, and it is the one that has to be read now.
+ */
+export function installSourceCondition(install) {
+    if (install === null || install.source === null)
+        return null;
+    // `present: null` is a check that could not be made, and the reference reports no condition
+    // for one either: an origin nobody may stat is not, on that evidence, an origin that is gone.
+    if (originStat(install.source).present !== false)
+        return null;
+    return {
+        key: 'install-source-missing',
+        sentence: `this server was installed from ${install.source}, which no longer exists, so nothing ` +
+            'can be refreshed in place there — reinstall bantamkit by name from a package registry ' +
+            'and restart the server.',
+    };
+}
+/**
+ * The shape, or nothing. A shape that could not be derived is a REPORTED gap.
+ *
+ * `buildIdentity` is where that gap is named, with its reason. It is not a degraded condition:
+ * an install this code cannot classify is not, on that evidence, an install that is broken, and
+ * a footer on every tool call saying otherwise would be the noise `degradedNotice` exists to
+ * avoid.
+ */
+function currentInstallOrNull() {
+    try {
+        return currentInstall();
+    }
+    catch (e) {
+        if (!(e instanceof Undetermined))
+            throw e;
+        return null;
+    }
+}
 /**
  * Everything wrong right now, worst first. An empty array means healthy.
  *
  * ORDER IS SEVERITY AND IT IS LOAD-BEARING, because the footer shows the first one: a pack
  * that vanished breaks every asset-backed surface; an unreadable layer makes recall ANSWER
  * WRONGLY rather than fail; a full index refuses the next save; a broken event log costs
- * diagnostics only.
+ * diagnostics only; and a dangling install origin costs nothing AT ALL right now — the server
+ * is serving correctly, and what is broken is the next attempt to update it. That is why it is
+ * last despite being the one that went unnoticed for five releases
+ * (`docs/roadmap-agent-stack.md` AS-7): severity here is what is failing, not what has been
+ * failing longest.
  *
  * EVERY CONDITION IS OBSERVED, NOT INFERRED — no heartbeat, no timer, no last-seen timestamp.
  * Each one is a state a test can construct and then watch this report: delete the pack, make a
@@ -276,8 +349,10 @@ export function eventLogCondition(log) {
  * claimed.
  *
  * THE COST, because this runs on every tool call: one `stat` for the index, one `stat` for the
- * pack, one directory listing per memory layer (two to four), and a field read for the log. No
- * fact file is opened and no index is parsed.
+ * pack, one directory listing per memory layer (two to four), a field read for the log, and one
+ * `stat` for the install origin. No fact file is opened, no index is parsed, and
+ * `node_modules` is NOT walked for a hidden lockfile — `currentInstall` does that once per
+ * process, because the bytes that were imported cannot change under a running one.
  */
 export function degradedConditions(memory, log) {
     return [
@@ -285,6 +360,7 @@ export function degradedConditions(memory, log) {
         unreadableLayerCondition(memory),
         indexPressureCondition(memory),
         eventLogCondition(log),
+        installSourceCondition(currentInstallOrNull()),
     ].filter((condition) => condition !== null);
 }
 /**

package/dist/memory/cli.js

@@ -4,7 +4,7 @@
  *
  * `docs/memory.md` states, as a design decision, that `lint`, `archived` and `restore`
  * are **not** agent tools — "lifecycle is an operator decision, not a model decision" —
- * and the eleven-tool surface holds to it; `compact` is the one exception since job42
+ * and the fourteen-tool surface holds to it; `compact` is the one exception since job42
  * (`memory_compact`, the on-refusal path the model reaches itself). `runtime-py` made that
  * position coherent in August 2026 by giving the operator `python -m bantamkit.memory`.
  * `runtime-ts` did not. MEASURED 2026-08-24 before this file existed: `node dist/cli.js -h`

package/dist/memory/component.d.ts

@@ -1,5 +1,6 @@
 import { type StoreBinding } from './layers.js';
 import { MemoryStore } from './store.js';
+import type { DreamResult } from './dream.js';
 /**
  * The model's spelling adapted to the store's contract: lowercase, `_`/space -> `-`.
  *
@@ -97,6 +98,30 @@ export interface RecallOutcome {
     readonly source: string | null;
     readonly unreadable: number;
 }
+/**
+ * What `dream` DID, beside the sentence it says about it.
+ *
+ * The same seam as `SaveOutcome`, `RecallOutcome` and `CompactOutcome`: `status` is read off
+ * a decision the pass already made — `DreamResult.applied`, `.overBudget`, `.changes` — and
+ * never off the reply. `result` carries the whole diff for a caller that wants the numbers
+ * rather than the prose.
+ *
+ * `status` is one of `consolidated`, `previewed`, `nothing-to-consolidate`,
+ * `refused-budget`, `no-profile-layer`.
+ */
+export interface DreamOutcome {
+    readonly reply: string;
+    readonly status: string;
+    readonly dryRun: boolean;
+    readonly merged: number;
+    readonly consumed: number;
+    readonly absolutised: number;
+    readonly superseded: number;
+    readonly indexBefore: number;
+    readonly indexAfter: number;
+    readonly budget: number;
+    readonly result: DreamResult | null;
+}
 export declare class Memory {
     readonly store: MemoryStore;
     readonly k: number;
@@ -140,7 +165,7 @@ export declare class Memory {
      * fact. The floor is the operator's configured default, not a constant, so a consumer who
      * really wants top-1 says so once at construction.
      */
-    recall(query: string, k?: number | null): string;
+    recall(query: string, k?: number | null, minRatio?: number): string;
     /**
      * `recall`, carrying the walk it performed as numbers rather than as prose.
      *
@@ -157,8 +182,18 @@ export declare class Memory {
      * refuses to list contributes nothing and raises the `unreadable` count instead of being
      * scored as empty; that distinction is the whole subject of `nothingToReport` below and
      * must not be undone here.
+     *
+     * `minRatio` (roadmap #6) rides through to every layer's `MemoryStore.recall` unchanged,
+     * so the gate is measured against EACH LAYER's own best score and never across layers: a
+     * profile fact does not have to out-score the project store's top hit to be admitted,
+     * because the two stores are answering as two stores. Its default is
+     * `RECALL_MIN_SCORE_RATIO` = 0.0, which keeps every fact `recall` was going to return,
+     * and nothing on the tool path passes anything else today. A ratio outside `[0.0, 1.0]`
+     * raises out of the FIRST layer, which is the writable project store, so it surfaces as
+     * the error it is rather than as an `unreadable` count — the read-only-layer `catch`
+     * below would otherwise file a caller's bad argument as a corrupt grant.
      */
-    recallOutcome(query: string, k?: number | null): RecallOutcome;
+    recallOutcome(query: string, k?: number | null, minRatio?: number): RecallOutcome;
     /**
      * Archive the stalest facts until a fact as large as the biggest one kept will fit.
      *
@@ -179,6 +214,42 @@ export declare class Memory {
      * is — `MemoryStore.compact` builds it with `pyJoin`.
      */
     compactOutcome(reserve?: number | null): CompactOutcome;
+    /** Consolidate what the project and profile layers hold under the same name. */
+    dream(dryRun?: boolean): string;
+    /**
+     * `dream`, with the decision it took carried beside the sentence it wrote.
+     *
+     * ONLY THE PROFILE LAYER IS CONSUMED. `layers` also carries read-only GRANTS, and a grant
+     * is another operator's store: consolidating a fact out of one is not this person's move
+     * to make, so `dream` never looks at them. The label is matched exactly (`profile`), never
+     * by prefix, because a grant is labelled `extra:<name>` and a prefix match on a directory
+     * called `profile-something` would reach one.
+     *
+     * A `Memory` constructed directly — not through `layered` — has no profile layer at all,
+     * and that is `no-profile-layer` rather than an error: there is nothing to consolidate
+     * ACROSS when only one layer is bound.
+     *
+     * `dryRun` DEFAULTS TO TRUE. This is the only op in this component that writes into the
+     * user's home directory, and it is the only one whose effect is machine-wide: a fact
+     * archived out of the profile store stops answering for every other project on this
+     * machine that has no store of its own. A destructive consolidation nobody can preview is
+     * not shippable, so the safe call is the short one.
+     */
+    dreamOutcome(dryRun?: boolean): DreamOutcome;
+    /**
+     * The whole diff as prose: what merged, what was dated, what moved, what it cost.
+     *
+     * THE HONESTY SENTENCE AT THE END IS NOT DECORATION. Row 5 was planned as a token saving
+     * and J45-1 measured that it is not one: the profile store has no `index.md` on disk, its
+     * index is derived at read time, and nothing loads it into a prompt — so deduplicating it
+     * frees approximately zero prompt bytes. The value is that one ruling now has one copy
+     * instead of two that can disagree, and the reply says which of those two things the
+     * operator just bought.
+     *
+     * `formatFixed3` and not `toFixed(3)` for the two similarity figures: see the header of
+     * `dream.ts`. CPython's `.3f` rounds ties to EVEN and they are reachable.
+     */
+    private static dreamReply;
     /**
      * `(index bytes, budget)` for the writable project store; bytes may be `null`.
      *

package/dist/memory/component.js

@@ -29,7 +29,8 @@ import { BantamError } from '../errors.js';
 import { pyStrip } from './factfile.js';
 import { countFacts, loadGrants, MEMORY_DIR_ENV, PROJECT_STORE, resolveProjectStore, } from './layers.js';
 import { pyHome, pyJoin, pyName, pyParent, pyResolve, PyOSError, PyUnicodeDecodeError } from './pyfs.js';
-import { DEFAULT_INDEX_BUDGET, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyHashKey, pyText, } from './store.js';
+import { DEFAULT_INDEX_BUDGET, MemoryBudgetExceeded, MemoryStore, MemoryValidationError, pyHashKey, pyText, RECALL_MIN_SCORE_RATIO, } from './store.js';
+import { dream as runDream, formatFixed3, SUPERSEDED_HEADING } from './dream.js';
 /**
  * The model's spelling adapted to the store's contract: lowercase, `_`/space -> `-`.
  *
@@ -177,8 +178,8 @@ export class Memory {
      * fact. The floor is the operator's configured default, not a constant, so a consumer who
      * really wants top-1 says so once at construction.
      */
-    recall(query, k = null) {
-        return this.recallOutcome(query, k).reply;
+    recall(query, k = null, minRatio = RECALL_MIN_SCORE_RATIO) {
+        return this.recallOutcome(query, k, minRatio).reply;
     }
     /**
      * `recall`, carrying the walk it performed as numbers rather than as prose.
@@ -196,8 +197,18 @@ export class Memory {
      * refuses to list contributes nothing and raises the `unreadable` count instead of being
      * scored as empty; that distinction is the whole subject of `nothingToReport` below and
      * must not be undone here.
+     *
+     * `minRatio` (roadmap #6) rides through to every layer's `MemoryStore.recall` unchanged,
+     * so the gate is measured against EACH LAYER's own best score and never across layers: a
+     * profile fact does not have to out-score the project store's top hit to be admitted,
+     * because the two stores are answering as two stores. Its default is
+     * `RECALL_MIN_SCORE_RATIO` = 0.0, which keeps every fact `recall` was going to return,
+     * and nothing on the tool path passes anything else today. A ratio outside `[0.0, 1.0]`
+     * raises out of the FIRST layer, which is the writable project store, so it surfaces as
+     * the error it is rather than as an `unreadable` count — the read-only-layer `catch`
+     * below would otherwise file a caller's bad argument as a corrupt grant.
      */
-    recallOutcome(query, k = null) {
+    recallOutcome(query, k = null, minRatio = RECALL_MIN_SCORE_RATIO) {
         const budget = k === null ? this.k : Math.max(k, this.k);
         const picked = [];
         const seen = new Set();
@@ -210,7 +221,7 @@ export class Memory {
             reached += 1;
             let facts;
             try {
-                facts = store.recall(query, budget, writable);
+                facts = store.recall(query, budget, writable, minRatio);
             }
             catch (e) {
                 if (!(e instanceof BantamError || e instanceof PyOSError || e instanceof PyUnicodeDecodeError)) {
@@ -312,6 +323,147 @@ export class Memory {
             budget: result.budget,
         };
     }
+    /** Consolidate what the project and profile layers hold under the same name. */
+    dream(dryRun = true) {
+        return this.dreamOutcome(dryRun).reply;
+    }
+    /**
+     * `dream`, with the decision it took carried beside the sentence it wrote.
+     *
+     * ONLY THE PROFILE LAYER IS CONSUMED. `layers` also carries read-only GRANTS, and a grant
+     * is another operator's store: consolidating a fact out of one is not this person's move
+     * to make, so `dream` never looks at them. The label is matched exactly (`profile`), never
+     * by prefix, because a grant is labelled `extra:<name>` and a prefix match on a directory
+     * called `profile-something` would reach one.
+     *
+     * A `Memory` constructed directly — not through `layered` — has no profile layer at all,
+     * and that is `no-profile-layer` rather than an error: there is nothing to consolidate
+     * ACROSS when only one layer is bound.
+     *
+     * `dryRun` DEFAULTS TO TRUE. This is the only op in this component that writes into the
+     * user's home directory, and it is the only one whose effect is machine-wide: a fact
+     * archived out of the profile store stops answering for every other project on this
+     * machine that has no store of its own. A destructive consolidation nobody can preview is
+     * not shippable, so the safe call is the short one.
+     */
+    dreamOutcome(dryRun = true) {
+        const profile = this.layers.find(([label]) => label === 'profile')?.[1] ?? null;
+        if (profile === null) {
+            return {
+                reply: 'nothing to consolidate: no profile layer is bound, so the project ' +
+                    `store ${this.store.root} is the only layer there is.`,
+                status: 'no-profile-layer',
+                dryRun,
+                merged: 0,
+                consumed: 0,
+                absolutised: 0,
+                superseded: 0,
+                indexBefore: 0,
+                indexAfter: 0,
+                budget: this.store.indexBudget,
+                result: null,
+            };
+        }
+        const result = runDream(this.store, profile, dryRun);
+        let status;
+        if (result.overBudget)
+            status = 'refused-budget';
+        else if (result.changes === 0)
+            status = 'nothing-to-consolidate';
+        else if (result.applied)
+            status = 'consolidated';
+        else
+            status = 'previewed';
+        return {
+            reply: Memory.dreamReply(status, result),
+            status,
+            dryRun: result.dryRun,
+            merged: result.merged.length,
+            consumed: result.consumed.length,
+            absolutised: result.absolutised.length,
+            superseded: result.superseded.length,
+            indexBefore: result.indexBefore,
+            indexAfter: result.indexAfter,
+            budget: result.budget,
+            result,
+        };
+    }
+    /**
+     * The whole diff as prose: what merged, what was dated, what moved, what it cost.
+     *
+     * THE HONESTY SENTENCE AT THE END IS NOT DECORATION. Row 5 was planned as a token saving
+     * and J45-1 measured that it is not one: the profile store has no `index.md` on disk, its
+     * index is derived at read time, and nothing loads it into a prompt — so deduplicating it
+     * frees approximately zero prompt bytes. The value is that one ruling now has one copy
+     * instead of two that can disagree, and the reply says which of those two things the
+     * operator just bought.
+     *
+     * `formatFixed3` and not `toFixed(3)` for the two similarity figures: see the header of
+     * `dream.ts`. CPython's `.3f` rounds ties to EVEN and they are reachable.
+     */
+    static dreamReply(status, result) {
+        const lines = [];
+        if (status === 'nothing-to-consolidate') {
+            lines.push(`nothing to consolidate: ${result.projectRoot} and ${result.profileRoot} ` +
+                'hold no fact under the same name, and no project fact carries a relative ' +
+                'date this pass will resolve.');
+        }
+        else {
+            const identical = result.merged.filter((merge) => merge.kind === 'identical').length;
+            const diverged = result.merged.length - identical;
+            const verb = status === 'consolidated' ? 'consolidated' : 'would consolidate';
+            lines.push(`${verb} ${result.merged.length} cross-layer name collision(s) — ${identical} ` +
+                `byte-identical, ${diverged} diverged and unioned — and rewrote ` +
+                `${result.rewritten.length} project fact(s). The survivor stays in the ` +
+                `project layer; the profile copy moves to ${result.archiveDir} and is NOT ` +
+                'deleted: restore it by name.');
+        }
+        for (const merge of result.merged) {
+            lines.push(`- ${pyText(merge.name)} (${merge.kind}, name+description similarity ` +
+                `${formatFixed3(merge.jaccard)}) — body ${merge.bodyBefore} -> ${merge.bodyAfter} ` +
+                `bytes, ${merge.blocksAdded} block(s) kept from the ${merge.consumedLayer} ` +
+                `copy, survivor in ${merge.survivorLayer}`);
+        }
+        for (const record of result.superseded) {
+            lines.push(`- superseded '${record.subject}': the ${record.lostLayer} copy ` +
+                `(${record.lostDate}) lost to the ${record.keptLayer} copy ` +
+                `(${record.keptDate}); the older claim is kept verbatim under ` +
+                `'${SUPERSEDED_HEADING}'`);
+        }
+        for (const hit of result.absolutised) {
+            lines.push(`- dated ${pyText(hit.name)} (${hit.layer}): '${hit.term}' -> ${hit.resolved}, ` +
+                `resolved against that fact's own mtime ${hit.basis}, not today`);
+        }
+        for (const hit of result.unresolved) {
+            lines.push(`- left alone in ${pyText(hit.name)} (${hit.layer}): '${hit.term}' — no exact day ` +
+                'follows from an mtime, so nothing was substituted');
+        }
+        for (const [name, reason] of result.refused) {
+            lines.push(`- refused ${pyText(name)}: ${reason}`);
+        }
+        for (const pair of result.similarUnmerged) {
+            lines.push(`- similar but NOT merged: ${pyText(pair.projectName)} (project) and ` +
+                `${pyText(pair.profileName)} (profile) score ${formatFixed3(pair.jaccard)}; this pass merges ` +
+                'on name equality only, so nothing was done about it');
+        }
+        lines.push(`project index ${result.indexBefore} -> ${result.indexAfter} bytes against a ` +
+            `${result.budget}-byte budget; the profile index (derived, no file on disk) ` +
+            `${result.profileIndexBefore} -> ${result.profileIndexAfter}; fact bytes ` +
+            `across both layers ${result.factBytesBefore} -> ${result.factBytesAfter}.`);
+        if (status === 'refused-budget') {
+            lines.push(`NOTHING WAS WRITTEN: the merged index would be ${result.indexAfter} bytes ` +
+                `against a ${result.budget}-byte budget. Call \`memory_compact\` to archive ` +
+                'the stalest facts, then run this again.');
+        }
+        else if (result.dryRun) {
+            lines.push('DRY RUN: nothing was written. Re-run with dry_run false to apply it.');
+        }
+        lines.push('This is a correctness pass, not a token saving: the profile index is derived ' +
+            'at read time and is not loaded from a file, so consolidating it frees ' +
+            'approximately no prompt bytes. What it buys is one copy of a ruling instead ' +
+            'of two that can diverge.');
+        return lines.join('\n');
+    }
     /**
      * `(index bytes, budget)` for the writable project store; bytes may be `null`.
      *