dsh-code 1.3.0 → 1.4.0

package/lib/types/{kernel-panels.d.ts → panels/kernel-panels.d.ts}

@@ -1,24 +1,18 @@
 /** Bounded, composer-safe panels for preset, session, and plugin kernel views. */
 import { type ReactElement } from 'react';
-import type { ModelDirectory, ModelRow } from './models.ts';
-import type { SubagentRow } from './subagents.ts';
-import type { ScheduleRow } from './render/projection.ts';
-import type { PermissionRow } from './permissions.ts';
-import type { PresetRow } from './presets.ts';
-import type { PluginRow } from './plugin-inventory.ts';
-import type { SessionDirectoryOptions, SessionRow } from './session-directory.ts';
-import type { ReviewBranch, ReviewCommit, ReviewSelection } from './git-workflow.ts';
-import { type UsageView } from './render/usage.ts';
-import { type StatusItemId } from './render/status.ts';
-/**
- * Apply one keystroke to a panel search query. IME commits arrive as one
- * multi-character chunk, so the whole printable run is appended; paste
- * markers are stripped and control-laden chunks are ignored.
- */
-export declare function editQuery(query: string, input: string, key: {
-    backspace?: boolean;
-    delete?: boolean;
-}): string | undefined;
+import type { ModelDirectory, ModelRow } from '../models.ts';
+import type { SubagentRow } from '../session/subagents.ts';
+import type { SearchRow } from '../runner/search-rows.ts';
+export type { SearchRow } from '../runner/search-rows.ts';
+import type { ScheduleRow } from '../render/projection.ts';
+import type { PermissionRow } from '../permissions.ts';
+import type { PresetRow } from '../presets.ts';
+import type { PluginRow } from '../plugin-inventory.ts';
+import type { SessionDirectoryOptions, SessionRow } from '../session/session-directory.ts';
+import type { ReviewBranch, ReviewCommit, ReviewSelection } from '../git-workflow.ts';
+import { type UsageView } from '../render/usage.ts';
+import { type StatusItemId } from '../render/status.ts';
+export { editQuery } from '../ui/query-editor.ts';
 export declare function ModePanel({ current, load, select, close }: {
     current: string;
     load: () => Promise<readonly PresetRow[]>;
@@ -110,23 +104,6 @@ export declare function ReviewPickerPanel({ loadBranches, loadCommits, choose, c
     choose: (selection: ReviewSelection) => void;
     close: () => void;
 }): ReactElement;
-/** One cross-session full-text search hit mapped from the session-query engine. */
-export interface SearchRow {
-    /** Session id (Enter resumes it through the switch machinery). */
-    readonly id: string;
-    /** Display label: session title or the short id form. */
-    readonly label: string;
-    /** Secondary facts line (workspace · preset markers). */
-    readonly detail: string;
-    /** Bounded plain-text excerpt around the strongest match. */
-    readonly snippet: string;
-    /** Match timestamp (relative labels derive from it). */
-    readonly updatedAt: number;
-    /** Whether the hit is a delegated subagent conversation (not resumable). */
-    readonly subagent: boolean;
-    /** Whether Enter may switch into it. */
-    readonly resumable: boolean;
-}
 /**
  * The /search panel: full-text search over every persisted session through
  * the in-process session-query engine (the same corpus the model's
@@ -182,13 +159,15 @@ export declare function EffortPanel({ row, current, select, back, onExit }: {
  * Enter/t opening the child's full transcript in the shared read-only
  * document view (the same projection the exporter uses).
  */
-export declare function AgentsPanel({ live, load, readTranscript, close }: {
+export declare function AgentsPanel({ live, load, readTranscript, attach, close }: {
     /** Live feed rows (child sessions observed this process). */
     live: readonly SubagentRow[];
     /** Load this session's persisted child sessions by lineage. */
     load: () => Promise<readonly SessionRow[]>;
     /** Read one child session's full transcript as markdown. */
     readTranscript: (id: string, signal?: AbortSignal) => Promise<string>;
+    /** Attach to one child as the whole view (the runner's live buses). */
+    attach: ((id: string, label: string) => void) | undefined;
     close: () => void;
 }): ReactElement;
 /**

package/lib/types/{language-panel.d.ts → panels/language-panel.d.ts}

@@ -4,7 +4,7 @@
  * repainting the whole screen so Static-region text switches too).
  */
 import { type ReactElement } from 'react';
-import { type LanguageName } from './i18n.ts';
+import { type LanguageName } from '../i18n.ts';
 export declare function LanguagePanel({ current, select, close }: {
     current: LanguageName;
     select: (name: LanguageName) => void;

package/lib/types/panels/model-panels.d.ts

@@ -0,0 +1,86 @@
+/** Model selection and provider-management panels for the terminal app. */
+import { type ReactElement } from 'react';
+import type { ModelDirectory, ModelRow } from '../models.ts';
+import { type DiscoveredModelView, type ProviderConfiguration, type ProviderSettingsDirectory, type ProviderTargetView } from '../provider-settings.ts';
+import { type ProviderAuthorizationDirectory, type ProviderAuthorizationRow } from '../authorization.ts';
+export declare function ModelPanel({ directory, error, current, onSelect, onProviders, onRetry, onClose }: {
+    directory: ModelDirectory | undefined;
+    error: string | undefined;
+    /** `provider/model` label of the applied model: the cursor lands on it once. */
+    current?: string;
+    onSelect: (row: ModelRow) => void;
+    onProviders?: () => void;
+    onRetry: () => void;
+    onClose: () => void;
+}): ReactElement;
+/** The provider-management stage reached from /model with `a`. */
+export declare function ProviderPanel({ directory, error, authorizations, authorizationError, onConfigure, onUnset, onRemove, onRetry, onBack, onExit }: {
+    directory: ProviderSettingsDirectory | undefined;
+    error: string | undefined;
+    authorizations: ProviderAuthorizationDirectory | undefined;
+    authorizationError: string | undefined;
+    onConfigure: (target: ProviderTargetView) => void;
+    onUnset: (target: ProviderTargetView) => void;
+    onRemove: (target: ProviderTargetView) => void;
+    onRetry: () => void;
+    onBack: () => void;
+    /** Leave the whole /model flow (Ctrl+C), not just this stage. */
+    onExit: () => void;
+}): ReactElement;
+/** Provider configuration editor: only explicit models are written to settings. */
+/**
+ * The unified provider setup page: API key, endpoint, and the explicit model
+ * list (with per-model context/output capacities) on ONE screen — the deep
+ * Tab menu and the separate key panel merged into a single discoverable
+ * surface. A saved key rides the same Enter as the endpoint and models; an
+ * empty endpoint keeps the provider's official default. Tab moves to the
+ * discovery page, which interrogates the real endpoint and returns checkable
+ * models for adoption; the last row also accepts hand-typed model ids.
+ */
+/** One declarable donor the setup page can copy reasoning efforts from verbatim. */
+export interface EffortDonor {
+    /** Provider route the declaration lives on. */
+    readonly provider: string;
+    /** Model id the declaration belongs to. */
+    readonly id: string;
+    /** The stored display-level to wire-value map, copied verbatim. */
+    readonly efforts: Record<string, string | null>;
+}
+export declare function ProviderSetupPanel({ target, authorization, onSubscribe, save, saveCredential, discover, effortDonors, done, back, onExit }: {
+    target: ProviderTargetView;
+    /**
+     * The provider's sign-in flow, when it offers a web (OAuth) channel: its
+     * presence adds the subscription/key mode layer at the top of the page.
+     */
+    authorization: ProviderAuthorizationRow | undefined;
+    /** Open the subscription channel: sign in when logged out, confirm sign-out when logged in. */
+    onSubscribe: (() => void) | undefined;
+    /** Models with declared efforts (settings first, catalog-advertised after) a model row can copy from. */
+    effortDonors: readonly EffortDonor[];
+    save: (target: ProviderTargetView, configuration: ProviderConfiguration) => Promise<void>;
+    saveCredential: ((target: ProviderTargetView, key: string) => Promise<void>) | undefined;
+    discover: (target: ProviderTargetView, request: {
+        readonly apiKey?: string;
+        readonly baseURL?: string;
+    }, signal?: AbortSignal) => Promise<readonly DiscoveredModelView[]>;
+    /** Report a successful save so the surface can notice the key rotation. */
+    done: (result: {
+        readonly key: boolean;
+    }) => void;
+    back: () => void;
+    /** Leave the whole /model flow (Ctrl+C), not just this page. */
+    onExit: () => void;
+}): ReactElement;
+/** Bounded destructive-action confirmation for credential or provider removal. */
+export declare function ProviderConfirmPanel({ target, kind, confirm, done, back }: {
+    target: ProviderTargetView;
+    kind: 'credential' | 'provider';
+    confirm: (target: ProviderTargetView) => Promise<void>;
+    done: () => void;
+    back: () => void;
+}): ReactElement;
+/**
+ * The /help overlay: one scrolling card with the keyboard map, the TUI-local
+ * commands, the live registry commands, and the user-invocable skills — the
+ * real command surface, replacing the one-line notice.
+ */

package/lib/types/{theme-panel.d.ts → panels/theme-panel.d.ts}

@@ -7,7 +7,7 @@
  * @module @deepseek-ai/dsh-tui/theme-panel
  */
 import { type ReactElement } from 'react';
-import { type ThemeName } from './theme.ts';
+import { type ThemeName } from '../theme.ts';
 /**
  * The /theme list: one row per theme, the current one marked with ●, the
  * focused one with ›. Enter applies the focused theme (the runner persists

package/lib/types/{update-panel.d.ts → panels/update-panel.d.ts}

@@ -9,7 +9,7 @@
  * here.
  */
 import { type ReactElement } from 'react';
-import type { LauncherUpdatePlan, LauncherUpdateStatus } from './update.ts';
+import type { LauncherUpdatePlan, LauncherUpdateStatus } from '../update.ts';
 /** Retained apply-progress lines (ring tail; npm output is ephemeral). */
 export declare const UPDATE_OUTPUT_CAP = 800;
 /** Keep the newest UPDATE_OUTPUT_CAP lines of streamed update output. */

package/lib/types/provider-settings.d.ts

@@ -197,6 +197,17 @@ export declare function loadProviderSettings(ctx: Context): Promise<ProviderSett
 export declare function saveProviderCredential(ctx: Context, target: ProviderTargetView, rawKey: string): Promise<void>;
 /** Save the endpoint and an explicit model allow-list without rebuilding the profile. */
 export declare function saveProviderConfiguration(ctx: Context, target: ProviderTargetView, configuration: ProviderConfiguration): Promise<void>;
+/**
+ * Switch one provider route to its subscription (plan sign-in) channel: the
+ * profile keeps neither a key reference nor an explicit model list, so the
+ * official catalog endpoint serves requests and the stored OAuth record — not
+ * a settings-named key override — authenticates them. Enabling a route that
+ * has no profile yet creates the empty profile that registers it.
+ * @param ctx - context carrying the `settings` service.
+ * @param target - provider row whose settings namespace owns the profile.
+ * @throws when the route is unmanaged or settings are read-only.
+ */
+export declare function enableProviderSubscription(ctx: Context, target: ProviderTargetView): Promise<void>;
 /**
  * Interrogate a provider endpoint for the models it really serves, through
  * the model-discovery capability the provider's settings namespace

package/lib/types/render/inspector.d.ts

@@ -48,6 +48,14 @@ export declare function liveRegionBudget(chrome: LiveRegionChrome): number;
  * accumulated `<Static>` output on every frame.
  */
 export declare function panelViewport(columns: number, rows: number): InspectorViewport;
+/**
+ * Viewport for an expanded (near-fullscreen) document overlay: the document
+ * replaces the transcript area entirely, so the half-screen overlay cap and
+ * the inter-section gaps drop away while the bottom live region (composer,
+ * status) and the Static-rewrite margin stay reserved. The result stays
+ * below terminal height, which is what keeps Ink off its full-rewrite path.
+ */
+export declare function expandedDocumentViewport(columns: number, rows: number): InspectorViewport;
 /** Backward-compatible name for the Ctrl+O-specific caller and tests. */
 export declare function inspectorViewport(columns: number, rows: number): InspectorViewport;
 /** Clamp a first-visible row to the range representable by one viewport. */

package/lib/types/render/text.d.ts

@@ -11,6 +11,8 @@
  *
  * @module @deepseek-ai/dsh-code/render/text
  */
+import { stringWidth } from './width.ts';
+export { stringWidth };
 /**
  * Compact token count: exact below 1K, then one-decimal-ish K/M.
  * @param n - token count.
@@ -35,6 +37,8 @@ export declare function singleLineText(text: string): string;
  * combining sequences never split mid-cluster.
  */
 export declare function truncateColumns(text: string, columns: number): string;
+/** Sanitize, clip, and right-pad one cell to an exact terminal-column width. */
+export declare function padColumns(text: string, columns: number): string;
 /** A display-safe suffix bounded by terminal rows and columns. */
 export interface DisplayTail {
     /** Sanitized suffix suitable for direct terminal rendering. */

package/lib/types/runner/harness-gate.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Load-time DeepSeek Harness version gate.
+ *
+ * The terminal driver is validated against exactly one Harness snapshot, and
+ * the host resolves every bare `@deepseek-ai/*` import the plugin makes
+ * against ITS OWN installed copies (the profile's `HostResolvedRootInclude`
+ * redirects bare names to the installed-host base). No install-time or
+ * load-time check exists anywhere on that path, so a user who updates `dsh`
+ * would otherwise run this build against unvetted upstream code silently.
+ *
+ * This gate mirrors how the host itself reads its identity: the running CLI
+ * entry (`process.argv[1]`) sits inside the `@deepseek-ai/dsh` package, whose
+ * manifest version is released in lockstep with the Harness packages bundled
+ * beside it. When the probe can identify the host it compares the running
+ * versions against the one this build declares and fails fast with an
+ * actionable message; when it cannot identify the host it stays silent rather
+ * than brick a supported embedding on a false positive.
+ *
+ * @module @deepseek-ai/dsh-code/runner/harness-gate
+ */
+/** The one Harness release this build was validated against. */
+export declare const EXPECTED_HARNESS_VERSION = "0.1.5-rc.2";
+/** Host packages whose bundled copy the plugin binds to at runtime. */
+export declare const HARNESS_GATE_PACKAGES: readonly ["@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-session"];
+/** Filesystem slice the probe needs; injectable so tests stay pure. */
+export interface HarnessFs {
+    /** Resolve a symlinked entry to its real path. */
+    realpathSync(path: string): string;
+    /** Read and parse one package.json; undefined when absent or unreadable. */
+    readManifest(path: string): {
+        name?: unknown;
+        version?: unknown;
+    } | undefined;
+}
+/** What the probe learned about the running host. */
+export interface HarnessProbe {
+    /** Installed-host package root, when identified. */
+    readonly hostRoot?: string;
+    /** Installed-host CLI version (`@deepseek-ai/dsh`). */
+    readonly hostVersion?: string;
+    /** Version of each gate package bundled beside the host, when present. */
+    readonly packages: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * Identify the running host and the Harness versions it provides.
+ * @param argv1 - `process.argv[1]`, the running CLI entry path.
+ * @param fs - filesystem slice; defaults to the real one.
+ * @returns the probe result; `packages` is empty when the host is unknown.
+ */
+export declare function probeRunningHarness(argv1: string | undefined, fs?: HarnessFs): HarnessProbe;
+/** One host fact that disagrees with the version this build declares. */
+export interface HarnessMismatch {
+    /** What was compared: the host CLI or one bundled package. */
+    readonly source: string;
+    /** The version this build was validated against. */
+    readonly expected: string;
+    /** The version the running host actually provides. */
+    readonly provided: string;
+}
+/**
+ * Compare one probe against the expected snapshot. Unknown facts never
+ * mismatch: the gate must stay silent when it cannot judge, not brick a
+ * supported embedding on missing evidence.
+ * @param expected - the Harness version this build declares.
+ * @param probe - the running host's identified versions.
+ * @returns every concrete disagreement, empty when compatible or unknown.
+ */
+export declare function harnessVersionMismatches(expected: string, probe: HarnessProbe): readonly HarnessMismatch[];
+/**
+ * Render the gate failure the user sees on stderr.
+ * @param expected - the Harness version this build declares.
+ * @param mismatches - the disagreements to report.
+ * @param hostRoot - installed-host root, when identified, for the fix hint.
+ * @returns the multi-line diagnostic.
+ */
+export declare function harnessGateMessage(expected: string, mismatches: readonly HarnessMismatch[], hostRoot?: string): string;
+/**
+ * Refuse to run against an identified-but-incompatible host.
+ * @param expected - the Harness version this build declares.
+ * @param probe - the running host's identified versions.
+ * @throws an Error carrying the gate diagnostic when a version disagrees.
+ */
+export declare function requireHarnessVersion(expected: string, probe: HarnessProbe): void;

package/lib/types/runner/input-history.d.ts

@@ -0,0 +1,31 @@
+/** Global input recall: the appended prompts and their durable JSONL file.
+ *
+ * One JSONL file under the DSH home. A missing file means an empty history and
+ * unreadable or corrupt content degrades to the valid lines it could parse,
+ * silently — recall is a convenience surface, never a gate.
+ *
+ * @module @deepseek-ai/dsh-code/input-history
+ */
+/** Live recall state plus its serialized durable writes. */
+export interface InputHistoryStore {
+    /** The recall list, newest last; read live by the composer. */
+    readonly entries: () => readonly string[];
+    /** Append one submitted line and persist it; '' is ignored. */
+    readonly record: (text: string) => void;
+    /** Await the pending writes (the quit flush). */
+    readonly flush: () => Promise<void>;
+}
+/**
+ * Load the recall history and return its live store.
+ *
+ * Serialized history writes: each submission appends one JSON line at the end
+ * of the file, so concurrent terminals add entries after each other instead of
+ * overwriting snapshots they read at their own boot. A multi-line draft still
+ * occupies one physical line (JSON escapes the newline), and a regular-length
+ * line reaches the disk as one positioned write; an oversized paste may
+ * interleave mid-line, which the next parse simply drops.
+ *
+ * @param path - absolute path of the JSONL recall file.
+ * @param onFailure - receives the write failure message for a bounded notice.
+ */
+export declare function createInputHistory(path: string, onFailure: (message: string) => void): InputHistoryStore;

package/lib/types/runner/mode-cycle.d.ts

@@ -0,0 +1,44 @@
+/** Shift+Tab mode-cycle stations for the terminal runner.
+ *
+ * Pure decision over the preset table and the committed plan fold: the runner
+ * applies the returned station, so the whole cycle is testable without a
+ * session.
+ *
+ * @module @deepseek-ai/dsh-code/mode-cycle
+ */
+/** One Shift+Tab station decision for the mode cycle. */
+export type ModeCycleDecision = {
+    readonly kind: 'permission';
+    readonly preset: string;
+} | {
+    readonly kind: 'plan-on';
+} | {
+    readonly kind: 'plan-off';
+    readonly preset: string;
+};
+/**
+ * Decide the next Shift+Tab station. The cycle keeps the preset table's
+ * own order (most restrictive first) and inserts ONE plan station between
+ * the most restrictive preset and the wrap target: with the shipped three
+ * presets the user sees workspace-write → danger-full-access → read-only
+ * → plan → workspace-write. Plan IS the most restrictive preset plus the
+ * plan prompt layer — entering it switches nothing (the cycle is already
+ * parked on read-only), and leaving it lands on the next preset after the
+ * most restrictive one. Without the /plan command the cycle is exactly the
+ * preset table.
+ *
+ * `planIntent` covers the committed fold's commit lag: upstream queues a
+ * plan switch during an open turn (and the command pipeline is async even
+ * idle), so the durable plan/mode event lands AFTER the press that chose
+ * it. While an intent from an earlier press is in flight it — not the
+ * stale committed fold — decides the station, so repeated presses advance
+ * the cycle instead of re-issuing the same plan transition (the stuck
+ * plan-on/plan-off toggle). Undefined falls back to the committed fold.
+ */
+export declare function planCycleDecision(input: {
+    readonly names: readonly string[];
+    readonly current: string;
+    readonly inPlan: boolean;
+    readonly planAvailable: boolean;
+    readonly planIntent?: boolean;
+}): ModeCycleDecision | undefined;

package/lib/types/runner/preferences.d.ts

@@ -0,0 +1,40 @@
+/** User-level preference files under the DSH home.
+ *
+ * The statusline, theme, language, and animations customizations each live in
+ * one small JSON file. They share exactly two policies: a missing file is the
+ * default and stays silent while a corrupt one degrades to the default with a
+ * surfaced warning (a user-authored customization must never fail silently),
+ * and every save goes through the serialized crash-atomic writer.
+ *
+ * @module @deepseek-ai/dsh-code/preferences
+ */
+import { type UserSettingsPersistence } from '../settings-file.ts';
+/** Absolute path of one preference file under the DSH home. */
+export declare function preferencePath(fileName: string): string;
+/** Outcome of reading one preference file. */
+export interface PreferenceRead<T> {
+    /** Parsed value; undefined when the file is missing or corrupt (keep the default). */
+    readonly value?: T;
+    /** Corruption message to surface; undefined for a missing or clean file. */
+    readonly warning?: string;
+}
+/**
+ * Read one field of a preference file. A missing file is silence — the default
+ * stands and nothing is reported — while unreadable JSON or a non-object
+ * document both warn and keep the default.
+ * @param path - absolute path of the preference file.
+ * @param field - the JSON field the file carries.
+ * @param parse - narrows the raw field to the usable value.
+ * @returns the parsed value and/or the warning to surface.
+ */
+export declare function readPreference<T>(path: string, field: string, parse: (raw: unknown) => T): PreferenceRead<T>;
+/**
+ * Persist one preference field through the serialized crash-atomic writer.
+ * A failed write is reported through `onFailure` instead of rejecting.
+ * @param persistence - the shared user-settings writer.
+ * @param path - absolute path of the preference file.
+ * @param field - the JSON field the file carries.
+ * @param value - the value to store under `field`.
+ * @param onFailure - receives the failure message for a bounded notice.
+ */
+export declare function savePreference(persistence: UserSettingsPersistence, path: string, field: string, value: unknown, onFailure: (message: string) => void): void;

package/lib/types/runner/quit.d.ts

@@ -0,0 +1,27 @@
+/** Ordered terminal quit cleanup.
+ *
+ * Pure sequencing: every step rejection is contained and the exit request is
+ * always reached exactly once, so a failing flush never strands the process.
+ *
+ * @module @deepseek-ai/dsh-code/quit
+ */
+/** One ordered step of the terminal quit cleanup. */
+export interface QuitCleanupStep {
+    /** Step label used in diagnostics and tests. */
+    readonly name: string;
+    /** The step's async work; a rejection is contained by the sequence. */
+    readonly run: () => Promise<void>;
+}
+/**
+ * Run the ordered quit cleanup, then request exit. Every step rejection is
+ * contained (reported through `onError`) so a failed flush or dispose never
+ * skips the remaining cleanup; the exit request is always reached exactly
+ * once.
+ * @param steps - the cleanup steps in dependency order (settle the visible
+ * session, await the final in-flight composition, await durable recall).
+ * @param exit - the terminal exit request (code 0).
+ * @param onError - optional failure sink; called once per failing step and
+ * itself contained, so a throwing sink cannot abort the sequence.
+ * @returns the names of the steps that started, in order (for tests).
+ */
+export declare function runQuitSequence(steps: readonly QuitCleanupStep[], exit: (code: number) => void, onError?: (name: string, error: unknown) => void): Promise<readonly string[]>;

package/lib/types/runner/search-rows.d.ts

@@ -0,0 +1,38 @@
+/** Cross-session search rows for the /search panel.
+ *
+ * Owns the panel row shape and the pure mapping from a session-query hit, so
+ * the row contract does not live inside the panel component that renders it
+ * and the runner can build rows without importing the panel module.
+ *
+ * @module @deepseek-ai/dsh-code/search-rows
+ */
+import type { SessionHeader } from '@deepseek-ai/dsh-session';
+/** One cross-session full-text search hit mapped from the session-query engine. */
+export interface SearchRow {
+    /** Session id (Enter resumes it through the switch machinery). */
+    readonly id: string;
+    /** Display label: session title or the short id form. */
+    readonly label: string;
+    /** Secondary facts line (workspace · preset markers). */
+    readonly detail: string;
+    /** Bounded plain-text excerpt around the strongest match. */
+    readonly snippet: string;
+    /** Match timestamp (relative labels derive from it). */
+    readonly updatedAt: number;
+    /** Whether the hit is a delegated subagent conversation (not resumable). */
+    readonly subagent: boolean;
+    /** Whether Enter may switch into it. */
+    readonly resumable: boolean;
+}
+/**
+ * Map one cross-session full-text hit onto the /search panel's row (pure).
+ * Labels fall back to the short id form — the engine's hit carries the
+ * strongest matching event, not the title observation.
+ */
+export declare function searchHitToRow(hit: {
+    header: SessionHeader;
+    bestMatch: {
+        snippet: string;
+        time: number;
+    };
+}): SearchRow;

package/lib/types/runner/session-io.d.ts

@@ -0,0 +1,46 @@
+/** Session directory IO exposed to the picker, /delete, and /export.
+ *
+ * The kernel persistence seam has NO deletion API by design — logs accumulate
+ * "until removed externally" — so removal is planned, layout-checked, and
+ * lease-guarded here before any file is touched. Every read goes through the
+ * in-process session-query engine, so this module stays free of `app.ts` and
+ * of the Ink tree.
+ *
+ * @module @deepseek-ai/dsh-code/runner/session-io
+ */
+import { type SessionDeletionPersistence, type SessionDirectoryOptions, type SessionQueryService, type SessionRow } from '../session/session-directory.ts';
+/**
+ * The persistence surface this module needs: the JSONL backend's public
+ * session root plus its per-session write handles. Typing the narrow shape
+ * instead of the upstream service keeps the IO injectable from a test double.
+ */
+export interface SessionIoPersistence extends SessionDeletionPersistence {
+    /** JSONL backend plugin config carrying the session root, when exposed. */
+    readonly config?: {
+        readonly root?: unknown;
+    };
+}
+/** Services the session IO closes over. */
+export interface SessionIoServices {
+    /** In-process session-query engine; absent in profiles without one. */
+    readonly sessionQuery?: SessionQueryService;
+    /** The durable persistence service; absent in profiles without one. */
+    readonly persistence?: SessionIoPersistence;
+    /** The session currently visible in the UI (self-deletion guard). */
+    readonly activeSessionId: () => string | undefined;
+}
+/** Session directory reads and the guarded /delete operation. */
+export interface SessionIo {
+    /** Project the session directory for the picker (query-filtered). */
+    readonly loadSessions: (options: SessionDirectoryOptions, signal?: AbortSignal) => Promise<readonly SessionRow[]>;
+    /** Delete one session subtree, returning the outcome line. */
+    readonly deleteSession: (id: string) => Promise<string>;
+    /** Render one session's whole transcript as export Markdown. */
+    readonly loadSessionTranscript: (id: string, signal?: AbortSignal) => Promise<string>;
+}
+/**
+ * Bind the session IO to one runner's services.
+ * @param services - the query engine, persistence, and the live-session probe.
+ * @returns the picker/delete/export reads used by the app bridge.
+ */
+export declare function createSessionIo(services: SessionIoServices): SessionIo;

package/lib/types/runner/session-target.d.ts

@@ -0,0 +1,42 @@
+/** Session identity resolution for one terminal runner invocation.
+ *
+ * Turns parsed startup flags into the session this process will run, and maps
+ * a session id onto a filename-safe export default. Resolution reads persisted
+ * headers, so it is the runner's only pre-composition persistence IO; the
+ * remaining helpers are pure.
+ *
+ * @module @deepseek-ai/dsh-code/session-target
+ */
+import type { SessionId, SessionEvent } from '@deepseek-ai/dsh-session';
+import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence';
+import type { TuiStartup } from '../startup.ts';
+/** The session identity this invocation will run, plus whether it is resumed. */
+export interface Target {
+    sessionId: string;
+    resume: boolean;
+    mode?: string;
+    cwd?: string;
+    seed?: readonly SessionEvent[];
+    parentSession?: SessionId;
+    /** Marks the session as a subagent conversation in the durable header. */
+    origin?: 'subagent';
+    seedLength?: number;
+}
+/**
+ * Reduce a session id to a filename-safe /export default-name suffix. Session
+ * ids are normally minted `session-<uuid>`, but `--session` accepts arbitrary
+ * user text: path separators must never leak into the default export filename
+ * (which would escape the session cwd).
+ * @param id - the session id.
+ * @returns at most the last 8 filename-safe characters.
+ */
+export declare function exportSessionIdSuffix(id: string): string;
+/**
+ * Resolve the invocation's target session against the persisted headers.
+ * @param startup - the parsed startup flags.
+ * @param persistence - the persistence service; required for resume/latest.
+ * @param cwd - the working directory `--continue` filters by.
+ * @returns the target identity.
+ * @throws with a user-facing message when the flags name nothing resolvable.
+ */
+export declare function resolveTarget(startup: TuiStartup, persistence: SessionPersistence | undefined, cwd: string): Promise<Target>;

package/lib/types/runner/startup-config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Resolve the runner's startup flags from the loose plugin config.
+ *
+ * The Cordis config schema is deliberately loose (`kind` is an unvalidated
+ * string, narrowed here), so this is the single place that maps a config row
+ * onto the `TuiStartup` the runner consumes — pure, and unit-testable without
+ * a plugin context.
+ *
+ * @module @deepseek-ai/dsh-code/runner/startup-config
+ */
+import type { TuiStartup } from '../startup.ts';
+/** The config row shape this resolver narrows; satisfied by the plugin schema. */
+export interface StartupConfigRow {
+    /** How this invocation obtains its session identity. */
+    readonly kind: string;
+    readonly sessionId?: string;
+    readonly mode?: string;
+    readonly theme?: string;
+    readonly prompt?: string;
+    readonly images?: readonly string[];
+}
+/**
+ * Narrow one config row to a startup.
+ *
+ * `resume`/`named` without a session id degrade to a fresh launch, an invalid
+ * theme string narrows to the dark default (and is therefore still present),
+ * and `mode` only survives on the kinds that can pre-compose a session.
+ * @param config - the validated plugin config.
+ * @returns the startup the runner will resolve a target from.
+ */
+export declare function resolveStartupConfig(config: {
+    readonly startup: StartupConfigRow;
+}): TuiStartup;