@avantf/dsh-mem 0.3.0 → 0.4.0

package/lib/types/envinit.js

@@ -1,402 +0,0 @@
-/**
- * Environment initialisation for the memory plugin, through the family base
- * `@avantf/dsh-plugin-base`.
- *
- * The shape is fixed by the base's DESIGN §7.2 and is the same for every plugin:
- *
- *   bootstrap (inlined) → load the base → register + declare the remaining resources → dispatch the
- *   `background` set → the plugin's own pre-mount check.
- *
- * What this plugin needs, in two phases:
- *
- *   1. **The gate, straight from the base** — the family compatibility gate is part of
- *      `@avantf/dsh-plugin-base` and arrived WITH the module the bootstrap loaded. There is no
- *      `mem:compat` item, no npm download and no managed `<home>/compat/**` copy any more; the base's
- *      `compat` module provides the rules, probes, report and post-registration check, and
- *      `runtimeFromCompat(framework)` derives this plugin's spec from it. The gate has to be runnable
- *      BEFORE anything is registered, because a proven incompatible host must refuse the mount with
- *      nothing half-registered. This replaces the bespoke self-heal the plugin used to run itself
- *      (`@avantf/mem-provision`'s `ensureCompatBase`), whose private root (`<dataHome>/dsh-compat/**`)
- *      the base deliberately does not read.
- *   2. **`mem:pandoc`** (`binary-archive`, `startup: 'background'`) — the documented "expensive but
- *      not startup-blocking" resource. It is declared AFTER the runtime exists, because its spec
- *      comes from the resolved config (`tools.auto_install`, `tools.mirror`), and it is dispatched
- *      without waiting: the caller continues its own initialisation and hooks the outcome through
- *      `onSettled`.
- *   3. **`mem:model`** (`model-cache`, `startup: 'background'`) — the embedding model. It uses the
- *      base's `flat` layout, whose files land at `<root>/<repo>/<file>` — exactly the shape
- *      `@huggingface/transformers` reads under its `cacheDir` — so the runtime loads the base's
- *      copy instead of fetching a second one. For the default repo the file list is the narrow set
- *      the runtime actually opens (see {@link MODEL_FILES}); any other repo omits the list, because
- *      a fixed six-file list made the item fail for a repo whose file set differs. The endpoint is
- *      the mirror only the operator (env) can move. It is NOT declared when the runtime reads its
- *      models elsewhere (`AVANTF_MEM_MODEL_CACHE`) — that would install a second, never-read copy.
- *      A model that cannot be fetched is a WARNING: the semantic path degrades to FTS+entity, it
- *      never refuses the mount.
- *
- * Two hard rules:
- *
- *   - **The base is never statically imported.** Only `import type` and the inlined bootstrap
- *     are static; the value comes from `loadFramework()`. A top-level value import would throw before
- *     the bootstrap ran — exactly the broken-tree case the bootstrap exists for.
- *   - **Nothing here refuses the mount.** "Cannot tell" is not "incompatible": a missing base,
- *     an unavailable gate or a failed resource is a WARNING, and the plugin mounts with its tools,
- *     service, prompt and Remote face intact.
- *
- * @module @avantf/dsh-mem/envinit
- */
-import { homedir } from 'node:os';
-import { join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { envAutoDownload, expandHome } from '@avantf/mem-contract';
-import { PANDOC_ARTIFACT_ID, PANDOC_BINARY, PANDOC_PACKS, PANDOC_VERSION } from '@avantf/mem-provision';
-import { loadFramework, readDependencyRange } from './envinit-bootstrap.js';
-import { baseIsUsable, interfaceVerdict } from './interface_gate.js';
-import { COMPAT_PACKAGE, reasonOf, runtimeFromCompat, warn, } from './provision.js';
-/** The family base package, as declared in this plugin's `peerDependencies`. */
-const FRAMEWORK_PACKAGE = '@avantf/dsh-plugin-base';
-/** The plugin namespace every item is declared under (`<plugin>:<name>`, framework DESIGN §13.4). */
-const PLUGIN = 'mem';
-/**
- * The item ids. `resolve()` / `onSettled` are keyed by them, so the DSH plugin compares against these
- * names rather than re-spelling literals.
- */
-export const PANDOC_ITEM = 'mem:pandoc';
-export const MODEL_ITEM = 'mem:model';
-/**
- * The default ONNX embedding repository — the one `semantic.local_model` defaults to and the one
- * {@link MODEL_FILES} describes. A DIFFERENT repo is a different file set, which is why the item
- * omits `spec.files` for it (see {@link managedModelSpec}).
- */
-export const DEFAULT_MODEL_REPO = 'Xenova/bge-small-zh-v1.5';
-/**
- * The files the local embedding runtime actually requests for the DEFAULT ONNX model.
- *
- * Measured, not guessed: with an empty cache, `@huggingface/transformers@4.x` resolving
- * `feature-extraction` for `Xenova/bge-small-zh-v1.5` fetches exactly these four — `config.json`,
- * `tokenizer.json`, `tokenizer_config.json` and the fp32 `onnx/model.onnx`. The repo ALSO carries
- * `special_tokens_map.json`, `vocab.txt` and seven other ONNX quantisations the default run never
- * opens; declaring them would download hundreds of megabytes of dead weight. The list stays narrow
- * to what is read.
- */
-export const MODEL_FILES = [
-    'config.json',
-    'tokenizer.json',
-    'tokenizer_config.json',
-    'onnx/model.onnx',
-];
-/** Startup budget for the blocking set; the framework's default is the same. */
-const DEADLINE_MS = 15_000;
-/** This module's warning token, so one grep finds every environment-initialisation line. */
-const OWN_PREFIX = 'envinit:';
-/**
- * The model item the framework should own, or `undefined` when it should not.
- *
- * Two refusals, both deliberate:
- *
- *   1. **Not a local backend** — nothing to provision.
- *   2. **The runtime reads its models from elsewhere** — `semantic.cache_dir` is not the framework's
- *      `<home>/models`. That happens through the operator escape hatch `AVANTF_MEM_MODEL_CACHE`
- *      (env layer ④): the runtime loads from that directory, so a `mem:model` item would install a
- *      full second copy under `<home>/models` that nothing ever reads (~190 MB). Declaring nothing
- *      is the fix; the caller warms from the override directory instead.
- *
- * `files` is the narrow {@link MODEL_FILES} set only for the DEFAULT repo; a user-changed repo has a
- * different file set, and a stale six-file list would make the item `failed` while the runtime could
- * serve it. Empty means "omit `spec.files`": the framework then installs the repository's own file
- * list.
- */
-export function managedModelSpec(semantic, modelsRoot) {
-    if (semantic.backend !== 'local_bge')
-        return undefined;
-    if (!sameDir(semantic.cache_dir, modelsRoot))
-        return undefined;
-    return {
-        repo: semantic.local_model,
-        files: semantic.local_model === DEFAULT_MODEL_REPO ? MODEL_FILES : [],
-        endpoint: semantic.mirror,
-    };
-}
-/** Same directory, after `~/` expansion and normalisation (a trailing slash is not a difference). */
-function sameDir(a, b) {
-    return resolve(expandHome(a)) === resolve(expandHome(b));
-}
-/**
- * The family root: `$AVANTF_HOME`, else `~/.avantf/env`.
- *
- * `AVANTF_HOME` is the same variable the engine uses for its DATA home (`memory/`, `knowledge/`),
- * and that is deliberate: setting it redirects a whole tree (data AND managed resources), which is
- * exactly what a test or a sandboxed host needs. Unset — the normal case — the family root is the
- * framework's documented default and the data home stays `~/.avantf`.
- */
-function resolveHome() {
-    const configured = process.env['AVANTF_HOME'];
-    return configured !== undefined && configured.trim() !== '' ? configured : join(homedir(), '.avantf', 'env');
-}
-/**
- * The download gate. Off when EITHER switch is off:
- *
- *   - `AVANTF_MEM_AUTO_DOWNLOAD=0` — this project's documented kill switch (the CLI, the MCP server
- *     and every test honour it);
- *   - `AVANTF_ENVINIT_AUTO_DOWNLOAD=0` — the family framework's switch, so an operator can turn the
- *     whole family's provisioning off in one place.
- *
- * The two-variable rule lives in ONE place (`@avantf/mem-contract`'s `envAutoDownload`), which the
- * config loader and both model adapters also call: a family switch that stops the framework but not
- * the runtime's own fetch is exactly the bug that duplication would reintroduce.
- */
-function envDownloadsAllowed() {
-    return envAutoDownload() ?? true;
-}
-/** A `ProvisionLogger` over the plugin's own logger (the framework also wants `debug`). */
-function provisionLogger(log) {
-    return {
-        debug: (message) => { log?.info(message); },
-        info: (message) => { log?.info(message); },
-        warn: (message) => { log?.warn(message); },
-        error: (message) => { log?.error(message); },
-    };
-}
-/**
- * The `mem:pandoc` item: the pinned pandoc release as a `binary-archive`.
- *
- * The packs are `@avantf/mem-provision`'s (`PANDOC_PACKS`), the single source of the URLs and the
- * measured digests; this only re-spells them in the framework's vocabulary (`format` → `archive`,
- * and the binary as a NAME the archive search finds rather than a path inside the archive). The
- * framework installs it to `<home>/tools/pandoc/3.11/bin/pandoc` — the same layout the converter
- * already resolves, which is what makes the handover a config change and not a code change.
- */
-function pandocItem(framework) {
-    const packs = {};
-    for (const [key, pack] of Object.entries(PANDOC_PACKS)) {
-        if (pack === undefined)
-            continue;
-        packs[key] = { url: pack.url, sha256: pack.sha256, archive: pack.format };
-    }
-    return {
-        id: PANDOC_ITEM,
-        kind: framework.BINARY_ARCHIVE_KIND,
-        spec: {
-            id: PANDOC_ARTIFACT_ID,
-            version: PANDOC_VERSION,
-            binary: PANDOC_BINARY,
-            packs,
-        },
-        target: { root: 'tools' },
-        // A missing converter degrades the knowledge base's document ingestion, never the mount.
-        onMissing: { atStartup: 'degrade', atUse: 'error' },
-        startup: 'background',
-        schemaVersion: framework.ITEM_SCHEMA_VERSION,
-    };
-}
-/**
- * The `mem:model` item: the embedding model as a `model-cache` in the framework's `flat` layout.
- *
- * `flat` places the files at `<home>/models/<repo>/<file>` — the same tree `semantic.cache_dir`
- * points at (the framework root, through `managedRoots`) and the same shape the local runtime reads.
- * `files` is the narrow default-repo set (see {@link MODEL_FILES}); it is OMITTED for any other repo,
- * whose file set this build cannot know, so the framework installs the repository's own list instead
- * of failing on a missing fixed path. `endpoint` is the mirror resolved from the operator's env
- * escape hatch, so neither the landing site nor the source is chosen by an end user's `config.yaml`.
- *
- * A missing model is a degraded semantic path, NOT a refused mount: both `onMissing` axes are
- * `degrade`, and the engine falls back to FTS+entity.
- */
-function modelItem(framework, model) {
-    return {
-        id: MODEL_ITEM,
-        kind: framework.MODEL_CACHE_KIND,
-        spec: {
-            repo: model.repo,
-            revision: 'main',
-            layout: 'flat',
-            ...(model.files.length === 0 ? {} : { files: [...model.files] }),
-            endpoint: model.endpoint,
-        },
-        target: { root: 'models' },
-        onMissing: { atStartup: 'degrade', atUse: 'degrade' },
-        startup: 'background',
-        schemaVersion: framework.ITEM_SCHEMA_VERSION,
-    };
-}
-let loaded;
-let loading;
-/**
- * Ensure the framework, then the compatibility base, then dispatch the expensive resources.
- *
- * Never throws. Returns `undefined` when the framework cannot be loaded — the caller then warns and
- * mounts on the legacy provisioning path (the engine's own `@avantf/mem-provision` sweep, whose
- * default directories are the pre-migration ones). A framework that loads but cannot provide the
- * base still returns a runtime, with `compat: undefined`: the mount must continue, and the resource
- * items are still worth dispatching.
- *
- * The result is cached per process; a FAILED load is not, so a profile reload retries instead of
- * replaying the first failure for the whole process lifetime.
- *
- * @param options - logger, family root, download policy and the test seams.
- * @returns the loaded runtime, or `undefined` when the framework itself is unavailable.
- */
-export async function loadEnvinit(options = {}) {
-    if (loaded !== undefined)
-        return loaded;
-    if (loading !== undefined)
-        return loading;
-    loading = loadGuarded(options).then((runtime) => {
-        // A failure is "cannot tell", not a verdict — and it may be transient (offline at boot,
-        // registry hiccup). Drop the cache so a profile reload, or a second instance in the same
-        // process, retries instead of replaying the first failure for the whole process lifetime.
-        if (runtime === undefined)
-            loading = undefined;
-        else
-            loaded = runtime;
-        return runtime;
-    }, () => {
-        loading = undefined;
-        return undefined;
-    });
-    return loading;
-}
-/** The guard that makes "never throws" true: every failure is a warning plus `undefined`. */
-async function loadGuarded(options) {
-    try {
-        return await loadOnce(options);
-    }
-    catch (error) {
-        warn(options.log, `${OWN_PREFIX} WARNING — environment initialisation failed (${reasonOf(error)}); the framework is SKIPPED and the plugin will mount anyway`);
-        return undefined;
-    }
-}
-/** The body of {@link loadEnvinit}; the cache above makes it run at most once per process. */
-async function loadOnce(options) {
-    const home = options.home ?? resolveHome();
-    const range = await readDependencyRange(fileURLToPath(import.meta.url));
-    const autoDownload = options.autoDownload ?? envDownloadsAllowed();
-    const deadlineMs = options.deadlineMs ?? DEADLINE_MS;
-    // Step 1–2: bootstrap → the framework itself (the package manager's copy, zero download). The
-    // plugin's declared range is not judged here; it goes to `envinitRange` below, per manifest.
-    const framework = options.framework ?? await loadFramework({
-        logger: {
-            warn: (message) => { warn(options.log, `${FRAMEWORK_PACKAGE}: ${message}`); },
-            info: (message) => { options.log?.info(`${FRAMEWORK_PACKAGE}: ${message}`); },
-        },
-    });
-    if (framework === undefined) {
-        warn(options.log, `${OWN_PREFIX} WARNING — ${FRAMEWORK_PACKAGE} could not be made available; the plugin falls back to its own provisioning and mounts anyway`);
-        return undefined;
-    }
-    // The RUNTIME interface gate, on its own axis: the generation this artifact was baked for
-    // (`lib/interface-version.json`, written by `scripts/link-envinit.mjs` with the bootstrap) versus
-    // the one the loaded base reports. The DECISION is the base's (`checkInterface` together with its
-    // one reader of the bake record); this plugin only consumes it. Package versions move every release
-    // and stay the INSTALL-time gate (the peer range), so the generation number is the axis that means
-    // "the kit and gate helper set I was written against is the one I loaded".
-    //
-    // The verdict, and why it is a DEGRADATION now rather than the bare warning it used to be: the
-    // interface is the family's MAIN contract, so a base from another generation is not a base whose
-    // shared capabilities this build may use. `incompatible` therefore withholds them — the prompt
-    // layer falls back to this plugin's own default text, the compatibility gate is skipped and the
-    // resources take the legacy path — by taking the SAME route as "the base is unavailable", which the
-    // caller already handles. The mount itself (tools, service, prompt sections, Remote, UI) is never
-    // refused: the family invariant is that only a PROVEN host break refuses, and a generation mismatch
-    // is not one. `cannot-tell` (no gate on the loaded base, no bake record) is a warning and nothing
-    // else — "cannot tell" is never "incompatible".
-    {
-        const verdict = interfaceVerdict(framework);
-        if (!baseIsUsable(verdict)) {
-            warn(options.log, `${OWN_PREFIX} WARNING — interface: ${verdict.reason ?? 'the loaded base implements another interface generation'};`
-                + ' the base\'s shared capabilities are NOT used (own prompt defaults, gate skipped, legacy provisioning) and the plugin mounts anyway');
-            return undefined;
-        }
-        if (verdict.status === 'cannot-tell') {
-            warn(options.log, `${OWN_PREFIX} WARNING — interface: ${verdict.reason ?? 'the interface generation cannot be told'}; using the loaded base anyway ("cannot tell" is never "incompatible")`);
-        }
-    }
-    // The compatibility gate is part of the base package and arrived WITH it: there is no `mem:compat`
-    // item, no npm download and no managed `~/.avantf/env/compat/**` any more. `runtimeFromCompat`
-    // takes the loaded base module directly. A gate that cannot be built is a WARNING (the plugin
-    // mounts and writes its own default prompts), never a refusal.
-    const disposers = [];
-    let compat;
-    try {
-        compat = runtimeFromCompat(options.compatModule ?? framework);
-    }
-    catch (error) {
-        warn(options.log, `${OWN_PREFIX} WARNING — the ${COMPAT_PACKAGE} compatibility gate could not be initialised (${reasonOf(error)}); the compatibility gate is SKIPPED and the plugin will mount anyway`);
-    }
-    let disposed = false;
-    return {
-        home,
-        kit: framework,
-        compat,
-        roots: { tools: join(home, 'tools'), models: join(home, 'models') },
-        provisionResources(plan, onSettled) {
-            if (disposed)
-                return;
-            const items = [];
-            if (plan.pandoc)
-                items.push(pandocItem(framework));
-            if (plan.model !== undefined)
-                items.push(modelItem(framework, plan.model));
-            if (items.length === 0)
-                return;
-            // A SECOND provisioner, on purpose: `policy.mirrors.archive` is the engine's `tools.mirror`,
-            // which is only known after the runtime resolved its config — while the compat provisioner had
-            // to exist before that, to run the gate. Two instances sharing one family root are supported by
-            // design (framework DESIGN §13.1), and their item sets are disjoint.
-            //
-            // `autoDownload` is per KIND: the env kill switches turn everything off, otherwise the model
-            // follows `semantic.auto_download` while pandoc keeps its own gate (`tools.auto_install`,
-            // which decides whether it is declared at all). Folding the two into one boolean would let
-            // `semantic.auto_download: false` skip a pandoc the operator explicitly asked for — or, the
-            // other way round, let a disabled model still hit the network.
-            const resources = framework.createProvisioner({
-                home,
-                envinitRange: range,
-                logger: provisionLogger(options.log),
-                policy: {
-                    autoDownload: autoDownload ? { [framework.MODEL_CACHE_KIND]: plan.modelAutoDownload } : false,
-                    deadlineMs,
-                    mirrors: { archive: [...plan.archiveMirrors] },
-                },
-            });
-            resources.register(framework.binaryArchiveProvider());
-            resources.register(framework.modelCacheProvider());
-            resources.declare({ plugin: PLUGIN, items });
-            disposers.push(resources);
-            // Dispatched, not awaited: `startup: 'background'` items never occupy the ensure budget.
-            // The `.catch` is not decoration: an unhandled rejection is FATAL on a strict host (Node's
-            // default `--unhandled-rejections=throw`), and a memory plugin must not be able to take the
-            // host down over a resource it could not fetch. The compat ensure above is awaited instead,
-            // so its rejection is handled by `loadGuarded`.
-            void resources.ensure({
-                only: items.map(item => item.id),
-                onSettled: (entry) => {
-                    try {
-                        onSettled(entry);
-                    }
-                    catch (error) {
-                        warn(options.log, `${OWN_PREFIX} WARNING — the onSettled callback failed (${reasonOf(error)})`);
-                    }
-                },
-            }).catch((error) => {
-                warn(options.log, `${OWN_PREFIX} WARNING — declaring the background resources failed (${reasonOf(error)}); the plugin continues (tools stay registered)`);
-            });
-        },
-        dispose() {
-            if (disposed)
-                return;
-            disposed = true;
-            for (const instance of disposers.splice(0)) {
-                try {
-                    instance.dispose();
-                }
-                catch {
-                    // Disposal is best-effort; a throwing release must not break unmount.
-                }
-            }
-            loaded = undefined;
-            loading = undefined;
-        },
-    };
-}
-//# sourceMappingURL=envinit.js.map

package/lib/types/envinit.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"envinit.js","sourceRoot":"","sources":["../../src/envinit.ts"],"names":[],"mappings":"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"}

package/lib/types/hints.js

@@ -1,53 +0,0 @@
-/**
- * The plugin's CONDITIONAL hint: ONE line, contributed only when either store already holds
- * something relevant to the message the user just sent (DESIGN §12).
- *
- * These are deliberately NOT part of the always-on usage sections. A usage section says WHEN a
- * store is worth consulting and therefore has to be paid for on every step of every session; this
- * says "there is something here, right now", which is only true sometimes. The two layers compose:
- * the section is the fallback for the paraphrase the lexical probe misses, and the hint is the
- * concrete nudge for the case it catches.
- *
- * ONE LINE FOR BOTH STORES, and it names ONE tool. `kb_query` is a cross-store retrieval (document
- * chunks AND memory facts), so a single line covers whichever store matched. Per-store lines used
- * to name two tools, which invited two overlapping calls — the memory facts came back twice, once
- * from `mem_recall` and again inside `kb_query`'s fused result — and made every memory↔knowledge
- * transition a fresh snapshot append. `mem_recall` remains the tool for the memory-only actions
- * (chain / probe / reason / contradict); the always-on memory usage section is where that is said.
- *
- * WHY THE LINE NAMES THE PLUGIN. This text is injected as runtime context, and the harness
- * materialises that as a USER-role snapshot in the conversation (`dsh-agent-loop`'s
- * `runtimeContext.project`). Without an author, a line like "记忆里有相关内容" reads as something
- * the user said. The `[avantf-mem]` prefix is what keeps the provenance honest.
- */
-export const RELEVANCE_HINT = '[avantf-mem] 记忆或知识库里有与上条用户消息相关的内容；需要时用 `kb_query` 检索。';
-/**
- * Map one answer to the contribution, as text.
- *
- * An empty string is the "contribute nothing" value: `renderContextSections` drops empty text, so
- * "nothing found" costs no tokens at all.
- */
-export function hintText(hit) {
-    return hit ? RELEVANCE_HINT : '';
-}
-/**
- * The plain text of an inbox message, or `''` when it carries none.
- *
- * `dsh-agent-loop`'s own extractor returns `undefined` unless the message is exactly ONE text
- * block; a steered or multi-part message would then silently produce no hint. Concatenating the
- * text blocks keeps the probe working for those, and non-text blocks (images) are simply skipped —
- * the probe is lexical, so it has nothing to say about them anyway.
- */
-export function messageText(message) {
-    const content = message?.content;
-    if (!Array.isArray(content))
-        return '';
-    return content
-        .map((block) => {
-        const b = block;
-        return b?.type === 'text' && typeof b.text === 'string' ? b.text : '';
-    })
-        .filter(Boolean)
-        .join('\n');
-}
-//# sourceMappingURL=hints.js.map

package/lib/types/hints.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"hints.js","sourceRoot":"","sources":["../../src/hints.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,CAAC,MAAM,cAAc,GACzB,uDAAuD,CAAA;AAEzD;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAiB;IACxC,OAAO,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,CAAA;AAClC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB;IAC1C,MAAM,OAAO,GAAI,OAAwC,EAAE,OAAO,CAAA;IAClE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAA;IACtC,OAAO,OAAO;SACX,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,MAAM,CAAC,GAAG,KAA0C,CAAA;QACpD,OAAO,CAAC,EAAE,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAA;IACvE,CAAC,CAAC;SACD,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC"}