dsh-better-sidebar 0.10.0

package/src/client/xlsx-view.tsx

@@ -0,0 +1,116 @@
+/**
+ * The .xlsx preview component: renders via the Univer sheets preset (data +
+ * formulas + formatting). Lives in its own module (split out of the former
+ * office-view.tsx) so it builds as a standalone lazy chunk
+ * (`lib/client-xlsx.js`) — the Univer family and SheetJS pull in several MB
+ * but are loaded only when a .xlsx is first opened. The docx stack never
+ * shares this script.
+ *
+ * Errors degrade to the shared download-button affordance, so a corrupted /
+ * encrypted / oversized file always leaves the user with a way to get it.
+ */
+import { useEffect, useRef, useState } from 'react'
+import { mediaUrl } from './api.ts'
+import { isZh, t } from './locales.ts'
+import { BinaryFallback, type LoadState, type OfficeViewProps } from './office-shared.tsx'
+import { xlsxWorkbookToUniver } from './xlsx-to-univer.ts'
+import css from './sidebar.module.css'
+// Univer's stylesheets ride the same dsh-css-inline pipeline as xterm's CSS
+// (one <style data-plugin-css> tag, idempotent). Static import so the styles
+// are present before the first .xlsx opens.
+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 function XlsxView(props: OfficeViewProps): JSX.Element {
+  const { scope, path, title } = props
+  const hostRef = useRef<HTMLDivElement>(null)
+  const univerRef = useRef<{ dispose: () => void } | null>(null)
+  const [load, setLoad] = useState<LoadState>({ status: 'loading' })
+
+  useEffect(() => {
+    let cancelled = false
+    const host = hostRef.current
+    if (host === null) return
+    void (async () => {
+      try {
+        const response = await fetch(mediaUrl(scope, path))
+        if (cancelled) return
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}`)
+        }
+        const buf = await response.arrayBuffer()
+        if (cancelled) return
+
+        // Dynamic imports — collapsed into the chunk by codeSplitting:false.
+        // The dynamic form keeps the source readable: each lib is only pulled
+        // in when an .xlsx is actually opened (semantically; the chunk still
+        // contains all of them — the chunk itself only loads on first .xlsx).
+        const XLSX = await import('xlsx')
+        const { createUniver, LocaleType, mergeLocales } = await import('@univerjs/presets')
+        const { UniverSheetsCorePreset } = await import('@univerjs/preset-sheets-core')
+        // Locales follow the DSH i18n system (the active locale); falls
+        // back to the browser language, then en-US.
+        const localePack = await (isZh()
+          ? import('@univerjs/preset-sheets-core/locales/zh-CN').then(m => m.default).catch(() => null)
+          : import('@univerjs/preset-sheets-core/locales/en-US').then(m => m.default).catch(() => null))
+
+        const wb = XLSX.read(buf, { type: 'array' })
+        const locale = isZh() ? LocaleType.ZH_CN : LocaleType.EN_US
+        const workbookData = xlsxWorkbookToUniver(wb, '0.25.1', locale)
+
+        if (cancelled) return
+        const { univer, univerAPI } = createUniver({
+          locale,
+          locales: localePack !== null ? { [locale]: mergeLocales(localePack) } : {},
+          presets: [UniverSheetsCorePreset({ container: host })],
+        })
+        univerRef.current = univer
+        univerAPI.createWorkbook(workbookData)
+        if (!cancelled) setLoad({ status: 'ready' })
+      } catch (error) {
+        if (!cancelled) {
+          try {
+            univerRef.current?.dispose()
+          } catch {
+            // Partially initialized instance — ignore disposal errors.
+          }
+          univerRef.current = null
+          host.innerHTML = ''
+          setLoad({ status: 'error', message: error instanceof Error ? error.message : String(error) })
+        }
+      }
+    })()
+    return () => {
+      cancelled = true
+      // Critical: dispose the Univer instance (canvas + workers + listeners).
+      try {
+        univerRef.current?.dispose()
+      } catch {
+        // Already torn down — ignore.
+      }
+      univerRef.current = null
+      // Clear the host in case dispose left DOM behind.
+      if (host !== null) host.innerHTML = ''
+    }
+  }, [scope.sessionId, scope.cwd, path])
+
+  return (
+    <div className={css.editorXlsx} aria-label={title}>
+      {/* Univer exclusively owns this element's descendants. React only owns
+          the sibling overlay, so Univer cannot remove a React child. */}
+      <div className={css.editorUniverHost} ref={hostRef} />
+      {load.status !== 'ready' && (
+        <div className={css.editorOfficeOverlay}>
+          {load.status === 'loading' && <div className={css.editorPlaceholder}>{t('loading')}</div>}
+          {load.status === 'error' && <BinaryFallback scope={scope} path={path} message={load.message} />}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/config.ts

@@ -0,0 +1,95 @@
+/**
+ * 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 {
+  SIDEBAR_PREFS_DEFAULTS,
+  SIDEBAR_PREFS_NS,
+  WIDTH_PERCENT_DEFAULT,
+  WIDTH_PERCENT_MAX,
+  WIDTH_PERCENT_MIN,
+  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 const Config: z<SidebarConfig> = z.object({
+  readLimit: z.number().step(1).min(1).default(512 * 1024),
+  mediaLimit: z.number().step(1).min(1).default(20 * 1024 * 1024),
+  listLimit: z.number().step(1).min(1).default(1000),
+  terminalsPerSession: z.number().step(1).min(1).default(3),
+  reconnectGraceMs: z.number().step(1).min(0).default(30_000),
+})
+
+/** 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 function resolveSidebarConfig(config: SidebarConfig | undefined): ResolvedSidebarConfig {
+  return {
+    readLimit: config?.readLimit ?? 512 * 1024,
+    mediaLimit: config?.mediaLimit ?? 20 * 1024 * 1024,
+    listLimit: config?.listLimit ?? 1000,
+    terminalsPerSession: config?.terminalsPerSession ?? 3,
+    reconnectGraceMs: config?.reconnectGraceMs ?? 30_000,
+  }
+}
+
+// ── User-facing "Side card" preferences ─────────────────────────────────────
+
+/** Schemastery schema for the user-facing preferences (validated by the settings service). */
+export const PrefsSchema: z<SidebarPrefs> = z.object({
+  openByDefault: z.boolean().default(true),
+  defaultWidthPercent: z.number().step(1).min(WIDTH_PERCENT_MIN).max(WIDTH_PERCENT_MAX).default(WIDTH_PERCENT_DEFAULT),
+  autoOpenSubagent: z.boolean().default(true),
+  autoOpenJobs: z.boolean().default(true),
+  agentTerminalTools: z.boolean().default(false),
+  bottomPanelAutoTerminal: z.boolean().default(true),
+  interceptOpenPath: z.boolean().default(true),
+  htmlViewerNoSandbox: z.boolean().default(false),
+  htmlViewerDefaultUnsafe: z.boolean().default(false),
+  browserNoSandbox: z.boolean().default(false),
+  browserInterceptLinks: z.boolean().default(true),
+  // Per-feature enable switches are OPEN maps (any tab/viewer id, built-in or
+  // external): an absent key means enabled, so old documents resolve to {}
+  // (everything on) with no migration. Non-boolean values fail validation.
+  tabsEnabled: z.dict(z.boolean()).default({}),
+  viewersEnabled: z.dict(z.boolean()).default({}),
+})

package/src/context-types.ts

@@ -0,0 +1,445 @@
+/**
+ * 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 }