@chatcode/cco-better-sidebar 0.18.0-alpha.0

package/lib/types/prefs-shared.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Shared "Side card" preference vocabulary (types + constants), consumed by
+ * BOTH halves: the host registers the schemastery schema over these values
+ * (config.ts) and the client reads/writes them through the settings RPC
+ * (client/prefs.ts, client/SideCardSection.tsx). Kept free of schemastery so
+ * the browser bundle never pulls the schema runtime in.
+ */
+/** The user-settings namespace holding the side card preferences. */
+export declare const SIDEBAR_PREFS_NS = "dsh-better-sidebar";
+/** User-facing side card preferences (new-conversation defaults). */
+export interface SidebarPrefs {
+    /** Whether a brand-new conversation opens the side card by default. */
+    openByDefault: boolean;
+    /** Default panel width as a percent of the window width (20–60). */
+    defaultWidthPercent: number;
+    /**
+     * Whether the sidebar auto-activates (opens the panel) and expands the
+     * Subagent page when the current conversation spawns a new subagent.
+     */
+    autoOpenSubagent: boolean;
+    /**
+     * Whether the sidebar auto-activates (opens the panel) and expands the
+     * Jobs page when a NEW background job appears for the current
+     * conversation (any new job id, not just the first one).
+     */
+    autoOpenJobs: boolean;
+    /**
+     * Whether the model-facing agent terminal tools (terminal_create / list /
+     * send / read / wait_for / resize / signal / close) are injected into the
+     * model's toolset. Off by default: the feature stays dormant until the
+     * user explicitly enables it in the side card settings.
+     */
+    agentTerminalTools: boolean;
+    /**
+     * Whether the model-facing `sidebar_open` tool is injected into the
+     * model's toolset — one tool that lets the model actively open a local
+     * file, a local folder (as a tree rooted there), or an HTTP(S) page in
+     * the calling session's sidebar. Off by default: the feature stays
+     * dormant until the user explicitly enables it in the side card settings.
+     */
+    agentOpenTools: boolean;
+    /**
+     * Custom terminal font-family stack (a CSS font-family value, e.g.
+     * `'JetBrains Mono', monospace`). Empty string follows the app's theme
+     * monospace font (`--ds-font-family-code`). Applied live to every
+     * terminal tab; configured under the terminal card's secondary settings.
+     */
+    terminalFontFamily: string;
+    /**
+     * Custom terminal font size in px (9–32). Applied live to every terminal
+     * tab; configured under the terminal card's secondary settings.
+     */
+    terminalFontSize: number;
+    /**
+     * Whether expanding the bottom panel for the FIRST time in a session tries
+     * to open a fresh terminal tab there (the terminal quota/type still gates
+     * the attempt). On by default; the switch lives under the terminal tab's
+     * row in the Side card settings.
+     */
+    bottomPanelAutoTerminal: boolean;
+    /**
+     * Whether chat-side file opens (tool-row path links, the produced-files
+     * row, prose file mentions — every path that funnels through the client
+     * runtime's `ctx.workspaces.openPath`) open in the sidebar editor instead
+     * of the Host OS's default application. On by default; the editor tab's
+     * own enable switch gates it too (both must be on for the takeover).
+     */
+    interceptOpenPath: boolean;
+    /**
+     * Whether the editor tab runs in merged mode: a path input replaces the
+     * plain header and a toggleable file-tree panel (with a global name
+     * search) docks at the tab's right edge. On by default; also makes brand
+     * new sessions seed an empty editor tab (tree panel open) instead of the
+     * explorer tab. The switch lives under the editor card's gear in the
+     * Side card settings; off restores the pre-merge editor exactly.
+     */
+    editorExplorer: boolean;
+    /**
+     * Whether the sidebar's filesystem routes enforce the workspace fence:
+     * every client-supplied path must resolve (through symlinks) inside the
+     * session workspace, else the route answers 403 "outside workspace". On
+     * by default; turning it OFF lets the file tree / editor read+write /
+     * media / HTML preview / upload routes reach ANY host path (e.g. the
+     * global ~/.chatcode-cli/AGENTS.md or a linked worktree outside the session cwd)
+     * — the trade-off being that any same-origin script (including
+     * third-party consumer plugins) can read/write outside the workspace
+     * through those routes while it is off. The switch lives under the files
+     * tab's gear in the Side card settings; the fence error surfaces offer a
+     * one-click global off + retry.
+     */
+    workspaceFence: boolean;
+    /**
+     * The shell the UI and agent terminals spawn (absolute path or bare
+     * executable name). Empty (default) keeps the legacy resolution order:
+     * `cordis.patch.yml` `config.shell`, then `$SHELL` / login shell /
+     * `powershell.exe` on Windows. Set it from the terminal card's gear in
+     * the Side card settings (or the yaml) to pin a specific shell — takes
+     * effect for terminals opened afterwards.
+     */
+    terminalShell: string;
+    /**
+     * Explicit arguments for `terminalShell`, space-separated (empty keeps
+     * the platform defaults; when set, they fully replace them — same
+     * contract as the yaml `shellArgs`).
+     */
+    terminalShellArgs: string;
+    /**
+     * Title-bar / shell compatibility scheme (the "位置兼容模式" setting):
+     * - `auto` (default): CONSERVATIVE — only the standard Window Controls
+     *   Overlay API (present in frameless Chromium shells that draw the
+     *   native caption buttons over web content) contributes real geometry;
+     *   without it nothing is modified, so plain-browser (web) behavior is
+     *   untouched.
+     * - `web`: EXPLICIT "ChatCode CLI Web" — never adapt, not even WCO
+     *   geometry (the user declares they run the plain web UI).
+     * - `preset`: apply the built-in shell preset named by
+     *   `titleBarPresetId` (data-driven, opt-in — see shell-presets.ts).
+     * - `custom`: apply the free-form `customCss` (and the legacy
+     *   `titleBarStripPx` strip).
+     */
+    titleBarScheme: TitleBarScheme;
+    /**
+     * The built-in shell preset id applied while `titleBarScheme` is
+     * `preset` ('' = no preset — nothing extra is applied).
+     */
+    titleBarPresetId: string;
+    /**
+     * Free-form CSS injected into the page (last in the cascade, so it can
+     * override the plugin's styles; use `!important` to override JS-written
+     * inline CSS variables). Applied while `titleBarScheme` is `custom`.
+     */
+    customCss: string;
+    /**
+     * LEGACY (kept for read-migration and downgrade mirroring only): position
+     * compatibility mode flag. The UI writes `titleBarScheme` instead; a
+     * stored `true` without a scheme migrates to the `custom` scheme (with
+     * `titleBarStripPx` preserved).
+     */
+    titleBarCompat: boolean;
+    /**
+     * LEGACY (kept for read-migration and downgrade mirroring only): the
+     * reserved top strip height in px used by the `custom` scheme (0–120,
+     * default 40). Drives the `--dsh-title-bar-strip` CSS variable: the
+     * toggle cluster drops `strip + 3px` and the right panel's content
+     * starts `strip` px below its top edge.
+     */
+    titleBarStripPx: number;
+    /**
+     * Whether the HTML previewer drops its sandboxed iframe. Sandbox ON (the
+     * default) renders previewed HTML in an opaque-origin iframe that cannot
+     * touch the GUI; turning it OFF runs the previewed page with the GUI's
+     * own origin — full read/write access to session files and internal
+     * APIs. Only for trusted local content; the setting copy warns.
+     */
+    htmlViewerNoSandbox: boolean;
+    /**
+     * Whether a newly opened HTML preview starts UNSANDBOXED (the per-surface
+     * temporary unlock pre-applied). Off by default: previews open sandboxed
+     * and the status row offers the one-tap unlock; when on, previews open
+     * in the red unsandboxed state and the status row offers a one-tap
+     * restore for the current file.
+     */
+    htmlViewerDefaultUnsafe: boolean;
+    /**
+     * Whether the browser tab drops its sandboxed iframe. Sandbox ON (the
+     * default) keeps browsed sites in an opaque origin with no GUI access;
+     * turning it OFF runs any visited site with the GUI's own origin — it
+     * can read session data and act as the logged-in GUI. Only for trusted
+     * sites; the setting copy warns.
+     */
+    browserNoSandbox: boolean;
+    /**
+     * MASTER switch: whether clicking an EXTERNAL link in the GUI (chat
+     * messages, tool rows, prose mentions) is taken over into the sidebar at
+     * all. On by default; the per-protocol granularity lives in
+     * `browserInterceptHttp` / `browserInterceptHttps` (the protocol flag
+     * must also be on), and the target tab's own enable switch gates it too.
+     * Ctrl/Cmd+click always bypasses the takeover. Kept as the master so old
+     * documents keep their meaning with no migration (an explicit `false`
+     * stays "never take over").
+     */
+    browserInterceptLinks: boolean;
+    /**
+     * Whether clicking an http EXTERNAL link in the GUI opens the sidebar
+     * (the built-in browser tab, or a plugin tab that declares `urlTarget`)
+     * instead of a new browser tab. On by default; gated on the
+     * `browserInterceptLinks` master and the target tab's own enable switch.
+     */
+    browserInterceptHttp: boolean;
+    /**
+     * Whether clicking an https EXTERNAL link in the GUI opens the sidebar
+     * instead of a new browser tab. OFF by default — most https sites (e.g.
+     * GitHub) refuse iframe embedding, so the system browser is the smoother
+     * default; gated on the `browserInterceptLinks` master and the target
+     * tab's own enable switch.
+     */
+    browserInterceptHttps: boolean;
+    /**
+     * Comma-separated allowlist of local (loopback) authorities the browser
+     * tab may navigate to — `localhost`, `127.0.0.1`, `127.0.0.1:5174`, or
+     * host:port pairs. Empty by default: loopback addresses stay blocked so a
+     * browsed page cannot probe local services. Each entry is either a bare
+     * hostname (all ports) or host:port; the GUI's own origin is always
+     * allowed regardless. The iframe sandbox still renders allowed local
+     * pages in an opaque origin, exactly like any other site.
+     */
+    browserAllowedLoopback: string;
+    /**
+     * Per-tab enable switches, keyed by tab descriptor id (`'explorer'`,
+     * `'my-plugin:db'`). An ABSENT key means enabled — only an explicit
+     * `false` disables a tab type (hidden from the + menu, `openTab` refuses,
+     * and derived flows like subagent auto-open / agent-terminal tabs stop).
+     * Already-open tabs of a disabled type keep rendering (closing one
+     * prevents reopening), matching the "existing conversations keep their
+     * own layouts" rule.
+     */
+    tabsEnabled: Record<string, boolean>;
+    /**
+     * Per-viewer enable switches, keyed by file viewer descriptor id
+     * (`'image'`, `'my-plugin:csv'`). An ABSENT key means enabled; a disabled
+     * viewer is skipped by `matchFileViewer` so files fall through to the
+     * next matching viewer (or the download button when none match).
+     */
+    viewersEnabled: Record<string, boolean>;
+    /**
+     * Plugin-owned settings blobs (v0.12.0+), keyed by descriptor id: each
+     * registered tab/viewer that declares `settings.pluginToggles` (or writes
+     * through `settings.render`'s `updatePluginSetting`) persists its values
+     * here — an open map, so third-party keys need no host PrefsSchema field.
+     * Values are JSON-serializable (the row controls produce strings /
+     * numbers / booleans; custom panels are responsible for their own).
+     */
+    pluginSettings: Record<string, Record<string, unknown>>;
+}
+/** Range contract of {@link SidebarPrefs.defaultWidthPercent}. */
+export declare const WIDTH_PERCENT_MIN = 20;
+export declare const WIDTH_PERCENT_MAX = 60;
+export declare const WIDTH_PERCENT_DEFAULT = 35;
+/** Range contract of {@link SidebarPrefs.terminalFontSize}. */
+export declare const TERMINAL_FONT_SIZE_MIN = 9;
+export declare const TERMINAL_FONT_SIZE_MAX = 32;
+export declare const TERMINAL_FONT_SIZE_DEFAULT = 13;
+/** Range contract of {@link SidebarPrefs.titleBarStripPx}. */
+export declare const TITLE_BAR_STRIP_MIN = 0;
+export declare const TITLE_BAR_STRIP_MAX = 120;
+export declare const TITLE_BAR_STRIP_DEFAULT = 40;
+/** The title-bar / shell compatibility schemes (see {@link SidebarPrefs.titleBarScheme}). */
+export declare const TITLE_BAR_SCHEMES: readonly ["auto", "web", "preset", "custom"];
+export type TitleBarScheme = typeof TITLE_BAR_SCHEMES[number];
+/** Fallback prefs used whenever the settings document is unreachable or malformed. */
+export declare const SIDEBAR_PREFS_DEFAULTS: SidebarPrefs;
+/** Clamp one width percent into the contract range (shared by schema and client reads). */
+export declare function clampWidthPercent(value: number): number;
+/** Clamp one terminal font size into the contract range (shared by schema and client reads). */
+export declare function clampTerminalFontSize(value: number): number;
+/** Clamp one title-bar strip height into the contract range (shared by schema and client reads). */
+export declare function clampTitleBarStrip(value: number): number;

package/lib/types/pty-deps.d.ts

@@ -0,0 +1,79 @@
+import type * as nodePtyNs from 'node-pty';
+/** The node-pty module surface the registries consume (spawn/kill/resize/…). */
+export type NodePtyModule = typeof nodePtyNs;
+/**
+ * The node-pty version range this plugin ships. MUST stay identical to the
+ * range DSH core declares (`@deepseek-ai/dsh-subprocess-local`): the same
+ * range keeps pnpm resolving both to one physical package.
+ */
+export declare const DSH_NODE_PTY_RANGE = "^1.1.0";
+/**
+ * The WebSocket close-code-1011 reason the host sends when node-pty is
+ * unavailable. The client recognizes this exact marker and fetches the full
+ * repair details from `/sidebar/api/terminal.deps` (a WS close reason is
+ * capped at 123 bytes, so the command itself cannot ride the close frame).
+ */
+export declare const PTY_DEPS_MISSING = "pty-deps-missing";
+/** A require-compatible loader, injectable for tests. */
+export type NodePtyRequire = (id: string) => unknown;
+/**
+ * Load node-pty once (synchronously) and cache the outcome. Returns null
+ * when the package or its native binding cannot be loaded; the cause stays
+ * queryable through {@link nodePtyLoadCause}. Never throws.
+ */
+export declare function loadNodePty(requireImpl?: NodePtyRequire): NodePtyModule | null;
+/** The recorded load failure (undefined when the load succeeded or never ran). */
+export declare function nodePtyLoadCause(): unknown;
+/** Forget the cached outcome (tests only — a real reload is otherwise one-shot). */
+export declare function resetNodePtyCache(): void;
+/** Load node-pty or throw the canonical degraded-mode error (class-constructor default). */
+export declare function loadRequiredNodePty(): NodePtyModule;
+/**
+ * Detect the DSH profile directory this plugin is installed into: the
+ * nearest ancestor of the plugin module that carries both `package.json`
+ * and `pnpm-workspace.yaml` (the profile root; the plugin resolves from the
+ * profile's node_modules). Falls back to `$CHATCODE_CLI_HOME/profiles/web`
+ * (with legacy `$DSH_HOME` as a read-only compatibility input), then the
+ * canonical ChatCode CLI home, and finally null.
+ */
+export declare function findProfileDir(fromFile?: string): string | null;
+/** The plugin package root (walk-up from the module; works for lib/ and src/ layouts). */
+export declare function findPluginRoot(fromFile?: string): string | null;
+/** Options for {@link buildRepairCommand}. */
+export interface RepairCommandOptions {
+    /** The plugin package root (where scripts/install.sh / install.ps1 live). */
+    pluginRoot: string | null;
+    /** The detected profile directory (null → the standard `web` profile). */
+    profileDir: string | null;
+    /** Platform override for tests; defaults to the live process. */
+    platform?: NodeJS.Platform;
+}
+/**
+ * The pasteable repair command for a broken node-pty install: rerun the
+ * plugin's own installer in `--repair` mode (idempotent: it re-writes the
+ * profile's `allowBuilds: node-pty: true` and re-installs/rebuilds the
+ * dependency). Falls back to ChatCode CLI's plugin command when the scripts are not
+ * shipped (exotic layouts).
+ */
+export declare function buildRepairCommand(options: RepairCommandOptions): {
+    command: string;
+    note?: string;
+};
+/** Structured status served by the `/sidebar/api/terminal.deps` endpoint. */
+export type NodePtyDepsStatus = {
+    ok: true;
+} | {
+    ok: false;
+    /** The require-time error message (module missing, native binding broken…). */
+    cause: string;
+    /** The pasteable repair command (terminal/cmd). */
+    command: string;
+    /** The detected profile name (null when undetected → the command defaults to web). */
+    profile: string | null;
+    /** Optional supplementary hint (fallback command only). */
+    note?: string;
+};
+/** Current node-pty dependency status (loaded vs degraded + repair info). */
+export declare function depsStatus(options?: {
+    fromFile?: string;
+}): NodePtyDepsStatus;

package/lib/types/pty-manager.d.ts

@@ -0,0 +1,168 @@
+import type { IPty } from 'node-pty';
+import { type NodePtyModule } from './pty-deps.ts';
+/**
+ * Restore the executable bit pnpm strips from node-pty's prebuilt
+ * spawn-helper (the macOS helper that forks and sets up the pty). Without it
+ * every spawn fails with `posix_spawnp failed`. Idempotent; mirrors
+ * @deepseek-ai/dsh-terminal-bash's ensure-spawn-helper postinstall, run at
+ * plugin activation so link-installed deployments get the fix too.
+ */
+export declare function ensureSpawnHelper(): void;
+/** One live terminal. */
+export interface SidebarPty {
+    /** `${sessionId}:${tabId}` registry key. */
+    key: string;
+    sessionId: string;
+    tabId: string;
+    /** The working directory the process was SPAWNED with (a reconnect that
+     *  resolves a different authoritative cwd respawns instead of reusing —
+     *  the page-load hydrate race can attach the real cwd after the first
+     *  connect, and a shell in the wrong directory must not linger). */
+    cwd: string;
+    pty: IPty;
+    /** Output accumulated since spawn (bounded; head dropped when over the limit). */
+    transcript: string;
+    /** Whether the top-level process exited (transcript stays replayable). */
+    exited: boolean;
+    exitCode?: number | null;
+}
+/**
+ * The terminal registry. `maxPerSession` bounds concurrent processes per
+ * conversation (the client caps tabs at the same number).
+ *
+ * Lifecycle of a UI-tab pty when its WebSocket drops:
+ * - **Close frame** (`{type:'close'}`): the user closed the tab → schedule a
+ *   0-ms close (quota released immediately).
+ * - **Park frame** (`{type:'park'}`): the user switched to another
+ *   conversation; the tab is still open in its session's persisted state but
+ *   its view unmounted → mark the pty as parked (no auto-close countdown).
+ *   The pty stays alive until the user switches back (a reconnecting view
+ *   calls `open()` which clears the parked state) or the tab is later closed
+ *   (a `{type:'close'}` frame from a fresh connection). Without `park`, a
+ *   bare socket drop would start the reconnect-grace countdown and kill the
+ *   shell after `reconnectGraceMs` — wrong for a session switch, where the
+ *   user is still actively using the app, just in another conversation.
+ * - **Bare socket drop** (no frame): page refresh, crash, plugin teardown →
+ *   schedule a close after `reconnectGraceMs` so a quick reconnect reattaches
+ *   the same shell.
+ */
+export declare class PtyManager {
+    private readonly shell;
+    private readonly maxPerSession;
+    private readonly shellArgs;
+    /** The loaded node-pty module (injected so a broken install degrades instead of crashing the plugin). */
+    private readonly nodePty;
+    private readonly sessions;
+    private readonly pendingCloses;
+    /** Tabs whose view unmounted because the user switched conversations — the
+     *  tab is still open in its session's state, so the pty must NOT enter the
+     *  reconnect-grace countdown. Cleared by `cancelClose` (a reconnecting
+     *  view's `open()` cancels it) or by `scheduleClose` (an explicit close
+     *  frame still kills a parked pty). */
+    private readonly parked;
+    constructor(shell: string, maxPerSession: number, shellArgs?: string[], 
+    /** The loaded node-pty module (injected so a broken install degrades instead of crashing the plugin). */
+    nodePty?: NodePtyModule);
+    /** All live terminal keys of one session. */
+    keysOf(sessionId: string): string[];
+    /**
+     * Open (or reuse) the terminal for a session/tab key. A handle whose
+     * process already exited is replaced with a fresh spawn (reconnecting a
+     * dead terminal must yield a live shell, not an input sink), and so is a
+     * live handle whose spawn cwd differs from the now-authoritative one (the
+     * first connect of a page load can arrive before the session hydrates, so
+     * it fell back to the process cwd — reconnecting with the real cwd must
+     * restart the shell in the right directory). Reopening also cancels any
+     * pending scheduled close (a reconnect within the grace window keeps the
+     * process alive).
+     * @param sessionId - conversation id.
+     * @param tabId - client tab id.
+     * @param cwd - initial working directory (the session's cwd).
+     * @param cols - initial terminal width.
+     * @param rows - initial terminal height.
+     * @returns the live handle.
+     * @throws {SidebarError} pty-error when the per-session cap is reached.
+     */
+    open(sessionId: string, tabId: string, cwd: string, cols: number, rows: number, shell?: string, shellArgs?: string[]): SidebarPty;
+    /**
+     * Schedule the terminal's destruction after `delayMs`. A tab close sends
+     * delay 0 (release the quota immediately); a bare socket drop (refresh,
+     * crash) uses the grace period so a quick reconnect keeps the process.
+     * `open()` cancels any pending close. Clears the parked state — an explicit
+     * close frame on a parked pty (the user switched back and closed the tab)
+     * still kills it.
+     */
+    scheduleClose(key: string, delayMs: number): void;
+    /**
+     * Park a terminal: the owning tab's view unmounted because the user
+     * switched to another conversation, but the tab is still open in its
+     * session's persisted state. Cancels any pending grace close and marks
+     * the pty so the host's `ws.on('close')` handler does NOT start the
+     * reconnect-grace countdown — the pty stays alive until the user switches
+     * back (a reconnecting view's `open()` clears this) or explicitly closes
+     * the tab (a `{type:'close'}` frame's `scheduleClose` clears this).
+     */
+    park(key: string): void;
+    /** Whether this pty was parked (its view unmounted for a session switch). */
+    isParked(key: string): boolean;
+    /** Cancel a pending scheduled close (the terminal is being reopened).
+     *  Also clears the parked state — a reconnecting view reattaches a parked
+     *  pty and resumes normal lifecycle. */
+    cancelClose(key: string): void;
+    /** Resolve a live handle by key, or undefined. */
+    get(key: string): SidebarPty | undefined;
+    /** Close a terminal and drop its state (the owning tab was closed). */
+    close(key: string): void;
+    /** Close every terminal (plugin teardown). */
+    disposeAll(): void;
+}
+/**
+ * Inputs for {@link defaultShell} resolution. Every field is optional and
+ * defaults to the live process, which keeps the no-argument call sites
+ * working while tests (and exotic embedders) can pin the platform, the
+ * environment, and the existence probe independently — the Windows chain
+ * never executes on the ubuntu CI runners, so it is only testable through
+ * these injection points.
+ */
+export interface ShellResolutionOptions {
+    /** Platform override (defaults to `process.platform`). */
+    platform?: NodeJS.Platform;
+    /** Environment override; the resolver only reads SHELL, DSH_SIDEBAR_SHELL, PATH, ProgramW6432, ProgramFiles, LOCALAPPDATA. */
+    env?: NodeJS.ProcessEnv;
+    /** Explicitly configured shell (the `shell` config field); wins over every automatic source. Empty means unset. */
+    explicit?: string;
+    /** File-existence probe override (defaults to `existsSync`). */
+    exists?: (path: string) => boolean;
+}
+/**
+ * The interactive shell for this platform, resolved like a terminal
+ * emulator: an explicitly configured shell (the `shell` config field) wins,
+ * then `$SHELL` on POSIX (deployment override), then the account's login
+ * shell from passwd, then `/bin/bash`. The passwd step matters because
+ * service managers and container inits often start dsh without `SHELL`, and
+ * the tab should still open the user's login shell (e.g. zsh) instead of
+ * silently degrading to bash.
+ *
+ * Windows previously short-circuited to `powershell.exe` (the inbox 5.1)
+ * before any resolution, so PowerShell 7 users always got a legacy shell
+ * without `??`/`?.`/ternary and with poor ANSI/UTF-8 defaults. The Windows
+ * chain is now: explicit shell → `DSH_SIDEBAR_SHELL` env override → first
+ * `pwsh.exe` found on PATH or in a known install directory → the 5.1
+ * fallback (machines without PowerShell 7 keep working).
+ */
+export declare function defaultShell(options?: ShellResolutionOptions): string;
+/**
+ * A short display name for a shell executable, used as the terminal tab
+ * title. `/bin/zsh` → `zsh`, `C:\...\powershell.exe` → `powershell`.
+ * Falls back to the raw value when no basename can be derived.
+ */
+export declare function shellDisplayName(shell: string): string;
+/**
+ * Spawn arguments that make the shell behave like a terminal-emulator tab:
+ * POSIX shells start as login shells (`-l`) so they read the profile files
+ * (`~/.profile`, `~/.zprofile`); Windows PowerShell takes no login flag.
+ *
+ * When explicit `configured` args are supplied they REPLACE the platform
+ * defaults entirely, giving deployments full control over shell startup.
+ */
+export declare function shellSpawnArgs(configured?: string[]): string[];

package/lib/types/tools.d.ts

@@ -0,0 +1,34 @@
+import type { Context } from './context-types.ts';
+import { AgentPtyRegistry } from './agent-pty.ts';
+/**
+ * Bound a string to a byte limit, marking truncation. Truncation never
+ * splits a multi-byte UTF-8 sequence: when the byte cap lands inside one,
+ * the walk-back retreats to the sequence's leading byte so the retained
+ * prefix decodes cleanly (a split would decode to U+FFFD).
+ * @internal exported for the unit tests, like {@link snapshotOf}.
+ */
+export declare function boundBytes(text: string, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * Register the eight terminal tools against the host tool registry. The
+ * `resolveCwd` callback threads the live session cwd (authoritative from the
+ * session store, falling back to the process cwd) so a freshly-created
+ * terminal lands in the right directory without the model passing it.
+ * Every uuid-keyed tool first asserts the terminal belongs to the calling
+ * session (`registry.assertOwned`), so one agent can never reach another
+ * session's terminals.
+ * @param ctx - host plugin context (carries the tools service).
+ * @param registry - the agent-owned terminal registry.
+ * @param resolveCwd - async cwd resolver for one session id. Resolves through
+ *  the session header, the client-supplied cwd, and the persistence index
+ *  before falling back to the host process cwd (production always provides
+ *  persistence, so the fallback is reached only in tests / stripped-down hosts).
+ * @returns a disposer that unregisters all eight tools (the caller gates
+ * registration on the side-card setting and calls this to turn them off).
+ */
+export declare function registerTools(ctx: Context, registry: AgentPtyRegistry, resolveCwd: (sessionId: string) => Promise<string>, readShellOverrides: () => {
+    shell?: string;
+    shellArgs?: string[];
+}): () => void;

package/lib/types/trust-fence.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Browser-trust fence for the sidebar routes, behaviorally identical to the
+ * /api gateway's fence in @deepseek-ai/dsh-client-connection
+ * (src/api-request-trust.ts + src/loopback-hostname.ts, BSD-3-Clause,
+ * copied here because the package does not export these helpers and the
+ * plugin must not depend on its internals). Host-header loopback or a
+ * configured trusted authority passes; cross-site browser markers refuse.
+ * This is a DNS-rebinding / cross-site defense, not authentication.
+ */
+import type { IncomingHttpHeaders } from 'node:http';
+/** The request facts the fence reads (structural subset of IncomingMessage). */
+interface ApiTrustRequest {
+    headers: IncomingHttpHeaders;
+}
+/** Whether a normalized URL hostname names the local loopback authority. */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/**
+ * Decide whether one sidebar request may reach the plugin routes.
+ * @param request - node HTTP request facts (headers).
+ * @param trustedHosts - non-loopback authorities this deployment serves.
+ * @returns true when the Host is ours (loopback or trusted) and browser markers are same-origin.
+ */
+export declare function isTrustedApiRequest(request: ApiTrustRequest, trustedHosts: readonly string[]): boolean;
+export {};

package/lib/types/ui-tweaks/archive.d.ts

@@ -0,0 +1,71 @@
+/**
+ * dsh-ui-tweaks — archive manager (host half).
+ *
+ * The browser Archive manager (the "归档" settings section, shown when the
+ * archiveManagerEnabled setting is on) lists archived sessions and offers
+ * two per-session actions plus batch actions through this same-origin route:
+ *
+ * - **restore** / **restore-all**: move a session out of the archive set. The
+ *   session log and its workspace accounting slot are kept untouched, so the
+ *   conversation reappears in the normal sidebar list.
+ * - **delete** / **delete-all**: PERMANENTLY delete a session — its durable
+ *   JSONL log is removed from disk, it is detached from every workspace's
+ *   accounting, removed from the archive set, dropped from the workspace
+ *   registry's in-memory header index, and best-effort-cleaned from the
+ *   session projection cache. Only a genuinely RUNNING agent is refused;
+ *   opened-but-idle sessions are also removed from the in-memory SessionStore
+ *   so they vanish from the live list immediately (the host relays
+ *   `session/disposed` as `host/session-removed`).
+ *
+ * DSH has no public API for either operation. The archive set lives in the
+ * `workspace` storage domain's global singleton (the same record
+ * `WorkspaceRegistry` keeps in memory), so this backend writes the filtered
+ * set through the live domain handle (`ctx.storageDomain.get('workspace')`)
+ * and keeps the registry's in-memory cache coherent in the same write, so the
+ * registry's next mutation cannot resurrect a restored id. Session-log
+ * deletion uses the persistence backend's own locator (`findLog`) so only the
+ * exact encoded session directory is removed; workspace accounting removal
+ * uses the registry's public `WorkspaceEntity.detachSession`.
+ * @module dsh-ui-tweaks/archive
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+/** Exact route used by the browser Archive panel. */
+export declare const ARCHIVE_ROUTE = "/_dsh/ui-tweaks/archive";
+/** Public Archive snapshot. Only session ids cross this boundary — the browser
+ * enriches them with titles / paths from its own session list feed. */
+export interface ArchiveSnapshot {
+    archivedSessionIds: string[];
+}
+/** A live session was targeted by a permanent delete. */
+export declare class SessionLiveError extends Error {
+    readonly code = "session-live";
+    constructor();
+}
+/** Same-origin Archive read/write handler. */
+export declare class ArchiveBackend {
+    private readonly ctx;
+    constructor(ctx: Context);
+    private registry;
+    private storageDomain;
+    private snapshot;
+    /** Remove one (or all) ids from the durable archive set, syncing the
+     * registry's in-memory cache in the same write. */
+    private writeArchiveSet;
+    /** Restore one session: remove it from the durable archive set. */
+    private restore;
+    /** Restore every archived session at once. */
+    private restoreAll;
+    /** Permanently delete one session: log, accounting, archive set, and caches. */
+    private deleteSession;
+    /** Permanently delete every archived session (live ones are skipped). */
+    private deleteAll;
+    /** Handle the exact Archive route. */
+    handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+}
+/**
+ * Attach the Archive route whenever a webServer service is present.
+ * @param ctx - plugin context owning route effects.
+ * @param backend - Archive handler.
+ */
+export declare function installArchiveWeb(ctx: Context, backend: ArchiveBackend): void;