dsh-ssh-tui 0.1.0

package/lib/types/tui.d.ts

@@ -0,0 +1,365 @@
+/**
+ * A small, dependency-light interactive terminal channel for DeepSeek
+ * Harness. It renders the durable session transcript, streams assistant
+ * output, shows tool-call cards, answers approval requests and
+ * `ask_user_question` prompts from the keyboard, and drives one configured
+ * agent with followup/steer.
+ *
+ * The renderer uses plain ANSI and a throttled full repaint, which keeps it
+ * predictable over slow SSH links and avoids terminal-library dependency
+ * drift inside the plugin.
+ */
+import type { Agent, ModelSelection, ModelSelectionRef } from '@deepseek-ai/dsh-agent';
+import type { Context } from '@deepseek-ai/cordis';
+/** Presentation configuration for the terminal channel. */
+export interface TuiConfig {
+    /** Exact shared agent/session identity driven by this terminal. */
+    sessionId: string;
+    /** Render model reasoning blocks. */
+    showReasoning?: boolean;
+    /** Maximum tool-result body lines retained on each card. */
+    maxToolOutputLines?: number;
+    /** Apply ANSI colors. */
+    color?: boolean;
+    /** Banner subtitle line shown while no session title exists. */
+    welcome?: string;
+    /** Whether this launch resumes an existing persisted session. */
+    resume?: boolean;
+    /** Provider route selected at launch (defaults to deepseek-official). */
+    provider?: string;
+    /** Model selected at launch (defaults to the saved/fallback model). */
+    model?: string;
+    /** Live model-selection ref installed on the agent; mutated by /model. */
+    selectionRef?: ModelSelectionRef;
+    /** Active agent-preset id (standard/code/minimal/cordis/...). */
+    presetId?: string;
+    /** Display name of the active preset. */
+    presetName?: string;
+    /** Switch the running TUI to another session (used by /resume). */
+    onSwitchSession?: (sessionId: string) => Promise<void> | void;
+    /** Notify the launcher of an explicit in-process selection change. */
+    onSelectionChanged?: (selection: ModelSelection) => void;
+    /** Open the history-session picker immediately after mounting (--resume). */
+    resumePicker?: boolean;
+}
+type Row = {
+    kind: 'user';
+    text: string;
+} | {
+    kind: 'assistant';
+    text: string;
+} | {
+    kind: 'reasoning';
+    text: string;
+    expanded: boolean;
+} | {
+    kind: 'brand';
+    text: string;
+} | {
+    kind: 'brand-logo';
+} | {
+    kind: 'tool';
+    callId: string;
+    name: string;
+    args: string;
+    status?: 'running' | 'ok' | 'error';
+    output: string;
+    title: string;
+    summary: string;
+    command?: string;
+    cwd?: string;
+    diff?: ToolDiffHunk[];
+    exitCode?: number;
+    signal?: string;
+    expanded: boolean;
+} | {
+    kind: 'system';
+    text: string;
+} | {
+    kind: 'error';
+    text: string;
+};
+type DisplayKind = Row['kind'] | 'tool-result' | 'diff-add' | 'diff-del' | 'diff-path';
+/** One file's change, matching the web diff-card contract (`card: 'diff'`). */
+interface ToolDiffHunk {
+    path: string;
+    oldText: string | null;
+    newText: string;
+}
+/** Lifecycle handle for a mounted interactive terminal channel. */
+export interface TuiController {
+    dispose(): Promise<void>;
+}
+/**
+ * Render workspace markdown into width-bounded terminal rows. Assistant
+ * replies get a bold-white base; code blocks, headings, quotes, lists, rules,
+ * links and inline spans keep their own ANSI treatment.
+ */
+export declare function renderMarkdownLines(text: string, width: number, color: boolean): string[];
+/** One renderable view of the input line: text plus the cursor's visual offset. */
+interface InputView {
+    text: string;
+    cursorOffset: number;
+    folded: boolean;
+}
+/**
+ * Fold a long single-line input into one terminal row around the cursor.
+ * Only the *display* is clipped; the caller keeps the original `input` intact
+ * for editing and submission.
+ */
+export declare function foldInputView(input: string, cursor: number, maxWidth: number): InputView;
+/** A recognized OpenCode provider route, used by /usage and /quota. */
+export type OpenCodeFlavor = 'zen' | 'go';
+export interface OpenCodeSource {
+    provider: string;
+    flavor: OpenCodeFlavor;
+    label: string;
+    apiKeyEnv: string;
+    baseURL?: string;
+}
+/**
+ * Classify the currently selected provider as an OpenCode route. Built-in
+ * `opencode`/`opencode-go` ids are recognized directly, and custom llm-pi-ai
+ * routes are recognized by their `opencode.ai` base URL.
+ */
+export declare function openCodeSourceFor(provider: string, llmPiAiSection: unknown): OpenCodeSource | null;
+/** Render the OpenCode Go quota payload as a transcript block. */
+export declare function formatOpenCodeGoUsage(payload: unknown, source: OpenCodeSource): string;
+/** One-line friendly tool-call presentation (command / path / arg summary). */
+export declare function presentToolCall(name: string, args: string): {
+    title: string;
+    summary: string;
+    command?: string;
+    cwd?: string;
+    diff?: ToolDiffHunk[];
+};
+/** Validate a tool/result meta payload's structured diff, mirroring the web card. */
+export declare function diffMetaDiffs(meta: unknown): ToolDiffHunk[] | null;
+/** One rendered diff body line with its display role. */
+interface DiffDisplayLine {
+    kind: DisplayKind;
+    text: string;
+}
+/** Flatten hunks into git-style `-`/`+` lines plus the web-compatible footer. */
+export declare function renderToolDiff(diffs: ToolDiffHunk[], maxLines: number): DiffDisplayLine[];
+/** Convert any parsed JSON value into readable indented display lines. */
+export declare function friendlyJsonLines(value: unknown, depth?: number): string[];
+/** Minimal tool-row shape the expanded-body renderer reads. */
+interface ToolBodySource {
+    diff?: ToolDiffHunk[];
+    command?: string;
+    status?: 'running' | 'ok' | 'error';
+    output: string;
+    args: string;
+}
+/**
+ * The expanded body of one tool card: diffs and shell output keep their
+ * dedicated views; every other tool's JSON arguments and JSON result are
+ * converted into readable indented content instead of raw JSON text.
+ */
+export declare function toolBodyLines(row: ToolBodySource, maxLines: number): DiffDisplayLine[];
+/** Recover the shell tools' exit marker, mirroring @deepseek-ai/dsh-shell/render. */
+export declare function parseExitStatus(text: string): {
+    body: string;
+    exitCode?: number;
+    signal?: string;
+};
+/** Compact token count, matching the web stats line (517 / 12.2K / 1.2M). */
+export declare function formatTokens(n: number): string;
+/** Compact duration, matching the web stats line (45.2s / 2m42s). */
+export declare function formatDuration(ms: number): string;
+export declare function formatTokensPerSecond(tokensPerSecond: number): string;
+/** Owns one interactive terminal channel and its agent event wiring. */
+export declare class SshTui {
+    private readonly ctx;
+    private readonly agent;
+    private readonly rows;
+    private streaming;
+    private input;
+    private cursor;
+    private inputFolded;
+    private history;
+    private historyIndex;
+    private status;
+    private dialog;
+    private dirty;
+    private disposed;
+    private exiting;
+    private renderTimer;
+    private readonly decoder;
+    private readonly color;
+    private readonly maxToolOutputLines;
+    private readonly showReasoning;
+    private readonly goodbye;
+    private readonly resume;
+    private readonly providerName;
+    private readonly selectionRef;
+    private readonly onSwitchSession;
+    private readonly onSelectionChanged;
+    private readonly resumePicker;
+    private readonly disposers;
+    private userQuestionDisposer;
+    private presetId;
+    private presetName;
+    private readonly useAlternateScreen;
+    private agentGone;
+    private onboarding;
+    private commandSuggestions;
+    private suggestionIndex;
+    private focusedRow;
+    private pendingMessages;
+    private lastActivity;
+    private stalledWarningShown;
+    private lastPaintAt;
+    private activeSubagents;
+    private subagentSessions;
+    private openToolCalls;
+    private readonly stats;
+    private openStepStats;
+    private readonly pendingToolTimes;
+    private readonly usageByStep;
+    private lastStatsTurn;
+    private scrollOffset;
+    private readonly clickableRows;
+    private streamingReasoning;
+    private escapeBuffer;
+    private escapeTimer;
+    private thinkingStartedAt;
+    private completionSignaled;
+    private completedAt;
+    private lastTitleUpdateAt;
+    private lastPaintRows;
+    private lastChromeKey;
+    constructor(ctx: Context, agent: Agent, config: TuiConfig);
+    /** Enter raw mode, switch to the alternate screen, and start listening. */
+    start(): void;
+    /** Replay the durable session log so a resumed session renders its history. */
+    replayHistory(): void;
+    /** Show the first-launch provider/API-key onboarding when nothing is configured. */
+    private maybeRunOnboarding;
+    /** Run the provider/API-key onboarding wizard. Resolves true when saved. */
+    private runOnboarding;
+    private cancelOnboarding;
+    /** Restore the terminal, flush the session, and request process exit. */
+    dispose(): Promise<void>;
+    /** Human-facing exit with goodbye and flush; called from key handling. */
+    requestExit(code: number): Promise<void>;
+    private write;
+    private markDirty;
+    /** Append one transcript row, bounding memory on long sessions. */
+    private pushRow;
+    /** The transcript rows that support per-row expand/collapse. */
+    private collapsibleRows;
+    /** Move the expand/collapse focus among reasoning and tool rows. */
+    private moveCollapsibleFocus;
+    /** Toggle the focused block; without focus, toggle the most recent one. */
+    private toggleCollapsible;
+    /** Expand all collapsible blocks, or collapse them again when all are open. */
+    private toggleAllCollapsible;
+    private paint;
+    private buildSuggestions;
+    private suggestionsVisible;
+    private currentSelectionLabel;
+    /** Replace one step's usage sample so a repeated report never double counts. */
+    private recordUsage;
+    /** The web-aligned session stats strip: counts, timings, cache, tokens. */
+    private statsText;
+    /** Refresh the terminal window title (throttled while running). */
+    private updateTerminalTitle;
+    /** Terminal bell on completion (opt out with DSH_TUI_NO_BELL=1). */
+    private playCompletionSignal;
+    private render;
+    private styleLine;
+    private readonly handleSessionEvent;
+    private readonly handleStatus;
+    private readonly handleError;
+    private readonly handleInboxClaimed;
+    private readonly handleInboxDiscarded;
+    private readonly handleDisposed;
+    /** Render a live subagent's own session events so its progress is visible. */
+    private readonly handleSubagentSessionEvent;
+    private readonly handleSubagentStart;
+    private readonly handleSubagentEnd;
+    private readonly handleApproval;
+    private readonly handleUserQuestions;
+    private openConfirm;
+    private closeConfirm;
+    private openQuestion;
+    /** Open one question dialog and await its answer (cancellation rejects). */
+    private askQuestion;
+    /** The stored llm-pi-ai profile for one provider route, when settings provide one. */
+    private piAiProviderProfile;
+    /** Default listing endpoint for a built-in OpenCode route with no stored base URL. */
+    private openCodeListingBaseURL;
+    /**
+     * Fetch the live model list for an OpenCode or third-party provider from its
+     * OpenAI-compatible listing endpoint. The provider route is deliberately not
+     * passed to discovery: pi-ai would answer a catalog route from its installed
+     * registry, while the TUI wants the endpoint's current list.
+     */
+    private discoverEndpointModels;
+    /** Add one endpoint-listed model to the stored provider profile when needed. */
+    private ensureProviderModelConfigured;
+    /** How many endpoint-listed models fit on one picker page alongside navigation. */
+    private readonly MODEL_PAGE_SIZE;
+    private readonly MODEL_PAGE_PREV;
+    private readonly MODEL_PAGE_NEXT;
+    /**
+     * One pick across a possibly long model list, paging through the digit
+     * dialog so an endpoint with dozens of models stays selectable.
+     */
+    private pickModelOption;
+    /** /model: pick a model and reasoning effort for the current provider. */
+    private runModelCommand;
+    /** /mode: pick an agent preset (standard / PTC / minimal / ...). */
+    private runModeCommand;
+    /** /resume: switch to a past session, or open a picker when no id is given. */
+    private runResumeCommand;
+    /** Current provider route selected for the running agent. */
+    private currentProvider;
+    /** Resolve one credential reference without exposing its value. */
+    private resolveCredential;
+    /** Query the OpenCode Go quota endpoint. */
+    private fetchOpenCodeGoUsage;
+    /** Explain Zen metered billing instead of pretending it has a quota. */
+    private zenUsageText;
+    /** /usage and /quota: show Zen billing info or live Go quota usage. */
+    private runUsageCommand;
+    private readonly handleData;
+    private handlePlainText;
+    private handleChar;
+    private handleDialogChar;
+    private handleOnboardingChar;
+    private advanceOnboarding;
+    /** Fetch the endpoint's model list into the onboarding wizard's models step. */
+    private fetchOnboardingModels;
+    private saveOnboarding;
+    /** Store one credential, falling back to a launch-environment override on shadow/absence. */
+    private saveCredential;
+    /** Write launch-environment overrides so they beat system-injected variables. */
+    private writeLaunchEnv;
+    /** Persist one variable into the Windows user environment (best-effort). */
+    private setWindowsEnv;
+    /** Idempotently source $DSH_HOME/env.sh from the user's POSIX shell rc files. */
+    private ensurePosixEnvHook;
+    private handleEscape;
+    /** Toggle the collapsible row under a click on the transcript area. */
+    private handleMouseClick;
+    private handleCtrlC;
+    private submit;
+    private runCommand;
+    private backspace;
+    private deleteAtCursor;
+    private moveCursor;
+    private historyBack;
+    private historyForward;
+}
+/**
+ * Mount the terminal channel once the configured agent exists.
+ *
+ * @param ctx - context supplying the agent registry, sessions, and event stream.
+ * @param config - target agent and presentation config.
+ * @returns lifecycle controller used by the Cordis effect disposer.
+ */
+export declare function mountTui(ctx: Context, config: TuiConfig): TuiController;
+export {};

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "dsh-ssh-tui",
+  "version": "0.1.0",
+  "description": "SSH-friendly interactive terminal TUI plugin for DeepSeek Harness",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "tui",
+    "terminal",
+    "ssh"
+  ],
+  "author": "cyjyyd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyjyyd/dsh-ssh-tui.git"
+  },
+  "homepage": "https://github.com/cyjyyd/dsh-ssh-tui#readme",
+  "bugs": {
+    "url": "https://github.com/cyjyyd/dsh-ssh-tui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./startup": {
+      "types": "./lib/types/startup.d.ts",
+      "default": "./lib/startup.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf lib",
+    "prepare": "npm run build",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck",
+    "install:dsh": "bash scripts/install.sh",
+    "install:npm": "bash scripts/install-npm.sh",
+    "uninstall:dsh": "bash scripts/uninstall.sh",
+    "verify:dsh": "bash scripts/verify.sh"
+  },
+  "engines": {
+    "node": ">=22.19"
+  },
+  "dependencies": {
+    "commander": "^14.0.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-default-model": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-cmdline": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-subagent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.6"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-user-approval": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-user-questions": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-credentials": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-settings": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-default-model": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-presets": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-cmdline": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-subagent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.6",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}