@itookit/dsht 0.6.3 → 0.6.7

package/README.i18n.yaml

@@ -1,3 +1,3 @@
 # Git blob hashes of the reviewed bilingual pair.
-README.md: 02d559e19c88336d6eb1f1e1ff80999bbfaa7274
-README.zh.md: b962a44f8a85716f4bd35f8afd0af7d140ffe0ca
+README.md: 1f5cde21326a6a1056ca90cba9e21e672ee332bb
+README.zh.md: 977cf5defbbe36cf37ca0d999b915a4aa81bfbfd

package/README.md

@@ -1,6 +1,14 @@
 # DeepSeek Harness Terminal
 
 English | [中文](README.zh.md)
+Run at first time(run `npx @deepseek-ai/dsh web`, then copy the output to DSH_URL):
+```bash
+export DSH_URL='http://127.0.0.1:3080/?token=<token>' && npx @itookit/dsht
+```
+Then every time only run (make sure `npx @deepseek-ai/dsh web` has run):
+```bash
+npx @itookit/dsht
+```
 
 ![DeepSeek Harness Terminal (dsht)](dsht-m.png)
 
@@ -166,7 +174,9 @@ npm start
 
 Both paths read the same `DSH_URL` and `DSH_TOKEN` variables.
 
-Select a workspace with ↑/↓ and Enter, then select a session or **New session**. **All sessions** also exposes sessions outside registered workspaces. **Add workspace (this directory)** registers the directory `dsht` itself runs in, and appears only while the host does not already have it; **Add workspace (host directory)** takes an existing absolute directory on the host, which may differ from your local filesystem, and Esc leaves that prompt for the picker again. Starting inside a registered workspace directory selects that workspace instead of showing the picker, with `←` in the session list switching to another; a session id passed on the command line still opens directly. Creating a session requires a selected workspace.
+Select a workspace with ↑/↓ and Enter, then select a session or **New session**. **All sessions** also exposes sessions outside registered workspaces. **Add workspace (this directory)** registers the directory `dsht` itself runs in: while the host does not already have it, it leads the list and is therefore the default selection; **Add workspace (host directory)** takes an existing absolute directory on the host, which may differ from your local filesystem, and Esc leaves that prompt for the picker again. Starting inside a registered workspace directory selects that workspace instead of showing the picker, with `←` in the session list switching to another; a session id passed on the command line still opens directly. Creating a session requires a selected workspace.
+
+While the host is unreachable, the startup pickers show what is wrong and how to fix it instead of an empty list. A first attempt still in flight is named as connecting; an unreachable host prints the `npx @deepseek-ai/dsh web` command that starts it together with the first-run `DSH_URL` line; a refused credential asks for that URL or `DSH_TOKEN`. The raw transport failure stays underneath as a dim diagnostic, and the client keeps retrying on its own.
 
 On first login, authentication exchanges the token at `GET /` and saves the cookie per HTTP origin. Later starts, including list commands, reuse that cookie without a token. The store uses `$XDG_STATE_HOME/dsht/auth`, or `~/.local/state/dsht/auth` when unset; `--auth-dir` or `DSHT_AUTH_DIR` overrides it. POSIX directories use 0700 and cookie files use 0600; Windows uses the account directory's inherited access controls. Launch tokens are never saved.
 

package/README.zh.md

@@ -2,6 +2,14 @@
 
 [English](README.md) | 中文
 
+第一次运行时，需要使用 DSH_URL 传入 `npx @deepseek-ai/dsh web` 启动时打印的 url:
+```bash
+export DSH_URL='http://127.0.0.1:3080/?token=<token>' && npx @itookit/dsht
+```
+以后运行只需要执行(当然必须确认`npx @deepseek-ai/dsh web` 已经启动):
+```bash
+npx @itookit/dsht
+```
 ![DeepSeek Harness Terminal（dsht）](dsht-m.png)
 
 > **dsht — 只要有终端，就能随时控制 DeepSeek Harness。**
@@ -166,7 +174,9 @@ npm start
 
 两种方式读取相同的 `DSH_URL` 和 `DSH_TOKEN` 变量。
 
-使用 ↑/↓ 和 Enter 选择工作区，然后选择已有会话或 **New session**。**All sessions** 同时显示未归属注册工作区的会话。**Add workspace (this directory)** 直接注册 `dsht` 自身所在的目录，只在服务端尚未注册它时出现；**Add workspace (host directory)** 接收服务端已有目录的绝对路径，该路径可能与本机文件系统不同，按 Esc 可以退回选择器。在已注册的工作区目录里启动时，直接选中该工作区而不再显示选择器（会话列表里的 `←` 仍可切到别的工作区）；命令行给出会话 ID 时依旧直接打开。新建会话前必须选择工作区。
+使用 ↑/↓ 和 Enter 选择工作区，然后选择已有会话或 **New session**。**All sessions** 同时显示未归属注册工作区的会话。**Add workspace (this directory)** 直接注册 `dsht` 自身所在的目录：服务端尚未注册它时，它排在列表最前，因此也是默认选中项；**Add workspace (host directory)** 接收服务端已有目录的绝对路径，该路径可能与本机文件系统不同，按 Esc 可以退回选择器。在已注册的工作区目录里启动时，直接选中该工作区而不再显示选择器（会话列表里的 `←` 仍可切到别的工作区）；命令行给出会话 ID 时依旧直接打开。新建会话前必须选择工作区。
+
+宿主不可达时，启动选择器显示的是原因与解决办法，而不是一个空列表：尚在进行的首次尝试写成"连接中"；连不上宿主时给出启动它的 `npx @deepseek-ai/dsh web` 命令与首次运行所需的 `DSH_URL` 行；凭据被拒时要求该 URL 或 `DSH_TOKEN`。原始传输错误以暗色诊断信息留在下方，客户端自行持续重连。
 
 首次登录通过 `GET /` 兑换 token，并按 HTTP origin 保存 cookie。后续启动和列表命令自动复用 cookie，无需再次提供 token。默认目录为 `$XDG_STATE_HOME/dsht/auth`，未设置时使用 `~/.local/state/dsht/auth`；可通过 `--auth-dir` 或 `DSHT_AUTH_DIR` 覆盖。POSIX 下目录权限为 0700、cookie 文件为 0600；Windows 使用账户目录继承的访问控制。启动 token 永不保存。
 

package/dist/ui/app.js

@@ -21,7 +21,8 @@ import { plainRows } from "./chat/shell-view.js";
 import { useHistoryView } from "./chat/use-history-view.js";
 import { Frozen } from "./frozen.js";
 import { CopyMode } from "./copy-mode.js";
-import { HelpPanel, HistoryDialog, ModelDialog, PickerScreen, PromptsDialog, QueueDialog, QueuedPreview, RemovalDialog, SearchResultsDialog, ThoughtsDialog } from "./dialogs/index.js";
+import { HelpPanel, HistoryDialog, ModelDialog, OfflinePanel, PickerScreen, PromptsDialog, QueueDialog, QueuedPreview, RemovalDialog, SearchResultsDialog, ThoughtsDialog } from "./dialogs/index.js";
+import { offlineGuidance } from "./offline.js";
 import { LoopDialog, LoopMenu } from "./dialogs/loop.js";
 import { usePanels } from "./dialogs/use-panels.js";
 import { PeekPanel } from "./dialogs/peek.js";
@@ -830,6 +831,13 @@ export function App({ controller, panelLifetimeMs = PANEL_LIFETIME_MS, theme = m
     // Needs-you is the one state that asks for action, so it outranks working; ready stays quiet.
     const stateColor = { needs: theme.status.critical, running: theme.status.working, idle: theme.colors.muted };
     const choices = state.screen === 'workspaces' ? [
+        // The directory this client runs in is the one case where no path has to be typed, and offering
+        // it only while the host has not registered it keeps the row from repeating itself. It leads the
+        // list so it is also the default selection: starting outside a registered workspace is exactly
+        // the situation the row exists for.
+        ...(state.workspaces.some(workspace => string(workspace.path) === controller.localDirectory) ? []
+            : [{ key: '@here', label: `+ Add workspace (this directory)  ${controller.localDirectory}`,
+                    action: () => operate(() => controller.actions.createWorkspace(controller.localDirectory)) }]),
         ...state.workspaces.map(workspace => {
             const counts = workspaceCounts(sessionsOf(workspace), new Set(pendingCounts.keys()));
             const name = string(workspace.title);
@@ -844,11 +852,6 @@ export function App({ controller, panelLifetimeMs = PANEL_LIFETIME_MS, theme = m
                 action: () => controller.actions.pickWorkspace(string(workspace.workspaceId)) };
         }),
         { key: '@all', label: 'All sessions', action: () => operate(() => controller.actions.switchSession('all')) },
-        // The directory this client runs in is the one case where no path has to be typed, and offering
-        // it only while the host has not registered it keeps the row from repeating itself.
-        ...(state.workspaces.some(workspace => string(workspace.path) === controller.localDirectory) ? []
-            : [{ key: '@here', label: `+ Add workspace (this directory)  ${controller.localDirectory}`,
-                    action: () => operate(() => controller.actions.createWorkspace(controller.localDirectory)) }]),
         { key: '@new', label: '+ Add workspace (host directory)', action: () => controller.actions.enterPath() },
     ] : [
         ...(state.workspaceId && !state.showAllSessions ? [{ key: '@new', label: '+ New session', action: () => operate(() => controller.actions.createSession()) }] : []),
@@ -882,6 +885,12 @@ export function App({ controller, panelLifetimeMs = PANEL_LIFETIME_MS, theme = m
     const peekPlainRows = useMemo(() => peek?.lines === undefined ? []
         : peek.lines.flatMap(line => plainRows(line, width, 'shell')), [peek?.lines, width]);
     const statusNotice = !['Connected', 'Idle', 'Running…', 'Responding…'].includes(state.status);
+    // A startup picker has nothing to list while the host is out of reach, so it carries the guidance
+    // in place of an empty list; every other screen keeps the status and failure lines instead.
+    const pickerScreen = state.screen === 'workspaces' || state.screen === 'sessions';
+    const offline = pickerScreen && !state.online
+        ? offlineGuidance({ status: state.status, base: controller.base, lastFailure: state.lastFailure })
+        : undefined;
     async function openSearchSession(sessionId, query) {
         await historyOperation(async (signal) => {
             if (!await controller.actions.selectSession(sessionId))
@@ -1038,13 +1047,14 @@ export function App({ controller, panelLifetimeMs = PANEL_LIFETIME_MS, theme = m
             missing: ledger.missing(),
         };
     })();
-    return _jsx(ThemeContext.Provider, { value: theme, children: _jsx(CopyMode.Provider, { value: copyMode, children: _jsx(Frozen, { frozen: copyMode, identity: `${width}:${stdout.rows}`, children: _jsxs(Box, { flexDirection: "column", paddingX: 1, height: Math.max(1, (stdout.rows ?? 30) - 1), overflowY: "hidden", children: [copyMode && _jsx(Text, { color: theme.accent, children: "Copy mode \u00B7 drag to select \u00B7 Esc / Ctrl+S resumes" }), _jsx(Box, { ref: headerSection, flexShrink: 0, children: _jsx(ChatHeader, { title: headerTitle, mode: controller.queries.sessionMode, width: width, frozen: displayPaused, identity: `${width}:${state.sessionId}` }) }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, minHeight: 0, overflowY: "hidden", children: [_jsxs(Box, { ref: bodyPrefix, flexDirection: "column", flexShrink: 0, children: [foreground && _jsxs(Text, { dimColor: true, children: [foreground.label, " \u00B7 Esc / Ctrl+C cancel"] }), _jsx(Frozen, { frozen: statusPaused, identity: state.sessionId ?? "", children: statusNotice && _jsx(Text, { dimColor: true, wrap: "truncate-end", children: safeText(state.status) }) }), state.lastFailure && _jsx(Text, { color: theme.colors.error, children: state.lastFailure })] }), state.screen === 'chat' && (peek === undefined ? _jsx(ChatViewport, { rows: visible, showHistoryHint: showHistoryHint, dialogOpen: dialogOpen, historyWindow: !!historyWindow, frozen: displayPaused, identity: `${width}:${state.sessionId}:${position}:${pageSize}`, boxRef: conversationBox })
+    return _jsx(ThemeContext.Provider, { value: theme, children: _jsx(CopyMode.Provider, { value: copyMode, children: _jsx(Frozen, { frozen: copyMode, identity: `${width}:${stdout.rows}`, children: _jsxs(Box, { flexDirection: "column", paddingX: 1, height: Math.max(1, (stdout.rows ?? 30) - 1), overflowY: "hidden", children: [copyMode && _jsx(Text, { color: theme.accent, children: "Copy mode \u00B7 drag to select \u00B7 Esc / Ctrl+S resumes" }), _jsx(Box, { ref: headerSection, flexShrink: 0, children: _jsx(ChatHeader, { title: headerTitle, mode: controller.queries.sessionMode, width: width, frozen: displayPaused, identity: `${width}:${state.sessionId}` }) }), _jsxs(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, minHeight: 0, overflowY: "hidden", children: [_jsxs(Box, { ref: bodyPrefix, flexDirection: "column", flexShrink: 0, children: [foreground && _jsxs(Text, { dimColor: true, children: [foreground.label, " \u00B7 Esc / Ctrl+C cancel"] }), _jsx(Frozen, { frozen: statusPaused, identity: state.sessionId ?? "", children: statusNotice && offline === undefined && _jsx(Text, { dimColor: true, wrap: "truncate-end", children: safeText(state.status) }) }), state.lastFailure && offline === undefined && _jsx(Text, { color: theme.colors.error, children: state.lastFailure })] }), state.screen === 'chat' && (peek === undefined ? _jsx(ChatViewport, { rows: visible, showHistoryHint: showHistoryHint, dialogOpen: dialogOpen, historyWindow: !!historyWindow, frozen: displayPaused, identity: `${width}:${state.sessionId}:${position}:${pageSize}`, boxRef: conversationBox })
                                     : _jsx(PeekPanel, { source: peek.source, ...(peek.error === undefined ? {} : { error: peek.error }), rows: peekVisible, position: peekPosition, total: peekTotal, width: width, now: Date.now(), boxRef: peekBox }))] }), _jsxs(Box, { flexDirection: "column", flexShrink: 0, children: [notice && _jsx(Text, { dimColor: true, children: safeText(notice) }), composerIntent && _jsx(Text, { color: theme.colors.context, children: composerIntent.hint }), loop && _jsx(LoopStatus, { progress: loop }), peek === undefined && _jsxs(Box, { borderStyle: "round", borderColor: pending ? theme.colors.context : state.online ? theme.accent : theme.border, paddingX: 1, flexDirection: "column", flexShrink: 1, minHeight: 3, children: [_jsx(Box, { flexDirection: "column", flexShrink: 1, minHeight: 0, overflowY: "hidden", children: loopForm && loopRecord ? _jsx(LoopDialog, { record: loopRecord, enabled: state.online && controller.queries.foreground === undefined, onStart: run => startLoopFromForm(loopForm.name, run), onBack: () => { setLoopForm(undefined); setInput('/loop '); setDismissedLoopMenu(undefined); }, onClose: () => setLoopForm(undefined) }, loopForm.name) : queueOpen && !pending ? _jsx(QueueDialog, { queued: queued, rows: stdout.rows ?? 30, width: width, unavailable: !!state.controlError, enabled: !input && foreground === undefined && state.online, canSelect: () => !input && controller.queries.foreground === undefined && controller.state.online && !controller.state.pending.length, onRemove: id => operate(() => controller.actions.removeQueued(id)) }) : removal ? _jsx(RemovalDialog, { removal: removal, enabled: !input && foreground === undefined && state.online, canSelect: () => !input && controller.queries.foreground === undefined && controller.state.online, onCancel: () => setRemoval(undefined), onConfirm: () => operate(async () => { if (await controller.actions.removeTarget(removal))
                                                     setRemoval(undefined); }) }) : models ? _jsx(ModelDialog, { models: models, rows: stdout.rows ?? 30, width: width, enabled: !input && foreground === undefined && state.online, canSelect: () => !input && controller.queries.foreground === undefined && controller.state.online, onChoose: (provider, model, effort) => operate(async () => { if (await controller.actions.selectModel(provider, model, effort))
-                                                    setModelPanel(undefined); }), onOpen: (provider, model) => setModelPanel({ catalog: models.catalog, provider, model }), onBack: () => setModelPanel({ catalog: models.catalog }), onClose: () => setModelPanel(undefined) }) : searchResults ? _jsx(SearchResultsDialog, { query: searchResults.query, items: searchResults.items, hasMore: searchResults.hasMore, width: width, enabled: !input && foreground === undefined, canSelect: () => !input && controller.queries.foreground === undefined, onOpen: sessionId => operate(() => openSearchSession(sessionId, searchResults.query)), onClose: () => setSearchPanel(undefined) }) : state.screen === 'workspaces' || state.screen === 'sessions' ? _jsx(PickerScreen, { title: state.screen === 'workspaces' ? 'Choose workspace' : state.showAllSessions ? 'Choose session · All workspaces' : 'Choose session', identity: `${state.screen}:${state.workspaceId ?? ''}`, choices: choices, width: pickerWidth, 
+                                                    setModelPanel(undefined); }), onOpen: (provider, model) => setModelPanel({ catalog: models.catalog, provider, model }), onBack: () => setModelPanel({ catalog: models.catalog }), onClose: () => setModelPanel(undefined) }) : searchResults ? _jsx(SearchResultsDialog, { query: searchResults.query, items: searchResults.items, hasMore: searchResults.hasMore, width: width, enabled: !input && foreground === undefined, canSelect: () => !input && controller.queries.foreground === undefined, onOpen: sessionId => operate(() => openSearchSession(sessionId, searchResults.query)), onClose: () => setSearchPanel(undefined) }) : pickerScreen ? offline === undefined ? _jsx(PickerScreen, { title: state.screen === 'workspaces' ? 'Choose workspace' : state.showAllSessions ? 'Choose session · All workspaces' : 'Choose session', identity: `${state.screen}:${state.workspaceId ?? ''}`, choices: choices, width: pickerWidth, 
                                                 // A rollup of badges is read through the key beside it; spelled-out states need no key, and a
                                                 // terminal too narrow for the whole key gets the badges alone rather than half a legend.
-                                                legend: state.screen === 'workspaces' && rollupStyle === 'badges' && pickerWidth >= 40 ? ROLLUP_LEGEND : undefined, enabled: state.online && foreground === undefined && !input, canSelect: () => !input && controller.state.online && controller.queries.foreground === undefined }) : _jsxs(_Fragment, { children: [thoughtList && _jsx(ThoughtsDialog, { identity: `thoughts:${state.sessionId}`, options: thoughtOptions, empty: !thoughtEntries?.length && !liveThought, rows: stdout.rows ?? 30, enabled: !input && foreground === undefined, canSelect: () => !input && controller.queries.foreground === undefined }), promptsOpen && state.screen === 'chat' && _jsx(PromptsDialog, { identity: "prompts", prompts: controller.queries.prompts, error: controller.queries.promptsError, width: width, enabled: !input && foreground === undefined, canSelect: () => !input && controller.queries.foreground === undefined, onChoose: text => { setInput(text); openPrompts(false); }, onEdit: prompt => {
+                                                legend: state.screen === 'workspaces' && rollupStyle === 'badges' && pickerWidth >= 40 ? ROLLUP_LEGEND : undefined, enabled: state.online && foreground === undefined && !input, canSelect: () => !input && controller.state.online && controller.queries.foreground === undefined })
+                                                : _jsx(OfflinePanel, { guidance: offline }) : _jsxs(_Fragment, { children: [thoughtList && _jsx(ThoughtsDialog, { identity: `thoughts:${state.sessionId}`, options: thoughtOptions, empty: !thoughtEntries?.length && !liveThought, rows: stdout.rows ?? 30, enabled: !input && foreground === undefined, canSelect: () => !input && controller.queries.foreground === undefined }), promptsOpen && state.screen === 'chat' && _jsx(PromptsDialog, { identity: "prompts", prompts: controller.queries.prompts, error: controller.queries.promptsError, width: width, enabled: !input && foreground === undefined, canSelect: () => !input && controller.queries.foreground === undefined, onChoose: text => { setInput(text); openPrompts(false); }, onEdit: prompt => {
                                                             setComposerIntent({
                                                                 hint: 'Editing saved prompt · Enter saves · Esc cancels',
                                                                 emptyNotice: 'Type the prompt text; Enter then saves it',

package/dist/ui/dialogs/index.d.ts

@@ -2,6 +2,7 @@ import { type ObjectValue } from '../../json.ts';
 import { type Message, type SavedPrompt } from '../../contracts.ts';
 import type { HistorySearch, RemovalTarget } from '../../contracts.ts';
 import type { QueuedInput } from '../../contracts.ts';
+import type { OfflineGuidance } from '../offline.ts';
 import { type Choice } from './picker.tsx';
 /** Pending host input with explicit removal.
  * @param props - Queue contents, geometry and availability.
@@ -91,6 +92,17 @@ export declare function PickerScreen({ title, identity, choices, enabled, canSel
     /** Marker key shown above the list, for a rollup too compact to spell its states out. */
     legend?: string;
 }): import("react").JSX.Element;
+/** What the startup picker shows while the host is unreachable.
+ *
+ * An empty list with a raw socket error beside it answers neither "what is wrong" nor "what do I do",
+ * so the picker is replaced by the state and the one command that resolves it. This is a startup
+ * surface only: a conversation keeps its transcript and lets the status bar report the loss.
+ * @param props - Guidance block built from the connection's published state.
+ * @returns The offline guidance panel.
+ */
+export declare function OfflinePanel({ guidance }: {
+    guidance: OfflineGuidance;
+}): import("react").JSX.Element;
 /** Newest-first reasoning summaries with the preceding user prompt.
  * @param props - Loaded entries and lazy paging action.
  * @returns The reasoning list.

package/dist/ui/dialogs/index.js

@@ -86,6 +86,18 @@ export function SearchResultsDialog({ query, items, hasMore, width, enabled, can
 export function PickerScreen({ title, identity, choices, enabled, canSelect, width, legend }) {
     return _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsx(Text, { bold: true, children: title }), legend !== undefined && _jsx(Text, { dimColor: true, wrap: "truncate-end", children: legend }), _jsx(Picker, { choices: choices, enabled: enabled, canSelect: canSelect, width: width }, identity)] });
 }
+/** What the startup picker shows while the host is unreachable.
+ *
+ * An empty list with a raw socket error beside it answers neither "what is wrong" nor "what do I do",
+ * so the picker is replaced by the state and the one command that resolves it. This is a startup
+ * surface only: a conversation keeps its transcript and lets the status bar report the loss.
+ * @param props - Guidance block built from the connection's published state.
+ * @returns The offline guidance panel.
+ */
+export function OfflinePanel({ guidance }) {
+    const theme = useTheme();
+    return _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsx(Text, { bold: true, color: theme.status.offline, wrap: "truncate-end", children: safeText(guidance.title) }), guidance.lines.map((line, index) => _jsx(Text, { wrap: "truncate-end", color: line.startsWith('  ') ? theme.colors.tool : undefined, children: safeText(line) }, index)), guidance.detail !== undefined && _jsx(Text, { dimColor: true, wrap: "truncate-end", children: safeText(guidance.detail) })] });
+}
 /** Newest-first reasoning summaries with the preceding user prompt.
  * @param props - Loaded entries and lazy paging action.
  * @returns The reasoning list.

package/dist/ui/offline.d.ts

@@ -0,0 +1,38 @@
+/** What the startup picker shows when the host it needs is not answering.
+ *
+ * `dsht` deliberately never starts Harness, so an unreachable host is an operator problem with a
+ * known fix. This module turns the connection's published status into a short, accurate block: the
+ * state first, then the one command that resolves it. It is pure text, so the wording is testable on
+ * its own and the rendering belongs to `dialogs/`.
+ */
+/** The command that starts the host this client talks to. */
+export declare const HOST_COMMAND = "npx @deepseek-ai/dsh web";
+/** What the startup picker shows while the host cannot be reached. */
+export interface OfflineGuidance {
+    /** Which host, and which of its three states the connection published. */
+    readonly title: string;
+    /** What happened and what to do about it, in reading order. */
+    readonly lines: readonly string[];
+    /** The raw transport failure, rendered dim under the guidance rather than as the message. */
+    readonly detail?: string;
+}
+/** The `DSH_URL` export that carries a first-run token for one host.
+ *
+ * `dsh web` prints its URL with a `token` parameter, and that printed line is what a first run
+ * exports unchanged; a host URL that already carries query parameters keeps its own separator.
+ * @param base - Host URL this client targets.
+ * @returns One `export DSH_URL=…` line.
+ */
+export declare function dshUrlLine(base: string): string;
+/** Build the startup guidance for one connection state.
+ *
+ * The first attempt is named as connecting rather than as offline: a client that has not finished
+ * trying yet has not learned that anything is wrong, and saying "offline" then would be a guess.
+ * @param source - Published connection status, host URL and last failure.
+ * @returns The guidance block; never empty, because the caller renders it only while offline.
+ */
+export declare function offlineGuidance(source: {
+    status: string;
+    base: string;
+    lastFailure?: string;
+}): OfflineGuidance;

package/dist/ui/offline.js

@@ -0,0 +1,57 @@
+/** What the startup picker shows when the host it needs is not answering.
+ *
+ * `dsht` deliberately never starts Harness, so an unreachable host is an operator problem with a
+ * known fix. This module turns the connection's published status into a short, accurate block: the
+ * state first, then the one command that resolves it. It is pure text, so the wording is testable on
+ * its own and the rendering belongs to `dialogs/`.
+ */
+/** The command that starts the host this client talks to. */
+export const HOST_COMMAND = 'npx @deepseek-ai/dsh web';
+/** The `DSH_URL` export that carries a first-run token for one host.
+ *
+ * `dsh web` prints its URL with a `token` parameter, and that printed line is what a first run
+ * exports unchanged; a host URL that already carries query parameters keeps its own separator.
+ * @param base - Host URL this client targets.
+ * @returns One `export DSH_URL=…` line.
+ */
+export function dshUrlLine(base) {
+    const separator = base.includes('?') ? '&' : '?';
+    const root = base.includes('?') || base.endsWith('/') ? base : `${base}/`;
+    return `export DSH_URL='${root}${separator}token=<token>'`;
+}
+/** Build the startup guidance for one connection state.
+ *
+ * The first attempt is named as connecting rather than as offline: a client that has not finished
+ * trying yet has not learned that anything is wrong, and saying "offline" then would be a guess.
+ * @param source - Published connection status, host URL and last failure.
+ * @returns The guidance block; never empty, because the caller renders it only while offline.
+ */
+export function offlineGuidance(source) {
+    const { base, status } = source;
+    const detail = source.lastFailure === undefined || source.lastFailure === '' ? undefined : source.lastFailure;
+    const url = dshUrlLine(base);
+    if (status === 'Login required') {
+        return { title: `Login required · ${base}`, lines: [
+                'No token was given, or the saved cookie no longer works.',
+                'Start the host and export the URL it prints, then run dsht again:',
+                `  ${url}`,
+                'Or export DSH_TOKEN. Tokens are never saved.',
+            ], ...(detail === undefined ? {} : { detail }) };
+    }
+    if (status === 'Connecting…') {
+        return { title: `Connecting… · ${base}`, lines: [
+                'Waiting for DeepSeek Harness at that address.',
+                'If nothing is listening yet, start it there:',
+                `  ${HOST_COMMAND}`,
+                'First run only, point dsht at the URL it prints:',
+                `  ${url}`,
+            ], ...(detail === undefined ? {} : { detail }) };
+    }
+    return { title: `Host offline · ${base}`, lines: [
+            'DeepSeek Harness is not answering yet.',
+            'Start it on that host; this screen reconnects by itself:',
+            `  ${HOST_COMMAND}`,
+            'First run only, point dsht at the URL it prints:',
+            `  ${url}`,
+        ], ...(detail === undefined ? {} : { detail }) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itookit/dsht",
-  "version": "0.6.3",
+  "version": "0.6.7",
   "type": "module",
   "description": "Remote-first TUI for DeepSeek Harness with SSH-friendly mobile access and request-level cost tracking",
   "engines": {