dsh-ssh-tui 0.7.1 → 0.7.3

package/lib/types/index.d.ts

@@ -6,6 +6,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 export { ATTACH_RECOVERY_WINDOW_MS, attachPeerVanished } from './attach.js';
+import z from '@deepseek-ai/schemastery';
 export declare const name = "ssh-tui";
 /** Core services required before the terminal channel can drive an agent. */
 export declare const inject: string[];
@@ -27,7 +28,51 @@ export interface Config {
     model?: string;
     /** Minimum milliseconds between paints; see DSH_TUI_PAINT_MS. */
     paintIntervalMs?: number;
+    /**
+     * The fields below are the TUI's live settings, i.e. the `ssh-tui` section.
+     * They ride on this entry's schema so 0.1.7 can project a form for it — and so
+     * a pre-0.1.7 `$DSH_HOME/settings.yaml` `ssh-tui:` section is imported into
+     * this entry rather than left behind.
+     */
+    /** UI language (`/language`); zh unless the environment says otherwise. */
+    language?: string;
+    /** Newest plugin version whose update notice was dismissed. */
+    skipUpdate?: string;
+    /** Workspace pane layout (`/view`). */
+    view?: string;
+    /** What a dropped display does (`/disconnect`). */
+    disconnect?: string;
+    /** Auto-approval mode (`/autoapproval`). */
+    autoApproval?: string;
+    /** Milliseconds a leftover finished Host waits before exiting; 0 = never. */
+    idleExit?: number;
 }
+/** Every field above, as schemastery resolves them (all optional). */
+interface ConfigFields {
+    sessionId?: string;
+    showReasoning?: boolean;
+    maxToolOutputLines?: number;
+    color?: boolean;
+    welcome?: string;
+    resume?: boolean;
+    resumePicker?: boolean;
+    provider?: string;
+    model?: string;
+    paintIntervalMs?: number;
+    language?: string;
+    skipUpdate?: string;
+    view?: string;
+    disconnect?: string;
+    autoApproval?: string;
+    idleExit?: number;
+}
+/**
+ * The entry's schema. Everything a launch supplies (`config:` in
+ * `cordis.patch.yml`, including its `!!js` expressions) stays ordinary,
+ * non-live configuration; the TUI's own settings are the live fields, which is
+ * what makes them visible to, and writable through, the 0.1.7 settings service.
+ */
+export declare const Config: z<ConfigFields>;
 /**
  * Mount the SSH TUI. The `main` agent is created here after the loader
  * settles, reading the saved default provider/model from

package/lib/types/job-label.d.ts

@@ -1,20 +1,51 @@
 /**
- * Friendly display names for background jobs.
+ * Friendly display names for background jobs and subagent chips.
  *
- * `job_*` cards otherwise read as the raw tool vocabulary (`job_output`,
- * `job_id: bash-1`), which is both untranslated and hard to talk about out
- * loud. Each job id instead gets a two-word alias — "蔚蓝水獭", "azure otter" —
- * derived from the id itself rather than from a random draw, so the same job
- * keeps one name across its call card, its result card, and every later
+ * Background `job_*` cards otherwise read as the raw tool vocabulary
+ * (`job_output`, `job_id: bash-1`). Each job id gets a two-token alias
+ * (hour + weather: 昏风 / twilight wind) derived from the id itself rather
+ * than from a random draw, so the same
+ * job keeps one name across its call card, its result card, and every later
  * `job_output` / `job_kill` mention. The model-facing id stays authoritative;
  * the alias is presentation only.
  *
+ * Subagent chips use a different scheme: a role distilled from the parent
+ * spawn description, joined to one of the four directional beasts
+ * (青龙 / 白虎 / 朱雀 / 玄武) hashed from the child session id.
+ *
  * @module dsh-ssh-tui/job-label
  */
+/** FNV-1a over the job id: stable, dependency-free, and well spread for short ids. */
+export declare function hashJobId(id: string): number;
 /**
  * One stable alias for a background job, or `undefined` when the id is empty
  * or the locale carries no vocabulary.
  * @param jobId - the native job id (`bash-1`, `pwsh-2`, …).
- * @returns the locale-formatted alias, e.g. `蔚蓝水獭` / `azure otter`.
+ * @returns the locale-formatted alias, e.g. `昏风` / `twilight wind`.
  */
 export declare function jobAlias(jobId: string): string | undefined;
+/** The four directional beasts, hashed from the child session id. */
+export declare const SUBAGENT_BEASTS: readonly ["azure-dragon", "white-tiger", "vermilion-bird", "black-tortoise"];
+export type SubagentBeastId = (typeof SUBAGENT_BEASTS)[number];
+export type SubagentRoleId = 'scout' | 'scribe' | 'artisan' | 'envoy' | 'inquirer' | 'sentinel' | 'steward' | 'courier';
+/** Distill a parent spawn description into one role id. */
+export declare function subagentRoleId(task: string): SubagentRoleId;
+/** Hash the child session onto one of the four beasts. */
+export declare function subagentBeastId(sessionId: string): SubagentBeastId;
+/** Localized role label (`探路` / `scout`). */
+export declare function subagentRoleLabel(role: SubagentRoleId): string;
+/** Localized beast label (`青龙` / `Azure Dragon`). */
+export declare function subagentBeastLabel(beast: SubagentBeastId): string;
+/**
+ * Chip title: `探路·青龙` / `Scout · Azure Dragon`.
+ * Falls back to the spawn-time label when neither task nor id can be named.
+ */
+export declare function subagentCourtesyName(input: {
+    sessionId: string;
+    task?: string;
+    fallback: string;
+}): string;
+/** True when a string looks like a session / tool-call id, not a display name. */
+export declare function looksLikeOpaqueId(value: string): boolean;
+/** Prefer a recorded tool name; never surface `call-<uuid>` as a title. */
+export declare function displayToolName(name: string | undefined): string;

package/lib/types/picker.d.ts

@@ -11,6 +11,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { openResumableSessionPager, type ResumableSession } from './session-list.js';
+import { type TerminalCapabilities } from './terminal-caps.js';
 /** What the launch picker decided. */
 export type SessionPickerResult = {
     kind: 'resume';
@@ -144,5 +145,7 @@ export interface SessionPickerOptions {
     stdin?: NodeJS.ReadStream;
     stdout?: NodeJS.WriteStream;
     openPager?: typeof openResumableSessionPager;
+    /** The terminal to act on; defaults to reading the environment (tests inject). */
+    terminalCaps?: TerminalCapabilities;
 }
 export declare function showSessionPicker(ctx: Context, color: boolean, signal?: AbortSignal, options?: SessionPickerOptions): Promise<SessionPickerResult>;

package/lib/types/plan.d.ts

@@ -1,7 +1,8 @@
 /**
  * Plan dock, todo lists, /find, prompt-injection cards, and compact errors.
  */
-import type { DisplayKind, PlanTodoItem, Row, SubagentLogEntry } from './transcript-types.js';
+import { type TextSegment } from './term-text.js';
+import type { DiffDisplayLine, DisplayKind, PlanTodoItem, Row, SubagentLogEntry } from './transcript-types.js';
 export declare const MAX_SUBAGENT_LOGS = 80;
 export declare const TODO_STATUS_MARK: Record<PlanTodoItem['status'], string>;
 /** True while a plan still belongs in the dock (latest incomplete work). */
@@ -78,10 +79,99 @@ export declare function parsePlanTodos(value: unknown): PlanTodoItem[];
 export declare function todoSummary(value: unknown): string;
 /** Compact ask_user_question summary from tool arguments. */
 export declare function askSummary(value: unknown): string;
-/** One-line subagent card header used while collapsed. */
-export declare function subagentHeaderText(row: Extract<Row, {
+/** First non-empty line, collapsed to a single scan line. */
+export declare function firstDisplayLine(text: string): string;
+/** Collapse a child-session blob to one short chip/wait-card line. */
+export declare function clipSubagentActivity(text: string, maxChars?: number): string;
+/** Running / ok / aborted / error → ANSI for the status dot and status word. */
+export declare function subagentStateColor(status: Extract<Row, {
     kind: 'subagent';
-}>, now?: number): string;
+}>['status']): '33' | '32' | '31' | '90';
+/**
+ * Rebuild a subagent chip from the parent spawn tool call that survives in the
+ * session log. Live `subagent/start` is not replayed, so resume would otherwise
+ * show a generic tool card titled from the English description ("probe").
+ */
+export declare function subagentRowFromSpawnTool(input: {
+    callId: string;
+    task: string;
+    provider?: string;
+    /** Model route for the child, when the caller knows it. */
+    modelProvider?: string;
+    local?: boolean;
+    status?: Extract<Row, {
+        kind: 'subagent';
+    }>['status'];
+    startedAt?: number;
+    endedAt?: number;
+    output?: string;
+}): Extract<Row, {
+    kind: 'subagent';
+}>;
+/**
+ * Courtesy title: distilled role plus a directional beast.
+ *
+ * The beast comes from the child's own session id, never the parent call id a
+ * replayed chip was built with: the same child must keep its symbol across a
+ * `--resume`.
+ */
+export declare function subagentDisplayName(row: Extract<Row, {
+    kind: 'subagent';
+}>): string;
+/**
+ * Short activity for the collapsed chip and wait card: prefer the parent
+ * task name, else a clipped last log line. Never the full child transcript.
+ */
+export declare function subagentChipSummary(row: Extract<Row, {
+    kind: 'subagent';
+}>): string;
+/** Header + SGR spans: identity color, status dot/word, muted summary. */
+export declare function buildSubagentHeader(input: {
+    focused: boolean;
+    title: string;
+    status: Extract<Row, {
+        kind: 'subagent';
+    }>['status'];
+    elapsedLabel: string;
+    summary: string;
+    spinner?: string;
+    inspectHint?: string;
+    /** Different provider from the parent: paint the title cyan, not violet. */
+    foreign?: boolean;
+}): {
+    plain: string;
+    segments: TextSegment[];
+};
+/** Map a folded child-session event onto an existing display role. */
+export declare function subagentLogDisplayKind(entry: SubagentLogEntry, status: Extract<Row, {
+    kind: 'subagent';
+}>['status']): DisplayKind;
+/**
+ * Overlay body: session line, stop reason, then the clipped child log.
+ *
+ * The child's session id is the one `/subagents kill` takes, so it belongs on
+ * this line — the collapsed chip stays free of opaque ids.
+ */
+export declare function subagentInspectLines(row: Extract<Row, {
+    kind: 'subagent';
+}>): DiffDisplayLine[];
+/**
+ * Classify a child-session error so the chip can say *why* it died, not just
+ * that it ended. Quota and expired auth get a command that actually helps;
+ * everything else keeps a clipped diagnostic.
+ */
+export declare function describeSubagentFailure(input: {
+    stopReason?: string;
+    message?: string;
+    provider?: string;
+}): {
+    hint: string;
+    kind: 'quota' | 'auth' | 'effort' | 'error';
+} | undefined;
 export declare function appendSubagentLog(row: Extract<Row, {
     kind: 'subagent';
 }>, entry: SubagentLogEntry): void;
+/** Fold a child user/plugin blob: reminders become one inject chip, not raw XML. */
+export declare function foldSubagentUserLog(row: Extract<Row, {
+    kind: 'subagent';
+}>, text: string, sourceKind?: string, plugin?: string): void;

package/lib/types/platform.d.ts

@@ -0,0 +1,215 @@
+/** This process is running on Windows. */
+export declare const IS_WINDOWS: boolean;
+/** Windows delivers resizes on the stream; everyone else raises SIGWINCH. */
+export declare function usesSigwinch(platform?: NodeJS.Platform): boolean;
+/** The launcher's environment file: a shell fragment or a `cmd` script. */
+export declare function envFileName(platform?: NodeJS.Platform): string;
+/** The shell a Windows user has: PowerShell, where POSIX code would say bash. */
+export declare function shellName(platform?: NodeJS.Platform): string;
+/**
+ * Whether lock liveness is decided by asking the OS about the process (Windows:
+ * `Get-Process` + creation time) rather than by reading `/proc` (Linux) or the
+ * command line (darwin).
+ *
+ * `lockOwnerIsAlive` returns early into `windowsProcessMatchesLock` when this is
+ * true; the POSIX body below it has no meaning there (`/proc` does not exist).
+ */
+export declare function usesProcessIdentity(platform?: NodeJS.Platform): boolean;
+/**
+ * How to start the background Host so it outlives this process *and* does not
+ * make its own children flash console windows on Windows.
+ *
+ * POSIX wants `detached: true` (setsid) so the Host survives the launcher and a
+ * hung-up terminal.
+ *
+ * Windows is the opposite, and the trade-off is forced: `detached: true` maps to
+ * DETACHED_PROCESS, and Windows ignores CREATE_NO_WINDOW (what `windowsHide`
+ * sets) when DETACHED_PROCESS is present. Every console child the Host then
+ * starts — each tool call, every shell, node, git — allocates its own console,
+ * which is a visible window flashing over the TUI. So the Host is spawned
+ * non-detached and inherits the launcher's console; descendants inherit it too
+ * instead of creating one.
+ *
+ * The price *was* on the lifecycle side, and it was measured (on the Windows CI
+ * leg by `scripts/tui-mock-probe.mjs --busy`, not reasoned about): libuv assigns
+ * a non-detached child to its global job object, which is created with
+ * KILL_ON_JOB_CLOSE. The launcher died, the job closed, and the Host was
+ * terminated with it — a closed terminal window ended the session's compute.
+ *
+ * This function still returns `detached: false` there, because it describes a
+ * *direct* spawn, and a direct spawn cannot have both properties: Node exposes
+ * `detached` (DETACHED_PROCESS, which makes Windows ignore CREATE_NO_WINDOW) and
+ * `windowsHide`, but not `CREATE_NEW_CONSOLE`. The way out is to not spawn the
+ * Host directly on Windows: {@link hostBootstrapCommand} starts it through the
+ * OS PowerShell, which *can* ask for a new console and hide it. This direct path
+ * stays as the fallback for a Windows box without PowerShell.
+ */
+export declare function hostSpawnOptions(platform?: NodeJS.Platform): {
+    detached: boolean;
+    windowsHide: boolean;
+};
+/**
+ * The Windows PowerShell that ships with the operating system.
+ *
+ * `powershell.exe` and not `pwsh.exe`: the latter is PowerShell 7, an optional
+ * install, while 5.1 is part of Windows 10/11. `%SystemRoot%` is where it lives
+ * (`%windir%` is the legacy spelling of the same thing); when neither is set
+ * there is nothing to find, and the caller falls back to a direct spawn.
+ */
+export declare function windowsPowerShellPath(env?: NodeJS.ProcessEnv): string | undefined;
+/** A PowerShell single-quoted literal; `''` is the only escape inside one. */
+export declare function psQuote(value: string): string;
+/**
+ * Quote one argv array into a Windows command line, the way `CreateProcess`
+ * parses it back (the rule from "Everyone quotes command line arguments the
+ * wrong way"): wrap in double quotes when the argument is empty or contains
+ * whitespace or a quote, double the backslashes that precede a quote, and double
+ * trailing backslashes before the closing quote. `Start-Process -ArgumentList`
+ * joins its array with spaces and adds no quoting of its own, so the line has to
+ * be right before it is handed over — a `DSH_HOME` with a space in it is the
+ * normal case, not the exotic one.
+ */
+export declare function windowsCommandLine(argv: string[]): string;
+/** `-EncodedCommand` wants base64 of UTF-16LE, which is also what dodges quoting. */
+export declare function encodePowerShellCommand(script: string): string;
+/**
+ * The bootstrap script: start the Host with **its own console, hidden**, and
+ * print its pid so the launcher can watch it.
+ *
+ * `Start-Process -WindowStyle Hidden` is the only way to ask for this from a
+ * Node process. It is ShellExecuteEx/CreateProcess with `CREATE_NEW_CONSOLE` and
+ * `SW_HIDE`: the Host gets a console of its own, so closing the user's terminal
+ * no longer takes it down, and that console is invisible, so the tool calls that
+ * inherit it do not flash. `-PassThru` gives the object whose `Id` is printed;
+ * `-RedirectStandardError` keeps the Host's stderr log, which the direct spawn
+ * used to feed through an inherited fd.
+ *
+ * The whole script travels as an encoded command, so nothing in it is ever
+ * re-parsed by a shell.
+ */
+export declare function hiddenConsoleHostScript(options: {
+    execPath: string;
+    argv: string[];
+    /** Where the Host's stderr goes; omitted only in tests. */
+    stderrFile?: string;
+    /** Where the Host's pid is written for the launcher to read. */
+    pidFile: string;
+}): string;
+/**
+ * Set on the Host's environment by the bootstrap below, through
+ * {@link bootstrapEnv}.
+ *
+ * The Host cannot ask whether it has a console of its own — Node exposes no such
+ * question — so the launcher tells it. That is what lets the one build where the
+ * lifecycle promise does not hold (Windows, no PowerShell, direct child) say so
+ * at boot instead of letting the user discover it by closing the window.
+ */
+export declare const TUI_HOST_START_ENV = "DSH_TUI_HOST_START";
+/** Marker value for a Host started with a hidden console of its own. */
+export declare const TUI_HOST_START_BOOTSTRAP = "hidden-console";
+/** The environment the bootstrap hands to the Host: the marker is added here. */
+export declare function bootstrapEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Whether this Host survives its terminal being closed.
+ *
+ * POSIX always does (`setsid`); Windows does exactly when the bootstrap started
+ * it. A Windows Host without the marker is the fallback direct child, which
+ * libuv's `KILL_ON_JOB_CLOSE` job takes down with the launcher — the one case
+ * worth a boot notice.
+ */
+export declare function hostHasOwnConsole(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): boolean;
+/** How the Host is started when it must not be a direct child. */
+export interface HostBootstrapCommand {
+    command: string;
+    args: string[];
+}
+/**
+ * The hidden-console bootstrap for this platform, or `undefined` when the Host
+ * should be spawned directly.
+ *
+ * Windows only, and only when the OS PowerShell is really there: the caller
+ * falls back to {@link hostSpawnOptions}, which keeps the boot working (without
+ * the survival property) on a machine where PowerShell is missing or blocked.
+ * `exists` is injectable so the decision is assertable on Linux.
+ */
+export declare function hostBootstrapCommand(options: {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    exists?: (path: string) => boolean;
+    execPath: string;
+    argv: string[];
+    stderrFile?: string;
+    pidFile: string;
+}): HostBootstrapCommand | undefined;
+/**
+ * A path a human can read, with the platform's own shorthand.
+ *
+ * `~/.dsh/env.sh` is the POSIX form; Windows users know `%USERPROFILE%`, and a
+ * `C:\Users\...` prefix spelled out is noise in a one-line hint.
+ */
+export declare function displayHomePath(home: string, file: string, options?: {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    userHome?: string;
+}): string;
+/**
+ * Who owns the files this plugin writes, and how to keep it that way.
+ *
+ * On POSIX the `mode` passed to `writeFile`/`mkdir` (`0o600`, `0o700`) is the
+ * whole story. **On Windows it is silently ignored**, and the files that matter
+ * here are not cosmetic: `env.cmd` carries API keys, the SuperGrok token file
+ * carries an OAuth grant, and the lock/socket directories carry session
+ * metadata. What they get instead is the ACL inherited from their parent — fine
+ * under `%USERPROFILE%\.dsh`, and *not* fine when `DSH_HOME` points somewhere
+ * shared (`C:\dsh`, a network share, a machine where `Users` can read the
+ * directory), which is exactly when nobody notices.
+ *
+ * So the intent is applied explicitly: `icacls` with inheritance removed and a
+ * single grant to the current user. The argv is built by a pure function so it
+ * can be asserted on Linux; applying it is best-effort by design — a machine
+ * without `icacls`, or a path held open by another process, must not fail the
+ * write that just succeeded. Failing closed here would mean a TUI that cannot
+ * save its own settings.
+ */
+/**
+ * The account `icacls` should grant, or undefined when the environment has none.
+ *
+ * `%USERDOMAIN%\%USERNAME%` where both are present: on a domain-joined machine a
+ * bare name can resolve to the machine-local account of the same name, and a
+ * grant to the wrong account — with inheritance already removed — would leave
+ * the user's own API keys inaccessible to them.
+ */
+export declare function aclUserName(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string | undefined;
+/**
+ * The exact `icacls` arguments for one path.
+ *
+ * `/inheritance:r` drops what the parent offered (this is the part that matters:
+ * adding a grant without removing inheritance leaves `Users` in place), and
+ * `(OI)(CI)` makes a directory's grant apply to what is created inside it —
+ * without it every new lock file would need its own call.
+ */
+export declare function restrictPathArgs(path: string, user: string, options?: {
+    directory?: boolean;
+}): string[];
+/** Directories and files whose contents must not be readable by other users. */
+export interface RestrictDeps {
+    /** Runner for `icacls`; injected by tests. Returns true on success. */
+    run?: (command: string, args: string[]) => boolean;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Apply `mode` on POSIX, a single-user ACL on Windows.
+ *
+ * Returns whether the restriction was applied. Never throws: the caller has
+ * already written the file, and a permission call is not worth losing it over.
+ */
+export declare function restrictPathToUser(path: string, options?: {
+    mode: number;
+    directory?: boolean;
+} & RestrictDeps): Promise<boolean>;
+/** Synchronous twin, for the sites that create their file with `openSync`. */
+export declare function restrictPathToUserSync(path: string, options?: {
+    mode: number;
+    directory?: boolean;
+} & RestrictDeps): boolean;

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

@@ -20,21 +20,13 @@
  *   every later launch falls back to the default.
  * @module dsh-ssh-tui/preset-authoring
  */
-import { type AgentPreset, type PresetMetadata } from '@deepseek-ai/dsh-agent-presets';
+import { presetDirectory, type AgentPreset, type PresetMetadata } from './preset-compat.js';
+export { presetDirectory };
 /** The id shape discovery accepts; a directory that fails it is skipped. */
 export declare const PRESET_ID_PATTERN: RegExp;
 /** Whether an id would be discovered at all. */
 export declare function validatePresetId(id: string): boolean;
-/**
- * The directory a preset owns.
- *
- * `AgentPreset.path` is the composition file the preset publishes, not the
- * directory, so anything that writes beside it (display metadata) starts here.
- * @param preset - a discovered preset.
- * @returns the absolute preset directory.
- */
-export declare function presetDirectory(preset: AgentPreset): string;
-export type PresetRefusalCode = 'invalid-id' | 'exists' | 'not-found' | 'read-only' | 'system' | 'running' | 'empty-metadata';
+export type PresetRefusalCode = 'invalid-id' | 'exists' | 'not-found' | 'read-only' | 'system' | 'managed' | 'running' | 'empty-metadata';
 export interface PresetRefusal {
     error: PresetRefusalCode;
     /** The id the refusal is about, when it names one. */
@@ -78,9 +70,11 @@ export interface PresetCompositionView {
 }
 /**
  * The authoring subset of the service, feature-detected rather than assumed:
- * the plugin still supports 0.1.2-rc.1, whose `agentPresets` may predate
- * `copy`, `remove`, `read`, and `compositionInventory`. A missing member turns
- * into a clear message instead of a crash.
+ * the two supported lines expose different preset services under the same
+ * `agentPresets` name. 0.1.5's `dsh-agent-presets` carries `copy`, `remove`,
+ * `read` and `compositionInventory`; the 0.1.7 registry
+ * (`dsh-agent-preset-registry`) does not. A missing member turns into a clear
+ * message instead of a crash.
  */
 export interface PresetAuthoringApi {
     readonly authorable?: boolean;

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

@@ -0,0 +1,58 @@
+/** 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. */
+    readonly order?: number;
+}
+/** Where a preset's composition came from, on the line that still records it. */
+export type PresetTrust = 'system' | 'user';
+/**
+ * One preset, as much of it as this plugin reads.
+ *
+ * `id`/`name`/`description`/`order`/`broken` are the fields both lines agree on.
+ * `path` (the composition file) and `trust` (the root it was discovered under)
+ * only exist on the 0.1.5 line; every consumer here treats them as optional,
+ * and the authoring paths refuse rather than guess when they are gone.
+ */
+export interface AgentPreset {
+    readonly id: string;
+    readonly name?: string;
+    readonly description?: string;
+    readonly order?: number;
+    readonly broken?: string;
+    /** 0.1.5 line only: absolute path of the preset's agent composition file. */
+    readonly path?: string;
+    /** 0.1.5 line only: trust recorded from the root it was discovered under. */
+    readonly trust?: PresetTrust;
+}
+/**
+ * The directory a preset owns, when the host still exposes one.
+ *
+ * `AgentPreset.path` is the composition file the preset publishes, not the
+ * directory, so anything that writes beside it (display metadata) starts here.
+ * `undefined` on a host that lists declarative presets instead of directories.
+ * @param preset - a discovered preset.
+ * @returns the absolute preset directory, or undefined when there is none.
+ */
+export declare function presetDirectory(preset: AgentPreset): string | undefined;
+/**
+ * Read a preset's display metadata. Every failure degrades to no metadata: a
+ * preset whose display text is missing, malformed, or unreadable still mounts.
+ * @param directory - the preset directory to read `preset.yml` from.
+ * @returns the published name/description/order, or `{}`.
+ */
+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;

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

@@ -9,7 +9,7 @@
  * service — the caller passes what `list()` returned.
  * @module dsh-ssh-tui/preset-picker
  */
-import type { AgentPreset } from '@deepseek-ai/dsh-agent-presets';
+import type { AgentPreset } from './preset-compat.js';
 /** One option as the question dialog wants it, plus the id it stands for. */
 export interface PresetPickerOption {
     id: string;