@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/plugins-info.d.ts

@@ -0,0 +1,43 @@
+/**
+ * /plugins diagnostics surface (C-070 trust disclosure + C-030 negotiation
+ * diagnostics): assembles the lines behind the `/plugins` command.
+ *
+ * Sections (overview):
+ *
+ * 1. TRUST BANNER — always the first line (C-070): plugins run in-process;
+ *    grants are behavioral constraints, not a security boundary; passing
+ *    validation is not proof of safety.
+ * 2. HOST DESCRIPTOR summary — what the running host actually advertises
+ *    (coordinates + generation), including drift-dropped contracts.
+ * 3. GRANT MATRIX — plugins × the registered permissions. The plugin set is
+ *    the union of FOOTPRINTS ONLY: keys of the grants file, pluginIds seen
+ *    in the effect ledger, and storage namespaces on disk (the host cannot
+ *    enumerate installed plugins — that knowledge lives in the dsh CLI
+ *    Loader). The header says so honestly.
+ * 4. LEDGER TAIL — the last 5 effect-ledger records.
+ *
+ * `/plugins check <path>` uses the parser and projection from the pinned
+ * @dsh-std/manifest revision, then evaluates every public/private protocol
+ * through one ProtocolCatalog. Manifests and on-disk files are UNTRUSTED input:
+ * every derived line passes cleanScalarText before it reaches the
+ * transcript.
+ */
+import type { GrantStore } from '../adapter/standard/grants.js';
+import type { HostDescriptorBuild } from '../adapter/standard/descriptor.js';
+/** How many plugins the matrix shows before an overflow note. */
+export declare const PLUGINS_MATRIX_MAX_ROWS = 20;
+/** How many ledger records the tail section shows. */
+export declare const PLUGINS_LEDGER_TAIL = 5;
+export interface PluginsInfoDeps {
+    /** Effective grant answers (the plugin-host row's store when mounted). */
+    grants: GrantStore;
+    /** The plugin-host row's descriptor build; undefined → row not mounted. */
+    host?: HostDescriptorBuild;
+    /** Test overrides; default under DATA_DIR. */
+    dataDir?: string;
+    ledgerFile?: string;
+    storageDir?: string;
+}
+/** The `/plugins` overview lines (banner always first). */
+export declare function pluginsInfoLines(args: string, deps: PluginsInfoDeps): string[];
+//# sourceMappingURL=plugins-info.d.ts.map

package/lib/types/dsh-adapter/plugins-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugins-info.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/plugins-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAWH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAA;AAC/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AAI5E,iEAAiE;AACjE,eAAO,MAAM,uBAAuB,KAAK,CAAA;AACzC,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,IAAI,CAAA;AAIpC,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,MAAM,EAAE,UAAU,CAAA;IAClB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,mBAAmB,CAAA;IAC1B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AA2KD,2DAA2D;AAC3D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,MAAM,EAAE,CAsF9E"}

package/lib/types/dsh-adapter/plugins-info.js

@@ -0,0 +1,293 @@
+/**
+ * /plugins diagnostics surface (C-070 trust disclosure + C-030 negotiation
+ * diagnostics): assembles the lines behind the `/plugins` command.
+ *
+ * Sections (overview):
+ *
+ * 1. TRUST BANNER — always the first line (C-070): plugins run in-process;
+ *    grants are behavioral constraints, not a security boundary; passing
+ *    validation is not proof of safety.
+ * 2. HOST DESCRIPTOR summary — what the running host actually advertises
+ *    (coordinates + generation), including drift-dropped contracts.
+ * 3. GRANT MATRIX — plugins × the registered permissions. The plugin set is
+ *    the union of FOOTPRINTS ONLY: keys of the grants file, pluginIds seen
+ *    in the effect ledger, and storage namespaces on disk (the host cannot
+ *    enumerate installed plugins — that knowledge lives in the dsh CLI
+ *    Loader). The header says so honestly.
+ * 4. LEDGER TAIL — the last 5 effect-ledger records.
+ *
+ * `/plugins check <path>` uses the parser and projection from the pinned
+ * @dsh-std/manifest revision, then evaluates every public/private protocol
+ * through one ProtocolCatalog. Manifests and on-disk files are UNTRUSTED input:
+ * every derived line passes cleanScalarText before it reaches the
+ * transcript.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseManifest, projectManifest } from '../adapter/standard/protocols.js';
+import { DATA_DIR } from '../utils/paths.js';
+import { t } from '../i18n.js';
+import { loadSpecData } from '../adapter/standard/registry.js';
+import { createContractIndex, validatePlugin, negotiate } from '../adapter/standard/admission.js';
+import { cleanScalarText } from './sanitize.js';
+import { PLUGIN_STORAGE_DIR } from './plugin-storage.js';
+import { EFFECT_LEDGER_FILE } from './effect-ledger.js';
+/** How many plugins the matrix shows before an overflow note. */
+export const PLUGINS_MATRIX_MAX_ROWS = 20;
+/** How many ledger records the tail section shows. */
+export const PLUGINS_LEDGER_TAIL = 5;
+/** Per-line cell cap for file-derived content. */
+const LINE_CELLS = 200;
+const cell = (value) => cleanScalarText(String(value ?? ''), LINE_CELLS);
+/** Parse the ledger file tolerantly (skip corrupt lines, never throw). */
+function readLedgerRecords(file) {
+    let text;
+    try {
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const line of text.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed !== null && typeof parsed === 'object')
+                records.push(parsed);
+        }
+        catch {
+            // Corrupt line: the diagnostics surface skips it (never rewrites).
+        }
+    }
+    return records;
+}
+/** The plugin set for the matrix: grants-file keys ∪ ledger pluginIds ∪
+ *  storage namespaces ('host'/'undeclared' ledger identities are not
+ *  plugins and are excluded). */
+function footprintPlugins(deps, dataDir, ledgerFile, storageDir) {
+    const found = new Set();
+    try {
+        const raw = JSON.parse(readFileSync(join(dataDir, 'extension-grants.json'), 'utf8'));
+        if (raw !== null && typeof raw === 'object') {
+            const table = raw;
+            for (const section of [table.grants, table.denies]) {
+                if (section !== null && typeof section === 'object') {
+                    for (const plugin of Object.keys(section))
+                        found.add(plugin);
+                }
+            }
+        }
+    }
+    catch {
+        // Missing/corrupt grants file: the GrantStore already answers deny;
+        // the matrix simply has no rows from this source.
+    }
+    for (const record of readLedgerRecords(ledgerFile)) {
+        if (typeof record.pluginId === 'string' && record.pluginId !== '' && record.pluginId !== 'host' && record.pluginId !== 'undeclared') {
+            found.add(record.pluginId);
+        }
+    }
+    try {
+        for (const entry of readdirSync(storageDir)) {
+            if (!entry.endsWith('.json'))
+                continue;
+            const namespace = decodeURIComponent(entry.slice(0, -'.json'.length));
+            if (namespace !== '')
+                found.add(namespace);
+        }
+    }
+    catch {
+        // No storage directory yet: no rows from this source.
+    }
+    void deps;
+    return [...found].sort();
+}
+/** `/plugins check <path>`: official parse/projection + profile validation + negotiation. */
+function checkManifestLines(pathArg, deps) {
+    const lines = [];
+    const target = resolve(pathArg);
+    if (!existsSync(target)) {
+        lines.push(t('plugins-check-not-found', { path: cell(pathArg) }));
+        return lines;
+    }
+    let source;
+    try {
+        source = readFileSync(target, 'utf8');
+    }
+    catch (error) {
+        lines.push(t('plugins-check-invalid-json', { err: cell(error instanceof Error ? error.message : String(error)) }));
+        return lines;
+    }
+    const data = loadSpecData();
+    if (data === undefined) {
+        lines.push(t('plugins-check-spec-unavailable'));
+        return lines;
+    }
+    let manifest;
+    try {
+        manifest = parseManifest(source, { source: target });
+        // Projection is an explicit admission stage. validatePlugin performs its
+        // own defensive projection too, but keeping this call here makes parser
+        // and projection failures distinguishable at the user-facing boundary.
+        projectManifest(manifest);
+    }
+    catch (error) {
+        const message = cell(error instanceof Error ? error.message : String(error));
+        lines.push(error instanceof SyntaxError
+            ? t('plugins-check-invalid-json', { err: message })
+            : t('plugins-check-schema-failed', { err: message }));
+        return lines;
+    }
+    const index = createContractIndex(data.registry, data.permissions);
+    try {
+        validatePlugin(index, manifest);
+    }
+    catch (error) {
+        lines.push(t('plugins-check-invalid', { err: cell(error instanceof Error ? error.message : String(error)) }));
+        return lines;
+    }
+    // No live host: do NOT fall back to a full advertised surface. The check
+    // stays static (validation only) and explicitly reports host-unavailable /
+    // non-live instead of participating in protocol support negotiation.
+    const host = deps.host;
+    if (host === undefined) {
+        lines.push(t('plugins-check-host-unavailable'));
+        return lines;
+    }
+    const granted = manifest.permissions
+        .map(request => ({
+        name: request.name,
+        scope: request.scope,
+        // `/plugins check` has no live activation instance. Passing an
+        // activation-less principal makes GrantStore fail closed when policy
+        // contains activation-scoped rules instead of treating them as global.
+        granted: deps.grants.allows({ componentId: manifest.id }, request.name, request.scope),
+    }));
+    const decision = negotiate(index, manifest, host.descriptor, granted);
+    lines.push(...decisionLines(decision));
+    if (decision.decision === 'waiting_authorization') {
+        // Close the loop on the five-state vocabulary: the user sees not just
+        // the state but the exact file + shape that flips it (the interactive
+        // grant flow is future work; this hint is its no-UI prerequisite).
+        lines.push(t('plugins-check-grant-hint', {
+            id: cell(manifest.id),
+            perms: cell(decision.deniedPermissions.join(', ')),
+        }));
+    }
+    if (host.dropped.length > 0) {
+        lines.push(t('plugins-check-dropped', { dropped: cell(host.dropped.join(', ')) }));
+    }
+    return lines;
+}
+function decisionLines(decision) {
+    switch (decision.decision) {
+        case 'compatible':
+            return [t('plugins-check-state', { state: 'compatible' })];
+        case 'compatible_degraded':
+            return [t('plugins-check-state', {
+                    state: `compatible_degraded (missingOptional: ${cell(decision.missingOptional.join(', '))})`,
+                })];
+        case 'waiting_authorization':
+            return [t('plugins-check-state', {
+                    state: `waiting_authorization (${cell(decision.reasonCode)}: ${cell(decision.deniedPermissions.join(', '))})`,
+                })];
+        case 'rejected': {
+            const detail = decision.missingRequired !== undefined
+                ? `${cell(decision.reasonCode)}: ${cell(decision.missingRequired.join(', '))}`
+                : `${cell(decision.reasonCode)}: facet ${cell(decision.facetApiVersion)} vs host [${cell((decision.hostFacetApiVersions ?? []).join(', '))}]`;
+            return [t('plugins-check-state', { state: `rejected (${detail})` })];
+        }
+        case 'unknown':
+            return [t('plugins-check-state', {
+                    state: `unknown (${cell(decision.reasonCode)}: ${cell(decision.unknownContracts.join(', '))})`,
+                })];
+    }
+}
+/** The `/plugins` overview lines (banner always first). */
+export function pluginsInfoLines(args, deps) {
+    const lines = [t('plugins-trust-banner')];
+    const trimmed = args.trim();
+    if (trimmed !== '') {
+        const [sub, ...rest] = trimmed.split(/\s+/);
+        if (sub === 'check') {
+            const pathArg = rest.join(' ');
+            if (pathArg === '') {
+                lines.push(t('plugins-check-usage'));
+                return lines;
+            }
+            lines.push(...checkManifestLines(pathArg, deps));
+            return lines;
+        }
+        lines.push(t('plugins-unknown-subcommand', { sub: cell(sub) }));
+        return lines;
+    }
+    const dataDir = deps.dataDir ?? DATA_DIR;
+    const ledgerFile = deps.ledgerFile ?? EFFECT_LEDGER_FILE;
+    const storageDir = deps.storageDir ?? join(dataDir, PLUGIN_STORAGE_DIR);
+    // ── Host Descriptor ──
+    if (deps.host === undefined) {
+        lines.push(t('plugins-host-unavailable'));
+    }
+    else {
+        const { descriptor, dropped } = deps.host;
+        lines.push(`Host Descriptor: ${cell(descriptor.hostId)} v${cell(descriptor.hostVersion)} · generation ${cell(descriptor.runtime.generationId)}`);
+        lines.push(`  facets: ${cell(descriptor.facetApiVersions.join(', ') || '—')}`);
+        for (const contract of descriptor.contracts) {
+            const definition = contract.definition.source === 'dsh-std'
+                ? contract.definition.package
+                : contract.definition.profileHash.slice(0, 19) + '…';
+            lines.push(`  ${cell(contract.apiVersion)}#${cell(contract.kind)} · definition ${cell(definition)} · perms ${cell(contract.permissions.join(', ') || '—')}`);
+        }
+        for (const coordinate of dropped) {
+            lines.push(`  ${cell(coordinate)} · ${t('plugins-contract-dropped')}`);
+        }
+    }
+    // ── 授权矩阵 ──
+    const plugins = footprintPlugins(deps, dataDir, ledgerFile, storageDir);
+    lines.push(t('plugins-matrix-note'));
+    const permissions = deps.grants.knownPermissions();
+    if (permissions.length === 0) {
+        lines.push(`  ${t('plugins-matrix-no-registry')}`);
+    }
+    else if (plugins.length === 0) {
+        lines.push(`  ${t('plugins-matrix-empty')}`);
+    }
+    else {
+        lines.push(`  ${permissions.map((permission, index) => `[${index + 1}] ${cell(permission)}`).join('  ')}`);
+        const shown = plugins.slice(0, PLUGINS_MATRIX_MAX_ROWS);
+        const width = Math.max(...shown.map(plugin => plugin.length), 8);
+        for (const plugin of shown) {
+            const diagnosticScope = (permission) => {
+                if (permission === 'storage.local.read' || permission === 'storage.local.write')
+                    return plugin;
+                if (permission === 'commands.invoke')
+                    return 'diagnostic.command';
+                return 'session:*';
+            };
+            const marks = permissions.map(permission => (deps.grants.allows({ componentId: plugin }, permission, diagnosticScope(permission)) ? '✓' : '·')).join(' ');
+            lines.push(`  ${cell(plugin).padEnd(width)}  ${marks}`);
+        }
+        if (plugins.length > shown.length) {
+            lines.push(`  ${t('plugins-footprint-overflow', { count: plugins.length - shown.length })}`);
+        }
+        // Actionable next step for the · marks (same loop-closer as the check
+        // path): the file path + rule shape, so granting needs no spec reading.
+        lines.push(`  ${t('plugins-grant-hint')}`);
+    }
+    // ── 台账尾 ──
+    const records = readLedgerRecords(ledgerFile);
+    if (records.length === 0) {
+        lines.push(t('plugins-ledger-empty'));
+    }
+    else {
+        lines.push(t('plugins-ledger-header', { file: cell(ledgerFile) }));
+        for (const record of records.slice(-PLUGINS_LEDGER_TAIL)) {
+            const resource = record.resource ?? {};
+            lines.push(`  #${cell(record.sequence)} ${cell(record.operation)} ${cell(resource.kind)}/${cell(resource.id)} ` +
+                `${cell(record.pluginId)} ${cell(record.result)}${typeof record.errorCode === 'string' ? ` (${cell(record.errorCode)})` : ''}`);
+        }
+    }
+    return lines;
+}

package/lib/types/dsh-adapter/preset-resolution.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Agent-preset resolution across upstream prerelease lines.
+ *
+ * Legacy rc.2 exports `resolveSessionPreset` and ships `code`; the 0.1.2 line
+ * replaces the helper with a projection definition and renames that preset to `ptc`.
+ * Keeping both compatibility decisions here prevents composition and channel
+ * code from acquiring prerelease-specific branches.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** One roster entry, as returned by `agentPresets.list()`/`resolve()`. */
+export interface AgentPresetInfo {
+    readonly id: string;
+    readonly trust: 'system' | 'user';
+    readonly name?: string;
+    readonly description?: string;
+    /** Present when the preset cannot compose a session (human-readable). */
+    readonly broken?: string;
+}
+/** The `ctx.agentPresets` service surface dsh-tui consumes. */
+export interface AgentPresetsLike {
+    readonly defaultId: string;
+    list(): Promise<readonly AgentPresetInfo[]>;
+    resolve(id?: string): Promise<AgentPresetInfo>;
+    mount(agentCtx: Context, id?: string): Promise<AgentPresetInfo>;
+    recompose(agentCtx: Context, id: string): Promise<AgentPresetInfo>;
+    /** Read one service from the agent's own scope chain (preset realms). */
+    serviceFor?(agent: {
+        ctx: Context;
+    }, key: string): unknown;
+}
+/** The mounted preset roster, or undefined in a rosterless composition. */
+export declare function rosterOf(ctx: Context): AgentPresetsLike | undefined;
+/** Resolve the durable preset projection: newest selection wins over header. */
+export declare function resolveRecordedPreset(session: {
+    header: {
+        agentPreset?: string;
+    };
+    events: readonly {
+        type: string;
+        data: unknown;
+    }[];
+}): string | undefined;
+/**
+ * Resolve an exact roster id first, then bridge the official rename in either
+ * direction. A successful list is required before aliasing so roster I/O or
+ * a broken exact preset can never be mistaken for an unknown id.
+ */
+export declare function resolveCompatiblePreset(presets: AgentPresetsLike, requested?: string): Promise<AgentPresetInfo>;
+/**
+ * The i18n dictionary id a roster preset's localized display text resolves
+ * under. The 0.1.2 line renamed the official PTC preset `code` → `ptc`, but
+ * the dictionary keys still use the legacy `code` id (`preset-name-code` /
+ * `preset-desc-code`), so the `/preset` picker's display lookup must bridge
+ * the roster id back. User-authored ids pass through untouched.
+ */
+export declare function presetDisplayId(id: string): string;
+//# sourceMappingURL=preset-resolution.d.ts.map

package/lib/types/dsh-adapter/preset-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preset-resolution.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/preset-resolution.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,0EAA0E;AAC1E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAAA;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,IAAI,IAAI,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC,CAAA;IAC3C,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IAC9C,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IAC/D,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;IAClE,yEAAyE;IACzE,UAAU,CAAC,CAAC,KAAK,EAAE;QAAE,GAAG,EAAE,OAAO,CAAA;KAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAC3D;AAED,2EAA2E;AAC3E,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,CAEnE;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAC7C,MAAM,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAChC,MAAM,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,EAAE,CAAA;CACnD,GAAG,MAAM,GAAG,SAAS,CASrB;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,gBAAgB,EACzB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,eAAe,CAAC,CAQ1B;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAElD"}

package/lib/types/dsh-adapter/preset-resolution.js

@@ -0,0 +1,52 @@
+/**
+ * Agent-preset resolution across upstream prerelease lines.
+ *
+ * Legacy rc.2 exports `resolveSessionPreset` and ships `code`; the 0.1.2 line
+ * replaces the helper with a projection definition and renames that preset to `ptc`.
+ * Keeping both compatibility decisions here prevents composition and channel
+ * code from acquiring prerelease-specific branches.
+ */
+/** The mounted preset roster, or undefined in a rosterless composition. */
+export function rosterOf(ctx) {
+    return ctx.get('agentPresets');
+}
+/** Resolve the durable preset projection: newest selection wins over header. */
+export function resolveRecordedPreset(session) {
+    for (let index = session.events.length - 1; index >= 0; index -= 1) {
+        const event = session.events[index];
+        if (event?.type !== 'agent-preset/selected')
+            continue;
+        if (event.data === null || typeof event.data !== 'object')
+            continue;
+        const selected = event.data.agentPreset;
+        if (typeof selected === 'string')
+            return selected;
+    }
+    return session.header.agentPreset;
+}
+/**
+ * Resolve an exact roster id first, then bridge the official rename in either
+ * direction. A successful list is required before aliasing so roster I/O or
+ * a broken exact preset can never be mistaken for an unknown id.
+ */
+export async function resolveCompatiblePreset(presets, requested) {
+    const fallback = requested === 'code' ? 'ptc' : requested === 'ptc' ? 'code' : undefined;
+    if (fallback === undefined)
+        return presets.resolve(requested);
+    const roster = await presets.list();
+    if (roster.some(preset => preset.id === requested))
+        return presets.resolve(requested);
+    if (roster.some(preset => preset.id === fallback))
+        return presets.resolve(fallback);
+    return presets.resolve(requested);
+}
+/**
+ * The i18n dictionary id a roster preset's localized display text resolves
+ * under. The 0.1.2 line renamed the official PTC preset `code` → `ptc`, but
+ * the dictionary keys still use the legacy `code` id (`preset-name-code` /
+ * `preset-desc-code`), so the `/preset` picker's display lookup must bridge
+ * the roster id back. User-authored ids pass through untouched.
+ */
+export function presetDisplayId(id) {
+    return id === 'ptc' ? 'code' : id;
+}

package/lib/types/dsh-adapter/presets.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Agent-presets roster integration (issue #8): compose each session's
+ * model-facing world (tools, prompt sections, projections) from one preset
+ * directory instead of the host composition.
+ *
+ * Mirrors the official host's integration (dsh-host-apiproxy's
+ * `composeAgent`): the preset id is resolved BEFORE create/resume because the
+ * session boundary snapshots `meta` (the durable header's `agentPreset`)
+ * before asynchronous setup begins; the mount itself runs inside the agent
+ * factory's `setup(agentCtx)` hook, where a composition failure rolls the
+ * whole creation back instead of publishing a half-configured agent.
+ *
+ * A deployment without the roster (bare `dsh --config cordis.yml` boots,
+ * older CLI without the shipped preset root) composes nothing: callers get
+ * no `setup` and every session shares the host composition — the behavior
+ * before presets existed.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { AgentSetup } from '@deepseek-ai/dsh-agent';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt';
+import { type ModelRoute } from '../modelRoute.js';
+/** The composition inputs for `agents.create`/`agents.resume`. */
+export interface PresetComposition {
+    /** Value for the durable header's `meta.agentPreset`; absent without a roster. */
+    readonly agentPreset?: string;
+    /** Factory setup hook mounting the preset onto the unpublished agent. */
+    readonly setup?: AgentSetup;
+}
+/**
+ * Resolve the preset one new/resumed session will run under and the setup
+ * that installs it. `requested` undefined adopts the roster default.
+ *
+ * Resolution failures (unknown/broken preset id, an empty roster that cannot
+ * supply even the default) degrade to the rosterless composition with a loud
+ * log line: a session that cannot start at all is worse than one running on
+ * the host composition.
+ *
+ * @param ctx - The plugin context (roster lookup + logging).
+ * @param requested - The preset id the caller wants, or undefined for the default.
+ * @returns The header value + setup hook, or an empty composition.
+ */
+export declare function composePreset(ctx: Context, requested?: string): Promise<PresetComposition>;
+/**
+ * The preset a PERSISTED session actually runs, read from its log: the last
+ * `agent-preset/selected` event wins over the creation header (a blank
+ * session may have switched). undefined when the log records none (sessions
+ * from before presets existed → the roster default applies at mount).
+ *
+ * @param ctx - The plugin context (persistence lookup).
+ * @param sessionId - The persisted session to inspect.
+ * @returns The running preset id, or undefined when unrecorded/unreadable.
+ */
+export declare function resolvePersistedPreset(ctx: Context, sessionId: SessionId): Promise<string | undefined>;
+/**
+ * The preset a LIVE session runs, resolved from its own log (last
+ * `agent-preset/selected` wins over the header). Used for fork-style creates
+ * (rewind/model switch) and for reading an already-live agent's composition.
+ *
+ * @param session - The live session.
+ * @returns The running preset id, or undefined when the log records none.
+ */
+export declare function runningPresetOf(session: unknown): string | undefined;
+/**
+ * The route a PERSISTED session actually ran, read from its log: the last
+ * `request/header` snapshot. undefined when the log records none (a session
+ * that never started a turn) or the artifact is unreadable.
+ *
+ * Resume feeds this back into `agents.resume({ agentOptions })` so the
+ * resumed agent's `options.model` is populated again — a cordis.yml that
+ * pins only `provider` (issue #67: a half-pin never merges) leaves
+ * agentOptions.model undefined, which breaks the `{{model}}` persona variable
+ * for the resumed agent's own assembly AND for every subagent it spawns
+ * (dsh-subagent's `resolveChildAgentOptions` inherits `parent.options.model`).
+ *
+ * @param ctx - The plugin context (persistence lookup).
+ * @param sessionId - The persisted session to inspect.
+ * @returns The recorded model route, or undefined when unrecorded/unreadable.
+ */
+export declare function resolvePersistedRoute(ctx: Context, sessionId: SessionId): Promise<ModelRoute | undefined>;
+/**
+ * Keep the official Minimal preset's model-facing contract at exactly two
+ * tools. The TUI mounts ask_user_question at the host layer so every other
+ * preset (including user presets) can use its questionnaire UI; host-layer
+ * tools otherwise merge into Minimal's scoped catalog as a third tool.
+ *
+ * This is a per-assembly filter rather than a startup-time decision because
+ * one TUI process can resume, create, or recompose sessions under different
+ * presets. The session log remains the source of truth for the active preset.
+ *
+ * @param assembly - Fully assembled prompt inputs for one model request.
+ * @param presetId - Preset recorded for the requesting session.
+ * @returns The original assembly, except ask_user_question is absent in Minimal.
+ */
+export declare function filterMinimalPresetTools(assembly: PromptAssembly, presetId: string | undefined): PromptAssembly;
+/**
+ * Read a service the way a joined agent sees it: through the preset scope
+ * chain when a roster is mounted (preset realms hide e.g. `compaction` from
+ * the root context), falling back to the host context otherwise. Mirrors the
+ * official host's `agentPresets.serviceFor(agent, key) ?? ctx.get(key)`.
+ *
+ * @param ctx - The plugin context (roster + host fallback).
+ * @param agent - The live agent whose scope chain resolves first.
+ * @param key - The cordis service key.
+ * @returns The service instance, or undefined when neither layer provides it.
+ */
+export declare function serviceForAgent<T>(ctx: Context, agent: {
+    ctx: Context;
+}, key: string): T | undefined;
+//# sourceMappingURL=presets.d.ts.map

package/lib/types/dsh-adapter/presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presets.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/presets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAA;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAA;AACpE,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAWtE,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAA;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAmBhG;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAW5G;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAGpE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAW/G;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,CAM/G;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE;IAAE,GAAG,EAAE,OAAO,CAAA;CAAE,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAKpG"}