@avantf/dsh-plugin-base 0.5.2 → 0.6.0

package/{dist → lib}/provisioner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provisioner.d.ts","sourceRoot":"","sources":["../src/provisioner.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EACV,SAAS,EACT,KAAK,EAeL,aAAa,EAMb,WAAW,EAEX,kBAAkB,EAMnB,MAAM,YAAY,CAAA;AAEnB,yDAAyD;AACzD,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAA6C,CAAA;AAEvF,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,QAAS,CAAA;AAEzC,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAepC,UAAU,iBAAiB;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CACtB;AAED;;;iFAGiF;AACjF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,iBAAiB,CAKvF;AA0DD;cACc;AACd,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAk+B1E"}
+{"version":3,"file":"provisioner.d.ts","sourceRoot":"","sources":["../src/provisioner.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EACV,SAAS,EACT,KAAK,EAeL,aAAa,EAMb,WAAW,EAEX,kBAAkB,EAOnB,MAAM,YAAY,CAAA;AAEnB,yDAAyD;AACzD,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAA6C,CAAA;AAEvF,kDAAkD;AAClD,eAAO,MAAM,mBAAmB,QAAS,CAAA;AAEzC,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAepC,UAAU,iBAAiB;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CACtB;AAED;;;iFAGiF;AACjF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,iBAAiB,CAKvF;AA0DD;cACc;AACd,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAy/B1E"}

package/{dist → lib}/provisioner.js

@@ -200,38 +200,48 @@ export function createProvisioner(options) {
     const listeners = new Set();
     /** Layout read-only state, decided once per process. */
     let readOnly;
-    let homeChecked = false;
+    /**
+     * The in-flight (then settled) home verdict. Every caller awaits the SAME promise, so a
+     * concurrent `declare`/`ensure` cannot slip past the gate while `readLayout` is still deciding:
+     * the old boolean was set BEFORE the await, so a second caller returned early with `readOnly`
+     * still unset and `ensureOne` then wrote into a too-new/mismatched home. The promise is never
+     * re-created — the verdict is once-per-process, and a rejection is part of the verdict: the body
+     * already folds ordinary IO failures into a `layout/unreadable` read-only code, so a promise
+     * that still rejects is not something a silent retry is expected to fix, and later callers
+     * observe the same failure rather than racing the home again.
+     */
+    let homePromise;
     const pendingDeclared = [];
     /** Decide the home's layout once. */
-    const checkHome = async () => {
-        if (homeChecked)
-            return;
-        homeChecked = true;
-        if (unsupported !== undefined && !unsupportedWarned) {
-            unsupportedWarned = true;
-            logger.warn(`unsupported-envinit: 本副本 ${FRAMEWORK_VERSION} 不满足插件声明的区间 "${String(options.envinitRange)}"；跳过该清单、降级挂载`);
-        }
-        try {
-            const result = await readLayout(fs, home, layout);
-            if (result.kind === 'none') {
-                await writeLayout(fs, home, layout, 'dsh-plugin-base');
+    const checkHome = () => {
+        homePromise ??= (async () => {
+            if (unsupported !== undefined && !unsupportedWarned) {
+                unsupportedWarned = true;
+                logger.warn(`unsupported-envinit: 本副本 ${FRAMEWORK_VERSION} 不满足插件声明的区间 "${String(options.envinitRange)}"；跳过该清单、降级挂载`);
             }
-            else if (result.kind === 'too-new') {
-                readOnly = 'layout/too-new';
-                logger.warn(`layout/too-new: ${home} 由更新的布局写入；本次只读不写`);
+            try {
+                const result = await readLayout(fs, home, layout);
+                if (result.kind === 'none') {
+                    await writeLayout(fs, home, layout, 'dsh-plugin-base');
+                }
+                else if (result.kind === 'too-new') {
+                    readOnly = 'layout/too-new';
+                    logger.warn(`layout/too-new: ${home} 由更新的布局写入；本次只读不写`);
+                }
+                else if (result.kind === 'mismatch') {
+                    readOnly = 'layout/mismatch';
+                    logger.warn(`layout/mismatch: ${home} 的布局是 "${result.file.layout}"，本次是 "${layout}"；本次只读不写`);
+                }
             }
-            else if (result.kind === 'mismatch') {
-                readOnly = 'layout/mismatch';
-                logger.warn(`layout/mismatch: ${home} 的布局是 "${result.file.layout}"，本次是 "${layout}"；本次只读不写`);
+            catch (error) {
+                // A read failure keeps the read-only CONSEQUENCE but gets its own code: every item's report
+                // would otherwise say `layout/too-new` — "a NEWER layout wrote this, leave it alone" — about a
+                // home whose layout nobody managed to read at all.
+                logger.warn(`layout: 无法读写 .layout.json（${reasonOf(error).message}）；按只读继续`);
+                readOnly = 'layout/unreadable';
             }
-        }
-        catch (error) {
-            // A read failure keeps the read-only CONSEQUENCE but gets its own code: every item's report
-            // would otherwise say `layout/too-new` — "a NEWER layout wrote this, leave it alone" — about a
-            // home whose layout nobody managed to read at all.
-            logger.warn(`layout: 无法读写 .layout.json（${reasonOf(error).message}）；按只读继续`);
-            readOnly = 'layout/unreadable';
-        }
+        })();
+        return homePromise;
     };
     /**
      * The failure a persisted row should carry: an explicit `lastError` if something ever sets one,
@@ -687,6 +697,8 @@ export function createProvisioner(options) {
             return settle(declared, started, 'skipped', 'policy/offline');
         const staging = stagingDir(home, item.id, (stagingSequence += 1));
         let published;
+        /** Set only when the core's own `publish()` placed the directory — see the catch below. */
+        let corePublished;
         const installCtx = {
             ...ctx,
             stage: async () => {
@@ -696,6 +708,7 @@ export function createProvisioner(options) {
             publish: async (dir, meta) => {
                 const resolved = await publish(declared, dir, meta);
                 published = resolved;
+                corePublished = resolved;
                 return resolved;
             },
             ...(onProgress === undefined
@@ -731,18 +744,27 @@ export function createProvisioner(options) {
                 },
             };
             putRow(declared, resolved.version, state, resolved.source);
-            return entryOf(declared, { action: 'installed', source: resolved.source, started, version: resolved.version });
+            // A provider that says it only REUSED an equivalent root (another process published it while
+            // this one waited) placed nothing: the honest action is `present`, not `installed`.
+            const action = resolved.reused === true ? 'present' : 'installed';
+            return entryOf(declared, { action, source: resolved.source, started, version: resolved.version });
         }
         catch (error) {
             const { code, message } = reasonOf(error);
-            // A published-but-unusable directory is quarantined, never deleted.
-            if (published !== undefined) {
+            // A published-but-unusable directory is quarantined, never deleted — but ONLY a directory the
+            // core itself published through `ctx.publish()`. A provider that bypasses `publish()`
+            // (`model-cache`, whose `dir` is the shared `snapshots/<sha>` that `refs/<revision>` and every
+            // sibling item of the same repo+sha point at) manages its own storage: renaming that directory
+            // here would dangle the ref and take healthy sibling items down with the failed one. Such a
+            // provider withdraws its own completion marker on verify failure instead (see
+            // `providers/model.ts`), which keeps the next `probe` honest without touching shared state.
+            if (corePublished !== undefined) {
                 try {
-                    await quarantineLocked(published.dir);
-                    logger.warn(`quarantined ${published.dir}: ${message}`);
+                    await quarantineLocked(corePublished.dir);
+                    logger.warn(`quarantined ${corePublished.dir}: ${message}`);
                 }
                 catch (renameError) {
-                    logger.warn(`could not quarantine ${published.dir}: ${reasonOf(renameError).message}`);
+                    logger.warn(`could not quarantine ${corePublished.dir}: ${reasonOf(renameError).message}`);
                 }
             }
             const state = { state: 'failed', code, detail: message };

package/lib/runtime_deps_helper.d.ts

@@ -0,0 +1,71 @@
+import type { DependencySource, InstallAttempt } from './providers/runtime_deps.js';
+import type { SessionNoticeRegistry, SessionNoticeSpec } from './session_notices.js';
+import type { ProvisionItem, ProvisionReportEntry, Provisioner, Resolved } from './types.js';
+/**
+ * What a plugin declares. A superset of {@link RuntimeDepsSpec} (the provider's own input) plus the
+ * identity and the notices: the spec fields are forwarded verbatim, so nothing here decides anything
+ * about packages, registries or managers.
+ */
+export interface RuntimeDepsConfig {
+    /** The plugin's namespace (`mem`); the default item id is `${namespace}:runtime-deps`. */
+    readonly namespace: string;
+    /** Override the item id; must still be prefixed with `${namespace}:`. */
+    readonly itemId?: string;
+    /** Package name → dependency spec. Forwarded to {@link RuntimeDepsSpec.packages}. */
+    readonly packages: Readonly<Record<string, string>>;
+    /** The registry/cache endpoints the attempts reference. */
+    readonly sources: readonly DependencySource[];
+    /** Install attempts, tried in order. */
+    readonly attempts: readonly InstallAttempt[];
+    /** Specifiers every successful root must resolve; non-empty. */
+    readonly verify: readonly string[];
+    /** Host-provided singletons, linked never installed. */
+    readonly peers?: Readonly<Record<string, string>>;
+    /** A lockfile whose bytes seed/audit the install. */
+    readonly lockfile?: string;
+    /**
+     * Notices to deliver once per session when this item is NOT ready. Each one's `when` selects which
+     * observed states match: `failed` → the item failed; `missing` → it is missing or was skipped;
+     * `degraded` → any of those three (the broad "the shared root is not there" condition).
+     */
+    readonly notices?: readonly SessionNoticeSpec[];
+}
+/** What {@link createRuntimeDeps} hands back. */
+export interface RuntimeDepsHandle {
+    /** The item to declare through the caller's own provisioner. */
+    readonly item: ProvisionItem;
+    /** The registry, pre-loaded with {@link RuntimeDepsConfig.notices}. */
+    readonly notices: SessionNoticeRegistry;
+    /**
+     * Ensure THIS item through the caller's provisioner and return its report entry.
+     *
+     * The item must already be declared (the helper never declares); `undefined` means the report
+     * carried no entry for it — a background item is dispatched and reports through `onSettled`
+     * instead, and `resolve()` reflects it as soon as it settles. A rejected `ensure` propagates: that
+     * is a dispatch failure, not a provisioning outcome.
+     */
+    ensure(provisioner: Provisioner): Promise<ProvisionReportEntry | undefined>;
+    /** The ready shared root as the core reports it, or `undefined` while it is not ready. */
+    resolve(): Resolved | undefined;
+    /**
+     * Resolve `specifier` from the shared root and import its entry (dynamic `import()`).
+     *
+     * Read-only by construction: `createRequire(<root>/package.json).resolve()` plus `import()` of the
+     * resolved file — no copy, no `node_modules` write, no link. The module is imported by FILE URL, so
+     * a package that must not be resolved twice through the host's tree still gets this root's copy.
+     *
+     * Rejects with a {@link ProvisionError} (`invalid-option`) when the root is not ready or the
+     * specifier is empty, and with the underlying resolution/import error otherwise — a failed resolve
+     * is the caller's specifier meeting this root, not a provisioning failure with a code.
+     */
+    load<T = unknown>(specifier: string): Promise<T>;
+}
+/**
+ * Build the handle for one shared runtime-dependency root.
+ *
+ * @param config - the plugin's declaration; forwarded to the provider field by field.
+ * @throws ProvisionError (`invalid-option`) for a namespace/itemId that cannot make a namespaced item
+ *   id — a caller bug at construction time, not a provisioning outcome.
+ */
+export declare function createRuntimeDeps(config: RuntimeDepsConfig): RuntimeDepsHandle;
+//# sourceMappingURL=runtime_deps_helper.d.ts.map

package/lib/runtime_deps_helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime_deps_helper.d.ts","sourceRoot":"","sources":["../src/runtime_deps_helper.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAmB,MAAM,6BAA6B,CAAA;AACpG,OAAO,KAAK,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACpF,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,WAAW,EAAE,QAAQ,EAAiB,MAAM,YAAY,CAAA;AAE3G;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,qFAAqF;IACrF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACnD,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAC7C,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAA;IAC5C,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACjD,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;CAChD;AAED,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,qBAAqB,CAAA;IACvC;;;;;;;OAOG;IACH,MAAM,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAAA;IAC3E,0FAA0F;IAC1F,OAAO,IAAI,QAAQ,GAAG,SAAS,CAAA;IAC/B;;;;;;;;;;OAUG;IACH,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CACjD;AAiDD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,iBAAiB,CA+E9E"}

package/lib/runtime_deps_helper.js

@@ -0,0 +1,161 @@
+/**
+ * `createRuntimeDeps` — the thin, library-level helper a plugin uses to DECLARE one shared
+ * runtime-dependency root and then reach it: the item, the session notices and the loader.
+ *
+ * It is sugar over two members this package already exports, never a second implementation of them:
+ *
+ *  - `runtimeDepsProvider()` (interface v5) owns the content-addressed store, the install attempts,
+ *    verify, peer linking and failure reporting;
+ *  - `createSessionNotices()` (interface v6) owns the once-per-session notice bookkeeping.
+ *
+ * What the helper adds is the wiring in between, and nothing else:
+ *
+ *  - **one item** built from the caller's spec — `kind: 'runtime-deps'`, the canonical
+ *    `<home>/deps/runtime` store, this build's item schema. Base names no package;
+ *  - **notices bound to the ITEM's real state**: each {@link SessionNoticeSpec.when} is mapped onto the
+ *    provisioner's own `resolve(item.id)`, re-read on every `consume` — so a root that healed stops
+ *    matching, exactly as the registry requires;
+ *  - **`ensure()` / `resolve()`** as the caller's handle onto the provisioner it already owns (the
+ *    plugin still declares the item and still calls `ensure`; the helper only narrows the answer to
+ *    this item);
+ *  - **`load()`**, which resolves a specifier from the shared root and imports it — it COPIES NO
+ *    PACKAGE and writes nothing, including no `node_modules`.
+ *
+ * Deliberately absent: no hook registration, no configuration reading, no filesystem access at
+ * construction, no session bookkeeping of its own. Base stays a library, and the plugin stays the only
+ * DSH lifecycle owner.
+ *
+ * @module runtime_deps_helper
+ */
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ProvisionError } from './errors.js';
+import { ITEM_SCHEMA_VERSION } from './provisioner.js';
+import { RUNTIME_DEPS_DIR, RUNTIME_DEPS_KIND } from './providers/runtime_deps.js';
+import { createSessionNotices } from './session_notices.js';
+/** `plugin` namespaces this build accepts in an item id: anything but `:`, `/` and whitespace. */
+const NAMESPACE = /^[^\s:/]+$/u;
+/** The observed states one {@link SessionNoticeSpec.when} covers. */
+function matchesWhen(when, state) {
+    if (state === undefined)
+        return false;
+    switch (state.state) {
+        case 'failed':
+            return when === 'failed' || when === 'degraded';
+        case 'missing':
+        case 'skipped':
+            return when === 'missing' || when === 'degraded';
+        // `pending` is deliberately NOT a notice: the install/job is still in flight, and a latch taken
+        // while it runs would make a "not ready" line permanent for that session even after it succeeds.
+        case 'pending':
+        case 'ready':
+            return false;
+    }
+}
+/**
+ * The `Resolved` shape of a ready handle.
+ *
+ * The fields come from the CORE's {@link ResourceHandle}; `entryDir` equals `dir` because the shared
+ * store publishes its root as the usable entry (the provider's own `resolvedOf` says the same), and
+ * `name` is the item id the caller declared. Nothing is invented: a handle that is not ready has no
+ * `Resolved` at all.
+ */
+function resolvedOf(state) {
+    if (state?.state !== 'ready')
+        return undefined;
+    const handle = state.handle;
+    return {
+        key: handle.key,
+        name: handle.id,
+        version: handle.version ?? '',
+        dir: handle.dir,
+        entryDir: handle.dir,
+        source: handle.source,
+        ...(Object.keys(handle.env).length === 0 ? {} : { env: handle.env }),
+    };
+}
+/** A declared list, or an empty one: a missing/malformed field is the provider's `invalid-option`. */
+function arrayOf(value) {
+    return Array.isArray(value) ? value : [];
+}
+/**
+ * Build the handle for one shared runtime-dependency root.
+ *
+ * @param config - the plugin's declaration; forwarded to the provider field by field.
+ * @throws ProvisionError (`invalid-option`) for a namespace/itemId that cannot make a namespaced item
+ *   id — a caller bug at construction time, not a provisioning outcome.
+ */
+export function createRuntimeDeps(config) {
+    const namespace = config.namespace;
+    if (typeof namespace !== 'string' || !NAMESPACE.test(namespace)) {
+        throw new ProvisionError('invalid-option', `runtime-deps 的 namespace 必须是插件名（不含 :、/ 与空白）：${JSON.stringify(namespace)}`);
+    }
+    const id = config.itemId ?? `${namespace}:runtime-deps`;
+    if (typeof id !== 'string' || !id.startsWith(`${namespace}:`) || id.length <= namespace.length + 1) {
+        throw new ProvisionError('invalid-option', `runtime-deps 的 itemId 必须以 "${namespace}:" 前缀化且非空：${JSON.stringify(config.itemId)}`);
+    }
+    // COPIED, field by field, for two reasons: the caller may keep mutating its own config object (the
+    // spec is content-key material, so it must be frozen at construction), and a missing field becomes an
+    // empty one, which the PROVIDER then rejects as `invalid-option` on the item — a bad declaration
+    // degrades to a failed item instead of throwing out of the plugin's mount path.
+    const spec = {
+        packages: { ...config.packages },
+        sources: arrayOf(config.sources).map(source => ({ ...source })),
+        attempts: arrayOf(config.attempts).map(attempt => ({ ...attempt })),
+        verify: [...arrayOf(config.verify)],
+        ...(config.peers === undefined ? {} : { peers: { ...config.peers } }),
+        ...(config.lockfile === undefined ? {} : { lockfile: config.lockfile }),
+    };
+    const item = {
+        id,
+        kind: RUNTIME_DEPS_KIND,
+        spec,
+        // The provider's canonical shared store: every plugin declaring the same spec meets in ONE root.
+        target: { root: RUNTIME_DEPS_DIR },
+        schemaVersion: ITEM_SCHEMA_VERSION,
+    };
+    /** The provisioner handed to {@link RuntimeDepsHandle.ensure}; notices need it to observe state. */
+    let active;
+    const stateNow = () => {
+        if (active === undefined)
+            return undefined;
+        try {
+            return active.resolve(id);
+        }
+        catch {
+            // `resolve` is a map read and does not throw; a hostile/partial provisioner must not turn a
+            // prompt line into a crash either way.
+            return undefined;
+        }
+    };
+    const resolveNow = () => resolvedOf(stateNow());
+    const notices = createSessionNotices();
+    for (const notice of arrayOf(config.notices)) {
+        notices.register(notice, () => matchesWhen(notice.when, stateNow()));
+    }
+    return {
+        item,
+        notices,
+        async ensure(provisioner) {
+            active = provisioner;
+            const report = await provisioner.ensure({ only: [id] });
+            return report.entries.find(entry => entry.id === id);
+        },
+        resolve: resolveNow,
+        async load(specifier) {
+            const resolved = resolveNow();
+            if (resolved === undefined) {
+                throw new ProvisionError('invalid-option', `runtime-deps 句柄尚未就绪：item ${id} 没有共享根（先 ensure，并在 settle 之后再 load）`);
+            }
+            if (typeof specifier !== 'string' || specifier.trim() === '') {
+                throw new ProvisionError('invalid-option', `runtime-deps.load 需要一个非空的 specifier（item ${id}）`);
+            }
+            // The root's own `package.json` is the resolution anchor: `node_modules` under it is what the
+            // provider installed, and it is the ONLY tree this import may see.
+            const entry = createRequire(join(resolved.dir, 'package.json')).resolve(specifier);
+            return (await import(pathToFileURL(entry).href));
+        },
+    };
+}
+//# sourceMappingURL=runtime_deps_helper.js.map

package/lib/session_notices.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Session-scoped notices — the generic, in-memory channel through which a plugin tells ONE agent
+ * session that one of its optional capabilities is not ready.
+ *
+ * The defect this exists for is a shape, not a package: a plugin provisions an optional capability
+ * (a shared runtime-dependency root, a model cache, an archive) in the BACKGROUND, mounts either way,
+ * and then has to say so in the owner's prompt — exactly once, with the caller's own wording, and
+ * without ever being able to refuse the mount or to leak a stale line after the capability healed.
+ * Every family plugin re-implemented that bookkeeping locally; this is the ONE implementation, so a
+ * fix here is a base release and not one rebuild per plugin.
+ *
+ * The registry deliberately knows nothing else:
+ *
+ *  - **No wording.** {@link SessionNoticeSpec.body} is returned VERBATIM; the registry adds no prefix,
+ *    no severity label and no punctuation. Base names no package, command or user-facing sentence.
+ *  - **No state of its own.** `state()` is the caller's predicate and it is evaluated on EVERY
+ *    {@link SessionNoticeRegistry.consume}: a healed dependency simply stops matching, without the
+ *    registry having to know what "healed" means.
+ *  - **No session identity.** The caller supplies the session id and decides which sessions may see a
+ *    line ({@link SessionNoticeRegistry.consume}'s `ownerOnly`); the registry only remembers, per
+ *    session id, which notice ids it has already delivered.
+ *  - **No persistence.** Session ids live in a `Map` for the lifetime of the instance. Nothing here
+ *    touches the filesystem, a database, `process.env` or any global: a notice is a prompt line, not
+ *    a record.
+ *  - **No throwing.** `consume` runs on the prompt path of a live agent; a caller bug or a throwing
+ *    `state()` must cost one skipped line, never the turn.
+ *
+ * The registry is a LIBRARY, not a DSH plugin: it registers no hook, mounts nothing and reads no
+ * configuration. The caller owns the lifecycle (which hook, which session, which text) and the
+ * registry owns only the once-per-session bookkeeping.
+ *
+ * @module session_notices
+ */
+/**
+ * One notice a caller may want shown.
+ *
+ * `id` is the notice's identity for the once-per-session latch, so it must be namespaced by the
+ * plugin's own item/plugin prefix (`<plugin>:…`): two plugins sharing a process must not be able to
+ * silently suppress each other's line by picking the same id.
+ */
+export interface SessionNoticeSpec {
+    /** Stable id, namespaced `<plugin>:…`; the unit the once-per-session rule applies to. */
+    readonly id: string;
+    /** How loud the line is. Ordering only — the registry renders no label for it. */
+    readonly severity: 'info' | 'warning' | 'degraded';
+    /**
+     * Which failure shape the notice describes. The caller's `state()` decides WHETHER it matches; this
+     * field is carried so the caller's own wiring (and the runtime-deps helper) can map one spec onto
+     * several observed states without inventing a second type.
+     */
+    readonly when: 'failed' | 'missing' | 'degraded';
+    /** The line itself, self-contained (no path into this repository's docs). Returned verbatim. */
+    readonly body: string;
+}
+/** The registry {@link createSessionNotices} returns. */
+export interface SessionNoticeRegistry {
+    /**
+     * Register one notice with the caller's state predicate.
+     *
+     * `state()` is called on every `consume`, so it must be cheap, total and side-effect free; a throw
+     * is a warning and skips that notice for that call (it is NOT latched, so a later consume may still
+     * deliver it). Registration is guarded the same way: a malformed spec, or a second registration of
+     * the same id, is a warning and is ignored — never a throw, because registration happens on the
+     * plugin's mount path.
+     */
+    register(spec: SessionNoticeSpec, state: () => boolean): void;
+    /**
+     * The notices that match RIGHT NOW and have not yet been delivered to `sessionId`, merged into one
+     * array of bodies: severity first (`degraded` > `warning` > `info`), then registration order.
+     *
+     * Every returned body is latched for that session id at the moment it is returned, so a notice is
+     * emitted at most once per session id even if `state()` flips back to `true` later. `consume` never
+     * throws: a throwing `state()` is a warning and that notice is skipped.
+     *
+     * `ownerOnly: true` is the caller's claim that this call is on behalf of the session that OWNS the
+     * plugin's delivery — the family's "the caller owns owner/worker filtering" rule. Only a claimed
+     * call is served, so a worker/other session stays quiet by not claiming; the caller that does want a
+     * line in every session simply claims from every session (the latch stays per session id either
+     * way). A call without the claim returns `[]` and latches nothing.
+     */
+    consume(sessionId: string, options?: {
+        ownerOnly?: boolean;
+    }): string[];
+}
+/**
+ * Build one session-notice registry.
+ *
+ * @param logger - optional warning sink. Omitted means diagnostics are dropped (the registry still
+ *   never throws); a throwing sink is swallowed for the same reason.
+ * @returns the registry; every member is total.
+ */
+export declare function createSessionNotices(logger?: {
+    warn(message: string): void;
+}): SessionNoticeRegistry;
+//# sourceMappingURL=session_notices.d.ts.map

package/lib/session_notices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session_notices.d.ts","sourceRoot":"","sources":["../src/session_notices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,yFAAyF;IACzF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAA;IAClD;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAA;IAChD,gGAAgG;IAChG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,OAAO,GAAG,IAAI,CAAA;IAC7D;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,EAAE,CAAA;CACxE;AA6CD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE;IAAE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,qBAAqB,CA+FpG"}

package/lib/session_notices.js

@@ -0,0 +1,172 @@
+/**
+ * Session-scoped notices — the generic, in-memory channel through which a plugin tells ONE agent
+ * session that one of its optional capabilities is not ready.
+ *
+ * The defect this exists for is a shape, not a package: a plugin provisions an optional capability
+ * (a shared runtime-dependency root, a model cache, an archive) in the BACKGROUND, mounts either way,
+ * and then has to say so in the owner's prompt — exactly once, with the caller's own wording, and
+ * without ever being able to refuse the mount or to leak a stale line after the capability healed.
+ * Every family plugin re-implemented that bookkeeping locally; this is the ONE implementation, so a
+ * fix here is a base release and not one rebuild per plugin.
+ *
+ * The registry deliberately knows nothing else:
+ *
+ *  - **No wording.** {@link SessionNoticeSpec.body} is returned VERBATIM; the registry adds no prefix,
+ *    no severity label and no punctuation. Base names no package, command or user-facing sentence.
+ *  - **No state of its own.** `state()` is the caller's predicate and it is evaluated on EVERY
+ *    {@link SessionNoticeRegistry.consume}: a healed dependency simply stops matching, without the
+ *    registry having to know what "healed" means.
+ *  - **No session identity.** The caller supplies the session id and decides which sessions may see a
+ *    line ({@link SessionNoticeRegistry.consume}'s `ownerOnly`); the registry only remembers, per
+ *    session id, which notice ids it has already delivered.
+ *  - **No persistence.** Session ids live in a `Map` for the lifetime of the instance. Nothing here
+ *    touches the filesystem, a database, `process.env` or any global: a notice is a prompt line, not
+ *    a record.
+ *  - **No throwing.** `consume` runs on the prompt path of a live agent; a caller bug or a throwing
+ *    `state()` must cost one skipped line, never the turn.
+ *
+ * The registry is a LIBRARY, not a DSH plugin: it registers no hook, mounts nothing and reads no
+ * configuration. The caller owns the lifecycle (which hook, which session, which text) and the
+ * registry owns only the once-per-session bookkeeping.
+ *
+ * @module session_notices
+ */
+/** The severity order of {@link SessionNoticeSpec.severity}, loudest first. */
+const SEVERITY_RANK = {
+    degraded: 0,
+    warning: 1,
+    info: 2,
+};
+/** The severities this build understands (a JS caller can hand over anything). */
+const SEVERITIES = ['info', 'warning', 'degraded'];
+/** The conditions this build understands. */
+const CONDITIONS = ['failed', 'missing', 'degraded'];
+/** `<plugin>:<rest>` — a notice id must be namespaced, see {@link SessionNoticeSpec.id}. */
+const NAMESPACED_ID = /^[^\s:]+:\S+$/u;
+/** Why a spec cannot be registered, or `undefined` when it can. Reads every field once. */
+function specProblem(spec, state) {
+    if (typeof spec !== 'object' || spec === null)
+        return 'spec 必须是对象';
+    const candidate = spec;
+    if (typeof candidate.id !== 'string' || !NAMESPACED_ID.test(candidate.id)) {
+        return `id 必须以 "<plugin>:" 前缀化（收到 ${JSON.stringify(candidate.id)}）`;
+    }
+    if (typeof candidate.severity !== 'string' || !SEVERITIES.includes(candidate.severity)) {
+        return `severity 只能是 ${SEVERITIES.join(' / ')}（收到 ${JSON.stringify(candidate.severity)}）`;
+    }
+    if (typeof candidate.when !== 'string' || !CONDITIONS.includes(candidate.when)) {
+        return `when 只能是 ${CONDITIONS.join(' / ')}（收到 ${JSON.stringify(candidate.when)}）`;
+    }
+    if (typeof candidate.body !== 'string' || candidate.body.trim() === '')
+        return 'body 必须是非空字符串';
+    if (typeof state !== 'function')
+        return 'state 必须是函数';
+    return undefined;
+}
+/**
+ * Build one session-notice registry.
+ *
+ * @param logger - optional warning sink. Omitted means diagnostics are dropped (the registry still
+ *   never throws); a throwing sink is swallowed for the same reason.
+ * @returns the registry; every member is total.
+ */
+export function createSessionNotices(logger) {
+    const entries = [];
+    /** notice id → the session ids it was already delivered to (the once-per-session latch). */
+    const delivered = new Map();
+    const warn = (message) => {
+        try {
+            logger?.warn(message);
+        }
+        catch {
+            // A logging failure must never break the prompt path this registry exists to serve.
+        }
+    };
+    const reasonOf = (error) => {
+        try {
+            if (error instanceof Error && typeof error.message === 'string' && error.message !== '')
+                return error.message;
+            return String(error);
+        }
+        catch {
+            return 'unknown';
+        }
+    };
+    const wasDelivered = (id, sessionId) => delivered.get(id)?.has(sessionId) === true;
+    const latch = (id, sessionId) => {
+        let sessions = delivered.get(id);
+        if (sessions === undefined) {
+            sessions = new Set();
+            delivered.set(id, sessions);
+        }
+        sessions.add(sessionId);
+    };
+    return {
+        register(spec, state) {
+            try {
+                const problem = specProblem(spec, state);
+                if (problem !== undefined) {
+                    warn(`session-notices: 忽略一个非法 notice — ${problem}`);
+                    return;
+                }
+                if (entries.some(entry => entry.id === spec.id)) {
+                    // "An id is emitted at most once" only has one meaning: the first registration owns the id.
+                    warn(`session-notices: notice id 重复，保留先注册的那个 — ${spec.id}`);
+                    return;
+                }
+                // Snapshot the delivery fields: the registry's decisions (ordering and the returned body) must
+                // not change because the caller later mutated the object it registered. `when` is validated
+                // above but belongs to the caller's own mapping — the registry matches on `state()` alone.
+                entries.push({
+                    id: spec.id,
+                    severity: spec.severity,
+                    body: spec.body,
+                    state,
+                    order: entries.length,
+                });
+            }
+            catch (error) {
+                warn(`session-notices: 注册 notice 失败，已忽略（${reasonOf(error)}）`);
+            }
+        },
+        consume(sessionId, options) {
+            try {
+                if (typeof sessionId !== 'string' || sessionId === '') {
+                    warn('session-notices: consume 需要一个非空的 session id');
+                    return [];
+                }
+                if (options?.ownerOnly !== true)
+                    return [];
+                const matched = [];
+                for (const entry of entries) {
+                    if (wasDelivered(entry.id, sessionId))
+                        continue;
+                    let active;
+                    try {
+                        active = entry.state();
+                    }
+                    catch (error) {
+                        // Skipped, NOT latched: the predicate failed, which says nothing about the notice itself.
+                        warn(`session-notices: notice ${entry.id} 的 state() 抛错，本次跳过（${reasonOf(error)}）`);
+                        continue;
+                    }
+                    if (active !== true)
+                        continue;
+                    matched.push({ id: entry.id, body: entry.body, rank: SEVERITY_RANK[entry.severity], order: entry.order });
+                }
+                matched.sort((left, right) => left.rank - right.rank || left.order - right.order);
+                const lines = [];
+                for (const item of matched) {
+                    lines.push(item.body);
+                    latch(item.id, sessionId);
+                }
+                return lines;
+            }
+            catch (error) {
+                warn(`session-notices: consume 失败，本次不返回任何 notice（${reasonOf(error)}）`);
+                return [];
+            }
+        },
+    };
+}
+//# sourceMappingURL=session_notices.js.map