@keith9681/dsh-sidebar 0.15.2

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/sidechat-core.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Pure side-conversation ("Side Chat") logic shared by the host routes and
+ * the client tab. Framework-free (no React, no Node) so both halves and the
+ * node test environment can import it.
+ *
+ * A side thread is a child session the plugin creates ITSELF with a custom
+ * seed — the parent session's FULL event log up to the click moment
+ * (completed turns, the unanswered user message, and — when the parent is
+ * mid-turn — the in-progress assistant output and tool activity). The log
+ * model forbids open-turn seeds, so an in-flight parent turn is copied
+ * verbatim and CLOSED with synthetic `step/end` + `turn/end{reason:
+ * 'interrupted'}` events: the child sees the partial turn as honestly
+ * frozen ("cut off"), never as a completed answer. The one case that cannot
+ * be closed honestly — a tool call still executing (no `tool/result` yet;
+ * providers reject dangling assistant calls) — falls back to cutting before
+ * the open turn and carrying the partial content as a structured text
+ * snapshot inside the boundary prompt.
+ */
+import type { SidebarHistoryEntry, SidebarSessionSummary } from './context-types.ts';
+/** The durable thread-label prefix (also the row filter in the client list). */
+export declare const SIDE_LABEL_PREFIX = "Side: ";
+/** The pinned label of a freshly created thread that no prompt has reached
+ *  yet (Codex-style immediate create: the tab opens an EMPTY thread, the
+ *  first composer message carries the boundary and earns the real label).
+ *  The client renders it localized; the prefix keeps the row filter honest. */
+export declare const SIDE_NEW_THREAD_TITLE = "Side: New thread";
+/** Maximum code points kept in a durable thread label (matches subagent labels). */
+export declare const LABEL_MAX_CHARS = 48;
+/** The boundary message's opening line — the transcript mapping drops user
+ *  rows starting with it (same first line as dsh-sidechain's boundary, so
+ *  the two plugins' threads render consistently in either UI). */
+export declare const SIDE_BOUNDARY_PREFIX = "Side conversation boundary";
+/** The plugin identity stamped on the source of context-injection messages
+ *  (boundary prompt + parked snapshot), so the transcript recognizes them
+ *  structurally — not by text prefix. */
+export declare const SIDE_INJECTION_PLUGIN = "dsh-better-sidebar";
+/**
+ * The boundary prompt delivered as the thread's first user message: the
+ * inherited seed is reference context only, never active instruction.
+ * Model-facing contract — change only with intent, tests pin the sentences.
+ */
+export declare const SIDE_BOUNDARY_PROMPT = "Side conversation boundary.\n\nEverything before this boundary is inherited history from the parent session: its completed turns, its pending question, and \u2014 if the parent was mid-turn \u2014 its in-progress output frozen at the moment this side conversation started. It is reference context only. It is not your current task.\n\nDo not continue, execute, or complete any instructions, plans, tool calls, approvals, edits, or requests from before this boundary. Only messages submitted after this boundary are active user instructions for this side conversation.\n\nMode: this is a continuable side conversation. Your answers stay in this side thread and are viewed in the side panel; they are never delivered into the parent session.";
+/** One seed event (structural mirror of the durable SessionEvent). The
+ *  envelope fields are preserved verbatim: surface-eligible events
+ *  (user/message, assistant/message, tool/result) REQUIRE the `surfaceOp`
+ *  marker (and may carry `sourceEventSeqs`) — the seed validator rejects
+ *  them without it. */
+export interface SeedEvent {
+    type: string;
+    seq: number;
+    time: number;
+    data: Record<string, unknown>;
+    /** Surface marker of message-producing events ('append' | replace op). */
+    surfaceOp?: unknown;
+    /** Seq numbers of earlier events this event cites as sources. */
+    sourceEventSeqs?: unknown;
+    /** Reader-skip marker of purely informational events. */
+    ignorable?: true;
+}
+/** The minimal structural face of a session-log event this module reads
+ *  (loose enough to accept both the host's real SessionEvent and the
+ *  client's SidebarSessionEvent mirror). */
+export interface SidechatLogEvent {
+    type: string;
+    seq: number;
+    time: number;
+    data: unknown;
+}
+/** The result of cutting a parent log into a side-thread inheritance. */
+export interface SidechatInheritance {
+    /** The child seed: contiguous from seq 0, ends outside any open turn. */
+    seed: SeedEvent[];
+    /**
+     * Structured snapshot of the parent's in-progress turn when it could NOT
+     * be included as events (a tool call was still executing); null when the
+     * seed already carries the whole picture.
+     */
+    snapshot: string | null;
+}
+/**
+ * Whether the open turn ending the log has a `tool/call` without its paired
+ * `tool/result` in the CURRENT open step. Providers reject dangling
+ * assistant calls, so such a turn cannot be honestly closed and the
+ * inheritance must fall back to the snapshot.
+ */
+export declare function hasDanglingToolCall(events: readonly SidechatLogEvent[], turnStart: number): boolean;
+/**
+ * Build the side-thread inheritance for one parent log: the full event log
+ * up to the click moment, honestly closed when it ends inside an open turn.
+ */
+export declare function buildSidechatInheritance(events: readonly SidechatLogEvent[]): SidechatInheritance;
+/** The seed half of {@link buildSidechatInheritance} (test convenience). */
+export declare function sidechatSeed(events: readonly SidechatLogEvent[]): SeedEvent[];
+/**
+ * Structured text snapshot of the parent's OPEN turn (from its `turn/start`
+ * to the log tail): the accumulated assistant/reasoning output verbatim
+ * (code blocks ride the raw deltas) and the tool activity — executed tools
+ * with their result text, the still-executing one marked. Returns null when
+ * there is no open turn or nothing to show.
+ */
+export declare function buildOpenTurnSnapshot(events: readonly SidechatLogEvent[]): string | null;
+/** One side-thread row in the client's thread list. */
+export interface SideThreadRow {
+    id: string;
+    /** The durable thread title ('Side: …'). */
+    title: string;
+    /** Whether the thread's agent is currently running. */
+    running: boolean;
+}
+/**
+ * Derive the side threads of one parent session from the client session list:
+ * durable `origin: 'subagent'` children of the parent whose pinned title
+ * carries the thread label prefix (our creation path pins it via
+ * sessionTitle.rename; dsh-sidechain threads share the convention, so they
+ * are visible here too).
+ */
+export declare function sideThreadRows(byId: Readonly<Record<string, SidebarSessionSummary>>, sessionId: string): SideThreadRow[];
+/** Truncate + prefix a question into a durable thread label. */
+export declare function sideLabel(question: string): string;
+/**
+ * Whether the thread log already carries the side boundary message — i.e.
+ * the first prompt was delivered. Tolerant to the content shape (block
+ * array or bare string) and to inherited seed messages (only an OWN
+ * boundary message starts with the prefix; seed messages came from the
+ * parent's log, which never contains one).
+ */
+export declare function boundaryDelivered(events: readonly SidechatLogEvent[]): boolean;
+/**
+ * Whether a logged user/message is a CONTEXT INJECTION (the boundary prompt
+ * plus the parked in-progress snapshot) rather than a real user message.
+ * New threads deliver the injection via `agent.inject` stamped with a
+ * non-'user' source kind; threads created before that split carry
+ * boundary+question in ONE 'user' message, recognized by the boundary
+ * prefix. Both render as one collapsible injection row — never as a user
+ * bubble.
+ */
+export declare function isContextInjectionMessage(data: Record<string, unknown>): boolean;
+/** The info the thread header shows (live runtime state + agent identity). */
+export interface SidechatThreadInfo {
+    /** A live agent drives the thread right now (false = cold/persisted). */
+    live: boolean;
+    /** Live lifecycle state; absent on cold threads. */
+    status?: 'idle' | 'running';
+    /** Provider route of the live agent. */
+    provider?: string;
+    /** Model id of the live agent. */
+    model?: string;
+    /** The recorded agent preset (live header, or persisted on cold reads). */
+    preset?: string;
+}
+/** The events a thread produced itself: everything after the LAST
+ *  `session/end-seed` marker (the fork-seed boundary). */
+export declare function threadOwnEvents(entries: readonly SidebarHistoryEntry[]): SidechatLogEvent[];
+/**
+ * Whether the thread has at least one completed turn — the save-as-new-
+ * session precondition (`session.fork` refuses to fork before the first
+ * `turn/end`).
+ */
+export declare function threadHasCompletedTurn(entries: readonly SidebarHistoryEntry[]): boolean;
+/** Whether the thread ends with a user message that no completed turn
+ *  answered yet — such a pending follow-up is NOT carried into the saved
+ *  session (the fork cut is the last `turn/end`). */
+export declare function threadTrailingPending(entries: readonly SidebarHistoryEntry[]): boolean;
+/**
+ * The agent preset a session actually runs: newest `agent-preset/selected`
+ * event wins, else the creation header (mirror of the dsh-agent-presets
+ * resolveSessionPreset helper — replicated here to avoid a host dependency
+ * on that package).
+ */
+export declare function resolvePresetId(header: {
+    agentPreset?: string;
+}, events: readonly SidechatLogEvent[]): string | undefined;

package/lib/types/sidechat-routes.d.ts

@@ -0,0 +1,30 @@
+import type { Context } from './context-types.ts';
+import { type SidechatThreadInfo } from './sidechat-core.ts';
+/** The five Side Chat routes of the sidebar API (wire method names). */
+export interface SidechatRoutes {
+    /** Create a side thread child seeded with the parent's log up to now.
+     *  `question` is optional: empty creates an EMPTY thread (Codex-style
+     *  immediate create); the first `sidechat.prompt` then carries the
+     *  boundary + snapshot and earns the thread its real label. */
+    'sidechat.start'(payload: unknown): Promise<{
+        childId: string;
+    }>;
+    /** Deliver one follow-up message to a thread (live, or cold-resumed). */
+    'sidechat.prompt'(payload: unknown): Promise<{
+        accepted: true;
+    }>;
+    /** Abort the thread's running turn (queued work is preserved). */
+    'sidechat.cancel'(payload: unknown): Promise<{
+        accepted: true;
+    }>;
+    /** Release the thread's live agent (session and history stay persisted). */
+    'sidechat.dispose'(payload: unknown): Promise<{
+        accepted: true;
+    }>;
+    /** Live state + agent identity for the thread header. */
+    'sidechat.info'(payload: unknown): Promise<SidechatThreadInfo>;
+}
+/** Build the Side Chat routes (all optional services degrade to a wire
+ *  error the tab surfaces inline). The record keys are the FULL wire method
+ *  names the /sidebar/api dispatcher looks up (`api[method]`). */
+export declare function buildSidechatApi(ctx: Context): SidechatRoutes;

package/lib/types/subagent-activity.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure derivation of the compact LIVE line shown on a running subagent card:
+ * the last text output and the last tool call of the child's session events.
+ * The host batch route feeds raw session events into this parser; the client
+ * only receives the already-folded `LastActivity` map. Renders nothing
+ * itself — the SubagentView component turns this into the card's status
+ * lines. Kept framework-free so the parser is unit-testable in the node
+ * environment.
+ */
+import type { SidebarSessionEvent } from './context-types.ts';
+/**
+ * Extract the concatenated plain text of a content-block list (the durable
+ * `ContentBlock[]` shape, structurally: blocks with `type: 'text'` carry
+ * `text`; anything else — tool_use, image, … — contributes nothing).
+ * @param content - the raw `content` field of a message event.
+ * @returns the joined text, or undefined when the message carries no text.
+ */
+export declare function contentText(content: unknown): string | undefined;
+/** The live status of one subagent card (both fields optional). */
+export interface LastActivity {
+    /** The latest assembled assistant text output in the tail. */
+    text?: string;
+    /** The latest tool call in the tail. */
+    tool?: {
+        name: string;
+        args: string;
+    };
+}
+/**
+ * Fold a session event log into the last text output + last tool call (each
+ * is the LAST occurrence in event order). Lifecycle events and raw
+ * `assistant/chunk` rows are ignored — the card shows what the subagent is
+ * doing right now, not its plumbing. The scan runs BACKWARD from the newest
+ * event and stops once both fields are found, so a long history costs only
+ * the recent tail in the common case.
+ * @param events - the session's append-only event log (oldest → newest).
+ * @param maxMessages - optional message-boundary window: only the tail's
+ *   last `maxMessages` surface messages (`user/message`, `assistant/message`)
+ *   and the events between them are considered, mirroring the old
+ *   `subagents.history({ maxMessages })` window. Stale activity older than
+ *   the window is never surfaced, and a long log is never scanned in full.
+ * @returns the last text and/or tool call; an empty object when the log has neither.
+ */
+export declare function lastActivity(events: readonly SidebarSessionEvent[], maxMessages?: number): LastActivity;

package/lib/types/subagent-live-route.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The live-preview route of the Subagent page ('subagents.live'): one
+ * request per refresh instead of N per-child `subagents.history` calls.
+ *
+ * The route takes the already-resolved topology root (`rootSessionId`),
+ * enumerates the whole descendant tree ONCE through the host subagent
+ * runtime (`ctx.get('subagents')` / `listDescendants`), keeps only rows the
+ * catalog reports running (`activity: 'running'` — the same gate the client
+ * renders cards on), and folds the newest text/tool activity from each
+ * child's attached session event log. It never touches DSH source and never
+ * reads the model's `job_output` cursor.
+ *
+ * Degradation contract:
+ * - `ctx.get('subagents')` missing or `listDescendants` failure → 503 (the
+ *   Subagent page has no topology to show in such deployments anyway).
+ * - One child's events missing/corrupt → that child is skipped, the rest of
+ *   the batch still returns.
+ */
+import type { Context } from './context-types.ts';
+import { type LastActivity } from './subagent-activity.ts';
+/** The live-preview routes of the /sidebar JSON API. */
+export interface SidebarSubagentLiveRoutes {
+    /**
+     * Fold one tree's running subagent histories into a compact live map.
+     * @param payload - `{ rootSessionId }`.
+     * @returns `{ live: Record<childSessionId, LastActivity> }`; children with
+     *   no text/tool yet are omitted.
+     */
+    live(payload: unknown): Promise<{
+        live: Record<string, LastActivity>;
+    }>;
+}
+/**
+ * The recent-message window of the live preview: only the last 12 surface
+ * messages of a child's log are folded, matching the old per-card
+ * `subagents.history({ maxMessages: 12 })` window. Keeps stale tool calls
+ * out of the preview and bounds the backward scan per child.
+ */
+export declare const LIVE_WINDOW_MESSAGES = 12;
+/**
+ * Build the live-preview routes bound to the plugin context.
+ * @param ctx - host plugin context.
+ */
+export declare function buildSubagentLiveApi(ctx: Context): SidebarSubagentLiveRoutes;

package/lib/types/tools.d.ts

@@ -0,0 +1,31 @@
+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 - live cwd resolver for one session id.
+ * @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) => 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/wire.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Wire helpers for the /sidebar JSON API: bounded body reading, response
+ * writing, and the shared error envelope. Every API method returns
+ * `{ok: true, value}` on success and `{ok: false, error: {code, message}}`
+ * (HTTP 4xx/5xx matching the code) on failure.
+ */
+import type { SidebarHttpRequest, SidebarHttpResponse } from './context-types.ts';
+/** Machine-readable error codes of the sidebar API. */
+export type SidebarErrorCode = 'bad-request' | 'not-found' | 'forbidden' | 'method-error' | 'too-large' | 'fs-error' | 'git-error' | 'pty-error' | 'pty-deps-missing' | 'job-error' | 'sidechat-error' | 'subagents-unavailable' | 'settings-rejected' | 'settings-conflict' | 'internal';
+/** One API failure with its wire code and HTTP status. */
+export declare class SidebarError extends Error {
+    readonly code: SidebarErrorCode;
+    readonly status: number;
+    constructor(code: SidebarErrorCode, message: string, status?: number);
+}
+/** Success envelope of one API method. */
+export interface SidebarOk<T> {
+    ok: true;
+    value: T;
+}
+/** Failure envelope of one API method. */
+export interface SidebarErr {
+    ok: false;
+    error: {
+        code: SidebarErrorCode;
+        message: string;
+    };
+}
+/** Read and parse the JSON request body (bounded; malformed → bad-request). */
+export declare function readJsonBody(req: SidebarHttpRequest): Promise<unknown>;
+/** Write a JSON response with the given status. */
+export declare function writeJson(res: SidebarHttpResponse, status: number, body: unknown): void;
+/** Write the success envelope. */
+export declare function writeOk(res: SidebarHttpResponse, value: unknown): void;
+/** Write the failure envelope for any thrown value (unknown → internal 500). */
+export declare function writeError(res: SidebarHttpResponse, error: unknown): void;
+/** Narrow an unknown payload value to a string, else throw bad-request. */
+export declare function requireString(payload: unknown, key: string): string;