@deepseek-ai/dsh-agent-presets 0.0.1-rc.1

package/lib/types/authoring.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Copying, reading, and deleting locally authored presets.
+ *
+ * Authoring is confined to a `user` root: the shipped `.system` set is part of
+ * the deployment, and letting a browser rewrite it would turn "reset to a known
+ * preset" into something the same caller could have broken first.
+ *
+ * The only authoring write is a whole-directory copy of an existing preset.
+ * No caller supplies composition text: the inputs are ids the host resolves
+ * against its own roots plus an optional display name, so authoring grants no
+ * capability the copied preset did not already carry.
+ * @module @deepseek-ai/dsh-agent-presets/authoring
+ */
+import { type AgentPreset, type PresetRoot } from './types.ts';
+/** A preset id that cannot be used as a directory name under a root. */
+export declare class InvalidPresetIdError extends Error {
+    /** The rejected id. */
+    readonly presetId: string;
+    constructor(
+    /** The rejected id. */
+    presetId: string);
+}
+/** A copy target that is already occupied — a copy never overwrites. */
+export declare class PresetExistsError extends Error {
+    /** The id that is already taken. */
+    readonly presetId: string;
+    constructor(
+    /** The id that is already taken. */
+    presetId: string);
+}
+/** Authoring was attempted where the deployment allows none. */
+export declare class PresetNotWritableError extends Error {
+    /** What the caller tried to change, for the diagnostic. */
+    readonly presetId: string;
+    constructor(
+    /** What the caller tried to change, for the diagnostic. */
+    presetId: string, reason: string);
+}
+/**
+ * The root locally authored presets are written to.
+ * @param roots - the configured roots in precedence order.
+ * @returns the absolute path of the first `user` root.
+ * @throws when the deployment configured no writable root.
+ */
+export declare function writableRoot(roots: readonly PresetRoot[]): string;
+/**
+ * Read one preset's composition text.
+ * @param preset - the resolved preset.
+ * @returns the file's contents.
+ */
+export declare function readComposition(preset: AgentPreset): Promise<string>;
+/**
+ * Create a preset by copying an existing one's whole directory.
+ *
+ * The copy carries everything the source directory holds — composition,
+ * metadata, skill directories, assets — because a preset is its directory,
+ * not one file. Symlinks are dereferenced so the copy is self-contained
+ * rather than a set of links back into the install it was copied from.
+ *
+ * The copied metadata is then rewritten: the source's description is kept
+ * (the file is the author's to edit afterwards), but its name and roster
+ * `order` are not — a copy presenting itself identically to its source, or
+ * sorted into the shipped set's declared order, would make the roster stop
+ * distinguishing them. With no name given and no description to keep, the
+ * file is removed so the copy publishes nothing rather than a blank.
+ * @param roots - the configured roots; the first `user` one receives the copy.
+ * @param source - the resolved preset the copy starts from.
+ * @param id - the new preset's id, which becomes its directory name.
+ * @param name - display name for the copy; omitted falls back to the id.
+ * @returns the absolute path of the new preset directory.
+ * @throws when the id is unusable or already occupied on disk, or the
+ * deployment configures no writable root.
+ */
+export declare function copyComposition(roots: readonly PresetRoot[], source: AgentPreset, id: string, name?: string): Promise<string>;
+/**
+ * Delete a locally authored preset.
+ *
+ * A shipped preset is refused: it belongs to the deployment. A preset a live
+ * session mounted is NOT refused — the composition was read at creation and is
+ * never re-read, so that session keeps running exactly as it was.
+ * @param roots - the configured roots.
+ * @param preset - the resolved preset to remove.
+ * @throws when the preset ships with the deployment or lies outside the writable root.
+ */
+export declare function deleteComposition(roots: readonly PresetRoot[], preset: AgentPreset): Promise<void>;
+//# sourceMappingURL=authoring.d.ts.map

package/lib/types/discovery.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Filesystem discovery of agent presets. A preset is a directory holding
+ * {@link COMPOSITION_FILE}, optionally beside a {@link METADATA_FILE} carrying
+ * its display text; the directory name is the preset id. Discovery
+ * re-reads the roots on every call so a preset authored while the process is
+ * running is visible without a restart.
+ *
+ * Discovery also owns preset HEALTH: a directory whose composition is
+ * missing or unloadable is reported as a broken roster row rather than
+ * skipped. A skipped directory would still occupy its id on disk — the copy
+ * path refuses the name while no surface shows anything to delete — and a
+ * malformed composition would otherwise read as an ordinary preset until the
+ * first session fails to mount it.
+ * @module @deepseek-ai/dsh-agent-presets/discovery
+ */
+import { type AgentPreset, type PresetRoot } from './types.ts';
+/** The composition file that makes a directory a preset. */
+export declare const COMPOSITION_FILE = "agent.cordis.yml";
+/**
+ * Scan one root for preset directories.
+ *
+ * An absent root yields no presets rather than throwing: the user root does
+ * not exist until the first locally authored preset, and naming a default
+ * that no root supplies already fails loud at resolution.
+ *
+ * Every directory whose name is a usable preset id is a roster row — broken
+ * when its composition is missing or unloadable. A directory named outside
+ * {@link PRESET_ID} is skipped instead: no copy could ever claim that name,
+ * so it blocks nothing, and reporting `.DS_Store`-grade residue as broken
+ * presets would teach users to ignore the marker.
+ * @param root - the directory and the trust its presets inherit.
+ * @returns the root's presets ordered by id.
+ */
+export declare function scanRoot(root: PresetRoot): Promise<AgentPreset[]>;
+/**
+ * Scan every root in precedence order.
+ * @param roots - roots in precedence order; an earlier root wins a duplicate id.
+ * @returns every discovered preset, first-root-wins per id.
+ */
+export declare function discoverPresets(roots: readonly PresetRoot[]): Promise<AgentPreset[]>;
+//# sourceMappingURL=discovery.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,273 @@
+/**
+ * Agent presets: each session composes its model-facing plugin set from one
+ * preset `cordis.yml`, mounted ONCE per preset under a standing scope and
+ * joined by every agent that names it.
+ *
+ * The standing mount is what makes a preset one composition rather than one
+ * per session: its plugin instances, tool registrations, prompt sections, and
+ * projection units exist exactly once, keyed per session inside the plugins
+ * themselves (they predate presets and were written for a shared world). An
+ * agent joins by having its scope key parented to the mount's
+ * ({@link bindScopeParent}), which makes the mount's registrations visible to
+ * that agent's views and the mount's listeners receive that agent's events —
+ * and a host reader with no agent at all (a cold transcript read) resolves
+ * the same standing registrations by preset id.
+ *
+ * This package owns the preset vocabulary, filesystem discovery, and the
+ * guarded standing mount. It does not decide when an agent is created — the
+ * agent factory's `setup(agentCtx)` hook is the one supported call site,
+ * because only there is the join installed while the agent is still
+ * unpublished, so a rejected composition rolls the whole creation back.
+ * @module @deepseek-ai/dsh-agent-presets
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type ScopeKey } from '@deepseek-ai/dsh-scope';
+import { type AgentPreset, type Config } from './types.ts';
+/** Settings namespace carrying the user's chosen default preset. */
+export declare const SETTINGS_NAMESPACE = "agent-presets";
+/** The user-writable slice of this plugin's config. */
+export interface AgentPresetSettings {
+    /** Preset mounted when a session names none. */
+    default?: string;
+}
+/** Runtime schema for the user-writable slice. */
+export declare const AgentPresetSettingsSchema: z<AgentPresetSettings>;
+export { COMPOSITION_FILE, discoverPresets, scanRoot } from './discovery.ts';
+export { METADATA_FILE, readPresetMetadata, renderPresetMetadata, type PresetMetadata, } from './metadata.ts';
+export { inactiveRows, leakedServices, livePresetMounts, mountPreset, serviceForAgent, standingMountFor, type JoinedPresetMount, type PresetMount, } from './mount.ts';
+export { copyComposition, deleteComposition, InvalidPresetIdError, PresetExistsError, PresetNotWritableError, readComposition, writableRoot, } from './authoring.ts';
+export { resolveSessionPreset, type PresetBearingSession } from './session.ts';
+export { PresetMountError, UnknownPresetError } from './types.ts';
+export type { AgentPreset, Config, PresetRoot, PresetTrust } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        agentPresets: AgentPresets;
+    }
+}
+/**
+ * Registry over the deployment's agent presets.
+ *
+ * Discovery is unmemoized: `list()` and `resolve()` re-read the roots on every
+ * call so a preset authored while the process runs is visible immediately,
+ * and a preset deleted underneath a picker disappears from the next read.
+ */
+export declare class AgentPresets extends Service {
+    config: Config;
+    static inject: string[];
+    /** Runtime schema for the preset roster. */
+    static Config: z<Config>;
+    /**
+     * The user layer over `config.default`, present only while a settings
+     * provider is composed. Held rather than snapshotted so a hot-reloaded
+     * document takes effect without a restart.
+     */
+    private settings;
+    /**
+     * The settings service behind {@link settings}, held for the one write this
+     * service makes: clearing a user default it has just deleted.
+     */
+    private settingsService;
+    /**
+     * The service's own untraced context. Methods invoked through the traceable
+     * proxy see `this.ctx` rebound to the CALLER's context, which carries a
+     * shadow; a subtree minted from it resolves every service through that
+     * shadow's fiber instead of each entry's own inject store, so preset rows
+     * would fail on the very services they declare. Standing mounts must hang
+     * off the untraced original (the `tasks-local` selfCtx precedent).
+     */
+    private readonly selfCtx;
+    constructor(ctx: Context, config: Config);
+    /**
+     * The preset id mounted when a caller names none.
+     *
+     * Read per call rather than cached: the settings document is hot-reloaded, so
+     * changing the default takes effect on the next session created and leaves
+     * every running session on the preset it was composed from.
+     */
+    get defaultId(): string;
+    /**
+     * Every preset the configured roots currently supply.
+     * @returns the presets, first-root-wins per id.
+     */
+    list(): Promise<AgentPreset[]>;
+    /**
+     * Resolve one preset by id.
+     *
+     * A broken preset resolves — deleting one, reading one, and reporting one
+     * all need the row — and the mounting paths refuse it AFTER resolution
+     * through {@link resolveMountable}.
+     * @param id - the preset id, or `undefined` for {@link defaultId}.
+     * @returns the resolved preset.
+     * @throws when no configured root supplies that id.
+     */
+    resolve(id?: string): Promise<AgentPreset>;
+    /**
+     * Resolve one preset that is about to compose an agent, refusing a broken
+     * one with its discovery-reported reason. Failing here rather than inside
+     * the loader keeps the answer the same for every unloadable shape — ghost
+     * directory, unparsable YAML, rowless list — and spends no mount attempt
+     * on a composition discovery already read as unusable.
+     * @param id - the preset id, or `undefined` for {@link defaultId}.
+     * @returns the resolved, mountable preset.
+     * @throws when the preset is unknown or discovery reports it broken.
+     */
+    private resolveMountable;
+    /**
+     * Standing mounts by preset id, single-flight so two agents racing the
+     * first use of one preset share one composition. A settled failure is
+     * removed so a later session retries a preset whose file has been fixed; a
+     * settled success serves until the composition FILE visibly changes — each
+     * generation records its file stamp, and a stale stamp starts the next
+     * generation for sessions created afterwards. Sessions already joined keep
+     * the generation they run on; a superseded one is never disposed while the
+     * process lives (reclaimed only by whole-tree teardown), so editing files
+     * is bounded by how often compositions change, not by session count.
+     */
+    private readonly standing;
+    /**
+     * Parent bindings of the agents this roster composed, keyed by the agent's
+     * scope key. The binding is dsh-scope's only re-link capability; holding it
+     * here makes this service the sole authority that can move an agent between
+     * standing compositions. WeakMap: entries die with their agents.
+     */
+    private readonly bindings;
+    /**
+     * Compose one agent from a preset: ensure the preset's standing mount, then
+     * parent the agent's scope key to it so the mount's registrations and
+     * listeners cover this agent.
+     *
+     * Call from the agent factory's `setup(agentCtx)`; a rejection there rolls
+     * the agent creation back, so a broken preset never yields a half-composed
+     * session.
+     * @param agentCtx - the agent's scope context.
+     * @param id - the preset id, or `undefined` for {@link defaultId}.
+     * @returns the preset that was composed, for the caller to record.
+     * @throws when the preset is unknown or its composition is unusable.
+     */
+    mount(agentCtx: Context, id?: string): Promise<AgentPreset>;
+    /**
+     * Join one agent to the SAME standing composition another already runs on.
+     *
+     * This is how a child agent inherits its parent's capabilities. It is a bind,
+     * not a mount: the parent's generation is already composed, so the child gets
+     * that exact instance — the same plugin objects, the same tool registrations,
+     * the same prompt sections. Re-resolving the parent's preset by id instead
+     * would re-read the roster, and a composition file edited since the parent
+     * started would hand the child a DIFFERENT generation than the one its
+     * parent's history was produced under (and a preset deleted since would fail
+     * the child outright while its parent keeps running).
+     *
+     * Synchronous, and with no composition failure mode of its own — it reads no
+     * roster, mounts nothing, and touches no file — which is what lets a child
+     * creation window use it: the two in-process subagent drivers compose their
+     * children inside a synchronous `setup`. It still rejects a caller error, as
+     * the `@throws` below record.
+     *
+     * A parent that joined no preset — a rosterless deployment — yields no join
+     * and no error: there, the model-facing rows sit in the host composition and
+     * the child already sees them through the global layer.
+     * @param agentCtx - the joining agent's scope context.
+     * @param parentCtx - the scope context of the agent whose composition to join.
+     * @returns the preset id joined, or undefined when the parent joined none.
+     * @throws when `agentCtx` carries no scope, or has already joined a preset.
+     */
+    composeFrom(agentCtx: Context, parentCtx: Context): string | undefined;
+    /**
+     * The preset one live agent runs on.
+     *
+     * Read from the live scope chain rather than from the session, so it answers
+     * for an agent whose session has not recorded a preset yet — a child agent
+     * whose durable header is being built from its parent's composition.
+     * @param agentCtx - the agent's scope context.
+     * @returns the preset id, or undefined when the agent joined none.
+     */
+    composedPreset(agentCtx: Context): string | undefined;
+    /** Whether this deployment configures a root locally authored presets go to. */
+    get authorable(): boolean;
+    /**
+     * Read one preset's composition text.
+     * @param id - the preset id.
+     * @returns the composition exactly as stored.
+     * @throws when no configured root supplies that id.
+     */
+    read(id: string): Promise<string>;
+    /**
+     * Create a locally authored preset by copying an existing one whole.
+     *
+     * Copy is the only authoring write. Composition text never crosses this
+     * seam: the source is named by id and its directory is copied as it stands,
+     * so the copy is exactly as loadable as its source and authoring grants no
+     * capability the roster did not already carry. The copy is NOT mounted to
+     * validate — a source that mounts today yields a copy that mounts today.
+     * @param from - the preset the copy starts from; shipped presets are the
+     * primary source, so any trust is accepted.
+     * @param id - the new preset's id, which becomes its directory name.
+     * @param name - display name for the copy; absent falls back to the id.
+     * @throws when the source is unknown, the id is unusable or already taken,
+     * or the deployment configures no writable root.
+     */
+    copy(from: string, id: string, name?: string): Promise<void>;
+    /**
+     * Delete a locally authored preset.
+     * @param id - the preset id.
+     * @throws when the preset is unknown or ships with the deployment.
+     */
+    remove(id: string): Promise<void>;
+    /**
+     * One agent's instance of a service its preset mounted.
+     *
+     * A preset publishes services behind `isolate` realms, which are invisible
+     * outside the group that declares them — including to the host. This is how a
+     * caller holding the agent reads one anyway: a request that is ABOUT a
+     * session but arrives from outside it, which is every browser RPC.
+     *
+     * Read addressing only. A host row that `inject`s a service cannot use this,
+     * because injection resolves before any session exists and has no agent to
+     * key by; such a service belongs on the host plane instead.
+     * @param agent - the agent whose composition to look inside.
+     * @param name - the service name as the preset's rows resolve it.
+     * @returns the agent's instance, or undefined when its preset mounts none.
+     */
+    serviceFor<K extends string & keyof Context>(agent: {
+        ctx: Context;
+    }, name: K): Context[K] | undefined;
+    /**
+     * Re-link one agent to a different preset's standing composition.
+     *
+     * Only valid while the agent has produced nothing: swapping tools mid
+     * conversation would leave logged tool calls the new composition cannot
+     * make. The CALLER owns that check — this method does not read session
+     * history.
+     *
+     * The swap is a parent re-link, not an unmount: standing mounts are shared
+     * and permanent, so the old composition stays for its other agents and the
+     * new one is ensured BEFORE the link moves. An unknown or unusable preset
+     * therefore throws with the agent exactly as it was — there is no torn-down
+     * state to restore. The re-link runs through the binding this roster kept
+     * from the agent's mount — dsh-scope's only re-link authority. An agent
+     * that never composed one has nothing to re-link: the switch is then the
+     * agent's first bind, exactly a mount.
+     * @param agentCtx - the agent's scope context.
+     * @param id - the preset to compose the agent from instead.
+     * @returns the preset now installed.
+     * @throws when the preset is unknown or its composition is unusable.
+     */
+    recompose(agentCtx: Context, id: string): Promise<AgentPreset>;
+    /**
+     * The standing scope key of one preset, for a host reader with no agent.
+     *
+     * A cold transcript read resolves tool presenters against the composition
+     * the session recorded, and the standing mount makes that possible without
+     * resuming anything: ensuring the mount composes plugins but starts no
+     * agent, no session, and no turn.
+     * @param id - the preset id, or `undefined` for {@link defaultId}.
+     * @returns the standing scope key readers pass as a registry view scope.
+     * @throws when the preset is unknown or its composition is unusable.
+     */
+    standingKeyFor(id?: string): Promise<ScopeKey>;
+    /** Resolve (or create, single-flight) the standing mount of one preset. */
+    private ensureStanding;
+}
+export default AgentPresets;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-agent-presets`.
+ * @module @deepseek-ai/dsh-agent-presets/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "agent-presets-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/metadata.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A preset's display metadata: the name and description a picker shows.
+ *
+ * It lives in its own file because the composition is a top-level list of
+ * plugin rows — YAML cannot carry sibling keys beside it, and faking a
+ * metadata row would hand the Loader something to load. Keeping it separate
+ * also keeps the composition exactly what its name says: a Cordis file the
+ * loader owns and the cordis preset can author.
+ *
+ * The file carries display text ONLY. `id` is the directory name and `trust`
+ * comes from the root a preset was discovered under, so neither is writable
+ * here — otherwise a locally authored preset could claim to be a shipped one.
+ *
+ * Every read failure degrades to no metadata. A preset whose display text is
+ * missing, malformed, or unreadable still mounts: presentation is not a
+ * capability, and a broken name must never become an agent that cannot start.
+ * @module @deepseek-ai/dsh-agent-presets/metadata
+ */
+/** The optional display-metadata file beside a preset's composition. */
+export declare const METADATA_FILE = "preset.yml";
+/** Display text a preset may publish about itself. */
+export interface PresetMetadata {
+    /** Human-facing name; falls back to the preset id when absent. */
+    readonly name?: string;
+    /** One sentence on what this preset is for. */
+    readonly description?: string;
+    /**
+     * Position within its group; lower comes first. A preset that declares
+     * none sorts after every preset that does, then by id — so the shipped set
+     * can read in capability order while authored ones stay alphabetical.
+     */
+    readonly order?: number;
+}
+/**
+ * Read one preset directory's display metadata.
+ *
+ * Absent, unparsable, and wrongly-shaped files are all the same answer —
+ * empty metadata — because the caller renders a picker, not a diagnostic.
+ * @param directory - the preset directory.
+ * @returns the display text the preset published, possibly empty.
+ */
+export declare function readPresetMetadata(directory: string): Promise<PresetMetadata>;
+/**
+ * Render display metadata as the file's contents.
+ *
+ * Absent fields are omitted rather than written empty, so a preset with no
+ * description does not ship a key that reads as an intentional blank.
+ * @param metadata - the display text to store.
+ * @returns the YAML document, or undefined when there is nothing to store.
+ */
+export declare function renderPresetMetadata(metadata: PresetMetadata): string | undefined;
+//# sourceMappingURL=metadata.d.ts.map

package/lib/types/mount.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Mount one preset composition under an agent's scope context, then prove the
+ * result is usable before the agent is published.
+ *
+ * The scope context is what makes the composition per-session: entry contexts
+ * chain to the context the subtree was plugged into, so every `ctx.tools`
+ * and `ctx.systemPrompt` registration inside the preset files into that
+ * agent's layer and unwinds with it. Two guards make that safe. A row that
+ * never reached a usable state is rejected, because a directly-plugged subtree
+ * is absent from `ctx.loader.entries()` and no boot audit covers it. A row that
+ * published a service into the ROOT realm is rejected, because such a service
+ * is process-global rather than per-session and the second session mounting the
+ * same preset collides with the first.
+ * @module @deepseek-ai/dsh-agent-presets/mount
+ */
+import { Context, type Fiber } from '@deepseek-ai/cordis';
+import type { EntryTree } from '@deepseek-ai/cordis-plugin-loader';
+import { type ScopeKey } from '@deepseek-ai/dsh-scope';
+import { type AgentPreset } from './types.ts';
+/** One preset composition currently installed under some agent. */
+export interface PresetMount {
+    /** The preset the subtree was composed from. */
+    readonly presetId: string;
+    /** The mounted subtree's fiber. */
+    readonly fiber: Fiber;
+    /** The standing scope key agents are parented to (undefined only in torn-down records). */
+    readonly key: ScopeKey | undefined;
+}
+/**
+ * Every preset composition still installed, pruning fibers disposed since the
+ * last read.
+ * @returns the live mounts.
+ */
+export declare function livePresetMounts(): PresetMount[];
+/**
+ * Service names the mounted subtree published into the root realm.
+ *
+ * A provider without an `isolate` realm stores its implementation under the
+ * root's symbol for that name, which is exactly the comparison below; a
+ * provider inside an `isolate` realm stores under a realm-private symbol and
+ * is correctly absent here.
+ * @param ctx - any context of the runtime whose service store is inspected.
+ * @param mount - the mounted subtree's fiber.
+ * @returns the leaked service names in lexical order.
+ */
+export declare function leakedServices(ctx: Context, mount: Fiber): string[];
+/** A live standing mount located through one agent already joined to it. */
+export type JoinedPresetMount = PresetMount & {
+    /** The standing key, definite because it is what the lookup matched on. */
+    readonly key: ScopeKey;
+};
+/**
+ * The standing composition one agent is joined to.
+ *
+ * The agent's own key is parented to its preset's standing key, so the mount
+ * is found by matching that parent rather than by walking up from the agent —
+ * the mount is not under the agent's fiber. An agent that joined no preset —
+ * a deployment composing no roster, or a child agent before its join — has no
+ * parent link and resolves to undefined.
+ * @param agentCtx - the agent's scope context.
+ * @returns the mount the agent joined, or undefined when it joined none.
+ */
+export declare function standingMountFor(agentCtx: Context): JoinedPresetMount | undefined;
+/**
+ * One agent's instance of a service its preset mounted.
+ *
+ * A preset publishes a service behind an `isolate` realm so two sessions
+ * cannot collide, and an entry-local realm is invisible to everything outside
+ * the group — including the agent's own scope context and the host. That is
+ * right for the rows inside the group and wrong for one caller: a request that
+ * is ABOUT a session but arrives from outside it, which is every browser RPC
+ * the api-proxy serves.
+ *
+ * Ownership is the same relation {@link leakedServices} reads, inverted: there
+ * it names implementations a subtree published into the ROOT realm, here it
+ * names the one this subtree published anywhere. Fiber membership is object
+ * identity for the reason stated on {@link withinFiber}.
+ *
+ * This is READ addressing for a caller that already holds the agent. It is not
+ * a general host handle on a session's internals: a host row that `inject`s a
+ * service cannot use it, because injection resolves before any session exists
+ * and has no agent to key by — such a service belongs on the host plane.
+ * @param ctx - any context of the runtime whose service store is inspected.
+ * @param agent - the agent whose mounted composition to look inside.
+ * @param name - the service name as the preset's rows resolve it.
+ * @returns the agent's instance, or undefined when its preset mounts none.
+ */
+export declare function serviceForAgent<K extends string & keyof Context>(ctx: Context, agent: {
+    ctx: Context;
+}, name: K): Context[K] | undefined;
+/**
+ * Rows that did not reach a usable state, each rendered as one diagnostic line.
+ *
+ * A row whose module failed to import or whose plugin threw already rejects the
+ * mount through the loader; what remains observable here is a row still waiting
+ * for a service the composition never supplies.
+ * @param tree - the mounted subtree.
+ * @returns one line per unusable row, empty when every enabled row is usable.
+ */
+export declare function inactiveRows(tree: EntryTree): string[];
+/**
+ * Mount `preset` under `agentCtx` and return only once every row is usable.
+ *
+ * The subtree is owned by `agentCtx`'s fiber, so it unwinds with the agent and
+ * the caller receives no disposer. A rejection leaves nothing mounted.
+ * @param agentCtx - the agent's scope context, from the agent factory's `setup`.
+ * @param preset - the resolved preset to compose the agent from.
+ * @throws when `agentCtx` carries no scope, a row is unusable, or a row
+ * published a service into the root realm.
+ */
+export declare function mountPreset(agentCtx: Context, preset: AgentPreset): Promise<void>;
+//# sourceMappingURL=mount.d.ts.map

package/lib/types/session.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The session-log record of which preset a session actually runs.
+ *
+ * The creation header names the preset a session STARTED with, and it is
+ * deep-frozen because that is a creation fact. A session may still change
+ * preset while it is blank, and the effect of that change outlives the blank
+ * window: the first turn — and every turn after it — runs under the newly
+ * mounted composition. Recording the change is what keeps the log honest, and
+ * it is required outright by the repo's model-visible ⟺ logged rule, since the
+ * preset decides the tool schemas and prompt sections the model sees.
+ *
+ * Reconstruction reads {@link resolveSessionPreset}, never the header alone.
+ * @module @deepseek-ai/dsh-agent-presets/session
+ */
+import type { SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session';
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * The session's agent preset was chosen after creation, while the session
+         * was still blank. Log-only: it records the composition later turns ran
+         * under, so a resumed or forked session rebuilds the same one instead of
+         * the header's creation-time value.
+         */
+        'agent-preset/selected': {
+            agentPreset: string;
+        };
+    }
+}
+/** The minimum a caller must supply to resolve a session's preset. */
+export interface PresetBearingSession {
+    /** The session's creation header. */
+    readonly header: SessionHeader;
+    /** The session's event log, oldest first. */
+    readonly events: readonly SessionEvent[];
+}
+/**
+ * The preset a session actually runs, newest selection winning.
+ *
+ * The header supplies the creation-time value; every later selection is a
+ * logged event, so the last one is the answer. Reading the header alone
+ * rebuilds a switched session under the composition it was created with, not
+ * the one its history was produced under.
+ * @param session - the session's header and event log.
+ * @returns the preset id, or `undefined` when the deployment composes none.
+ */
+export declare function resolveSessionPreset(session: PresetBearingSession): string | undefined;
+//# sourceMappingURL=session.d.ts.map