@achasoft/dsh-advanced-sidebar 0.1.0 → 0.3.0

package/types/client/preview-driver.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The panel's end of the agent channel: poll for work, execute it against the frame, report back.
+ *
+ * There is no host-to-browser push in an out-of-tree plugin, so the direction is inverted — the
+ * panel asks the Host whether the agent wants anything, and answers with what it found. This module
+ * owns that loop, the frame-side execution, and the console capture the agent reads through.
+ *
+ * Three rules shape everything here:
+ *
+ * 1. **Only same-origin frames can be inspected.** A page framed from another origin has no
+ *    reachable `document`, and `contentDocument === null` is the only reliable test for it. Every
+ *    read and every write refuses such a frame by name, so the model gets "this page is
+ *    cross-origin" instead of a timeout or an empty DOM.
+ * 2. **The agent's window into the frame is bounded.** The DOM walk stops at a node count and a
+ *    text length, the eval result is serialized with a cycle-safe replacer under a character cap,
+ *    and the console buffer is a ring. A page that logs per animation frame cannot flood a model's
+ *    context through this tool.
+ * 3. **Nothing here throws across the boundary.** A command that a page rejects — a missing
+ *    selector, an expression that throws, a frame that navigated mid-command — comes back as a
+ *    readable sentence, because a rejected promise at this layer would be an unexplained tool
+ *    timeout.
+ * @module @achasoft/dsh-advanced-sidebar/client/preview-driver
+ */
+import type { PreviewControlMessage } from '../host/types.ts';
+import type { PreviewFace } from './preview-types.ts';
+/** The frame as this driver needs to see it. */
+export interface FrameView {
+    /** The iframe element, or null while none is mounted. */
+    readonly element: HTMLIFrameElement | null;
+    /**
+     * The frame's document, or null when it is cross-origin or not loaded yet.
+     *
+     * Read from the element each time rather than cached: a navigation replaces the document, and a
+     * cached reference to the old one would answer about the page the operator just left.
+     */
+    readonly document: Document | null;
+    /** The frame's window, or null when it is cross-origin or not loaded yet. */
+    readonly window: Window | null;
+}
+/**
+ * What the driver needs from the panel around it.
+ *
+ * Callbacks rather than a React reference: the loop runs outside the render cycle, and a panel that
+ * re-rendered on every tick would re-run its own effects at poll cadence.
+ */
+export interface DriverHooks {
+    /** Read the frame as it is right now. */
+    frame: () => FrameView;
+    /** Apply a mode change the agent asked for. */
+    control: (message: PreviewControlMessage) => void;
+    /** Force the frame to remount and reload. */
+    reload: () => void;
+    /** Apply a viewport the agent asked for. */
+    resize: (width: number, height: number) => void;
+}
+/**
+ * The polling driver. One instance per mounted panel; `stop()` releases it.
+ */
+export declare class PreviewDriver {
+    private readonly face;
+    private readonly clientId;
+    private readonly sessionId;
+    private readonly hooks;
+    /** Console entries captured since the last report, oldest first. */
+    private readonly buffer;
+    /** Commands currently executing, so a poll that overlaps the previous one does not double-run. */
+    private readonly running;
+    private timer;
+    private stopped;
+    /**
+     * @param face - the Remote face the panel was handed.
+     * @param clientId - this browser tab's identity, generated once per panel mount.
+     * @param sessionId - the session the panel serves.
+     * @param hooks - how to read and act on the frame.
+     */
+    constructor(face: PreviewFace, clientId: string, sessionId: string, hooks: DriverHooks);
+    /**
+     * Start polling. Idempotent, so a re-render may call it again freely.
+     * @param bind - the panel's current state, refreshed on every poll.
+     */
+    start(bind: () => {
+        mounted: boolean;
+        mode: 'server' | 'file' | 'url' | 'scratchpad';
+        filePath?: string | undefined;
+        workspacePath?: string | undefined;
+        url?: string | undefined;
+        inspectable: boolean;
+        width: number;
+        height: number;
+    }): void;
+    /** Stop polling. Called when the panel unmounts. */
+    stop(): void;
+    /**
+     * Execute one command and report what it did.
+     * @param command - the command.
+     */
+    private execute;
+    /**
+     * Run one command against the frame.
+     * @param command - the command.
+     * @returns the result, or the sentence explaining the refusal.
+     */
+    private run;
+    /**
+     * Take everything captured since the last drain.
+     * @returns the entries, oldest first.
+     */
+    private drain;
+    /**
+     * Wrap the frame's console, once per document.
+     *
+     * Called from the poll rather than from a load listener because a navigation can complete between
+     * two polls, and the check is one property read on the frame's own window.
+     */
+    private captureConsole;
+    /**
+     * Append one captured entry, dropping the oldest past the ring.
+     * @param entry - the entry.
+     */
+    private push;
+}

package/types/client/preview-storage.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Where the Preview panel's scratchpad document lives between reloads.
+ *
+ * A scratchpad is a thought being worked out, not a deliverable, so it is stored in this browser
+ * rather than written to the workspace as a file — and per workspace, because two projects'
+ * experiments have nothing to do with each other.
+ *
+ * Split out of the mode component so the rules are testable without a DOM, and so every storage
+ * failure is handled in one place: `localStorage` may be absent (a non-browser host), disabled
+ * (private modes and hardened settings), or full, and none of those may take the panel down. Each is
+ * reported as "nothing saved" or "the write was refused", which the editor renders as a note.
+ * @module @achasoft/dsh-plugins/dsh-advanced-sidebar/client/preview-storage
+ */
+/**
+ * Largest document this mode will store.
+ *
+ * A person typing HTML reaches a few kilobytes; a megabyte is a paste of something that belongs in a
+ * file. The Host's own route refuses more than its limit, so reading is capped here too rather than
+ * discovering the refusal after a round trip.
+ */
+export declare const MAX_SCRATCHPAD_CHARS: number;
+/**
+ * The storage key one workspace's scratchpad lives under.
+ *
+ * The workspace path is the whole identity: two sessions in one directory are editing the same
+ * experiment, and a session with no directory shares one global scratchpad rather than losing it.
+ * @param workspace - the absolute workspace path, or undefined.
+ * @returns the key.
+ */
+export declare function scratchpadKey(workspace: string | undefined): string;
+/**
+ * Read one workspace's saved document.
+ * @param workspace - the absolute workspace path.
+ * @returns the saved document, or undefined when there is none or storage refuses.
+ */
+export declare function readScratchpad(workspace: string | undefined): string | undefined;
+/**
+ * Write one workspace's document, reporting a refused write instead of throwing.
+ * @param workspace - the absolute workspace path.
+ * @param text - the document.
+ * @returns true when the browser accepted it.
+ */
+export declare function writeScratchpad(workspace: string | undefined, text: string): boolean;

package/types/client/preview-types.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The Preview panel's own faces: what its modes are handed, and the narrow slice of the dock's
+ * injected face the command driver needs.
+ *
+ * Split out from the panel component so the driver — which is not a React component and must be
+ * testable and readable on its own — does not import the component that imports it.
+ * @module @achasoft/dsh-advanced-sidebar/client/preview-types
+ */
+import type { PanelHostInjected } from './contract.ts';
+/** The dock's injected face without the reserved `hooks` compartment, as every panel receives it. */
+export type PanelFace = Omit<PanelHostInjected, 'hooks'>;
+/**
+ * The endpoints the command driver calls, and only those.
+ *
+ * Narrowed deliberately: a driver handed the whole panel face could reach a git write, and the
+ * point of the split is that the agent channel's browser end can do exactly three things — ask for
+ * work, report a result, and say it left.
+ */
+export type PreviewFace = Pick<PanelFace, 'previewPoll' | 'previewResult' | 'previewRelease'>;
+/** Which mode the Preview panel is showing. */
+export type PreviewMode = 'server' | 'file' | 'url' | 'scratchpad';

package/types/client/preview-values.d.ts

@@ -0,0 +1,43 @@
+/**
+ * How a value that crossed the frame boundary is turned into text a model can read.
+ *
+ * Everything the agent channel reports — a console argument, an `eval` result, an element — arrived
+ * from a page nobody controls. A page can hold a cyclic object, a `BigInt`, a getter that throws, a
+ * function, a DOM node, or an `Error`, and `JSON.stringify` refuses three of those outright. Each is
+ * projected to something readable rather than failing the command, because "a model asked for
+ * something awkward" is an ordinary event and an unexplained tool failure is not.
+ *
+ * Pure and frame-free, so the whole projection is stated in tests without a document.
+ * @module @achasoft/dsh-advanced-sidebar/client/preview-values
+ */
+/** Largest JSON body one `eval` result may produce. */
+export declare const EVAL_CAP: number;
+/**
+ * Render one console argument the way a browser's own console would read it.
+ * @param value - the argument.
+ * @returns a string.
+ */
+export declare function describeValue(value: unknown): string;
+/**
+ * Serialize a value with cycles broken and DOM nodes projected to their markup.
+ * @param value - the value.
+ * @returns the JSON text, or undefined when the value serializes to `undefined`.
+ */
+export declare function stringify(value: unknown): string | undefined;
+/**
+ * Build a replacer that keeps one reference per object, so a cycle serializes instead of throwing.
+ *
+ * A fresh replacer per call, because the seen-set is per serialization: sharing one across calls
+ * would label a value `[circular]` only because an earlier, unrelated call had already seen it.
+ * @returns the replacer.
+ */
+export declare function createReplacer(): (key: string, value: unknown) => unknown;
+/**
+ * Serialize a value the way a model can read it.
+ * @param value - the evaluated value.
+ * @returns the JSON text, and why it is not JSON when it is not.
+ */
+export declare function safeJson(value: unknown): {
+    text: string;
+    note?: string;
+};

package/types/host/deletion.d.ts

@@ -1,29 +1,46 @@
 /**
  * Session deletion.
  *
- * No harness capability deletes a session: session persistence is append-only and exposes no delete
- * verb, and the workspace registry can only ARCHIVE — hide a session while keeping its log and its
- * accounting slot. Delete is therefore assembled here from the two things that do exist, and it is
- * honest about which one it managed:
+ * No harness capability deletes a session. Delete is therefore the one thing that does exist — the
+ * workspace registry's ARCHIVE, which hides a session while keeping its log and its accounting slot —
+ * and it is honest that this is all it did.
  *
- * - `archive` hides the session. Reversible in principle (the durable slot is preserved), and the
- *   only mode that can act on a session that is currently live.
- * - `purge` additionally removes the persistence backend's own per-session artifact. Nothing undoes
- *   that, and a backend that keeps no per-session artifact (SQLite) reports the archive alone.
+ * `deleteMode: 'purge'` asked for more: the backend's own per-session artifact removed as well. On
+ * the harness this release targets (`0.1.5-rc.2`) that cannot be done correctly, and so it is not
+ * attempted:
  *
- * A live session is never purged. Its writer holds the artifact open and a running turn would keep
- * appending to a file that no longer exists, so the archive commits and the reason is returned.
+ * - The published `SessionPersistence` contract is `create`, `open`, `flush`, `stat` and `list`. It
+ *   has no removal verb and no way to ask where a session's bytes live; the `supportsRawArtifacts`
+ *   flag and `locate()` this module used to read were never part of it, so purging was silently
+ *   impossible while the settings still offered it.
+ * - The JSONL backend keeps a session as a DIRECTORY — one immutable file per format generation plus
+ *   a `session.lock` write lease — behind an in-process cold-log memo, and the workspace registry and
+ *   the session projection cache index its header. Unlinking files underneath all of that bypasses the
+ *   lease another process may hold, leaves stale caches answering for a log that is gone, and is the
+ *   same class of out-of-band edit that produces "torn record" corruption reports.
+ *
+ * So the capability is reported as unavailable with that reason, the settings card shows the reason
+ * and refuses to select `purge`, and a composition that still configures it gets an archive whose
+ * result says, every time, why nothing was removed. When the harness grows a supported removal verb,
+ * this is the one module to change.
  * @module @achasoft/dsh-advanced-sidebar/host/deletion
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { AdvancedSidebarSettings, DeleteSessionRequest, DeleteSessionResult } from './types.ts';
 /** What Delete can do on this Host right now. */
 export interface DeletionCapability {
-    /** Whether the persistence backend exposes a per-session artifact that could be removed. */
+    /** Whether a session's durable log can be removed. Always false on this harness; see the module. */
     readonly canPurge: boolean;
     /** Why purging is unavailable, when it is. */
     readonly reason?: string;
 }
+/**
+ * Why `purge` is unavailable, in the words the settings card and the Delete result show.
+ *
+ * One sentence for both, so the reason a person reads before choosing a mode is the reason they read
+ * after pressing Delete.
+ */
+export declare const PURGE_UNAVAILABLE_REASON: string;
 /**
  * Commits Delete for the sidebar menu. Stateless apart from the context and settings it reads.
  */
@@ -31,27 +48,19 @@ export declare class SessionDeleter {
     private readonly ctx;
     private readonly source;
     /**
-     * @param ctx - Host context carrying the workspace registry and session persistence.
+     * @param ctx - Host context carrying the workspace registry.
      * @param source - reads the current settings section; called per request.
      */
     constructor(ctx: Context, source: () => AdvancedSidebarSettings);
     /**
      * Report whether the durable log can be removed at all.
-     * @returns the capability, with a reason when purging is impossible.
+     * @returns the capability, with the reason purging is impossible.
      */
     describe(): DeletionCapability;
     /**
-     * Hide one session, and remove its durable artifact when the mode and the Host allow it.
+     * Hide one session, and say plainly when a requested purge did not happen.
      * @param request - the session to delete.
-     * @param signal - cancellation for the persistence listing.
      * @returns what was actually done, or a classified failure.
      */
-    delete(request: DeleteSessionRequest, signal?: AbortSignal): Promise<DeleteSessionResult>;
-    /**
-     * Find the backend artifact for one session, or say why it will not be removed.
-     * @param sessionId - the session to look up.
-     * @param signal - cancellation for the persistence listing.
-     * @returns the artifact path, or the reason purging is skipped.
-     */
-    private locateArtifact;
+    delete(request: DeleteSessionRequest): Promise<DeleteSessionResult>;
 }

package/types/host/git.d.ts

@@ -19,6 +19,20 @@ import type { AdvancedSidebarSettings, CapabilityState, GitCommitMessageRequest,
  * @returns the message, trimmed.
  */
 export declare function stripFence(text: string): string;
+/**
+ * The `-c` overrides that disarm the untrusted filter programs one config listing names.
+ *
+ * An empty value is git's own "no command" for a filter (`convert.c` runs a driver only when its
+ * command is non-empty), so the file is then hashed as its bytes, exactly as with no driver at all.
+ * @param listing - `git config --show-scope --name-only --get-regexp` output, one `scope<TAB>key` per
+ * line; a line with no scope (an older git) is treated as untrusted.
+ * @returns the overrides, or the key git could not be told about safely.
+ */
+export declare function filterOverrides(listing: string): {
+    readonly config: readonly string[];
+} | {
+    readonly unsafeKey: string;
+};
 /**
  * Reads one workspace's git state. One instance serves every request; the resolved `git` path is
  * cached across calls and dropped whenever a lookup fails, so installing git later needs no restart.
@@ -91,6 +105,47 @@ export declare class GitReader {
      * @returns the push, the reading after it, or a classified failure.
      */
     push(request: GitPushRequest, signal?: AbortSignal): Promise<GitPushResult>;
+    /**
+     * The arguments that publish one branch to one remote and record it as the upstream.
+     *
+     * Both names come from repository state, not from the browser — and repository state is not
+     * trusted either. A HEAD of `refs/heads/--receive-pack=/tmp/x` is a valid ref (`check-ref-format`
+     * accepts it) that `git status` reports as the branch `--receive-pack=/tmp/x`; handed to
+     * `git push` as a bare argument, git parsed it as the option and ran `/tmp/x` as the remote's
+     * receive-pack. So three independent things stand in the way:
+     *
+     * 1. Both names are refused outright when they begin with `-`.
+     * 2. The branch must pass `git check-ref-format --branch`, which is git's own branch-name grammar
+     *    (it rejects a leading `-`, `..`, control characters, `@{`) and must echo back unchanged, so a
+     *    `@{-1}` shorthand cannot be expanded into some other branch. The remote must make a valid
+     *    remote-tracking ref, which is how git itself validates a remote name.
+     * 3. The push names the refs after `--`, where `git push` (parse-options) stops reading options,
+     *    and as a fully qualified `refs/heads/<b>:refs/heads/<b>` refspec, which also cannot be read as
+     *    a shorter ref with the same name on the remote. `--set-upstream` records the same tracking
+     *    branch it records for the short spelling.
+     * @param repository - the resolved repository.
+     * @param remote - the remote to publish to, from `git remote`.
+     * @param branch - the current branch, from `git status`.
+     * @param signal - cancellation for the validation invocations.
+     * @returns the push arguments, or the failure to return.
+     */
+    private publishArgv;
+    /**
+     * Whether git accepts a name as a branch name, spelled exactly as given.
+     * @param repository - the resolved repository.
+     * @param branch - the name, already known not to begin with `-`.
+     * @param signal - cancellation for the invocation.
+     * @returns true when `check-ref-format --branch` accepts it and echoes it back unchanged.
+     */
+    private isValidBranchName;
+    /**
+     * Whether git accepts a name as a remote name.
+     * @param repository - the resolved repository.
+     * @param remote - the name, already known not to begin with `-`.
+     * @param signal - cancellation for the invocation.
+     * @returns true when `refs/remotes/<remote>/HEAD` is a well-formed ref, git's own remote-name rule.
+     */
+    private isValidRemoteName;
     /**
      * Ask the deployment's own model to write a commit message for what is staged.
      *
@@ -104,7 +159,7 @@ export declare class GitReader {
     draftCommitMessage(request: GitCommitMessageRequest, signal?: AbortSignal): Promise<GitCommitMessageResult>;
     /**
      * The patch a drafted message describes, bounded so a large change cannot become a large request.
-     * @param root - absolute repository root.
+     * @param repository - the resolved repository.
      * @param amend - describe the previous commit's content as well as the index.
      * @param signal - cancellation for the invocations.
      * @returns the patch and whether it was cut, or the failure to return.
@@ -112,14 +167,14 @@ export declare class GitReader {
     private stagedPatch;
     /**
      * Whether HEAD has a parent commit.
-     * @param cwd - absolute repository root.
+     * @param repository - the resolved repository.
      * @param signal - cancellation for the invocation.
      * @returns true when `HEAD~1` resolves.
      */
     private hasParent;
     /**
      * The remote an unpublished branch would be published to.
-     * @param cwd - absolute repository root.
+     * @param repository - the resolved repository.
      * @param signal - cancellation for the invocation.
      * @returns `origin` when it exists, else the first remote, else undefined.
      */
@@ -147,21 +202,21 @@ export declare class GitReader {
     private contain;
     /**
      * The author `git commit` would record.
-     * @param cwd - the repository root.
+     * @param repository - the resolved repository.
      * @param signal - cancellation for the invocation.
      * @returns `Name <email>`, or undefined when git has no identity configured.
      */
     private author;
     /**
      * Whether the index differs from HEAD.
-     * @param cwd - the repository root.
+     * @param repository - the resolved repository.
      * @param signal - cancellation for the invocation.
      * @returns true when a commit would record something.
      */
     private hasStaged;
     /**
      * Report what the panel may do to this repository.
-     * @param cwd - the repository root.
+     * @param repository - the resolved repository.
      * @param signal - cancellation for the identity lookup.
      * @returns the write capability.
      */
@@ -181,10 +236,41 @@ export declare class GitReader {
      */
     private locateRepository;
     /**
-     * Run one git invocation with this plugin's own bounds.
+     * The overrides that switch off the content filters a repository's own config defines.
+     *
+     * Listing config runs nothing — `git config` reads files — so this is safe to ask before any
+     * reading. `--show-scope` arrived in git 2.26; an older git refuses the flag, and the listing is
+     * then repeated without it and every filter it names is treated as untrusted, which can only make
+     * a reading more conservative. A listing that fails both ways fails the reading: a status that
+     * cannot prove its filters are disarmed is not run.
+     * @param root - absolute repository root.
+     * @param signal - cancellation for the listing.
+     * @returns the `-c` pairs, or the failure to return.
+     */
+    private untrustedFilterConfig;
+    /**
+     * Run one READING: an invocation the panel makes on its own, which must run no program the
+     * repository's config names.
+     *
+     * On top of {@link git}'s own `core.fsmonitor` override it disarms the repository's content
+     * filters. Writes (`add`, `restore`, `commit`, `push`) deliberately do not go through here: they are
+     * an operator's explicit action, a filter such as LFS is part of what staging correctly means, and a
+     * commit's hooks are a real answer the panel reports.
+     * @param repository - the resolved repository, carrying its filter overrides.
+     * @param args - arguments after the executable and the overrides.
+     * @param signal - the caller's cancellation.
+     * @param maxBytes - the caller's own output bound, when it has one.
+     * @param cwd - directory to run in; the repository root unless the reading is relative to the workspace.
+     * @returns the finished command.
+     */
+    private read;
+    /**
+     * Run one git invocation with this plugin's own bounds and {@link INVOCATION_CONFIG}.
      * @param cwd - directory to run in.
-     * @param args - arguments after the executable.
+     * @param args - arguments after the executable and the invocation config.
      * @param signal - the caller's cancellation.
+     * @param maxBytes - the caller's own output bound, when it has one.
+     * @param timeoutMs - the caller's own wall-clock bound, when it has one.
      * @returns the finished command.
      */
     private git;

package/types/host/index.d.ts

@@ -17,7 +17,8 @@
 import { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
-import type { AdvancedSidebarSettings, AdvancedSidebarView, DeleteSessionRequest, DeleteSessionResult, GitCommitMessageRequest, GitCommitMessageResult, GitCommitRequest, GitCommitResult, GitDiffRequest, GitDiffResult, GitPushRequest, GitPushResult, GitStageRequest, GitStageResult, GitStatusRequest, GitStatusResult, ListEntriesRequest, ListEntriesResult, OpenInRequest, OpenInResult, PreviewListRequest, PreviewListResult, PreviewLogsRequest, PreviewLogsResult, PreviewStartRequest, PreviewStartResult, PreviewStopRequest, PreviewStopResult, ReadFileRequest, ReadFileResult, TaskKillRequest, TaskKillResult, TaskOutputRequest, TaskOutputResult, TerminalAckResult, TerminalCloseRequest, TerminalOpenRequest, TerminalOpenResult, TerminalReadRequest, TerminalReadResult, TerminalSignalRequest, TerminalWriteRequest } from './types.ts';
+import type { PreviewCommandBody } from './ui-preview-tool.ts';
+import type { AdvancedSidebarSettings, AdvancedSidebarView, DeleteSessionRequest, DeleteSessionResult, GitCommitMessageRequest, GitCommitMessageResult, GitCommitRequest, GitCommitResult, GitDiffRequest, GitDiffResult, GitPushRequest, GitPushResult, GitStageRequest, GitStageResult, GitStatusRequest, GitStatusResult, ListEntriesRequest, ListEntriesResult, OpenInRequest, OpenInResult, PreviewCommandResult, PreviewFileInfoRequest, PreviewFileInfoResult, PreviewFileKind, PreviewListRequest, PreviewListResult, PreviewLogsRequest, PreviewLogsResult, PreviewPollRequest, PreviewPollResult, PreviewReleaseRequest, PreviewReleaseResult, PreviewResultAck, PreviewResultRequest, PreviewStartRequest, PreviewStartResult, PreviewStopRequest, PreviewStopResult, ReadFileRequest, ReadFileResult, TaskKillRequest, TaskKillResult, TaskOutputRequest, TaskOutputResult, TerminalAckResult, TerminalCloseRequest, TerminalOpenRequest, TerminalOpenResult, TerminalReadRequest, TerminalReadResult, TerminalSignalRequest, TerminalWriteRequest } from './types.ts';
 export type * from './types.ts';
 export { REVEAL_TARGET_ID } from './open-in.ts';
 /**
@@ -27,7 +28,7 @@ export { REVEAL_TARGET_ID } from './open-in.ts';
  * Host validates, while a Remote namespace is read as `ctx.remote.advancedSidebar.…` and so must be
  * an identifier.
  */
-export declare const ADVANCED_SIDEBAR_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+export declare const ADVANCED_SIDEBAR_SETTINGS_NAMESPACE: "advanced-sidebar";
 /** Deployment configuration for the advanced sidebar; the `advanced-sidebar` section's own shape. */
 export type Config = AdvancedSidebarSettings;
 declare module '@deepseek-ai/cordis' {
@@ -47,6 +48,8 @@ export declare class AdvancedSidebarService extends TypertRemoteService {
     private readonly tasks;
     private readonly deleter;
     private readonly preview;
+    private readonly surface;
+    private readonly bindings;
     /**
      * @param ctx - Host context; every capability this service uses is resolved optionally, so a
      * deployment missing one still serves a view that explains which panel is dark and why.
@@ -173,6 +176,38 @@ export declare class AdvancedSidebarService extends TypertRemoteService {
      * @returns the delta and the state, or a classified failure.
      */
     previewLogs(request: PreviewLogsRequest): Promise<PreviewLogsResult>;
+    /**
+     * Describe one workspace file for the Preview panel's Files mode.
+     *
+     * Separate from `readFile`, which returns text for the Files panel's reader: a preview needs the
+     * kind, the size, the same-origin URL, and a change token, and it must not pull a 200 MB video
+     * through the wire to find out what it is.
+     * @param request - the workspace and the file inside it.
+     * @param signal - gateway-supplied cancellation for the resolution and metadata reads.
+     * @returns the file's kind and frame URL, or a classified failure.
+     */
+    previewFileInfo(request: PreviewFileInfoRequest, signal: AbortSignal): Promise<PreviewFileInfoResult>;
+    /**
+     * Register one Preview panel and take whatever the agent queued for it.
+     *
+     * This is the polling half of the agent channel: the browser calls it while a preview is mounted,
+     * the call is the panel's liveness heartbeat, and its answer carries the commands to execute.
+     * @param request - which panel, where it is, and whether a preview is actually rendered.
+     * @returns the work to do, or a classified failure.
+     */
+    previewPoll(request: PreviewPollRequest): Promise<PreviewPollResult>;
+    /**
+     * Record what one command did.
+     * @param request - the panel, the command id, and the outcome.
+     * @returns settlement.
+     */
+    previewResult(request: PreviewResultRequest): Promise<PreviewResultAck>;
+    /**
+     * Say that one panel is gone, so its queued work is dropped and its waits fail now.
+     * @param request - the panel that closed.
+     * @returns settlement.
+     */
+    previewRelease(request: PreviewReleaseRequest): Promise<PreviewReleaseResult>;
     /**
      * Read one file for the Files panel preview.
      * @param request - the file and the workspace it must stay inside.
@@ -200,11 +235,68 @@ export declare class AdvancedSidebarService extends TypertRemoteService {
      */
     taskOutput(request: TaskOutputRequest): Promise<TaskOutputResult>;
     /**
-     * Delete one session: archive it, and remove its durable artifact when the mode and Host allow.
+     * Delete one session: archive it, and report plainly that a configured purge did not happen.
      * @param request - the session to delete.
-     * @param signal - gateway-supplied cancellation for the persistence listing.
      * @returns what was actually done, or a classified failure.
      */
-    deleteSession(request: DeleteSessionRequest, signal: AbortSignal): Promise<DeleteSessionResult>;
+    deleteSession(request: DeleteSessionRequest): Promise<DeleteSessionResult>;
+    /**
+     * Queue one command against the session's Preview panel and wait for its answer.
+     * @param sessionId - the session whose panel should execute it.
+     * @param body - the command, without its id, panel, or deadline.
+     * @returns the result, or a sentence explaining why there is none.
+     */
+    queueCommand(sessionId: string, body: PreviewCommandBody): Promise<{
+        ok: true;
+        result: PreviewCommandResult;
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    /**
+     * Point the session's panel at a URL.
+     *
+     * The panel decides for itself how to frame it — a loopback URL goes through this Host's proxy and
+     * becomes inspectable, anything else is framed cross-origin and is not — so the answer says which
+     * happened rather than the tool guessing.
+     * @param sessionId - the session whose panel should show it.
+     * @param url - the absolute `http(s)` URL, already validated by the caller.
+     * @param waitMs - how long the panel may take to mount and load.
+     * @returns the outcome and what the panel is now framing.
+     */
+    openUrl(sessionId: string, url: string, waitMs: number): Promise<{
+        ok: true;
+        message: string;
+        detail: Record<string, unknown>;
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    /**
+     * Point the session's panel at one workspace file.
+     * @param request - the session, the workspace, the file, its kind, and the wait budget.
+     * @returns the outcome and where the panel is now framed from.
+     */
+    openFile(request: {
+        sessionId: string;
+        workspacePath: string;
+        filePath: string;
+        kind: PreviewFileKind;
+        waitMs: number;
+    }): Promise<{
+        ok: true;
+        message: string;
+        detail: Record<string, unknown>;
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    /**
+     * Read one workspace file's preview description, for the tool's own `open` validation.
+     * @param request - the workspace and the file.
+     * @param signal - cancellation for the reads.
+     * @returns the description, or a classified failure.
+     */
+    describeFile(request: PreviewFileInfoRequest, signal?: AbortSignal): Promise<PreviewFileInfoResult>;
 }
 export default AdvancedSidebarService;