@avantf/dsh-plugin-base 0.5.3 → 0.6.1

package/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,CAs/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/lib/provisioner.js

@@ -744,7 +744,10 @@ 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);

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

package/lib/state.d.ts

@@ -58,7 +58,14 @@ export type StatusRead = {
 } | {
     readonly kind: 'unreadable';
 };
-/** Read `status.json`; a newer schema yields `too-new`. */
+/**
+ * Read `status.json`; a newer schema yields `too-new`.
+ *
+ * A STRUCTURALLY damaged file (rows not an array, a row that is not an object, a row without
+ * `key`/`version`) is `unreadable`, never `ok` with fewer rows: a dropped row silently drops a
+ * reference, and a reader that treats the result as the complete reference list (GC) would then
+ * delete a live root. `unreadable` is the "cannot tell" the callers already know how to handle.
+ */
 export declare function readStatus(fs: ProvisionFs, home: string): Promise<StatusRead>;
 /** Merge two row sets by `key × version`; newer `updated_at` wins, `items`/`plugins` are unioned. */
 export declare function mergeRows(current: readonly StatusRow[], incoming: readonly StatusRow[]): readonly StatusRow[];

package/lib/state.d.ts.map

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

package/lib/state.js

@@ -52,7 +52,14 @@ export async function writeLayout(fs, home, layout, writtenBy) {
     const file = { schemaVersion: LAYOUT_SCHEMA_VERSION, layout, writtenBy };
     await fs.atomicWrite(layoutPath(home), new TextEncoder().encode(`${JSON.stringify(file, null, 2)}\n`));
 }
-/** Read `status.json`; a newer schema yields `too-new`. */
+/**
+ * Read `status.json`; a newer schema yields `too-new`.
+ *
+ * A STRUCTURALLY damaged file (rows not an array, a row that is not an object, a row without
+ * `key`/`version`) is `unreadable`, never `ok` with fewer rows: a dropped row silently drops a
+ * reference, and a reader that treats the result as the complete reference list (GC) would then
+ * delete a live root. `unreadable` is the "cannot tell" the callers already know how to handle.
+ */
 export async function readStatus(fs, home) {
     const path = statusPath(home);
     if (!(await exists(fs, path)))
@@ -63,15 +70,17 @@ export async function readStatus(fs, home) {
     const schemaVersion = typeof raw['schemaVersion'] === 'number' ? raw['schemaVersion'] : 0;
     if (schemaVersion > STATUS_SCHEMA_VERSION)
         return { kind: 'too-new' };
-    const rows = Array.isArray(raw['rows']) ? raw['rows'] : [];
+    const rows = raw['rows'];
+    if (!Array.isArray(rows))
+        return { kind: 'unreadable' };
     const parsed = [];
     for (const row of rows) {
         if (!isRecord(row))
-            continue;
+            return { kind: 'unreadable' };
         const key = str(row['key']);
         const version = typeof row['version'] === 'string' ? row['version'] : undefined;
         if (key === undefined || version === undefined)
-            continue;
+            return { kind: 'unreadable' };
         const lastError = isRecord(row['last_error']) ? row['last_error'] : undefined;
         const code = lastError === undefined ? undefined : str(lastError['code']);
         const detail = lastError === undefined ? undefined : str(lastError['detail']);
@@ -165,6 +174,13 @@ export async function persistStatus(fs, lock, home, rows, logger) {
             const existing = await readStatus(fs, home);
             if (existing.kind === 'too-new')
                 return 'too-new';
+            // A structurally damaged file is NOT an empty one: overwriting it would drop the rows of every
+            // other plugin (and with them the references GC trusts), so it is left untouched and reported
+            // the same way an unreadable/corrupt file already was.
+            if (existing.kind === 'unreadable') {
+                logger.warn(`state: ${statusPath(home)} 结构不可读，本次不覆盖（保留原文，状态面按只读处理）`);
+                return 'read-only';
+            }
             const base = existing.kind === 'ok' ? existing.rows : [];
             const merged = mergeRows(base, rows);
             const file = { schemaVersion: STATUS_SCHEMA_VERSION, rows: merged };

package/lib/types.d.ts

@@ -5,7 +5,7 @@
 import type { ProvisionCode } from './errors.js';
 /** The kinds the framework ships providers for; these names are reserved.
  *  @stable */
-export type BuiltinKind = 'npm-package' | 'binary-archive' | 'model-cache';
+export type BuiltinKind = 'npm-package' | 'binary-archive' | 'model-cache' | 'runtime-deps';
 /** A kind is a namespaced string; third-party kinds must carry a prefix.
  *  @stable */
 export type Kind = BuiltinKind | (string & {});
@@ -260,6 +260,13 @@ export interface ProvisionFs {
     readlink(path: string): Promise<string | undefined>;
     copyFile(from: string, to: string): Promise<void>;
     chmod(path: string, mode: number): Promise<void>;
+    /** The canonical path with every symlink resolved.
+     *
+     *  Optional, and absent means "this seam cannot tell": a provider that identifies a directory
+     *  physically (the same host copy must name one shared root, however it was spelled) uses it when
+     *  present and falls back to the spelled path when not. It is read-only, so an fs that cannot
+     *  answer costs nothing but a weaker identity — never a failed install. */
+    realpath?(path: string): Promise<string>;
 }
 /** Control-plane mutual exclusion; the default is `<home>/.envinit/.lock`.
  *   @stable */
@@ -330,6 +337,12 @@ export interface Resolved {
     readonly source: ResourceSource;
     /** Environment additions for the handle (a managed binary's PATH). */
     readonly env?: Readonly<Record<string, string>>;
+    /**
+     * `true` when `install()` found an equivalent root already published (another process wrote it
+     * while this one waited) and reused it: nothing was placed by this call, so the core reports the
+     * item as `present` instead of `installed`. Omitted = the provider placed what it returned.
+     */
+    readonly reused?: boolean;
 }
 /** @stable */
 export interface ProviderContext {