@khorsheed/dsh-capability-catalog 0.1.95

package/lib/types/mcps.d.ts

@@ -0,0 +1,64 @@
+/**
+ * MCP server management: parse a pasted mcp.json snippet into a normalized
+ * `CatalogMcpServerConfig`, keep the configured servers (this process — the
+ * first version carries them in memory; persistence to the settings namespace
+ * + credential store lands with the connection layer), and extract declared
+ * credentials so the UI can ask for them once and never show the plaintext.
+ *
+ * The actual connection + tool discovery is a pluggable seam: `connect` is a
+ * stub in v1 (tools list fills once we bind the dsh-mcp-client connection or
+ * the catalog's own thin client).
+ * @module @khorsheed/dsh-capability-catalog/mcps
+ */
+import type { CatalogJsonValue, CatalogMcpCredentialDecl, CatalogMcpServerConfig, CatalogMcpTool, McpTransport } from './types.ts';
+/** Secret marker put in a config field whose value lives in the credential store. */
+export declare const SECRET_REF_PREFIX = "secretRef:";
+/** A parsed server from a pasted mcp.json server entry. */
+export interface ParsedMcpServer {
+    readonly serverName: string;
+    readonly config: CatalogMcpServerConfig;
+    /** Credential declarations to prompt for (label → config reference path). */
+    readonly credentials: readonly {
+        readonly ref: string;
+        readonly label: string;
+    }[];
+}
+/** Detect transport from a raw server entry shape. */
+export declare function detectTransport(entry: Record<string, unknown>): McpTransport;
+/**
+ * Parse one MCP server entry (a `mcpServers` value) into a normalized config,
+ * extracting credential references. The pasted payload may be the whole
+ * `mcpServers` object (we take a single entry — the Add-MCP flow is one server
+ * per add) or a bare server entry.
+ * @param serverName - the server key.
+ * @param entry - the server's raw config value.
+ */
+export declare function parseServerEntry(serverName: string, entry: Record<string, unknown>): ParsedMcpServer;
+/** Flag a config field secret in the read-only display: `secretRef:x → ·secretRef·`,
+ * preserving any scheme prefix (e.g. `Bearer ·secretRef·`). */
+export declare function maskSecret(value: string): string;
+/** Mask a server config for the wire (the Remote DTO): replace every `secretRef:`
+ * marker (bare or scheme-prefixed) with `·secretRef·`, so neither the secret key
+ * name nor the marker is exposed to the browser. */
+export declare function maskConfig(config: CatalogMcpServerConfig): CatalogMcpServerConfig;
+/** Whether the config still has an unfilled credential (= prompts for it). */
+export declare function hasUnconfiguredCredentials(credentials: readonly CatalogMcpCredentialDecl[]): boolean;
+/** Resolve `secretRef:` markers in a config into plaintext before connecting
+ * (the catalog resolves via the stored credential values, then connects).
+ * Replaces embedded markers too, so a scheme-prefixed value (`Bearer secretRef:a`)
+ * resolves to `Bearer <value>`. */
+export declare function resolveConfigSecrets(config: CatalogMcpServerConfig, resolve: (ref: string) => Promise<string | undefined>): Promise<CatalogMcpServerConfig>;
+/** Sort tools by name and default each to enabled. */
+export declare function finalizeTools(tools: readonly CatalogMcpTool[]): CatalogMcpTool[];
+/**
+ * Map each bare secret config key (env/header name, or a query param) to its
+ * catalog-stored, namespaced credential ref (`mcp.<server>.<kind>.<key>`). The
+ * host store namespaces refs by server so multiple servers with the same env
+ * key don't collide. Mirrors the store's `credentialRefsOf` scan — the client
+ * needs the same mapping to write values for a freshly-added server before the
+ * next snapshot round-trips the namespaced refs.
+ */
+export declare function credentialStoredRefs(serverName: string, config: CatalogMcpServerConfig): Readonly<Record<string, string>>;
+export { SECRET_REF_PREFIX as _SECRET_REF_PREFIX };
+export type { CatalogJsonValue };
+//# sourceMappingURL=mcps.d.ts.map

package/lib/types/mcps.js

@@ -0,0 +1,157 @@
+/**
+ * MCP server management: parse a pasted mcp.json snippet into a normalized
+ * `CatalogMcpServerConfig`, keep the configured servers (this process — the
+ * first version carries them in memory; persistence to the settings namespace
+ * + credential store lands with the connection layer), and extract declared
+ * credentials so the UI can ask for them once and never show the plaintext.
+ *
+ * The actual connection + tool discovery is a pluggable seam: `connect` is a
+ * stub in v1 (tools list fills once we bind the dsh-mcp-client connection or
+ * the catalog's own thin client).
+ * @module @khorsheed/dsh-capability-catalog/mcps
+ */
+/** Secret marker put in a config field whose value lives in the credential store. */
+export const SECRET_REF_PREFIX = 'secretRef:';
+/** Values that look like a credential to prompt for (env/header/query key). */
+const CREDENTIALISH = /(KEY|TOKEN|SECRET|PASSWORD|API_KEY|ACCESS?_?KEY|AUTH)/i;
+/** Find every `secretRef:<token>` marker in a config value (scheme-prefixed or bare). */
+const SECRET_REF_RE = /secretRef:([A-Za-z0-9_.-]+)/g;
+/** Detect transport from a raw server entry shape. */
+export function detectTransport(entry) {
+    if (typeof entry['command'] === 'string')
+        return 'stdio';
+    return 'streamable-http';
+}
+/**
+ * Parse one MCP server entry (a `mcpServers` value) into a normalized config,
+ * extracting credential references. The pasted payload may be the whole
+ * `mcpServers` object (we take a single entry — the Add-MCP flow is one server
+ * per add) or a bare server entry.
+ * @param serverName - the server key.
+ * @param entry - the server's raw config value.
+ */
+export function parseServerEntry(serverName, entry) {
+    const transport = detectTransport(entry);
+    const credentials = [];
+    const env = [];
+    const headers = [];
+    const extract = (value, ref, label) => {
+        if (typeof value !== 'string' || value === '')
+            return value ?? '';
+        if (CREDENTIALISH.test(label)) {
+            credentials.push({ ref, label });
+            // Preserve a scheme prefix (Bearer/Basic/Token) so the header stays valid;
+            // only the token is replaced by the secret marker.
+            const scheme = /^(Bearer|Basic|Token)\s+/i.exec(value);
+            return scheme !== null ? `${scheme[0]}${SECRET_REF_PREFIX}${ref}` : `${SECRET_REF_PREFIX}${ref}`;
+        }
+        return value;
+    };
+    if (transport === 'stdio') {
+        const cmd = typeof entry['command'] === 'string' ? entry['command'] : undefined;
+        const args = Array.isArray(entry['args'])
+            ? entry['args'].filter((a) => typeof a === 'string')
+            : undefined;
+        const cwd = typeof entry['cwd'] === 'string' ? entry['cwd'] : undefined;
+        const rawEnv = (entry['env'] ?? {});
+        for (const [k, v] of Object.entries(rawEnv))
+            env.push([k, extract(v, k, k)]);
+        return {
+            serverName,
+            config: { serverName, transport, ...(cmd !== undefined ? { command: cmd } : {}), ...(args !== undefined ? { args } : {}), ...(cwd !== undefined ? { cwd } : {}), ...(env.length > 0 ? { env } : {}), enabled: false },
+            credentials,
+        };
+    }
+    const url = typeof entry['url'] === 'string' ? entry['url'] : '';
+    const rawHeaders = (entry['headers'] ?? {});
+    for (const [k, v] of Object.entries(rawHeaders))
+        headers.push([k, extract(v, k, k)]);
+    // Query-string secret (e.g. `?key=`). Keep a ref marker in the URL.
+    return {
+        serverName,
+        config: { serverName, transport, url, ...(headers.length > 0 ? { headers } : {}), enabled: false },
+        credentials,
+    };
+}
+/** Flag a config field secret in the read-only display: `secretRef:x → ·secretRef·`,
+ * preserving any scheme prefix (e.g. `Bearer ·secretRef·`). */
+export function maskSecret(value) {
+    return value.replace(SECRET_REF_RE, '·secretRef·');
+}
+/** Mask a server config for the wire (the Remote DTO): replace every `secretRef:`
+ * marker (bare or scheme-prefixed) with `·secretRef·`, so neither the secret key
+ * name nor the marker is exposed to the browser. */
+export function maskConfig(config) {
+    const env = (config.env ?? []).map(([k, v]) => [k, maskSecret(v)]);
+    const headers = (config.headers ?? []).map(([k, v]) => [k, maskSecret(v)]);
+    const url = config.url !== undefined ? maskSecret(config.url) : undefined;
+    return {
+        ...config,
+        ...(env.length > 0 ? { env } : {}),
+        ...(headers.length > 0 ? { headers } : {}),
+        ...(url !== undefined ? { url } : {}),
+    };
+}
+/** Whether the config still has an unfilled credential (= prompts for it). */
+export function hasUnconfiguredCredentials(credentials) {
+    return credentials.some(c => !c.configured);
+}
+/** Resolve `secretRef:` markers in a config into plaintext before connecting
+ * (the catalog resolves via the stored credential values, then connects).
+ * Replaces embedded markers too, so a scheme-prefixed value (`Bearer secretRef:a`)
+ * resolves to `Bearer <value>`. */
+export async function resolveConfigSecrets(config, resolve) {
+    const resolveValue = async (value) => {
+        let out = value;
+        for (const m of value.matchAll(SECRET_REF_RE)) {
+            const ref = m[1];
+            const resolvedValue = (await resolve(ref)) ?? '';
+            out = out.replace(`secretRef:${ref}`, resolvedValue);
+        }
+        return out;
+    };
+    const env = [];
+    for (const [k, v] of config.env ?? [])
+        env.push([k, await resolveValue(v)]);
+    const headers = [];
+    for (const [k, v] of config.headers ?? [])
+        headers.push([k, await resolveValue(v)]);
+    const url = config.url !== undefined ? await resolveValue(config.url) : undefined;
+    return {
+        ...config,
+        ...(env.length > 0 ? { env } : {}),
+        ...(headers.length > 0 ? { headers } : {}),
+        ...(url !== undefined ? { url } : {}),
+    };
+}
+/** Sort tools by name and default each to enabled. */
+export function finalizeTools(tools) {
+    return [...tools].sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Map each bare secret config key (env/header name, or a query param) to its
+ * catalog-stored, namespaced credential ref (`mcp.<server>.<kind>.<key>`). The
+ * host store namespaces refs by server so multiple servers with the same env
+ * key don't collide. Mirrors the store's `credentialRefsOf` scan — the client
+ * needs the same mapping to write values for a freshly-added server before the
+ * next snapshot round-trips the namespaced refs.
+ */
+export function credentialStoredRefs(serverName, config) {
+    const out = {};
+    const isSecret = (v) => /secretRef:/.test(v);
+    for (const [k, v] of config.env ?? []) {
+        if (isSecret(v))
+            out[k] = `mcp.${serverName}.env.${k}`;
+    }
+    for (const [k, v] of config.headers ?? []) {
+        if (isSecret(v))
+            out[k] = `mcp.${serverName}.header.${k}`;
+    }
+    if (config.url !== undefined) {
+        for (const m of config.url.matchAll(/secretRef:([A-Za-z0-9_.-]+)/g)) {
+            out[m[1]] = `mcp.${serverName}.query.${m[1]}`;
+        }
+    }
+    return out;
+}
+export { SECRET_REF_PREFIX as _SECRET_REF_PREFIX }; // re-export for tests if needed

package/lib/types/modes.d.ts

@@ -0,0 +1,65 @@
+/**
+ * MODES: reading the catalog through each agent preset.
+ *
+ * A dsh instance composes every session from an agent preset — 「模式」 in the
+ * settings copy, `preset` in the code: the same deployment can run a full
+ * coding agent, a minimal single-tool one, or a user-authored preset, and each
+ * of those sees a DIFFERENT set of skills and tools. The catalog's default read
+ * answers for one of them (the deployment default). "Which of these does this
+ * mode actually load, and which modes load it?" is a different question, and
+ * this module is the whole answer to it.
+ *
+ * Two shapes travel:
+ *
+ * - a mode ROSTER ({@link modeOptions}) — the presets a viewer offers, with the
+ *   deployment default marked so a picker can label one 「标准模式（默认）」;
+ * - a mode FACE ({@link readModeFaces}) — what one mode's standing scope
+ *   actually registers, read through the same `resolvePresetScope` +
+ *   `catalogSnapshot` path the default read uses, so a mode view and the
+ *   default view cannot drift apart.
+ *
+ * Reading a mode is NOT free: resolving a preset's standing scope MOUNTS its
+ * composition (the roster's single-flight standing mount), so a face read for a
+ * mode nothing has composed yet composes it. That is the price of the only
+ * honest answer — a composition file says which plugins a mode NAMES, not which
+ * tools and skills those plugins register once they run — and it is why the
+ * settings surface asks for faces only when a human chooses to compare modes.
+ *
+ * Both functions are pure over their inputs (the caller supplies the roster rows
+ * and the face reader), so their unit tests need no Cordis context.
+ * @module @khorsheed/dsh-capability-catalog/modes
+ */
+import type { CapabilityCatalogSnapshot, CatalogModeFace, CatalogPresetOption } from './types.ts';
+import type { PresetRosterRow } from './preset-scope.ts';
+/**
+ * The mode roster a viewer offers: the agent-preset rows, path-free, with the
+ * deployment default marked.
+ *
+ * Roster order is preserved — the roster already orders shipped presets by the
+ * `order` they publish — because a picker that re-sorts hands the human a
+ * different order every time the roster grows.
+ * @param rows - the roster rows (`agentPresets.list()`).
+ * @param defaultId - the preset a session naming none composes, when known.
+ * @returns the options a mode picker renders, in roster order.
+ */
+export declare function modeOptions(rows: readonly PresetRosterRow[], defaultId: string | undefined): readonly CatalogPresetOption[];
+/**
+ * Read one face per mode, in roster order.
+ *
+ * A BROKEN preset is not read at all: discovery already refused it, and asking
+ * the roster to mount it would spend a mount attempt on a composition known to
+ * be unusable. It keeps its row with `unavailable` set, so a comparison can say
+ * which mode is missing instead of silently showing an empty face — "this mode
+ * has no tools" and "this mode could not be read" are different claims, and a
+ * viewer that conflates them is worse than one that omits the mode.
+ *
+ * A reader answering `undefined` means the same thing (its scope did not
+ * resolve, so the answer would be the global layer wearing a mode's name).
+ * Faces are read SEQUENTIALLY: each read may start a mount, and walking the
+ * roster's single-flight mount in order is cheaper than racing it.
+ * @param options - the mode roster (from {@link modeOptions}).
+ * @param readFace - read one mode's face; undefined when its scope refuses.
+ * @returns one face per option, roster order preserved.
+ */
+export declare function readModeFaces(options: readonly CatalogPresetOption[], readFace: (presetId: string) => Promise<CapabilityCatalogSnapshot | undefined>): Promise<readonly CatalogModeFace[]>;
+//# sourceMappingURL=modes.d.ts.map

package/lib/types/modes.js

@@ -0,0 +1,97 @@
+/**
+ * MODES: reading the catalog through each agent preset.
+ *
+ * A dsh instance composes every session from an agent preset — 「模式」 in the
+ * settings copy, `preset` in the code: the same deployment can run a full
+ * coding agent, a minimal single-tool one, or a user-authored preset, and each
+ * of those sees a DIFFERENT set of skills and tools. The catalog's default read
+ * answers for one of them (the deployment default). "Which of these does this
+ * mode actually load, and which modes load it?" is a different question, and
+ * this module is the whole answer to it.
+ *
+ * Two shapes travel:
+ *
+ * - a mode ROSTER ({@link modeOptions}) — the presets a viewer offers, with the
+ *   deployment default marked so a picker can label one 「标准模式（默认）」;
+ * - a mode FACE ({@link readModeFaces}) — what one mode's standing scope
+ *   actually registers, read through the same `resolvePresetScope` +
+ *   `catalogSnapshot` path the default read uses, so a mode view and the
+ *   default view cannot drift apart.
+ *
+ * Reading a mode is NOT free: resolving a preset's standing scope MOUNTS its
+ * composition (the roster's single-flight standing mount), so a face read for a
+ * mode nothing has composed yet composes it. That is the price of the only
+ * honest answer — a composition file says which plugins a mode NAMES, not which
+ * tools and skills those plugins register once they run — and it is why the
+ * settings surface asks for faces only when a human chooses to compare modes.
+ *
+ * Both functions are pure over their inputs (the caller supplies the roster rows
+ * and the face reader), so their unit tests need no Cordis context.
+ * @module @khorsheed/dsh-capability-catalog/modes
+ */
+/**
+ * The mode roster a viewer offers: the agent-preset rows, path-free, with the
+ * deployment default marked.
+ *
+ * Roster order is preserved — the roster already orders shipped presets by the
+ * `order` they publish — because a picker that re-sorts hands the human a
+ * different order every time the roster grows.
+ * @param rows - the roster rows (`agentPresets.list()`).
+ * @param defaultId - the preset a session naming none composes, when known.
+ * @returns the options a mode picker renders, in roster order.
+ */
+export function modeOptions(rows, defaultId) {
+    return rows.map(row => ({
+        id: row.id,
+        ...row.name === undefined ? {} : { name: row.name },
+        ...row.description === undefined ? {} : { description: row.description },
+        ...row.broken === undefined ? {} : { broken: row.broken },
+        ...row.id === defaultId ? { isDefault: true } : {},
+    }));
+}
+/**
+ * Read one face per mode, in roster order.
+ *
+ * A BROKEN preset is not read at all: discovery already refused it, and asking
+ * the roster to mount it would spend a mount attempt on a composition known to
+ * be unusable. It keeps its row with `unavailable` set, so a comparison can say
+ * which mode is missing instead of silently showing an empty face — "this mode
+ * has no tools" and "this mode could not be read" are different claims, and a
+ * viewer that conflates them is worse than one that omits the mode.
+ *
+ * A reader answering `undefined` means the same thing (its scope did not
+ * resolve, so the answer would be the global layer wearing a mode's name).
+ * Faces are read SEQUENTIALLY: each read may start a mount, and walking the
+ * roster's single-flight mount in order is cheaper than racing it.
+ * @param options - the mode roster (from {@link modeOptions}).
+ * @param readFace - read one mode's face; undefined when its scope refuses.
+ * @returns one face per option, roster order preserved.
+ */
+export async function readModeFaces(options, readFace) {
+    const faces = [];
+    for (const option of options) {
+        const identity = {
+            preset: option.id,
+            ...option.name === undefined ? {} : { name: option.name },
+            ...option.description === undefined ? {} : { description: option.description },
+            isDefault: option.isDefault === true,
+        };
+        if (option.broken !== undefined) {
+            faces.push({ ...identity, skills: [], tools: [], unavailable: option.broken });
+            continue;
+        }
+        let face;
+        try {
+            face = await readFace(option.id);
+        }
+        catch {
+            // The reader owns its own reporting; a throw here must still leave the
+            // other modes comparable.
+            face = undefined;
+        }
+        faces.push(face === undefined
+            ? { ...identity, skills: [], tools: [], unavailable: 'the preset resolved no standing scope' }
+            : { ...identity, skills: face.skills, tools: face.tools });
+    }
+    return faces;
+}

package/lib/types/namespace.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The settings namespace owned by the capability-catalog plugin. Plain string
+ * so both the host half (settings registration) and the browser half (the
+ * settings.plugin.item card key) import it without dragging host-only
+ * dependencies into the client bundle.
+ */
+/** Settings namespace owned by the capability-catalog plugin. */
+export declare const CAPABILITY_CATALOG_NS = "capability-catalog";
+//# sourceMappingURL=namespace.d.ts.map

package/lib/types/namespace.js

@@ -0,0 +1,8 @@
+/**
+ * The settings namespace owned by the capability-catalog plugin. Plain string
+ * so both the host half (settings registration) and the browser half (the
+ * settings.plugin.item card key) import it without dragging host-only
+ * dependencies into the client bundle.
+ */
+/** Settings namespace owned by the capability-catalog plugin. */
+export const CAPABILITY_CATALOG_NS = 'capability-catalog';

package/lib/types/official-tools.d.ts

@@ -0,0 +1,3 @@
+/** Generated from the pinned harness checkout — do not edit by hand. Run scripts/gen-official-tools.mts. */
+export declare const OFFICIAL_TOOLS: readonly string[];
+//# sourceMappingURL=official-tools.d.ts.map

package/lib/types/official-tools.js

@@ -0,0 +1,44 @@
+/** Generated from the pinned harness checkout — do not edit by hand. Run scripts/gen-official-tools.mts. */
+export const OFFICIAL_TOOLS = [
+    "ask_user_question",
+    "bash",
+    "cordis_define",
+    "cordis_inspect_list",
+    "cordis_inspect_query",
+    "cordis_inspect_self",
+    "cordis_run",
+    "cordis_stop",
+    "cordis_undefine",
+    "create_goal",
+    "edit",
+    "get_goal",
+    "interrupt_agent",
+    "job_kill",
+    "job_list",
+    "job_output",
+    "list_agents",
+    "list_subagent_models",
+    "lsp",
+    "pwsh",
+    "ralph",
+    "read",
+    "read_image",
+    "send_message",
+    "session_event_read",
+    "session_event_search",
+    "session_event_trace",
+    "session_search",
+    "session_trace",
+    "str_replace_editor",
+    "terminal_close",
+    "terminal_list",
+    "terminal_open",
+    "terminal_read",
+    "terminal_send",
+    "terminal_signal",
+    "todo_write",
+    "update_goal",
+    "web_fetch",
+    "web_search",
+    "write"
+];

package/lib/types/preset-scope.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Resolving WHICH scope the catalog reads — and the one place where a listing
+ * and a fingerprint part company.
+ *
+ * The catalog reads the skill and tool registries at an agent preset's
+ * standing scope, because that is the view the model actually has. Resolving
+ * it can fail: the composition may mount no roster, the named preset may not
+ * exist, or its composition may refuse to mount.
+ *
+ * The roster face depends on the host line: 0.1.5 exposes a lease-free
+ * `standingKeyFor(id)`, while rc.1 replaced it with a LEASED
+ * `acquireScope(id)` — the resolved lease carries the key and a release on
+ * `Symbol.asyncDispose`, and a lease never released leaks a generation user,
+ * so the preset's scope is never collected. Both faces resolve through
+ * {@link acquireStandingScope}; callers that hold the key across reads own
+ * the release (see {@link ResolvedPresetScope.dispose}).
+ *
+ * A LISTING degrades on all three. The settings card must not go blank
+ * because a preset has a bad row, and the global layer is a useful, honestly
+ * unlabelled answer there.
+ *
+ * A FINGERPRINT must not. Falling back to the global layer and stamping the
+ * requested preset's name on the result hands back a hash that is not that
+ * preset's face — which is precisely the "claim with nothing behind it" the
+ * hash exists to eliminate. It was not hypothetical: on a real sub-dsh whose
+ * preset carried one invalid row, two scopes rostering two different presets
+ * produced one identical hash, silently, and the only way to notice was to
+ * already know the answer.
+ * @module @khorsheed/dsh-capability-catalog/preset-scope
+ */
+/** The slice of the agent-preset roster the catalog reads. */
+export interface PresetRosterSlice {
+    readonly defaultId?: string;
+    /** The 0.1.5 face: a lease-free read of one preset's standing scope key. */
+    readonly standingKeyFor?: (id?: string) => Promise<unknown>;
+    /**
+     * The rc.1 face: a LEASED read resolving to `{ key } & AsyncDisposable`.
+     * An unknown preset rejects `agent-preset/not-found`, a broken one
+     * `agent-preset/invalid`. Typed as unknown: the key is opaque to the
+     * catalog, and `Symbol.asyncDispose` is untyped under the es2024 target —
+     * {@link acquireStandingScope} narrows both structurally.
+     */
+    readonly acquireScope?: (id?: string) => Promise<unknown>;
+    /** Every preset the deployment supplies, for a scope picker. */
+    readonly list?: () => Promise<readonly PresetRosterRow[]>;
+}
+/** One roster row, structurally narrowed to what a picker needs. */
+export interface PresetRosterRow {
+    readonly id: string;
+    readonly name?: string;
+    readonly description?: string;
+    /** Why this preset cannot compose a session, when it cannot. */
+    readonly broken?: string;
+}
+/**
+ * A standing-scope read, normalized across roster faces: the key, and the
+ * release when the face leases. The key outlives the release — the roster
+ * reaps a generation only once its preset is unregistered AND unleased — so
+ * a reader that finished its reads may release without unmounting the scope.
+ */
+export interface StandingScopeRead {
+    /** The standing scope key, or undefined when the roster resolved none. */
+    readonly key: unknown | undefined;
+    /** Releases the rc.1 lease; undefined on the lease-free 0.1.5 face. */
+    readonly dispose?: () => Promise<void>;
+}
+/** A resolved reading position: the scope key, and the preset it is honestly labelled with. */
+export interface ResolvedPresetScope {
+    /** The standing scope key, or undefined for the global layer. */
+    readonly scope: unknown | undefined;
+    /** The preset id — set ONLY when a standing scope actually resolved. */
+    readonly preset: string | undefined;
+    /**
+     * Releases the scope lease, when the roster leases (rc.1). Undefined on the
+     * 0.1.5 face, which carries no lease. A caller holding `scope` across reads
+     * must dispose in a `finally` after the LAST read — never releasing leaks a
+     * generation user, so the preset's scope is never collected.
+     */
+    readonly dispose?: () => Promise<void>;
+}
+/**
+ * Acquire one preset's standing scope key from whichever face the roster
+ * offers — 0.1.5's lease-free `standingKeyFor` first, rc.1's leased
+ * `acquireScope` when that is absent. Errors propagate unchanged, so the
+ * caller owns the strict/degrade policy; the caller also owns the release.
+ * @param roster - the agent-preset roster (already probed present).
+ * @param id - the preset to read, or undefined for the deployment default.
+ * @returns the key and the lease release, if the face leases.
+ */
+export declare function acquireStandingScope(roster: PresetRosterSlice, id: string | undefined): Promise<StandingScopeRead>;
+/**
+ * Resolve the catalog's reading scope.
+ *
+ * Resolving a preset MOUNTS it (the roster's single-flight standing mount),
+ * so this is not a free read: asking for the capability face of a preset
+ * nothing has composed yet composes it.
+ * @param roster - the optional agent-preset roster (`ctx.get('agentPresets')`).
+ * @param presetId - the preset to read, or undefined for the deployment default.
+ * @param strict - fingerprint mode: throw rather than degrade to the global layer.
+ * @returns the scope to read at and the label it may carry.
+ * @throws in strict mode when the roster is absent for a named preset, or
+ *   cannot resolve a standing scope.
+ */
+export declare function resolvePresetScope(roster: PresetRosterSlice | undefined, presetId: string | undefined, strict: boolean): Promise<ResolvedPresetScope>;
+//# sourceMappingURL=preset-scope.d.ts.map