@khorsheed/dsh-local-agent-dsh 0.2.0-rc.1 → 0.2.0

package/lib/types/provision.d.ts

@@ -5,29 +5,38 @@
  * `<scoped home>/profiles/<name>` — a manifest listing the official
  * `@deepseek-ai/dsh-base` layer, the family headless composition as the
  * profile's own patch layer (copied verbatim from the headless bundle's
- * `cordis.patch.yml`), and a single symlink resolving
- * `@khorsheed/dsh-local-agent-dsh-headless` from the sub-profile's
- * node_modules (the loader resolves the patch's insert rows through it).
+ * `cordis.patch.yml`), and `@khorsheed/dsh-local-agent-dsh-headless` in
+ * the sub-profile's node_modules (the loader resolves the patch's insert
+ * rows through it) — a copy of the bundle for the host profile, a symlink
+ * for the `-unit` twin and for the pinned single-profile form (see
+ * `HeadlessBundleMount`).
  * Everything else the boot needs (dsh-base and its whole dependency graph,
  * cordis, the healed `profiles/node_modules` fallback) is resolved from the
  * dsh installation anchor automatically, so provisioning costs no pnpm
  * install.
  *
- * A sub-profile may additionally carry a PRESET ROSTER: one appended patch
- * layer inserting `@deepseek-ai/dsh-agent-presets` with a `default` preset
- * id. Without it the sub-dsh's model-facing rows come from the host plane and
- * the agent reads them off the global layer — which is why "the same harness
- * under two presets" was not a thing a condition could ask for. With it, the
- * scope directory IS the capability face: two scopes whose rosters name two
- * presets are two subjects, and the difference is a file a person can read.
+ * A sub-profile may additionally compose an AGENT PRESET (host 0.2.0's
+ * declarative form): the bundle package that declares the preset — an
+ * `@deepseek-ai/dsh-agent-preset` row in its own bundle patch — joins the
+ * manifest's bundle list, and one appended patch layer inserts
+ * `@deepseek-ai/dsh-agent-preset-registry` with that preset as its
+ * `default`. Without it the sub-dsh's model-facing rows come from the host
+ * plane and the agent reads them off the global layer — which is why "the
+ * same harness under two presets" was not a thing a condition could ask for.
+ * With it, the scope directory IS the capability face: two scopes naming two
+ * presets are two subjects, and the difference is files a person can read.
  *
- * Where the preset DIRECTORY lives is the scope's business too. The roster
- * derives a user root of `<$DSH_HOME>/.agent-presets` and the sub-dsh runs
- * with `DSH_HOME` pointed at the scoped home, so a scope that keeps its own
- * copy there is resolved identically on the host and inside an evaluation
- * unit (which bind-mounts the scope, and nothing else). `provisionDshScope`
- * below is the entry that puts the copy there, records what the scope
- * composes in a file of its own, and rosters it with no `roots` at all.
+ * Where the preset PACKAGE lives is the scope's business too. The scope keeps
+ * its own copy at `<scoped home>/preset-packages/<id>` and the sub-profile
+ * resolves it through a RELATIVE symlink in its own `node_modules`, so the
+ * package is found identically on the host and inside an evaluation unit
+ * (which bind-mounts the scope, and nothing else). The copy comes from the
+ * evaluation instance's own installation of the same package, which is also
+ * what the instance's capability catalog measures. `provisionDshScope` below
+ * is the entry that makes the copy, records what the scope composes in a
+ * file of its own, and composes it. (0.1.x wrote a roster row for
+ * `@deepseek-ai/dsh-agent-presets` and a `<scoped home>/.agent-presets/<id>`
+ * directory instead; 0.2.0 ships neither the roster nor the directory scan.)
  *
  * It may also carry a PERMISSION BOUNDARY: one appended patch layer pinning
  * `sandbox-policy`'s mode and `user-approval`'s policy to one of dsh's own
@@ -36,7 +45,7 @@
  * sub-dsh on a developer's machine and the wrong one inside an evaluation
  * unit, where the container IS the boundary and nobody is there to answer an
  * approval prompt. The layer is a FILE in the scope directory for the same
- * reason the roster is: a scoped home bind-mounted into a unit carries its
+ * reason the preset layer is: a scoped home bind-mounted into a unit carries its
  * own boundary with it, and the value never has to ride the spawn env (where
  * every name enters the unit's composite fingerprint) or be baked into an
  * image.
@@ -52,31 +61,22 @@
  */
 /** Default name of the sub-dsh profile under the scoped home. */
 export declare const DEFAULT_SUB_PROFILE_NAME = "headless-local-agent-dsh";
-/** One preset root the sub-profile's roster scans. */
-export interface DshSubProfilePresetRoot {
-    /** Directory holding preset sub-directories; a leading `~` is expanded by the roster. */
-    path: string;
-    /** Trust level; the roster defaults it to `user`. */
-    trust?: 'system' | 'user';
-}
 /**
- * The preset roster a sub-profile composes.
+ * The agent preset a sub-profile composes.
  *
- * `id` is the preset every sub-dsh session of this scope runs on. With no
- * `roots`, the roster's own derived roots apply: the presets shipped inside
- * `@deepseek-ai/dsh-agent-presets`, then `<scoped home>/.agent-presets` —
- * the sub-dsh runs with `DSH_HOME` pointed at the scoped home, so dropping a
- * preset directory THERE is how a scope gets a preset of its own.
+ * `id` is the preset every sub-dsh session of this scope joins — the
+ * registry row's `default`. `package` is the bundle package that DECLARES it
+ * (an `@deepseek-ai/dsh-agent-preset` row in its bundle patch): it joins the
+ * sub-profile's bundle list and resolves from the sub-profile's own
+ * `node_modules`, where provisioning links the scope's copy of it. Absent
+ * `package` writes the registry row alone, for an id the sub-dsh's own
+ * installation already declares.
  */
 export interface DshSubProfilePreset {
-    /** The preset id the sub-dsh composes (`[a-z0-9][a-z0-9-]*`, a directory name). */
+    /** The preset id the sub-dsh composes (`[a-z0-9][a-z0-9-]*`). */
     id: string;
-    /** Extra roots to scan, in precedence order. */
-    roots?: readonly DshSubProfilePresetRoot[];
-    /** Keep the roster's bundled presets (default true, the roster's own default). */
-    includeShippedRoot?: boolean;
-    /** Keep `<scoped home>/.agent-presets` (default true, the roster's own default). */
-    includeUserRoot?: boolean;
+    /** The bundle package declaring that preset. */
+    package?: string;
 }
 /**
  * A sub-dsh permission preset: dsh's own three-word vocabulary, spelled the
@@ -87,6 +87,8 @@ export interface DshSubProfilePreset {
 export type DshSubProfilePermissions = 'read-only' | 'workspace-write' | 'danger-full-access';
 /** Config the provisioning step reads. */
 export interface DshSubProfileConfig {
+    /** Local launches only: read a per-process model snapshot from the private launch environment. */
+    inheritModelConfiguration?: boolean;
     /** Sub-dsh profile name under the scoped home. */
     profileName?: string;
     /**
@@ -96,9 +98,19 @@ export interface DshSubProfileConfig {
      */
     headlessBundleDir?: string;
     /**
-     * Compose a preset roster into the sub-profile. Absent leaves the
+     * The headless bundle directory as an evaluation UNIT sees it (the image's
+     * own install, `/opt/dsh-headless/node_modules/@khorsheed/dsh-local-agent-dsh-headless`
+     * on the dataset image). Present, provisioning writes a second sub-profile,
+     * `<profileName>-unit`, identical but for that symlink target, and
+     * container rounds launch it — so the host profile can link the bundle THIS
+     * instance resolves (its own host line) while the unit keeps the image's.
+     * Absent, both kinds of round share one profile, as before this existed.
+     */
+    unitHeadlessBundleDir?: string;
+    /**
+     * Compose an agent preset into the sub-profile. Absent leaves the
      * sub-profile exactly as every scope had it before this field existed: no
-     * roster row, and the agent reading the global layer.
+     * registry row, and the agent reading the global layer.
      */
     preset?: DshSubProfilePreset;
     /**
@@ -110,22 +122,23 @@ export interface DshSubProfileConfig {
     permissions?: DshSubProfilePermissions;
 }
 /**
- * The roster package the roster row names.
+ * The registry package the registry row names.
  *
  * Deliberately NOT symlinked into the sub-profile the way the headless bundle
  * is. The headless bundle is a `@khorsheed` package the dsh installation does
- * not carry, so it must be linked in from the plugin installation; the roster
- * is an OFFICIAL package, already in the installation anchor's closure beside
- * `@deepseek-ai/dsh-base`. Linking a second copy would give it a second
- * `@deepseek-ai/cordis` — and cordis does service lookup and type checks by
- * instance identity, so the symptom would be silently missing services rather
- * than an error (the same failure the dual-filesystem contract in the README
- * describes for the bundle). A deployment whose anchor genuinely lacks the
- * roster gets the loader's own "cannot resolve" message, which names the
+ * not carry, so it must be linked in from the plugin installation; the
+ * registry is an OFFICIAL package, already in the installation anchor's
+ * closure beside `@deepseek-ai/dsh-base`. Linking a second copy would give it
+ * a second `@deepseek-ai/cordis` — and cordis does service lookup and type
+ * checks by instance identity, so the symptom would be silently missing
+ * services rather than an error. A deployment whose anchor genuinely lacks the
+ * registry gets the loader's own "cannot resolve" message, which names the
  * module better than provisioning could.
  */
-export declare const PRESET_ROSTER_MODULE = "@deepseek-ai/dsh-agent-presets";
-/** A preset id doubles as a directory name — the roster's own rule. */
+export declare const PRESET_REGISTRY_MODULE = "@deepseek-ai/dsh-agent-preset-registry";
+/** The declarative preset row a preset bundle package carries in its patch. */
+export declare const PRESET_ROW_MODULE = "@deepseek-ai/dsh-agent-preset";
+/** A preset id doubles as a directory name inside the scope. */
 export declare const SUB_PROFILE_PRESET_ID_RE: RegExp;
 /**
  * Resolve the family headless bundle's directory. The bundle is a declared
@@ -136,25 +149,31 @@ export declare const SUB_PROFILE_PRESET_ID_RE: RegExp;
  */
 export declare function resolveHeadlessBundleDir(config?: DshSubProfileConfig): string;
 /**
- * The roster layer appended to the sub-profile's patch, or `''` when the
+ * The preset layer appended to the sub-profile's patch, or `''` when the
  * sub-profile composes no preset.
  *
+ * One insert of the 0.2.0 preset registry with the preset as its `default`:
+ * every sub-dsh session that names no preset joins this one (the headless
+ * agent loader mounts it through the registry's `mount`). The preset's own
+ * declaration rides the bundle layer — the package that declares it is in
+ * the manifest's bundle list — so this layer never repeats the composition.
+ *
  * It is a SEPARATE patch operation appended after the headless bundle's own
  * list, which is what keeps the two independent: an upgraded headless bundle
- * rewrites its half and the roster survives, and dropping the preset drops
+ * rewrites its half and the preset survives, and dropping the preset drops
  * exactly these lines.
- * @param preset - the roster to compose, or undefined for none.
+ * @param preset - the preset to compose, or undefined for none.
  * @returns the YAML text to append (already newline-terminated), or `''`.
  */
-export declare function presetRosterLayer(preset: DshSubProfilePreset | undefined): string;
+export declare function presetRegistryLayer(preset: DshSubProfilePreset | undefined): string;
 /**
  * The preset id a provisioned sub-profile's patch composes, read back from
- * the file. The roster layer is generated, so it is also parseable: a lock
+ * the file. The preset layer is generated, so it is also parseable: a lock
  * check or a status surface can answer "which preset does this scope run?"
  * without booting the sub-dsh.
  * @param homeDir - the harness scoped home.
  * @param profileName - the sub-profile name (default {@link DEFAULT_SUB_PROFILE_NAME}).
- * @returns the preset id, or undefined when the sub-profile composes no roster.
+ * @returns the preset id, or undefined when the sub-profile composes no preset.
  */
 export declare function readSubProfilePreset(homeDir: string, profileName?: string): string | undefined;
 /**
@@ -193,40 +212,59 @@ export declare function permissionBoundaryLayer(permissions: DshSubProfilePermis
  * @returns the pinned mode, or undefined when the sub-profile pins none.
  */
 export declare function readSubProfilePermissions(homeDir: string, profileName?: string): DshSubProfilePermissions | undefined;
+/** Suffix of the evaluation-unit twin of a sub-profile (see `unitHeadlessBundleDir`). */
+export declare const UNIT_PROFILE_SUFFIX = "-unit";
+/**
+ * The profile name an evaluation UNIT launches for this config: the
+ * `-unit` twin when one is configured, else the one sub-profile.
+ * @param config - provisioning config.
+ * @returns the profile name a container round passes to `--profile`.
+ */
+export declare function unitSubProfileName(config?: DshSubProfileConfig): string;
 /**
  * Provision (idempotently) the sub-dsh headless profile in the harness
  * scoped home: manifest, the headless patch as the profile's own patch
- * layer, and the bundle symlink. A file whose content already matches is
- * left untouched, so re-running after a restart is a no-op; a drifted file
- * (an upgraded headless bundle, or a profile provisioned by the pre-T6
- * scheme whose manifest listed the headless bundle as a layer) is rewritten,
- * which heals it before the sub-dsh boots.
+ * layer, and the headless bundle (a copy; a symlink in the `-unit` twin or under a lone `headlessBundleDir` pin) — plus, when a preset package is composed,
+ * the relative link resolving it from the scope's own copy, and, when
+ * `unitHeadlessBundleDir` is configured, the `-unit` twin a container round
+ * launches. A file whose content already matches is left untouched, so
+ * re-running after a restart is a no-op; a drifted file (an upgraded headless
+ * bundle, or a profile provisioned by an earlier scheme) is rewritten, which
+ * heals it before the sub-dsh boots.
  * @param homeDir - the `dsh` harness's scoped home (its `$DSH_HOME` root).
  * @param config - profile naming and bundle-dir overrides.
- * @returns the absolute sub-profile directory.
+ * @returns the absolute (host) sub-profile directory.
  */
 export declare function provisionDshSubProfile(homeDir: string, config?: DshSubProfileConfig): string;
 /**
- * The preset root a harness home derives — the roster's own rule, spelled
- * here because this module has to write into it.
+ * Where a scope keeps its own copy of each preset PACKAGE it composes:
+ * `<scoped home>/preset-packages/<id>`. (0.1.x used `.agent-presets/<id>`,
+ * the directory roster's derived user root; 0.2.0 has no directory scan.)
  */
-export declare const USER_PRESET_DIR = ".agent-presets";
+export declare const SCOPE_PRESET_PACKAGES_DIR = "preset-packages";
+/**
+ * The scope's copy of one preset package.
+ * @param homeDir - the harness scoped home.
+ * @param id - the preset id.
+ * @returns the directory, whether or not it exists.
+ */
+export declare function scopePresetPackageDir(homeDir: string, id: string): string;
 /**
  * The scope's own declaration of what its sub-profile composes.
  *
  * A FILE in the scope directory, for the third time and the same reason as
- * the roster layer and the permission boundary: a scoped home bind-mounted
+ * the preset layer and the permission boundary: a scoped home bind-mounted
  * into an evaluation unit carries its own composition with it, and nothing
  * has to ride the spawn env or be baked into an image.
  *
  * It exists because the plugin's own `config` is instance-global — one
  * deployment, one answer — while a preset is a property of the SUBJECT. Two
- * scopes rostering two presets was therefore unexpressible, and the only way
- * to build it was to hand-append the roster layer to each scope's patch. That
+ * scopes composing two presets was therefore unexpressible, and the only way
+ * to build it was to hand-append the preset layer to each scope's patch. That
  * hand edit does not survive: this module regenerates the patch WHOLE, and
  * the registry re-provisions a scope the first time anything names it in a
- * fresh host process — so the roster silently disappears on the next restart,
- * and the next read-back reports a scope that rosters nothing.
+ * fresh host process — so the layer silently disappears on the next restart,
+ * and the next read-back reports a scope that composes nothing.
  */
 export declare const SCOPE_SUB_PROFILE_FILENAME = "sub-profile.json";
 /** What {@link SCOPE_SUB_PROFILE_FILENAME} may say. */
@@ -254,127 +292,136 @@ export declare function readScopeSubProfile(homeDir: string): DshScopeSubProfile
  */
 export declare function writeScopeSubProfile(homeDir: string, declaration: DshScopeSubProfile): void;
 /**
- * Every absolute filesystem path a preset composition names.
+ * Every absolute filesystem path a preset bundle patch names.
  *
  * An absolute path is the one thing in a composition that cannot be true in
  * two places at once, and a preset used as an evaluation factor is copied:
- * it is read on the host from the deployment's preset root, again from the
+ * it is read on the host from the instance's installation, again from the
  * scope's own copy, and a third time inside a unit where the scope is bound
  * at a different mount point. `skill-filesystem` resolves each
  * `customSkillDirs` entry with `resolve()`, so an absolute entry is taken as
  * written and a bare relative one resolves against the process's cwd —
  * neither travels.
  *
- * What does travel is the loader's own expression form, which the shipped
- * `cordis` preset already uses:
+ * What does travel is resolving the package's own directory through the
+ * loader's `baseUrl` (the declaring profile's root), the form the official
+ * web-app presets use:
  *
  * ```yaml
  * customSkillDirs:
- *   - !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('skills/', baseUrl))"
+ *   - !!js "process.getBuiltinModule('node:path').join(process.getBuiltinModule('node:path').dirname(process.getBuiltinModule('node:module').createRequire(baseUrl).resolve('<pkg>/package.json')), 'skills')"
  * ```
  *
- * `baseUrl` is the composition's own directory (the include rewrites it), so
- * the root resolves wherever the preset is installed.
- *
  * Unparsable YAML reports NO findings: the loader is the authority on whether
  * a composition loads, and refusing a preset because this reader could not
  * parse it would be this module overruling it.
- * @param text - the `agent.cordis.yml` content.
+ * @param text - the bundle patch content.
  * @returns the offending literals, in document order, deduplicated.
  */
 export declare function compositionAbsolutePaths(text: string): string[];
 /**
- * Whether two preset directories are the same directory, byte for byte.
+ * Whether two preset package directories are the same directory, byte for
+ * byte.
  *
  * This is the whole claim the evaluation rests on: a capability face carries
  * no filesystem path, so the fingerprint taken against the deployment's copy
  * describes the scope's copy exactly when the two hold the same bytes.
- * @param a - one preset directory.
+ * @param a - one preset package directory.
  * @param b - the other.
  * @returns true when both hold the same files with the same contents.
  */
 export declare function presetTreesEqual(a: string, b: string): boolean;
+/** One installed bundle package that declares a preset. */
+export interface DshPresetPackage {
+    /** The package name (what the sub-profile manifest lists). */
+    name: string;
+    /** The package directory, symlinks resolved. */
+    dir: string;
+}
+/**
+ * Find the bundle package, among a profile's direct dependencies, whose
+ * bundle patch declares preset `id`.
+ *
+ * This is how the 0.2.0 host itself learns the preset: a profile's direct
+ * `dsh.bundle`-declaring dependency mounts its patch, and the patch's
+ * `@deepseek-ai/dsh-agent-preset` row registers the id. Reading the same files
+ * is what lets a scope copy exactly the package the evaluation instance's
+ * capability catalog measures.
+ * @param profileDir - the instance profile directory (holding `package.json`).
+ * @param id - the preset id.
+ * @returns the declaring package, or undefined when none (or more than one) declares it.
+ */
+export declare function findPresetPackage(profileDir: string, id: string): DshPresetPackage | undefined;
 /** What {@link snapshotScopePreset} did. */
 export interface DshScopePresetSnapshot {
-    /** The scope's copy of the preset directory. */
+    /** The scope's copy of the preset package. */
     dir: string;
+    /** The package name the copy carries. */
+    packageName: string;
     /** Whether that copy is byte-for-byte the deployment's own. */
     matchesSource: boolean;
     /** Whether this call wrote it. */
     copied: boolean;
 }
 /**
- * Give one scope its own copy of a preset, from the deployment's preset root.
+ * Give one scope its own copy of a preset package, from the evaluation
+ * instance's own installation of it.
  *
- * The copy is what makes a preset reachable on BOTH paths. The roster derives
- * a user root of `<$DSH_HOME>/.agent-presets`, and the sub-dsh runs with
- * `DSH_HOME` pointed at the scoped home — which is `<scope>/.agent-presets`
- * on the host and `/creds/dsh/.agent-presets` inside an evaluation unit,
- * one directory, because the unit binds the scope. A roster pointed at the
- * deployment's root instead resolves on the host and names a path the unit
- * does not have.
+ * The copy is what makes a preset reachable on BOTH paths. The sub-profile
+ * resolves the package through a relative link to
+ * `<scope>/preset-packages/<id>`, which is one directory on the host and
+ * inside an evaluation unit, because the unit binds the scope.
  *
  * `refresh` is the difference between provisioning a condition and healing a
- * scope. A deliberate provision re-syncs from the deployment's copy, because
+ * scope. A deliberate provision re-syncs from the instance's copy, because
  * that is the moment a new lock is minted and an edited preset should be
  * picked up. Every other provisioning leaves an existing copy alone: nothing
- * may move the subject under a run.
+ * may move the subject under a run — and a healing call whose instance no
+ * longer carries the package keeps the copy, reporting `matchesSource: false`.
  * @param homeDir - the harness scoped home.
- * @param presetRoot - the deployment's preset root.
- * @param id - the preset id (a directory name in both roots).
+ * @param instanceProfileDir - the instance profile directory, or undefined when unknown.
+ * @param id - the preset id.
  * @param options - `refresh` re-syncs an existing copy.
  * @returns where the copy is and whether it matches the source.
- * @throws when the source is missing, is not a preset, or names an absolute path.
+ * @throws when no copy can be made: no installed package declares the id, or it is not a usable preset package.
  */
-export declare function snapshotScopePreset(homeDir: string, presetRoot: string, id: string, options?: {
+export declare function snapshotScopePreset(homeDir: string, instanceProfileDir: string | undefined, id: string, options?: {
     refresh?: boolean;
 }): DshScopePresetSnapshot;
-/**
- * The deployment's own preset root, when the caller names no other.
- *
- * The roster's own derivation, repeated here because the provisioning paths
- * that heal a scope (a host round, a live runtime) have no settings service
- * in reach: a non-blank `$DSH_HOME`, else the `~/.dsh` installation default
- * (the precedence of `resolveDshHome` in `@deepseek-ai/dsh-home-paths` —
- * the default was once hardcoded to `.dsh-official`, pointing a desktop
- * instance at another instance's home; 2026-09-30).
- */
-export declare function defaultPresetRoot(): string;
 /** Per-scope inputs {@link provisionDshScope} takes. */
 export interface DshScopeProvisionOptions {
     /**
      * The preset this scope composes. Present, it is authoritative: it is
      * persisted into the scope's own declaration and its copy is re-synced from
-     * the deployment's preset root. Absent, the scope's declaration decides.
+     * the instance's installation. Absent, the scope's declaration decides.
      */
     preset?: string;
-    /** The deployment's preset root; defaults to `<$DSH_HOME>/.agent-presets`. */
-    presetRoot?: string;
+    /**
+     * The evaluation instance's own profile directory, whose direct
+     * dependencies are searched for the package declaring the preset.
+     */
+    instanceProfileDir?: string;
 }
 /** What {@link provisionDshScope} left in the scope. */
 export interface DshScopeProvisioned {
     /** The sub-profile directory. */
     profileDir: string;
-    /** The preset the sub-profile now rosters, when it rosters one. */
+    /** The preset the sub-profile now composes, when it composes one. */
     preset?: string;
-    /** The scope's own copy of that preset, when it keeps one. */
+    /** The scope's own copy of that preset package, when it keeps one. */
     presetSnapshot?: {
         matchesSource: boolean;
     };
 }
 /**
- * Provision one scope: its own preset copy, its declaration, and the
- * sub-profile that rosters it.
+ * Provision one scope: its own preset package copy, its declaration, and the
+ * sub-profile that composes it.
  *
  * The preset resolves in one order, and the order is the decision: the
  * CALLER's explicit request, then the SCOPE's own declaration, then the
  * deployment's plugin config. The first is how a condition says which subject
  * this scope is; the second is how that survives a restart; the third is the
  * deployment-wide answer every scope had before either existed.
- *
- * A scope-owned preset rosters with NO `roots`. The roster's derived user
- * root is exactly the scope's copy on both paths, so leaving the roots alone
- * is what gives the host and the unit one resolution rule instead of two.
  * @param homeDir - the harness scoped home.
  * @param config - the deployment's sub-profile config.
  * @param options - per-scope inputs.