dsh-ssh-tui 0.7.1 → 0.7.2

package/lib/types/session-route.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Per-session provider/model memory.
+ *
+ * The parent route and the subagent route used to be one global choice: `/model`
+ * and `/submodel` wrote a default that every later session inherited. Once a
+ * child could run on a *different* supplier that stopped being enough — resuming
+ * an old conversation silently re-ran it on whatever the last conversation used,
+ * and there was no way to see which supplier had paid for the earlier one.
+ *
+ * Each session's effective route is recorded here, next to the TUI's other
+ * per-session state under `$DSH_HOME`, and applied when that session starts
+ * again. A new session still starts from the global default; the record only
+ * ever overrides it for the session it belongs to, and never for another one.
+ *
+ * The record is a cache of a decision, not a source of truth: every field is
+ * parsed defensively, and a route whose provider no longer exists is still
+ * applied (the launcher reports the failure the same way it would for a CLI
+ * flag).
+ *
+ * @module dsh-ssh-tui/session-route
+ */
+import { type SubagentSelectionRef } from './subagent-model.js';
+/** Subagent route as this session ran it; no provider means "follows parent". */
+export interface SessionSubagentRoute {
+    provider?: string;
+    model: string;
+    reasoningEffort?: string;
+}
+/** One session's route: what `/model`, `/provider`, `/submodel` settled on. */
+export interface SessionRoute {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+    subagent?: SessionSubagentRoute;
+    /** Epoch ms of the last write; the oldest records are pruned first. */
+    updatedAt: number;
+}
+/**
+ * How many sessions keep a record. The file is a convenience cache, and a
+ * hundred-odd conversations is more history than a resume picker offers.
+ */
+export declare const SESSION_ROUTE_LIMIT = 200;
+export declare function sessionRoutePath(dshHome?: string): string;
+/** Parse one record; anything that cannot name a route is dropped. */
+export declare function parseSessionRoute(raw: unknown): SessionRoute | undefined;
+/** Parse the whole file; a file from another version reads as empty. */
+export declare function parseSessionRoutes(raw: unknown): Map<string, SessionRoute>;
+export declare function loadSessionRoutes(path?: string): Promise<Map<string, SessionRoute>>;
+/** The record for one session, or undefined when it never had one. */
+export declare function loadSessionRoute(sessionId: string, path?: string): Promise<SessionRoute | undefined>;
+/** Keep the newest `limit` records, so the file cannot grow without bound. */
+export declare function pruneSessionRoutes(entries: ReadonlyMap<string, SessionRoute>, limit?: number): Map<string, SessionRoute>;
+export declare function saveSessionRoutes(path: string, entries: ReadonlyMap<string, SessionRoute>): Promise<boolean>;
+/**
+ * Record one session's route, leaving every other session alone.
+ *
+ * Read-modify-write on purpose: two Hosts (two SSH windows) can be open at
+ * once, and neither may drop the other's entry.
+ */
+export declare function saveSessionRoute(sessionId: string, route: Omit<SessionRoute, 'updatedAt'>, path?: string): Promise<boolean>;
+/** Whether two records describe the same route (the timestamp is ignored). */
+export declare function sameSessionRoute(left: SessionRoute | undefined, right: Omit<SessionRoute, 'updatedAt'> | undefined): boolean;
+/**
+ * Shape a live parent route plus the subagent selection into a record.
+ *
+ * Shared by the TUI (which reports what its refs hold) and the launcher (which
+ * writes it), so the two cannot disagree about what a session was running on.
+ * An empty provider or model yields nothing: a record that cannot name a route
+ * would come back as a lie.
+ */
+export declare function sessionRouteInput(input: {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+    subagent?: {
+        provider?: string;
+        model: string;
+        reasoningEffort?: string;
+    };
+}): Omit<SessionRoute, 'updatedAt'> | undefined;
+/**
+ * Providers the harness ships with. They are routable in any install even when
+ * the adapter list is still warming up, so a record naming one is never treated
+ * as stale on that basis alone.
+ */
+export declare const BUILTIN_ROUTABLE_PROVIDERS: readonly ["deepseek-official", "xai", "opencode-go", "opencode"];
+/**
+ * Whether this install can still route to a provider.
+ *
+ * Deliberately permissive: the cost of wrongly *keeping* a record is an error the
+ * harness already reports clearly (an unknown route, the same one a launch flag
+ * would hit), while wrongly *dropping* one silently loses the session's route —
+ * which is the whole feature. So a provider counts as routable when it is a
+ * built-in, appears in the adapter list, has a configured `llm-pi-ai` profile, or
+ * is listed by the adapter's own model catalog.
+ */
+export declare function providerIsRoutable(input: {
+    provider: string;
+    /** Ids from `llm.listProviders()`. */
+    listed?: readonly string[];
+    /** Ids with an `llm-pi-ai.providers.<id>` section. */
+    configured?: readonly string[];
+}): boolean;
+/** What a resumed session's record is worth in this install. */
+export interface RouteAvailabilityPlan {
+    /** The parent route, when the provider it names can still be routed to. */
+    route?: SessionRoute;
+    /** The subagent route, when its own pin can be routed to as well. */
+    subagent?: SessionSubagentRoute;
+    /** Recorded parent provider that is gone; the caller says so on screen. */
+    droppedProvider?: string;
+    /** Recorded subagent pin that is gone; the app-level setting takes over. */
+    droppedSubagentProvider?: string;
+}
+/**
+ * Decide what of a recorded route still applies.
+ *
+ * A provider that no longer exists takes its whole record with it: the session
+ * was configured around that supplier (its model, its effort, and the children
+ * it pinned), so the honest answer is the app-level default for all of it rather
+ * than a half-restored route. A pinned *child* provider that is gone is narrower:
+ * the parent route is kept and the children fall back to the app-level subagent
+ * setting. An inherited child route has no pin to check — it follows the parent,
+ * which was just found routable.
+ */
+export declare function routeAvailabilityPlan(input: {
+    recorded?: SessionRoute;
+    routable: (provider: string) => boolean;
+}): RouteAvailabilityPlan;
+/**
+ * Apply a resumed session's record to the live selection.
+ *
+ * Returns what the record was worth (see `routeAvailabilityPlan`) so the
+ * launcher can say which route the session came back on — and, when a supplier
+ * has been removed since, which one it fell back from. A new session is left
+ * alone, and so is a resumed one that never had a record: both start from the
+ * app-level defaults, which is the behaviour before any of this existed.
+ *
+ * The subagent route is applied in memory only: it belongs to the conversation
+ * being resumed, and writing it back to the settings would make one session's
+ * pin the default for every later session.
+ */
+export declare function restoreSessionRoute(input: {
+    sessionId: string;
+    resume: boolean;
+    subagentSelection: SubagentSelectionRef;
+    path?: string;
+    /** Availability test; omitted means "everything is routable". */
+    routable?: (provider: string) => boolean;
+}): Promise<RouteAvailabilityPlan>;
+/** One remembered route as the launch waterfall sees it. */
+export interface LaunchRouteSource {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+export interface LaunchRouteInput {
+    /** In-process change from `/model` or `/setup` earlier in this process. */
+    live?: LaunchRouteSource;
+    /** Launch flags (`--provider` / `--model`). */
+    cli?: {
+        provider?: string;
+        model?: string;
+    };
+    /** This session's own record, when the launch resumes it. */
+    session?: SessionRoute;
+    /** Global default (the settings file, or `agent-default-model`). */
+    saved?: LaunchRouteSource;
+    /** Last model per provider, used only when no user default section exists. */
+    remembered?: LaunchRouteSource;
+}
+export interface LaunchRoute {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+/**
+ * The route a launch should run on, in one place.
+ *
+ * Precedence: an in-process change, then launch flags, then the session's own
+ * record, then the global default, then the last remembered route. A resumed
+ * conversation therefore comes back on the supplier it was actually using, while
+ * a new one still starts from the default — and an explicit flag still wins,
+ * because that is this launch's ask.
+ *
+ * The reasoning effort travels with the route it was chosen for: it is taken
+ * from whichever source supplied the provider/model, and only when the flags did
+ * not move the route away from it. A CLI that changes either half must not
+ * inherit the saved effort of a different model.
+ */
+export declare function resolveLaunchRoute(input: LaunchRouteInput): LaunchRoute;

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

@@ -24,6 +24,33 @@ export declare const DEFAULT_XAI_SUBAGENT_MODEL = "grok-4.5";
  * with flash-like ids ranked first.
  */
 export declare function defaultSubagentModelForProvider(provider: string, listed?: readonly string[], parentModel?: string): string;
+/**
+ * Canonical id of the supplier behind a route.
+ *
+ * The settings file can name the same supplier two ways — `xai` against
+ * `grok`, `deepseek-official` against `deepseek` — and a `/submodel` pin that
+ * spells the parent's own provider differently is still the parent's provider.
+ * Only those aliases collapse: an id the TUI cannot vouch for (`deepseek-eu`,
+ * `grok-mirror`, a relay) stays itself, because two routes it cannot prove
+ * share a bill are two providers.
+ */
+export declare function canonicalProviderId(provider: string | undefined): string;
+/**
+ * True when `child` is a different supplier from `parent`.
+ *
+ * This is the one condition that earns a subagent an accent colour: a child
+ * that follows the parent — or that was pinned back onto the parent's own
+ * provider — is on the parent's route and must read as such.
+ */
+export declare function subagentProviderDiffers(parent: string | undefined, child: string | undefined): boolean;
+/**
+ * Identity SGR for a subagent chip title. Same provider as the parent stays
+ * the violet used since the courtesy-name work; a different provider uses
+ * cyan so the foreign route is visible without a second color layer.
+ */
+export declare const SUBAGENT_IDENTITY_SGR = "38;5;141";
+export declare const SUBAGENT_FOREIGN_SGR = "38;5;80";
+export declare function subagentIdentitySgr(foreign: boolean): typeof SUBAGENT_IDENTITY_SGR | typeof SUBAGENT_FOREIGN_SGR;
 /**
  * True when the stored subagent model still belongs to the parent provider
  * family. An explicit leftover DeepSeek flash id after switching to xAI is
@@ -75,7 +102,33 @@ export interface SubagentSelection {
 /** Mutable selection handle shared by the settings watcher and the TUI. */
 export interface SubagentSelectionRef {
     current: SubagentSelection;
+    /**
+     * Where `current` came from.
+     *
+     * A route restored from a session's own record (`session`) outranks the
+     * settings watcher: the host fires `onChange` on writes to *any* section, so a
+     * `/model` or a `/doctor --fix` would otherwise put the app-level default back
+     * and silently drop the pin the conversation was resumed with. A user change
+     * through `/submodel` hands ownership back to the settings.
+     */
+    source?: 'settings' | 'session';
 }
+/**
+ * Adopt a session's own subagent route, outranking the settings watcher.
+ * @param ref - the shared selection handle.
+ * @param selection - the route the session's record names.
+ */
+export declare function adoptSessionSubagentSelection(ref: SubagentSelectionRef, selection: SubagentSelection): void;
+/**
+ * Hand the ref back to the settings watcher.
+ *
+ * Called when a user change makes the settings the source again, and before a
+ * new session starts in this process — a session-scoped route must not leak into
+ * the next conversation. Only a readable section may replace the current value:
+ * resetting on a settings service that is not up yet would swap the route for
+ * the built-in default instead.
+ */
+export declare function releaseSessionSubagentSelection(ref: SubagentSelectionRef, settingsValue: unknown): void;
 /** Settings schema for `$DSH_HOME/settings.yaml`. */
 export declare const SUBAGENT_SETTINGS_SCHEMA: z<Schemastery.ObjectS<{
     provider: z<string, string>;

package/lib/types/term-text.d.ts

@@ -4,6 +4,7 @@
  * Isolated so the launch session picker can clip labels without loading
  * the interactive TUI class.
  */
+import { type ColorDepth } from './color-depth.js';
 /**
  * Codex-style compact elapsed: `0s`, `1m 05s`, `1h 01m 01s`.
  * Used by the workspace wait card while the model has not streamed yet.
@@ -116,9 +117,9 @@ export declare function wrapTracked(text: string, width: number): {
     end: number;
 }[];
 /** Paint one already-wrapped output line by the segments overlapping its range. */
-export declare function paintSegmentedLine(line: string, start: number, end: number, segments: readonly TextSegment[]): string;
+export declare function paintSegmentedLine(line: string, start: number, end: number, segments: readonly TextSegment[], depth?: ColorDepth): string;
 /** Wrap `text` and color each output line by overlapping `segments`. */
-export declare function wrapSegmented(text: string, width: number, segments: readonly TextSegment[]): string[];
+export declare function wrapSegmented(text: string, width: number, segments: readonly TextSegment[], depth?: ColorDepth): string[];
 export declare function truncate(text: string, maxLines: number): string;
 /** One OSC-8 hyperlink span in a painted row, in display columns. */
 export interface PaintedLinkHit {

package/lib/types/tool-present.d.ts

@@ -3,7 +3,7 @@
  */
 import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-questions';
 import { type TextSegment } from './term-text.js';
-import type { DisplayKind, Row, ToolDiffHunk } from './transcript-types.js';
+import type { DiffDisplayLine, Row, ToolDiffHunk } from './transcript-types.js';
 export declare const SHELL_TOOL_NAMES: Set<string>;
 export declare const DIFF_TOOL_NAMES: Set<string>;
 export declare const JOB_TOOL_NAMES: Set<string>;
@@ -12,7 +12,6 @@ export declare function formatModelList(models: readonly string[], max?: number)
 /** Prefer the fields a human scans for; fall back to the first scalar pairs. */
 export declare function friendlyArgsSummary(name: string, args: string): string;
 export declare function countDiffLines(hunks: readonly ToolDiffHunk[] | undefined): number;
-/** Added / removed line counts for a diff (`oldText: null` means a new file). */
 export declare function countDiffAddDel(hunks: readonly ToolDiffHunk[] | undefined): {
     add: number;
     del: number;
@@ -121,21 +120,7 @@ export declare function presentToolCall(name: string, args: string): {
 export declare function diffMetaDiffs(meta: unknown): ToolDiffHunk[] | null;
 /** Split one diff side into content lines (trailing newline is a terminator). */
 export declare function diffContentLines(text: string): string[];
-/** One rendered diff body line with its display role. */
-export interface DiffDisplayLine {
-    kind: DisplayKind;
-    text: string;
-    /**
-     * Ranges of `text` to emphasise, in UTF-16 offsets. They travel with the line
-     * rather than being baked in as escapes because the painter sanitises the text
-     * it styles — an escape inserted down here would be stripped, leaving a
-     * literal `[7m` on screen.
-     */
-    spans?: readonly {
-        start: number;
-        end: number;
-    }[];
-}
+export type { DiffDisplayLine } from './transcript-types.js';
 /** Cap one flat diff/body row list to `maxLines` while preserving the final line. */
 export declare function capDisplayLines(lines: readonly DiffDisplayLine[], maxLines: number): DiffDisplayLine[];
 /** Running / ok / error → ANSI color for the status dot and status word only. */

package/lib/types/transcript-types.d.ts

@@ -8,6 +8,10 @@ export type SubagentLogKind = 'user' | 'assistant' | 'tool' | 'result' | 'turn'
 export interface SubagentLogEntry {
     kind: SubagentLogKind;
     text: string;
+    /** Parent tool-call id, so a later result can settle on the same log line. */
+    callId?: string;
+    /** Result body kept beside the call line, when the caller has one. */
+    detail?: string;
 }
 /** One todo-list item as the plan card renders it. */
 export interface PlanTodoItem {
@@ -62,14 +66,24 @@ export type Row = {
 } | {
     kind: 'subagent';
     sessionId: string;
+    /** Live child id when this chip was first built from the parent spawn tool. */
+    childSessionId?: string;
+    /** Parent spawn tool-call id, so the wrapper's result can find this child. */
+    spawnCallId?: string;
+    /** Model route the child runs on. Never the subagent backend name (`spawn`). */
+    modelProvider?: string;
     runId: string;
     provider: string;
     local: boolean;
     label: string;
+    /** Parent `subagent` tool description, when the spawn call named the job. */
+    task?: string;
     status: 'running' | 'ok' | 'error' | 'aborted';
     startedAt: number;
     endedAt?: number;
     stopReason?: string;
+    /** One-line failure explanation shown on the collapsed chip. */
+    failHint?: string;
     lastActivity: string;
     logs: SubagentLogEntry[];
     expanded: boolean;
@@ -161,7 +175,36 @@ export type CollapsibleBlock = Extract<Row, {
     kind: 'streaming-reasoning';
     expanded: boolean;
 };
-export type DisplayKind = Row['kind'] | 'tool-result' | 'diff-add' | 'diff-del' | 'diff-path' | 'todo-done' | 'todo-active' | 'todo-pending' | 'todo-failed' | 'todo-skipped' | 'plan-dock';
+export type DisplayKind = Row['kind'] | 'tool-result' | 'diff-add' | 'diff-del' | 'diff-path' | 'todo-done' | 'todo-active' | 'todo-pending' | 'todo-failed' | 'todo-skipped' | 'plan-dock' | 'subagent-header';
+/** One rendered diff/inspect body line with its display role. */
+export interface DiffDisplayLine {
+    kind: DisplayKind;
+    text: string;
+    /**
+     * Ranges of `text` to emphasise, in UTF-16 offsets. They travel with the line
+     * rather than being baked in as escapes because the painter sanitises the text
+     * it styles — an escape inserted down here would be stripped, leaving a
+     * literal `[7m` on screen.
+     */
+    spans?: readonly {
+        start: number;
+        end: number;
+    }[];
+    /**
+     * Parts of `text` that carry their own role, for a line that holds two at
+     * once: the columns of a side-by-side diff are a removal on the left and an
+     * addition on the right, and painting the row as either one would mislabel
+     * half of it. Offsets are UTF-16 into `text`; anything not covered keeps the
+     * line's own `kind`.
+     */
+    columns?: readonly DiffDisplayColumn[];
+}
+/** One part of a line, painted with its own display role. */
+export interface DiffDisplayColumn {
+    start: number;
+    end: number;
+    kind: DisplayKind;
+}
 /** One file's change, matching the web diff-card contract (`card: 'diff'`). */
 export interface ToolDiffHunk {
     path: string;