@keith9681/dsh-sidebar 0.15.2

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

@@ -0,0 +1,603 @@
+/**
+ * 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
+ * - webRuntime: @deepseek-ai/dsh-web-app (bind-derived trusted hosts)
+ * - slots: the client runtime SlotRegistry
+ * - effect: the DSH-vendored cordis lifecycle helper
+ * Drift from upstream is contained to this file.
+ *
+ * This file must stay FREE of Node.js types (`node:http`, `node:stream`,
+ * `Buffer`): it is part of the CLIENT-reachable declaration graph (the
+ * `Context` in `TabComponentProps` and the `declare module` augmentation),
+ * so a Node import here would leak into browser-only consumer builds. The
+ * webServer faces below are therefore structural mirrors with plain
+ * interfaces (the host casts to real Node types at the few boundaries that
+ * need them — e.g. the `ws` upgrade hook in src/index.ts).
+ */
+import type { Context } from 'cordis';
+import type { BetterSidebarService } from './client/service.ts';
+/** The request face route handlers see (structural subset of node's
+ *  IncomingMessage: the URL/method/header reads and the async body
+ *  iteration `readJsonBody` uses). */
+export interface SidebarHttpRequest {
+    url?: string;
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    [Symbol.asyncIterator](): AsyncIterator<string | Uint8Array>;
+}
+/** The response face route handlers write to (structural subset of node's
+ *  ServerResponse: the status/header/body writes the routes use). */
+export interface SidebarHttpResponse {
+    statusCode: number;
+    writeHead(status: number, headers?: Record<string, string>): void;
+    end(body?: string | Uint8Array): void;
+}
+/** The upgrade socket face (structural subset: the destroy the fences use). */
+export interface SidebarUpgradeSocket {
+    destroy(): void;
+}
+/** The upgrade head bytes (Buffer at runtime; typed as bytes so no Node
+ *  global leaks into the declaration graph). */
+export type SidebarUpgradeHead = Uint8Array;
+/** One named webserver route (mirror of the host-webserver WebRoute). */
+export interface SidebarWebRoute {
+    kind: 'exact' | 'prefix';
+    path: string;
+    handler: (req: SidebarHttpRequest, res: SidebarHttpResponse) => void | Promise<void>;
+}
+/** One exact-path HTTP upgrade registration (mirror of WebUpgradeRoute). */
+export interface SidebarWebUpgradeRoute {
+    path: string;
+    handler: (req: SidebarHttpRequest, socket: SidebarUpgradeSocket, head: SidebarUpgradeHead) => 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;
+}
+/**
+ * The web runtime service face (mirror of @deepseek-ai/dsh-web-app's
+ * WebRuntimeValues): the bind-derived trust list the /api gateway's fence
+ * accepts — LAN IP literals sampled when the server binds all interfaces,
+ * plus explicit `--trusted-host` authorities.
+ */
+export interface SidebarWebRuntime {
+    trustedHosts: readonly string[];
+}
+/** 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;
+    /**
+     * Create a session + agent with a custom seed (mirror of the runtime
+     * AgentRegistry.create) — the Side Chat thread-creation seam: the SAME
+     * public seam api-proxy's session.fork and the subagent fork provider use.
+     */
+    create?(options: unknown): Promise<{
+        agent: SidebarAgent;
+        dispose(): Promise<void>;
+    }>;
+    /**
+     * Resume an agent on a persisted session (mirror of the runtime
+     * AgentRegistry.resume) — the Side Chat cold-continuation seam after a
+     * DSH restart or a closed thread.
+     */
+    resume?(options: unknown): Promise<{
+        agent: SidebarAgent;
+        dispose(): Promise<void>;
+    }>;
+}
+/** The host subagent runtime face (`ctx.subagents`; optional — the live
+ *  batch route degrades to a 503 when the deployment lacks it). Only the
+ *  read-only descendant enumeration this plugin needs is mirrored. */
+export interface SidebarSubagentsService {
+    /**
+     * Enumerate the root's complete session-backed subagent tree in stable
+     * pre-order without loading or resuming an Agent (mirror of
+     * `SubagentRuntime.listDescendants`).
+     */
+    listDescendants(rootSessionId: string, signal?: AbortSignal): Promise<SidebarSubagentDescendantEntry[]>;
+}
+/** One descendant row of `ctx.subagents.listDescendants` (structural mirror). */
+export type SidebarSubagentDescendantEntry = {
+    kind: 'child';
+    id: string;
+    activity: 'running' | 'inactive';
+    hasChildren: boolean;
+    mode: 'one-shot' | 'continuable';
+    label?: string;
+    parentId: string;
+    depth: number;
+} | {
+    kind: 'diagnostic';
+    id: string;
+    reason: 'corrupt' | 'unsupported' | 'unavailable';
+    parentId: string;
+    depth: number;
+};
+/** The host agent-presets service face (mirror of the runtime agentPresets
+ *  service): resolves and mounts the preset composition a session recorded,
+ *  so a resumed or forked session rebuilds the same tool/prompt world its
+ *  history was produced under. */
+export interface SidebarAgentPresetsService {
+    /** Resolve a preset id; undefined resolves the deployment default. */
+    resolve(presetId?: string): Promise<{
+        id: string;
+    }>;
+    /** Mount a preset's composition into an agent scope before publication. */
+    mount(agentCtx: unknown, presetId: string): Promise<void>;
+}
+/** The host session-title service face (mirror of the sessionTitle service). */
+export interface SidebarSessionTitleService {
+    /** Rename one live session's title (pins it against auto-regeneration). */
+    rename(session: unknown, title: string): {
+        title: string;
+        eventSeq: number;
+    };
+}
+/** The host session-persistence face (mirror of the sessionPersistence
+ *  service): detached inspection of a persisted session, used to compose the
+ *  recorded preset when a Side Chat thread cold-resumes. */
+export interface SidebarSessionPersistenceService {
+    inspect(sessionId: string): Promise<{
+        meta: {
+            cwd?: string;
+            agentPreset?: string;
+        };
+        events: readonly SidebarSessionEvent[];
+    }>;
+}
+/** 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 generic session-history RPC face the Side Chat transcript polls
+ *  (subagent.history verifies subagent-catalog membership, which our custom
+ *  side-thread children do not have — the generic session.history reads any
+ *  durable log directly). */
+export interface SidebarSessionHistoryRpc {
+    history(payload: {
+        sessionId: string;
+        beforeSeq?: number;
+        maxMessages?: number;
+    }, signal?: AbortSignal): Promise<SidebarRpcResponse<{
+        events: SidebarHistoryEntry[];
+        hasMore: boolean;
+    }>>;
+}
+/** The wire face the Subagent activity summary needs (subset of `ctx.connection`). */
+export interface SidebarConnectionHandle {
+    api: {
+        sessions: SidebarSessionHistoryRpc;
+        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;
+    /**
+     * Fork a session from a completed-turn prefix of the source and resolve
+     * the child session id (mirror of the runtime ISessions.fork — throws on
+     * failure). The Side Chat "save as new session" action uses this to
+     * promote a hidden side thread into a top-level session.
+     */
+    fork?(opts: {
+        sessionId: string;
+        atSeq?: number;
+        increaseTitle?: boolean;
+    }): Promise<string>;
+    /**
+     * Resolve the stable session binding of one listed session (mirror of the
+     * runtime ISessions.binding); the saved-session rename uses the face's
+     * behavior verbs.
+     */
+    binding?(id: string): {
+        session: {
+            rename(title: string): Promise<unknown>;
+        };
+    } | undefined;
+    /**
+     * 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;
+        webRuntime: SidebarWebRuntime;
+        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 client module system (rc.8+): resolves module-table specifiers
+         * (seed words, graph rows) — the chunk loader's externals go through it
+         * (`ctx.modules.import`). rc.7 exposed the same surface as the
+         * `window.__DSH_MODULES__` page global; the loader keeps that fallback.
+         */
+        modules: {
+            import(specifier: string): Promise<unknown>;
+        };
+        /**
+         * 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, and to create /
+         * resume the Side Chat thread agents).
+         */
+        agents: SidebarAgentsService;
+        /**
+         * The host subagent runtime (`ctx.subagents`; optional — the Subagent
+         * page's live batch route reads descendant catalogs through it).
+         */
+        subagents: SidebarSubagentsService;
+        /**
+         * The host agent-presets service (`ctx.get('agentPresets')`; optional —
+         * absent deployments compose nothing and every session shares the host
+         * composition).
+         */
+        agentPresets: SidebarAgentPresetsService;
+        /**
+         * The host session-title service (`ctx.get('sessionTitle')`; optional —
+         * the Side Chat thread label pin degrades to the auto-generated title).
+         */
+        sessionTitle: SidebarSessionTitleService;
+        /**
+         * The host session-persistence service (`ctx.get('sessionPersistence')`;
+         * optional — needed only for the Side Chat cold-resume composition).
+         */
+        sessionPersistence: SidebarSessionPersistenceService;
+        /**
+         * 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-operations.d.ts

@@ -0,0 +1,28 @@
+/** Inputs of one upload: the session scope plus the request body stream. */
+export interface WorkspaceUploadInput {
+    /** The session workspace root; target and directory must stay inside it. */
+    cwd: string;
+    /** Absolute upload directory chosen by the client (inside `cwd`). */
+    dir: string;
+    /** Relative path below `dir` (absolute paths, '.', '..' and empty segments refused). */
+    relativePath: string;
+    /** The request body stream (raw bytes). */
+    chunks: AsyncIterable<string | Uint8Array>;
+    /** Byte cap; an oversized upload is refused without touching the target. */
+    limit: number;
+}
+/**
+ * Stream `chunks` into `dir/relativePath` atomically: a uniquely named temp
+ * sibling receives the bytes, then is renamed over the target. The parent
+ * directory is created on demand (recursive), so folder uploads work before
+ * any level exists. The unique temp name keeps concurrent uploads to the same
+ * target independent (each writes and renames its own file; the last rename
+ * wins) and never blocks later uploads after a crashed process.
+ *
+ * @throws SidebarError with a wire code for containment, shape, and size
+ * failures; the temp file is always removed on failure.
+ */
+export declare function writeWorkspaceUpload(input: WorkspaceUploadInput): Promise<{
+    path: string;
+    size: number;
+}>;

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

@@ -0,0 +1,24 @@
+/** One search: the relative paths of the matching entries (dirs included so
+ *  the client can hint where matches live) plus the truncation flag. */
+export interface FsSearchResult {
+    matches: string[];
+    truncated: boolean;
+}
+/** Search budgets (both injectable for tests). */
+export interface FsSearchOptions {
+    /** Row cap of the result list (default 200). */
+    maxMatches?: number;
+    /** Total entries visited before the walk gives up (default 100_000). */
+    maxVisited?: number;
+}
+/**
+ * Search `root` recursively for entries whose name contains `query`
+ * (case-insensitive).
+ * @param root - absolute search root.
+ * @param query - the name substring; empty matches nothing.
+ * @param opts - budget overrides (tests).
+ * @returns the matching paths RELATIVE to `root` ('/'-separated), sorted,
+ *  plus whether a budget cut the walk short. An unreadable level is skipped
+ *  (permission errors never fail the whole search).
+ */
+export declare function searchFiles(root: string, query: string, opts?: FsSearchOptions): Promise<FsSearchResult>;