dsh-better-sidebar 0.10.0

package/lib/types/client/subagent-jobs.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Pure derivations for the Subagent page's background-job section. Kept
+ * framework-free so the node test environment can unit-test them: the job
+ * rows arrive through the harness `session/jobs` push mirror
+ * (`jobsBySession` in the sessions list feed) — nothing here issues
+ * requests, and the row ordering / status mapping mirror the official
+ * ui-jobs header list.
+ */
+import type { SidebarSessionList, SidebarJobStatus, SidebarJobView } from '../context-types.ts';
+import type { CopyKey } from './locales.ts';
+/** One row of the jobs section: the job plus its owning session's title. */
+export interface TreeJob {
+    ownerSessionId: string;
+    ownerTitle: string;
+    job: SidebarJobView;
+}
+/** Whether the registry still holds the job open (its duration ticks). */
+export declare function isJobLive(job: SidebarJobView): boolean;
+/**
+ * Every session id of the topology tree rooted at `rootId` (the root plus
+ * each session whose uninterrupted subagent-origin chain reaches it — same
+ * lineage semantics as {@link countSubagentDescendants}; cycles fail soft).
+ * Sessions outside the tree (orphans, other trees) are excluded, so the
+ * jobs section never shows foreign work.
+ */
+export declare function treeSessionIds(byId: SidebarSessionList['byId'], rootId: string | undefined): Set<string>;
+/**
+ * Whether a NEW background job appeared for one session between two
+ * consecutive list snapshots (a job id the previous snapshot lacked).
+ * Unlike the subagent auto-open (0 → N only), ANY new job id triggers: the
+ * agent may start several jobs over a session, and each new one should
+ * surface the Jobs page (a fresh page load never triggers — its baseline
+ * starts at the current snapshot).
+ */
+export declare function detectNewJob(prev: SidebarSessionList, next: SidebarSessionList, sessionId: string): boolean;
+/**
+ * Collect the background jobs of the whole current tree, owner-labeled.
+ * Sessions without a mirror entry contribute nothing; an absent mirror
+ * (runtime older than the jobs feed) yields an empty list.
+ */
+export declare function collectTreeJobs(byId: SidebarSessionList['byId'], jobsBySession: Readonly<Record<string, readonly SidebarJobView[]>> | undefined, rootId: string | undefined): TreeJob[];
+/**
+ * Live rows first in start order, then settled rows newest-first (mirror of
+ * the official ui-jobs ordering); a tie falls back to start order so the
+ * sort never depends on the host's map iteration.
+ */
+export declare function orderJobs(rows: readonly TreeJob[]): TreeJob[];
+/** The sidebar's StateDot states for the five wire statuses. */
+export type JobDotState = 'ongoing' | 'warning' | 'done' | 'error';
+/**
+ * Status marker semantics. `stopping` and `killed` share the attention
+ * color: both mean the work ended (or is ending) on request rather than on
+ * its own.
+ */
+export declare function jobDotState(status: SidebarJobStatus): JobDotState;
+/** Human status word of one wire status (localized through the passed translator). */
+export declare function jobStatusLabel(status: SidebarJobStatus, t: (key: CopyKey, params?: Record<string, string | number>) => string): string;
+/**
+ * Elapsed time in at most two adjacent units (mirror of the official
+ * ui-jobs duration wording). A background job that outlives an hour is
+ * already exceptional, so hours is the widest unit.
+ */
+export declare function formatJobDuration(elapsedMs: number, t: (key: CopyKey, params?: Record<string, string | number>) => string): string;

package/lib/types/client/theme.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Live theme access for surfaces that cannot consume the token colors
+ * directly — xterm's palette and CodeMirror's theme extensions need concrete
+ * values, but the app's scheme flips at runtime (ui-layout's ThemePresenter
+ * projects prefers-color-scheme and the user's choice onto
+ * body[data-ds-dark-theme] and html { color-scheme }). This module reads the
+ * resolved scheme and token values, and notifies subscribers on flips, so
+ * the terminal and the editor re-theme in place instead of freezing in the
+ * scheme they happened to be created under.
+ */
+/** Whether the app shell resolved to the dark scheme.
+ *
+ * The presenter sets `html { color-scheme }` together with the body palette
+ * attribute, so a set color-scheme means the decision is authoritative (an
+ * absent attribute is then LIGHT even when the OS prefers dark — the user
+ * chose light). Before the presenter has run, fall back to the OS media
+ * query as the best guess.
+ */
+export declare function isDarkScheme(): boolean;
+/** One token's computed value on <body> ('' while the theme has not applied). */
+export declare function tokenValue(name: string): string;
+/**
+ * Subscribe to color-scheme flips (the presenter toggles the body
+ * attribute). The callback fires after the attribute changed; re-read the
+ * scheme inside it.
+ * @returns the disposer.
+ */
+export declare function subscribeColorScheme(callback: () => void): () => void;

package/lib/types/client/xlsx-to-univer.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Convert a SheetJS (xlsx) workbook into Univer's {@link IWorkbookData} so
+ * {@link XlsxView} can render it through the Univer sheets preset.
+ *
+ * v1 scope (matches docs/plans/2026-08-10-office-preview-design.md §3.6):
+ * - Sheet names + order
+ * - Cell values, typed (string / number / boolean / error → force-string)
+ * - Cell formulas (text form; Univer's formula engine computes them)
+ * - Merged cells (!merges → mergeData)
+ * - Column widths (!cols → columnData) and row heights (!rows → rowData)
+ *
+ * Out of scope for v1 (SheetJS community edition does not parse them and the
+ * Pro edition is commercial): cell styles (font/fill/border/alignment),
+ * conditional formatting, charts. Users who need style fidelity get the
+ * download button on the binary placeholder.
+ *
+ * The function is pure (no DOM, no Univer imports) so it is unit-testable
+ * without jsdom or canvas.
+ */
+import type * as XLSX from 'xlsx';
+import { type LocaleType, type IWorkbookData } from '@univerjs/presets';
+/** SheetJS workbook (the slice of the module we use). */
+type XLSXWorkbook = XLSX.WorkBook;
+/**
+ * Build a Univer workbook snapshot from a SheetJS workbook.
+ *
+ * @param wb - the parsed workbook from `XLSX.read(buf, { type: 'array' })`
+ * @param appVersion - the Univer package version, written into `appVersion`
+ *   (Univer requires the field but does not gate on it).
+ * @param locale - the locale Univer should render in.
+ */
+export declare function xlsxWorkbookToUniver(wb: XLSXWorkbook, appVersion: string, locale: LocaleType): IWorkbookData;
+export {};

package/lib/types/client/xlsx-view.d.ts

@@ -0,0 +1,10 @@
+import { type OfficeViewProps } from './office-shared.tsx';
+import '@univerjs/preset-sheets-core/lib/index.css';
+/**
+ * Render a .xlsx file via Univer. The sheets preset creates a canvas-based
+ * spreadsheet (formula bar, sheet tabs, formula engine) sized to its
+ * container, so the host fills the pane. Unmounting calls `univer.dispose()`
+ * — without it the canvas, workers, and DOM listeners leak (mirrors the
+ * xterm dispose discipline in TerminalView).
+ */
+export declare function XlsxView(props: OfficeViewProps): JSX.Element;

package/lib/types/config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Serializable configuration and defaults for the sidebar host half. Loader
+ * schema validation normally fills defaults; {@link resolveSidebarConfig}
+ * applies the same defaults for direct callers that bypass the Loader.
+ * @module dsh-better-sidebar/config
+ */
+import z from 'schemastery';
+import { type SidebarPrefs } from './prefs-shared.ts';
+export { SIDEBAR_PREFS_DEFAULTS, SIDEBAR_PREFS_NS, WIDTH_PERCENT_DEFAULT, WIDTH_PERCENT_MAX, WIDTH_PERCENT_MIN, type SidebarPrefs, } from './prefs-shared.ts';
+/** Tunable sidebar host limits (every field optional; defaults fill in). */
+export interface SidebarConfig {
+    /** Read cap of one text file (bytes); larger files return truncated. */
+    readLimit?: number;
+    /** Media route cap (bytes); larger binaries are refused. */
+    mediaLimit?: number;
+    /** Explorer row bound of one level. */
+    listLimit?: number;
+    /** Terminals per session. */
+    terminalsPerSession?: number;
+    /** How long a disconnected terminal process survives awaiting a reconnect. */
+    reconnectGraceMs?: number;
+}
+/** Schemastery schema for the plugin configuration. */
+export declare const Config: z<SidebarConfig>;
+/** Fully defaulted sidebar host settings. */
+export interface ResolvedSidebarConfig {
+    readLimit: number;
+    mediaLimit: number;
+    listLimit: number;
+    terminalsPerSession: number;
+    reconnectGraceMs: number;
+}
+/**
+ * Apply direct-call defaults after Loader schema validation has normally run.
+ *
+ * @param config - Deployment-provided sidebar host settings.
+ * @returns Complete settings consumed by the host half.
+ */
+export declare function resolveSidebarConfig(config: SidebarConfig | undefined): ResolvedSidebarConfig;
+/** Schemastery schema for the user-facing preferences (validated by the settings service). */
+export declare const PrefsSchema: z<SidebarPrefs>;

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

@@ -0,0 +1,431 @@
+/**
+ * Structural types for the cordis services this plugin consumes, plus the
+ * Context augmentation both halves share. A third-party plugin resolves
+ * outside the DSH monorepo's single cordis instance, so the upstream
+ * `declare module 'cordis'` augmentations do not reach this Context — and
+ * the npm cordis package does not declare the DSH-vendored runtime members
+ * (`ctx.effect`, service properties). The members below mirror the actual
+ * runtime shapes this plugin touches:
+ * - webServer: @deepseek-ai/dsh-host-webserver (the WebServer)
+ * - sessions: host side @deepseek-ai/dsh-session (SessionStore), client
+ *   side the runtime ISessions list feed
+ * - conversation: client side ui-conversation's IConversation (composer
+ *   draft), read lazily through `ctx.get` — cross-plugin service reads need
+ *   an inject declaration, so the direct property is never typed here
+ * - loader: @cordisjs/plugin-loader (entry options)
+ * - slots: the client runtime SlotRegistry
+ * - effect: the DSH-vendored cordis lifecycle helper
+ * Drift from upstream is contained to this file.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Duplex } from 'node:stream';
+import type { Context } from 'cordis';
+import type { BetterSidebarService } from './client/service.ts';
+/** One named webserver route (mirror of the host-webserver WebRoute). */
+export interface SidebarWebRoute {
+    kind: 'exact' | 'prefix';
+    path: string;
+    handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+}
+/** One exact-path HTTP upgrade registration (mirror of WebUpgradeRoute). */
+export interface SidebarWebUpgradeRoute {
+    path: string;
+    handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>;
+}
+/** The webServer service face this plugin uses. */
+export interface SidebarWebServer {
+    register(route: SidebarWebRoute): () => void;
+    registerUpgrade(route: SidebarWebUpgradeRoute): () => void;
+}
+/** A published session's header slice the sidebar reads (authoritative cwd). */
+export interface SidebarSessionHeader {
+    cwd?: string;
+}
+/** The host session store face (`ctx.sessions.get(id)` returns the live session). */
+export interface SidebarSessionStore {
+    get(id: string): {
+        header: SidebarSessionHeader;
+        /**
+         * The live session's append-only event log (immutable snapshot; absent
+         * on sessions the runtime has not hydrated). Read-only access — the
+         * jobs.output route replays `job_output` tool/result rows from it.
+         */
+        events?: readonly SidebarSessionEvent[];
+    } | undefined;
+}
+/** One loader entry's options slice (the connection row's resolved config). */
+export interface SidebarLoaderEntry {
+    options: {
+        name: string;
+        config?: unknown;
+    };
+}
+/** The loader face used to read the connection row's trustedHosts config. */
+export interface SidebarLoader {
+    entries(): Iterable<SidebarLoaderEntry>;
+}
+/** Registration options the sidebar passes to `ctx.slots.register` (subset of the real options). */
+export interface SidebarSlotRegisterOptions {
+    name: string;
+    key?: string;
+    id?: string;
+    order?: number;
+    label?: string | (() => string);
+    /** Chain routing selector (returns the matched value, or null to pass on). */
+    select?: (owner: unknown) => unknown;
+    priority?: number;
+    locale?: string;
+    registrant?: string;
+    /** Business-face factory; args depend on the slot scope. */
+    inject?: (...args: any[]) => Record<string, unknown>;
+    children?: Record<string, unknown>;
+}
+/** The client slots service face (register returns the disposer). */
+export interface SidebarSlotsService {
+    register(options: SidebarSlotRegisterOptions, component: unknown): () => void;
+    /**
+     * Run a callback for each declaration lifetime of a slot (the runtime
+     * SlotRegistry.inject): a no-op while the slot is undeclared, so the
+     * settings section registration waits for the settings shell.
+     */
+    inject(key: string, callback: () => () => void): () => void;
+}
+/** The client session list row the sidebar reads (cwd for the explorer). */
+export interface SidebarSessionSummary {
+    id: string;
+    cwd?: string;
+    displayTitle: string;
+    /** Coarse durable origin for navigation filtering (subagent children). */
+    origin?: 'subagent';
+    /** Durable direct parent session id (present on subagent children). */
+    parentId?: string;
+    /** Whether the session's agent is currently running. */
+    running?: boolean;
+}
+/** One healthy subagent catalog child row (structural mirror of the runtime). */
+export interface SidebarSubagentChildEntry {
+    kind: 'child';
+    id: string;
+    /** Whether the child Agent driver is running at the Host sampling boundary. */
+    activity: 'running' | 'inactive';
+    /** Whether a direct descendant has durable `origin: 'subagent'`. */
+    hasChildren: boolean;
+    mode: 'one-shot' | 'continuable';
+    label?: string;
+}
+/** One unreadable catalog row (corrupt / unsupported / unavailable). */
+export interface SidebarSubagentDiagnosticEntry {
+    kind: 'diagnostic';
+    id: string;
+    reason: 'corrupt' | 'unsupported' | 'unavailable';
+}
+/** The per-parent lazy catalog delivered through the sessions list feed. */
+export interface SidebarSubagentCatalog {
+    entries: Array<SidebarSubagentChildEntry | SidebarSubagentDiagnosticEntry>;
+    parentAvailable: boolean;
+    state: 'loading' | 'ready' | 'error';
+    error: {
+        code?: string;
+        message?: string;
+    } | null;
+}
+/** Durable parent/child address that selects subagent transport in the client. */
+export interface SidebarSubagentAddress {
+    parentSessionId: string;
+    childSessionId: string;
+    mode: 'one-shot' | 'continuable';
+}
+/** Minimal structural mirror of one session event (the subagent history tail). */
+export interface SidebarSessionEvent {
+    type: string;
+    seq: number;
+    time: number;
+    data: Record<string, unknown>;
+}
+/** One history row: the durable event plus an optional tool presentation view. */
+export interface SidebarHistoryEntry {
+    event: SidebarSessionEvent;
+    view?: unknown;
+}
+/** Lifecycle status set of one background job (closed wire union). */
+export type SidebarJobStatus = 'running' | 'stopping' | 'completed' | 'killed' | 'failed';
+/**
+ * One background job as the client mirror sees it (wire `JobView` shape:
+ * id/kind/label/status/detail?/startedAt/finishedAt?).
+ */
+export interface SidebarJobView {
+    /** Registry-issued `<kind>-N` identity, stable for the job's whole life. */
+    id: string;
+    /** Producer kind (`bash`, `pwsh`, `subagent`, …; open string by design). */
+    kind: string;
+    /** Producer-supplied one-line label: the command, or the delegation description. */
+    label: string;
+    /** Current lifecycle state. */
+    status: SidebarJobStatus;
+    /** Kind-specific status detail ('exit code: 3'), present once supplied. */
+    detail?: string;
+    /** Epoch ms when the job was registered. */
+    startedAt: number;
+    /** Epoch ms when the job settled; absent while live. */
+    finishedAt?: number;
+}
+/** The host jobs registry face the sidebar routes touch (structural mirror of `JobRegistry`). */
+export interface SidebarJobsService {
+    /** Request cancellation; throws for an unknown or foreign job. */
+    kill(id: string, caller?: SidebarAgent, reason?: string): 'requested' | 'already-finished';
+}
+/** The host agent registry face (structural mirror of the runtime `ctx.agents`). */
+export interface SidebarAgentsService {
+    /** The live agent registered under a session id, or undefined when not live. */
+    get(id: string): SidebarAgent | undefined;
+}
+/** RPC result slot mirror (`RpcResult<T>` on the wire). */
+export type SidebarRpcResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/** Unary response mirror (`RpcResponse<T>` on the wire). */
+export interface SidebarRpcResponse<T> {
+    rpcId: unknown;
+    result: SidebarRpcResult<T>;
+}
+/** The wire face the Subagent activity summary needs (subset of `ctx.connection`). */
+export interface SidebarConnectionHandle {
+    api: {
+        subagents: {
+            history(payload: SidebarSubagentAddress & {
+                beforeSeq?: number;
+                maxMessages?: number;
+            }, signal?: AbortSignal): Promise<SidebarRpcResponse<{
+                events: SidebarHistoryEntry[];
+                hasMore: boolean;
+            }>>;
+        };
+    };
+}
+/** The client session list snapshot the sidebar subscribes to. */
+export interface SidebarSessionList {
+    current: string | undefined;
+    byId: Record<string, SidebarSessionSummary>;
+    /** Direct durable catalogs keyed by their selected parent address. */
+    subagentsByParent?: Readonly<Record<string, SidebarSubagentCatalog>>;
+    /**
+     * Background jobs per session, last-wins from the harness's `session/jobs`
+     * push (a missing key is an empty set). Absent on runtime snapshots older
+     * than the jobs mirror — the sidebar simply shows no job rows.
+     */
+    jobsBySession?: Readonly<Record<string, readonly SidebarJobView[]>>;
+}
+/** The client sessions service face (only the list feed is needed). */
+export interface SidebarSessionsService {
+    list: {
+        getSnapshot(): SidebarSessionList;
+        subscribe(fn: () => void): () => void;
+    };
+    /**
+     * Select a listed session as current (mirror of the runtime ISessions.open)
+     * — used to jump back to the main agent from the topology root node.
+     */
+    open?(id: string): void;
+    /**
+     * Resolve an Agent-scoped context view for one session (mirror of the
+     * runtime ISessions.scope) — the ticket `ctx.conversation.input.for`
+     * requires to reach that session's composer.
+     */
+    scope(id: string): Context | undefined;
+    /**
+     * Open a healthy catalog child through its exact direct-parent address
+     * (mirror of the runtime ISessions.openSubagent).
+     */
+    openSubagent?(address: SidebarSubagentAddress): void;
+    /**
+     * Resolve an already discovered direct-parent address without opening it.
+     */
+    subagentAddress?(id: string): SidebarSubagentAddress | undefined;
+    /**
+     * Mark whether a catalog surface is consuming live membership updates.
+     */
+    setSubagentCatalogOpen?(parentSessionId: string, open: boolean): void;
+    /**
+     * Refresh one direct-child catalog.
+     */
+    refreshSubagents?(parentSessionId: string): Promise<void>;
+}
+/**
+ * The client locale service face (mirror of @deepseek-ai/dsh-client-locale's
+ * LocaleRuntime — only the slices the sidebar touches). The sidebar follows
+ * the DSH i18n system: the active locale is the Host-backed preference
+ * (`locale.preference` in settings.yaml) rather than the raw browser
+ * language, and the sidebar's zh/en dictionaries register into the service's
+ * namespace registry under `betterSidebar`.
+ */
+export interface SidebarLocaleService {
+    /** Current immutable locale snapshot (uSES-safe; `active` is 'zh' | 'en' today). */
+    getSnapshot(): {
+        active: string;
+    };
+    /** Subscribe to snapshot changes (locale switch or dictionary registration). */
+    subscribe(fn: () => void): () => void;
+    /** Register one locale's dictionary for a namespace; returns the disposer. */
+    register(ns: string, locale: string, dict: Record<string, string>): () => void;
+}
+/** The composer draft face the sidebar reaches through `ctx.conversation.input`. */
+export interface SidebarSessionInput {
+    /** The live input store (draft read for append). */
+    state: {
+        getSnapshot(): {
+            draft: string;
+        };
+    };
+    /** Replace the draft text (the input machine's single public write path). */
+    setDraft(text: string): void;
+}
+/** The composer draft face the sidebar reaches through `ctx.get('conversation')`. */
+export interface SidebarConversation {
+    input: {
+        for(actx: Context): SidebarSessionInput;
+    };
+}
+/**
+ * The client workspaces service face (mirror of the runtime IWorkspaces). Only
+ * the chat's file-open funnel is touched: `openPath` hands an absolute path
+ * to the Host OS's default application, and every chat-side file open
+ * (tool rows, produced-files, prose mentions) funnels through it.
+ */
+export interface SidebarWorkspacesService {
+    /** Open a filesystem path with the Host operating system's default application. */
+    openPath(path: string): Promise<void>;
+}
+/**
+ * The invariant service face (mirror of @deepseek-ai/dsh-invariants'
+ * InvariantRegistry). The upstream augmentation does not reach this Context
+ * (dual-cordis-instance resolution), so the register signature is restated
+ * structurally, exactly like the other service faces above.
+ */
+export interface SidebarInvariantsService {
+    /** Reserve one package's checks and install them in the service's child fiber. */
+    register(packageName: string, installer: (ctx: Context, fail: (message: string) => never) => void | Promise<void>): () => void;
+}
+/** The settings service face (mirror of @deepseek-ai/dsh-settings' SettingsProvider). */
+export interface SidebarSettingsService {
+    /**
+     * Register one namespace schema (the resolved value layers schema defaults,
+     * then the composition base, then the user document).
+     */
+    register<T>(ns: string, schema: unknown, options?: {
+        base?: Partial<T>;
+        applies?: 'live' | 'restart';
+    }): {
+        get(): T;
+        watch(callback: (next: T, prev: T) => void | Promise<void>): () => void;
+        update(patch: object): Promise<void>;
+        replace(section: object): Promise<void>;
+    };
+    /** Redacted descriptors of every registered namespace (secrets stripped). */
+    describe(options?: {
+        redactSecrets?: boolean;
+    }): Array<{
+        ns: string;
+        value?: unknown;
+        base?: unknown;
+        user?: unknown;
+        applies: 'live' | 'restart';
+        revision: number;
+    }>;
+    /** Service-level merge write with the revision guard (a stale writer is refused). */
+    update(ns: string, patch: object, expectedRevision?: number): Promise<void>;
+}
+/**
+ * The tools service face (mirror of @deepseek-ai/dsh-tools' ToolRuntime).
+ * The host half registers model-facing tools here; the registry attaches the
+ * returned disposer to the contributing fiber so unloading unregisters them.
+ */
+export interface SidebarToolsService {
+    /** Register one tool definition (raw JSON-Schema or defineTool-sugar form). */
+    register(tool: unknown): () => void;
+}
+/**
+ * The agent face a tool sees on `exec.agent` (mirror of @deepseek-ai/dsh-agent's
+ * Agent). Only the slices the terminal tools touch are restated: the live
+ * session identity and its header cwd, both readonly.
+ */
+export interface SidebarAgent {
+    /** The live session identity shared with the session log. */
+    readonly id: string;
+    /** The live session this agent drives. */
+    readonly session: {
+        /** The session's header (validated cwd, lineage metadata). */
+        readonly header: {
+            readonly cwd?: string;
+        };
+    };
+}
+declare module 'cordis' {
+    interface Context {
+        webServer: SidebarWebServer;
+        sessions: SidebarSessionStore & SidebarSessionsService;
+        connection: SidebarConnectionHandle;
+        loader: SidebarLoader;
+        slots: SidebarSlotsService;
+        workspaces: SidebarWorkspacesService;
+        settings: SidebarSettingsService;
+        invariants: SidebarInvariantsService;
+        tools: SidebarToolsService;
+        /**
+         * The client locale service (`@deepseek-ai/dsh-client-locale`): the
+         * sidebar's copy follows its active locale and registers its
+         * dictionaries under the `betterSidebar` namespace. Client side only.
+         */
+        locale: SidebarLocaleService;
+        /**
+         * The host background-job registry (`ctx.get('jobs')`; optional — the
+         * sidebar routes degrade to a 503 when the deployment lacks it).
+         */
+        jobs: SidebarJobsService;
+        /**
+         * The host live-agent registry (`ctx.get('agents')`; optional — used to
+         * resolve the caller the jobs fence compares against).
+         */
+        agents: SidebarAgentsService;
+        /**
+         * The client-side sidebar registry: external plugins register tab types
+         * and file previewers here. Provided by the client half (see
+         * {@link ./client/index.tsx}); undefined on the host side.
+         */
+        betterSidebar: BetterSidebarService;
+        /**
+         * Subscribe to the session append feed (mirror of the cordis event API):
+         * the listener receives every appended session event with the LIVE
+         * Session instance that appended it. The api-proxy pushes the same feed
+         * to browsers; the sidebar uses it to mirror job_output events the
+         * session store's own log can lag behind (restart divergence). Returns
+         * the disposer.
+         */
+        on(event: string, listener: (session: unknown, event: SidebarSessionEvent) => void): () => void;
+        /**
+         * Register a lifecycle callback (DSH-vendored cordis): runs at plugin
+         * activation; its returned cleanup runs at disposal.
+         */
+        effect(fn: () => void | (() => void), label?: string): void;
+    }
+}
+/**
+ * Dual cordis-scope augmentation: DSH's runtime (and the public packages)
+ * resolve against the vendored `@deepseek-ai/cordis` scope, which DSH's own
+ * packages already augment with `effect`/`on`/service members. This side only
+ * adds the sidebar service member so consumers importing `Context` from
+ * `@deepseek-ai/cordis` (instead of the public `cordis` above) still see
+ * `ctx.betterSidebar`.
+ */
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        betterSidebar: BetterSidebarService;
+    }
+}
+export type { Context };

package/lib/types/fs-tree.d.ts

@@ -0,0 +1,41 @@
+/** One explorer row. */
+export interface SidebarFsEntry {
+    name: string;
+    path: string;
+    isDir: boolean;
+    hidden: boolean;
+}
+/** One listed level. */
+export interface SidebarFsListing {
+    path: string;
+    entries: SidebarFsEntry[];
+    truncated: boolean;
+}
+/** Directory-first, case-insensitive name ordering (VSCode explorer order). */
+export declare function compareEntries(a: SidebarFsEntry, b: SidebarFsEntry): number;
+/**
+ * List one directory level.
+ * @param path - absolute directory path.
+ * @param maxEntries - row bound of one level (extra rows flag `truncated`).
+ * @returns the sorted listing.
+ * @throws {SidebarError} fs-error when the level is unreadable or not a directory.
+ */
+export declare function listDirectory(path: string, maxEntries?: number): Promise<SidebarFsListing>;
+/** The root row label of a listing: the last path segment (or the full path at the filesystem root). */
+export declare function rootLabel(path: string): string;
+/** Parent of a path, or undefined at the filesystem root (the explorer's "up" target). */
+export declare function parentOf(path: string): string | undefined;
+/** Normalize a caller-supplied path to an absolute, resolved path or throw fs-error. */
+export declare function requireAbsolute(path: string): string;
+/**
+ * Whether `target` lies under `base` (or equals it), tolerant of separator
+ * style and — on Windows, where the filesystem is case-insensitive — of
+ * letter case. The media route uses this instead of a raw `startsWith` so a
+ * case-mismatched or mixed-separator path can never be misclassified
+ * (e.g. `C:\Users\Me` vs `c:/users/me/file.png`).
+ * @param platform - filesystem semantics; injectable so both branches are
+ * unit-testable on any host.
+ */
+export declare function isWithin(base: string, target: string, platform?: NodeJS.Platform): boolean;
+/** Message text of an unknown thrown value. */
+export declare function messageOf(error: unknown): string;