@treeseed/dsh-chapters 0.1.17 → 0.1.18

package/lib/preset.d.ts

@@ -1,55 +1,46 @@
 /**
- * The `chapters` agent preset: its composition, and the ONLY sanctioned way this
- * plugin makes a preset EXIST on a host that composes presets from declaration
- * rows (>= 0.1.7-alpha.1; "Nothing reads $DSH_HOME/.agent-presets any more").
+ * The `chapters` agent preset row — our implementation of the host's own
+ * `@deepseek-ai/dsh-agent-preset` declaration row, mounted from the bundle patch
+ * (`cordis.patch.yml`, row id `preset-chapters`), so the preset is a visible Loader entry
+ * exactly like `preset-standard` / `preset-ptc` rather than something a plugin does aside.
  *
- * WHY THIS FILE IS CODE AND NOT A SHIPPED PATCH LAYER
- * ---------------------------------------------------
- * The host's idiom is a `@deepseek-ai/dsh-agent-preset` row carried by a bundle
- * patch layer, listed in `package.json` `dsh.bundle.patch`. Shipping that row as
- * a SECOND layer means `dsh.bundle.patch` becomes an ARRAY, and both halves of
- * that are fatal on a pre-0.1.7 host — measured on the pinned e2e closure
- * (0.1.5-rc.1), not reasoned about:
- *
- *   - array `patch`: `TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must
- *     be of type string. Received an instance of Array` at
- *     `dsh-app-boot/lib/index.js:853` (`join(packageDir, declared)`) — the host
- *     never boots.
- *   - the row itself, in ANY layer a legacy host reads:
- *     `dsh: plugin tree failed to load: ... failed to import loader entry
- *     preset-chapters (@deepseek-ai/dsh-agent-preset): Cannot find package` — a
- *     legacy host's plugin tree aborts the boot on one unresolvable row.
- *   - gating it with `disabled: !!js get('agentPresets')?.register === undefined`
- *     does not work either: the Loader evaluates `disabled` BEFORE services are
- *     mounted, so the expression is truthy on a 0.2.x host too and the row never
- *     registers (measured: `preset-v2 … failed to import`, roster without it).
+ * WHY OUR ROW AND NOT THE HOST PACKAGE DIRECTLY
+ * --------------------------------------------
+ * A preset can be unusable in two ways and both are total: one unresolvable child row makes
+ * the WHOLE preset `broken` (`mountPreset` throws on any failed row → `record.broken` →
+ * `retain()` refuses with `agent-preset/invalid`), which is the same user-visible failure as
+ * a missing preset — every chapters session stops composing while its durable log sits there
+ * intact. Measured on the stable release with a composition copy-anchored to the alpha:
+ * `@deepseek-ai/dsh-tool-schedule` is not published at 0.2.0-rc.2 at all, and the boot said
+ * `preset "chapters" is DECLARED BUT BROKEN — tool-schedule … never started`.
  *
- * Registering through `ctx.get('agentPresets').register(definition)` is the same
- * call the host's own declaration-row plugin makes
- * (`dsh-agent-preset/lib/index.js`: `[Service.init]` → `this.ctx.agentPresets.register(this.config)`),
- * made from a row that resolves on EVERY host: this package. The tradeoff is
- * honest and stated in docs/contract.md: the composition is not visible in a
- * patch-layer dump, so the roster (not a file) is the evidence — which is the
- * rule this module enforces anyway.
+ * So this row does what the host's does, plus drop-what-will-not-load. It also refuses to
+ * brick a host predating the mechanism: a `@deepseek-ai/dsh-agent-preset` row is
+ * unresolvable before 0.1.7-alpha.1, and ONE unresolvable row aborts a legacy plugin tree
+ * (`plugin tree failed to load: … Cannot find package`), while a row naming our own package
+ * resolves wherever our package runs. The support floor is 0.2.0, so that is now
+ * belt-and-braces rather than the reason — and it is why the row plugin is ours.
  *
- * WHY ROWS ARE PRUNED AGAINST THE INSTALLED HOST
- * ----------------------------------------------
- * The host's standard plugin list is not stable across the versions this package
- * must serve. Measured against published `@deepseek-ai/dsh-web-app` presets:
- * 0.2.0-rc.1/rc.2 lack `dsh-time-context` and `dsh-tool-schedule`;
- * `dsh-tool-schedule` is not published at 0.2.0-rc.x AT ALL (first real version
- * 0.2.1-alpha.1), and `dsh-plugin-market` exists only at 0.2.1-alpha.4. One
- * unresolvable row does not degrade: `mountPreset` throws on any failed row, the
- * registry stores it as `record.broken`, and `retain()` then refuses with
- * `agent-preset/invalid` — every session choosing `chapters` stops composing,
- * while its durable log sits there intact. So a row whose package does not
- * resolve is DROPPED here and reported, instead of taking the preset down.
+ * WHAT IS COPIED FROM THE HOST'S PLUGIN, LINE FOR LINE
+ * ---------------------------------------------------
+ *  - `static inject = ['agentPresets']` — the registry's shape, never a version test.
+ *  - `static [EntryGroup.key] = true` — "preserve child expressions until their own plugins
+ *    activate". Without it the Loader interpolates `!!js` against the HOST context, and
+ *    `disabled: !!js process.platform === 'win32'` stops belonging to the child row that
+ *    owns it.
+ *  - `[Service.init]` `yield`s the registry's disposer, so Cordis owns the registration's
+ *    lifetime. That also disposes of the trap the first draft fell into: calling
+ *    `ctx.effect(disposer)` from `apply()` fires when the apply FIBER finishes, which
+ *    un-registered the preset the instant it had been registered (measured on 0.2.0-rc.2:
+ *    `register()` reported success while the roster came back without `chapters`).
  *
  * @module dsh-chapters/src/preset
  */
-/** One mounted plugin row of a preset composition (the Loader's own shape).
- * A group row carries its children in `config`; an ordinary row carries a
- * config map — the Loader accepts both under the same key. */
+import { Service } from '@deepseek-ai/cordis';
+import { EntryGroup } from '@deepseek-ai/cordis-plugin-loader';
+import z from '@deepseek-ai/schemastery';
+/** One mounted plugin row of a preset composition (the Loader's own shape). A group row
+ *  carries its children in `config`; an ordinary row carries a config map. */
 export interface PresetRow {
     id: string;
     name: string;
@@ -58,99 +49,75 @@ export interface PresetRow {
     group?: boolean;
     isolate?: Record<string, boolean>;
 }
-/** The `AgentPreset` Config the host registers (`dsh-agent-preset/lib/index.js:13-20`). */
+/** The preset definition, in the shape `AgentPresetRegistry.register()` accepts — the host
+ *  plugin's own Config: id, name?, description?, order, plugins. */
 export interface PresetDefinition {
     id: string;
-    name: string;
-    description: string;
-    order: number;
+    name?: string;
+    description?: string;
+    order?: number;
     plugins: PresetRow[];
 }
-/**
- * WHY THE DELEGATION ROWS CARRY NO `toolFilter`, although the host's own alpha.1/alpha.2
- * list denied `schedule_*` there.
- *
- * Measured on a real 0.2.1-alpha.4 boot: `tool-subagent` does NOT strip an unknown key —
- * it rejects the removed one outright, and the WHOLE preset goes broken:
- *   `tool-subagent: toolFilter is no longer supported; configure persona and tool plugins
- *    in an Agent Preset and select it with agentPreset (spawn only)`
- * while the same composition on 0.2.0-rc.2 (which still accepts `toolFilter`) mounts. So a
- * key that one supported host accepts and the next one THROWS on is worse than dropping it:
- * the deny list protected nothing on rc.2 (no schedule tools exist there at all) and would
- * break every chapters session on the alpha. The general rule this incident writes down:
- * carry only config keys EVERY supported host accepts, and let the roster line — not a
- * file on disk — be the evidence that the composition is usable.
- */
-/**
- * The chapters preset: the host's standard coding-agent composition with EXACTLY
- * four deltas, each one a product decision of ours.
- *
- *  1. `compaction-basic` → `@treeseed/dsh-chapters/engine` (thresholdRatio 0.9):
- *     the zero-inference `summarize()` — chapters from the log, no model tokens.
- *  2. `tool-result-pruner.thresholdChars` 8192 → 1000000, deliberately dormant:
- *     chapters defer oversized results at ARCHIVE time (verbatim bodies +
- *     artifact references), never in-surface, where a prune is a prefix cliff on
- *     local hardware.
- *  3. the persona gains the PLOT: suffix (plot carriage through in-place
- *     checkpoints) and keeps no `{{cwd}}` (see PLOT_SUFFIX).
- *  4. `tool-ralph` mounted ENABLED — the bounded goal loop the continuation
- *     children run. The host ships it disabled; enabling it here is ours.
- *
- * @param platform the platform the shell-gated rows are decided against; a
- *        parameter so the rows are testable on any machine.
- */
-export declare function chaptersPresetRows(platform?: NodeJS.Platform, thresholdRatio?: number): PresetRow[];
-/** The preset identity. `config.id` is DURABLE STATE: every continuation child's
- *  log records it as `agent-preset/selected`, so renaming it orphans those
- *  sessions (`agent-preset/not-found` on open). */
+/** The preset identity. `config.id` is DURABLE STATE: every continuation child's log
+ *  records it as `agent-preset/selected`, so renaming it orphans those sessions. */
 export declare const CHAPTERS_PRESET_ID = "chapters";
-export declare function chaptersPresetDefinition(platform?: NodeJS.Platform, thresholdRatio?: number): PresetDefinition;
-/** A row whose own module cannot be imported would activate as failed, and one
- *  failed row makes the WHOLE preset broken (`mountPreset` throws) — so it is
- *  dropped, with the reason, instead of taking every chapters session down.
+/**
+ * Drop rows whose module cannot be imported, keeping the group structure intact.
  *
- *  The probe is asked with the row's FULL specifier, so a package that exists but
- *  no longer exports the subpath (`.../tools`, `.../list-agents`) is caught too —
- *  those are the renames that eat presets.
+ * The probe is asked with the row's FULL specifier, so a package that still exists but no
+ * longer exports the subpath a row names (`…/tools`, `…/list-agents`) is caught too — those
+ * renames are what eat presets between host versions.
  *
  * @param rows the composition, groups included.
  * @param resolvable asked with each row's module specifier. MUST NOT throw.
+ * @returns the composition to register, and every drop NAMED — a silent drop is how a
+ *          preset loses a tool nobody notices.
  */
-export declare function pruneResolvableRows(rows: PresetRow[], resolvable: (specifier: string) => boolean): {
+export declare function pruneUnresolvableRows(rows: PresetRow[], resolvable: (specifier: string) => boolean): {
     kept: PresetRow[];
     dropped: string[];
 };
-/** What registering a preset can end up as. Every arm has its own log line and
- *  its own remedy, because the silent case is the one that cost a human hours. */
+/** What registering a preset can end up as. Every arm has its own log line and its own
+ *  remedy, because the silent case is the one that cost a human hours. */
 export type RegisterOutcome = {
     state: 'registered';
-}
-/** config.installChaptersPreset=false: the operator owns the preset, we do not register. */
- | {
-    state: 'disabled';
-} | {
-    state: 'already-declared';
 } | {
     state: 'pruned';
     dropped: string[];
+} | {
+    state: 'already-declared';
 } | {
     state: 'unsupported';
 } | {
     state: 'failed';
     reason: string;
 };
-/** The narrow surface of `ctx.get('agentPresets')` this module uses. */
+/** The narrow surface of `ctx.get('agentPresets')` this row uses. */
 export interface PresetRegistryLike {
     register?: (definition: PresetDefinition) => Promise<() => Promise<void>>;
     list?: () => Promise<unknown>;
-    /** Host-side inventory of every declared preset and its mounted rows —
-     *  `compositionInventory()` in `@deepseek-ai/dsh-agent-preset-registry`. */
+    /** `compositionInventory()` in `@deepseek-ai/dsh-agent-preset-registry`: every declared
+     *  preset with its mounted rows and their Loader states. */
     compositionInventory?: () => Promise<unknown>;
 }
-/** One mounted row of a live preset composition, as the host's own inventory reports it.
+/**
+ * Register a declared preset, dropping rows this host cannot import.
+ *
+ * Split out of the plugin class so every arm is unit-testable without a host: the caller
+ * hands in the registry surface and a resolver.
+ *
+ * @returns the outcome AND the disposer the registry hands back — the caller must keep it
+ *          alive for the row's lifetime, which is what yielding it from `[Service.init]`
+ *          does; nothing else has the right lifetime (see the module header).
+ */
+export declare function registerPrunedPreset(presets: PresetRegistryLike | undefined, definition: PresetDefinition, resolvable: (specifier: string) => boolean): Promise<{
+    outcome: RegisterOutcome;
+    disposer?: () => Promise<void>;
+}>;
+/** One mounted row of a live preset composition, as the host's inventory reports it.
  *  `fiberState` is the Loader's state for that row; an enabled row that is not `active`
  *  cannot serve a session, and the roster's `broken` flag reports that only for the whole
- *  mount — which is why the witness asks for the rows too. */
+ *  mount — which is why the witness asks for the rows as well. */
 export interface InventoryRow {
     entryId?: string;
     moduleName?: string;
@@ -165,27 +132,55 @@ export interface InventoryEntry {
 }
 /** Find one preset in an inventory response, tolerating a missing or odd shape. */
 export declare function inventoryEntry(raw: unknown, presetId: string): InventoryEntry | undefined;
-/** Enabled rows of one preset that are not active. A row `pending` a host service can
- *  still activate later, so this is reported apart from `broken`, never as a refusal. */
+/** Enabled rows of one preset that are not active. A row `pending` a host service can still
+ *  activate later, so this is reported apart from `broken` and never as a refusal. */
 export declare function unusableRows(entry: InventoryEntry | undefined): string[];
 /**
- * Make the `chapters` preset exist on a host that composes presets from
- * declaration rows, and say what happened.
+ * Whether a module specifier can be imported from THIS package's resolution family.
  *
- * @param presets the host's `agentPresets` service, or undefined on a host that
- *        has no preset registry at all (then the legacy directory copy is the
- *        delivery, and this returns 'unsupported').
- * @param dispose owner for the disposer the registry hands back — registering
- *        without it would leave a standing preset mount after unmount.
+ * Two limits are the host's, not ours to paper over: a RELATIVE specifier resolves without
+ * touching the filesystem (so a file-URL row would always be reported resolvable — the
+ * composition uses package specifiers only, and the drift test pins that), and a name that
+ * resolves is not yet a name that ACTIVATES, which is what the roster line reports as
+ * `DECLARED BUT BROKEN`. Never throws: an unresolvable specifier is the answer.
  */
-export declare function registerChaptersPreset(presets: PresetRegistryLike | undefined, opts: {
-    resolvable: (specifier: string) => boolean;
-    platform?: NodeJS.Platform;
-    /** Engine pressure threshold for the realm row; the host plane's
-     *  `config.compactionThresholdRatio` is what feeds it (no hardcoded tunables). */
-    thresholdRatio?: number;
-    dispose: (disposer: () => Promise<void>) => void;
-}): Promise<{
-    outcome: RegisterOutcome;
-    definition: PresetDefinition;
-}>;
+export declare function resolvableFromThisPackage(specifier: string): boolean;
+/** The narrow slice of the Cordis context this row needs. */
+interface RowCtx {
+    agentPresets: PresetRegistryLike;
+    logger?: {
+        info?: (m: string) => void;
+        warn?: (m: string) => void;
+    };
+}
+/**
+ * The declaration row. `config` IS the preset definition, exactly as the host's
+ * `AgentPreset` plugin consumes it, so a profile patch can override `preset-chapters`
+ * wholesale or `disabled: true` it — the two things a runtime registration done in
+ * `apply()` cannot offer, and the reason this is a row.
+ */
+export default class ChaptersPresetRow {
+    static inject: readonly ["agentPresets"];
+    /** Preserve child `!!js` expressions until their own plugins activate. */
+    static [EntryGroup.key]: boolean;
+    static Config: z<Schemastery.ObjectS<{
+        id: z<string, string>;
+        name: z<string, string>;
+        description: z<string, string>;
+        order: z<number, number>;
+        plugins: z<any[], any[]>;
+    }>, Schemastery.ObjectT<{
+        id: z<string, string>;
+        name: z<string, string>;
+        description: z<string, string>;
+        order: z<number, number>;
+        plugins: z<any[], any[]>;
+    }>>;
+    ctx: RowCtx;
+    config: PresetDefinition;
+    constructor(ctx: RowCtx, config: PresetDefinition);
+    /** Registers, then yields the disposer so Cordis owns the registration's lifetime — the
+     *  host's own row plugin does exactly this (`yield await this.ctx.agentPresets.register(…)`). */
+    [Service.init](): AsyncGenerator<() => Promise<void>, void>;
+}
+export {};