@achasoft/dsh-advanced-sidebar 0.1.0 → 0.3.0

package/types/host/types.d.ts

@@ -124,6 +124,25 @@ export interface AdvancedSidebarSettings {
     previewScrollback: number;
     /** TERM-to-KILL grace when a preview server is stopped. */
     previewGraceMs: number;
+    /**
+     * Largest workspace file a preview mode will hand to the browser, in bytes.
+     *
+     * Separate from `filesMaxPreviewBytes`, which bounds a TEXT preview rendered inside the panel:
+     * this one bounds a media response streamed into a frame, and a video is legitimately far larger
+     * than any file worth reading as text. Past it the panel reports the size and offers
+     * "open with the default application" instead.
+     */
+    readonly previewMaxFileBytes: number;
+    /** Wall-clock bound on one proxied upstream request, in milliseconds. */
+    readonly previewProxyTimeoutMs: number;
+    /**
+     * How long an agent command waits for the panel to answer before the tool reports a timeout,
+     * in milliseconds. Long enough for a frame load plus an `open`, short enough that a model turn is
+     * not spent waiting on a browser tab that is not there.
+     */
+    readonly previewCommandTimeoutMs: number;
+    /** How long a bind is trusted after its last poll before the surface is reported as unmounted. */
+    readonly previewBindTtlMs: number;
 }
 /** Availability of one Host-backed panel, with the reason when it is unavailable. */
 export interface CapabilityState {
@@ -157,6 +176,15 @@ export interface AdvancedSidebarView {
     readonly preview: CapabilityState & {
         /** How many preview servers this plugin currently holds open. */
         readonly running: number;
+        /**
+         * Where the same-origin preview routes are, when the Host serves them.
+         *
+         * Absent means no `webServer` capability is mounted, which is the headless case: the Server and
+         * URL modes still work through the frame's own origin, but a workspace file cannot be framed at
+         * all and the agent cannot inspect a cross-origin page. The panel says so rather than offering a
+         * mode that cannot work.
+         */
+        readonly surface?: PreviewSurfaceInfo;
     };
     /** Whether a job registry is mounted, and what may be done to a record. */
     readonly tasks: CapabilityState & {
@@ -875,3 +903,316 @@ export interface PreviewLogsSuccess {
 }
 /** Log read, or a classified failure. */
 export type PreviewLogsResult = PreviewLogsSuccess | PreviewFailure;
+/**
+ * How the browser should present one workspace file.
+ *
+ * The kinds are the browser's own vocabulary on purpose, not MIME types: `iframe` covers HTML,
+ * `markdown` covers a text file this panel renders itself, `image`/`media`/`pdf` are handed
+ * straight to a native element, `text` is shown in the monospace reader, and `other` is the honest
+ * "there is nothing to render here" state that still offers the file's size and its OS application.
+ */
+export type PreviewFileKind = 'iframe' | 'markdown' | 'image' | 'media' | 'pdf' | 'text' | 'other';
+/** What one workspace file is, and where it can be framed from. */
+export interface PreviewFileInfo {
+    /** Absolute Host path that was resolved and contained. */
+    readonly path: string;
+    /** Basename, for a title. */
+    readonly name: string;
+    /** How the browser should present it. */
+    readonly kind: PreviewFileKind;
+    /** MIME type for the frame's response, or `text/plain` for a kind that is never framed. */
+    readonly contentType: string;
+    /** Size on disk in bytes. */
+    readonly bytes: number;
+    /**
+     * Whether the file is small enough for `previewMaxFileBytes`.
+     *
+     * A file over the cap is reported, not refused: the panel shows the size and the OS application,
+     * which is more useful than an error about a limit nobody can see.
+     */
+    readonly withinLimit: boolean;
+    /**
+     * Same-origin URL the file can be framed from, when the Host serves files.
+     *
+     * Absent when no `webServer` is mounted; then only the non-framed kinds are offered.
+     */
+    readonly url?: string;
+    /**
+     * Opaque token that changes when the file's content or size does.
+     *
+     * The panel re-reads it on a quiet poll and reloads the frame when it moves, which is what makes
+     * an edit on disk show up without a manual refresh. Deliberately not a timestamp: a backend may
+     * not expose one, and a token is the interface `ctx.fs` already offers.
+     */
+    readonly token: string;
+    /** True when the file is a regular file; a directory or a socket is reported as `other`. */
+    readonly regular: boolean;
+}
+/** Why a file could not be described. */
+export type PreviewFileFailureCode = 
+/** No filesystem capability is mounted. */
+'no-filesystem'
+/** The workspace or the path left the workspace. */
+ | 'path-denied'
+/** Nothing is at the path, or it is not a regular file. */
+ | 'not-a-file'
+/** The filesystem refused the metadata read; the message carries its error. */
+ | 'read-failed';
+/** A classified file-info failure, carried as a value. */
+export interface PreviewFileFailure {
+    readonly ok: false;
+    readonly code: PreviewFileFailureCode;
+    readonly message: string;
+}
+/** File metadata, or a classified failure. */
+export type PreviewFileInfoResult = ({
+    readonly ok: true;
+} & PreviewFileInfo) | PreviewFileFailure;
+/** Describe one workspace file for the Preview panel. */
+export interface PreviewFileInfoRequest {
+    /** Absolute Host workspace directory the path must stay inside. */
+    readonly workspacePath: string;
+    /** Absolute Host path, or a path relative to the workspace — the panel sends what it has. */
+    readonly path: string;
+}
+/** Where an agent asked the panel to point itself. */
+export type PreviewRequestedMode = 'server' | 'file' | 'url' | 'scratchpad';
+/** Ask one panel: where are you, and can you take a command? */
+export interface PreviewBindRequest {
+    /** Identifies this browser tab, so commands reach the panel that answered last. */
+    readonly clientId: string;
+    /** The session whose panel this is. */
+    readonly sessionId: string;
+    /** Which mode the panel is showing. */
+    readonly mode: PreviewRequestedMode;
+    /** The file being previewed, when the mode is `file`. */
+    readonly filePath?: string;
+    /** The absolute workspace every path this panel sends must stay inside. */
+    readonly workspacePath?: string;
+    /** What the mode is currently pointing the frame at, when it points anywhere. */
+    readonly url?: string;
+    /** True when the frame's document is same-origin with the GUI, so the agent may inspect it. */
+    readonly inspectable: boolean;
+    /** Frame viewport height in CSS pixels. */
+    readonly width: number;
+    /** Frame viewport height in CSS pixels. */
+    readonly height: number;
+}
+/** One class of result an agent command can produce. */
+export type PreviewResultKind = 'open' | 'dom' | 'eval' | 'console' | 'click' | 'input' | 'reload' | 'resize' | 'close';
+/** One element of a DOM reading. */
+export interface PreviewDomNode {
+    /** Lower-case tag name. */
+    readonly tag: string;
+    /** `id` and `class` as one readable selector fragment, empty when the element has neither. */
+    readonly selector: string;
+    /** The element's own direct text, collapsed and cut. */
+    readonly text: string;
+    /** Computed `display`. */
+    readonly display: string;
+    /** Rendered border box in CSS pixels, relative to the frame's viewport. */
+    readonly box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Nesting depth below the requested root. */
+    readonly depth: number;
+}
+/** What one `dom` command answered. */
+export interface PreviewDomResult {
+    readonly kind: 'dom';
+    /** The selector the reading was taken from; empty means the document element. */
+    readonly selector: string;
+    /** The frame's inner size in CSS pixels. */
+    readonly viewport: {
+        width: number;
+        height: number;
+    };
+    /** Matching elements, breadth-first, capped by the tool's own ceiling. */
+    readonly nodes: readonly PreviewDomNode[];
+    /** The root element's `innerText`, collapsed and cut. */
+    readonly text: string;
+    /** True when the cap cut the walk short. */
+    readonly truncated: boolean;
+    /** The frame's URL as the browser reports it, so a redirect is visible. */
+    readonly url: string;
+}
+/** What one `eval` command answered. */
+export interface PreviewEvalResult {
+    readonly kind: 'eval';
+    /**
+     * The expression's value, serialized to JSON.
+     *
+     * A value JSON cannot represent arrives as its `String(value)` — plus a `note` — rather than
+     * failing the command: a DOM node or a function is an ordinary thing to evaluate to, and
+     * `"null"` with no explanation is a worse answer than `"[object HTMLDivElement]"`.
+     */
+    readonly value: string;
+    /** Why the value is not JSON, when it is not. */
+    readonly note?: string;
+    /** True when the value's JSON form was cut at the tool's ceiling. */
+    readonly truncated: boolean;
+}
+/** One buffered console line or uncaught error. */
+export interface PreviewConsoleEntry {
+    /** Which sink produced it. */
+    readonly level: 'log' | 'info' | 'warn' | 'error' | 'uncaught' | 'rejection';
+    /** The text, with its arguments joined. */
+    readonly text: string;
+    /** Epoch ms, in the frame's own clock. */
+    readonly at: number;
+}
+/** What one `console` command answered. */
+export interface PreviewConsoleResult {
+    readonly kind: 'console';
+    /** Entries after the requested cursor, oldest first. */
+    readonly entries: readonly PreviewConsoleEntry[];
+    /** Cursor to pass to the next `console` command. */
+    readonly cursor: number;
+    /** True when the requested cursor had already fallen out of the retained window. */
+    readonly lossy: boolean;
+}
+/** What one `reload`/`resize` command answered. */
+export interface PreviewAckResult {
+    readonly kind: 'ack';
+    /** One line describing what happened, for the tool's text block. */
+    readonly detail: string;
+    /** The viewport after the command, when it changed one. */
+    readonly width?: number;
+    /** The viewport height after the command, when it changed one. */
+    readonly height?: number;
+}
+/** Every successful command result. */
+export type PreviewCommandResult = PreviewDomResult | PreviewEvalResult | PreviewConsoleResult | PreviewAckResult;
+/** One command the panel must execute against its frame. */
+export interface PreviewCommand {
+    /** Echo of the request id, which the result must carry back. */
+    readonly id: string;
+    /** The panel this command belongs to; a panel ignores a command addressed elsewhere. */
+    readonly clientId: string;
+    /** What to do. */
+    readonly kind: PreviewResultKind;
+    /** CSS selector for `dom`, `click`, and `type`. */
+    readonly selector?: string;
+    /** JavaScript source for `eval`. */
+    readonly expression?: string;
+    /** Cursor already consumed by a previous `console`. */
+    readonly cursor?: number;
+    /** Text `type` must set before dispatching its events. */
+    readonly text?: string;
+    /** Key `type` must dispatch after setting the value, e.g. `Enter`. */
+    readonly key?: string;
+    /** Viewport `resize` must apply. */
+    readonly width?: number;
+    /** Viewport height `resize` must apply. */
+    readonly height?: number;
+    /** How long the panel may spend on it before giving up, in milliseconds. */
+    readonly timeoutMs: number;
+}
+/** Where an agent asked the panel to point itself, as a control message. */
+export interface PreviewOpenMessage {
+    /** The panel this message belongs to. */
+    readonly clientId: string;
+    /** Which mode to show. */
+    readonly mode: PreviewRequestedMode;
+    /** Which file to preview, when the mode is `file`. */
+    readonly filePath?: string;
+    /** Which URL to point at, when the mode is `url`. */
+    readonly url?: string;
+    /** Absolute workspace the file path is relative to. */
+    readonly workspacePath?: string;
+}
+/** Apply one open request to the panel's own state. */
+export interface PreviewControlMessage {
+    /** Discriminator for the message union. */
+    readonly control: 'open';
+    /** What to open. */
+    readonly open: PreviewOpenMessage;
+}
+/** Everything the panel must act on after one poll. */
+export interface PreviewMessage {
+    /** Commands to execute, oldest first. */
+    readonly commands: readonly PreviewCommand[];
+    /** Mode changes to apply. */
+    readonly controls: readonly PreviewControlMessage[];
+}
+/** Ask for the work queued against one panel. */
+export interface PreviewPollRequest {
+    /** The panel asking. */
+    readonly clientId: string;
+    /** The session that panel belongs to. */
+    readonly sessionId: string;
+    /** True while a preview is actually mounted; a closed panel stops claiming commands. */
+    readonly mounted: boolean;
+    /** What the panel is doing right now. */
+    readonly bind: PreviewBindRequest;
+}
+/** The panel's next work, or a classified failure. */
+export interface PreviewPollSuccess {
+    readonly ok: true;
+    /** The work, possibly empty. */
+    readonly message: PreviewMessage;
+    /**
+     * Epoch ms after which this poll's bind is stale.
+     *
+     * The panel echoes nothing back; it simply keeps polling. The Host uses the interval to decide
+     * that a tab was closed or navigated away, which is what makes the agent's next command fail with
+     * "no preview surface" instead of waiting out its timeout.
+     */
+    readonly bindTtlMs: number;
+}
+/** Why a panel could not be polled. */
+export type PreviewPollFailureCode = 
+/** No preview server capability is mounted, so there is nothing to report. */
+'no-subprocess'
+/** The plugin is unloading. */
+ | 'closed';
+/** A classified poll failure, carried as a value. */
+export interface PreviewPollFailure {
+    readonly ok: false;
+    readonly code: PreviewPollFailureCode;
+    readonly message: string;
+}
+/** Poll outcome. */
+export type PreviewPollResult = PreviewPollSuccess | PreviewPollFailure;
+/** Report what one command did. */
+export interface PreviewResultRequest {
+    /** The panel reporting. */
+    readonly clientId: string;
+    /** Echo of {@link PreviewCommand.id}. */
+    readonly id: string;
+    /** True when the command was executed. */
+    readonly ok: boolean;
+    /** Why it was not, when it was not. */
+    readonly error?: string;
+    /** What it produced, when it was. */
+    readonly result?: PreviewCommandResult;
+    /** Console entries observed since the panel last reported; appended to the Host's buffer. */
+    readonly console?: readonly PreviewConsoleEntry[];
+}
+/** Settlement of a result report. */
+export type PreviewResultAck = {
+    readonly ok: true;
+} | PreviewPollFailure;
+/** Say that a panel is closed, so its queued work is dropped. */
+export interface PreviewReleaseRequest {
+    /** The panel that closed. */
+    readonly clientId: string;
+}
+/** Settlement of a release. */
+export type PreviewReleaseResult = {
+    readonly ok: true;
+} | PreviewPollFailure;
+/** Where the same-origin preview routes live. */
+export interface PreviewSurfaceInfo {
+    /** Absolute path of the workspace-file route, without a trailing slash. */
+    readonly fileRoute: string;
+    /** Absolute path prefix of the loopback reverse proxy, without a trailing slash. */
+    readonly proxyRoute: string;
+    /** Whether this Host has a `webServer` capability at all. */
+    readonly available: boolean;
+    /** Why it does not, when it does not. */
+    readonly reason?: string;
+}

package/types/host/ui-bridge.d.ts

@@ -0,0 +1,197 @@
+/**
+ * The host↔browser channel behind the model-facing `ui_preview` tool.
+ *
+ * An out-of-tree plugin cannot add a wire frame, so there is no push channel from the Host to a
+ * browser tab: the browser half already polls this plugin's Typert endpoints, and the tool uses that
+ * same path backwards. A command is a record in a queue; the panel's driver polls for its queue,
+ * executes what it finds against the frame, and posts the result back. This module owns the queue,
+ * the results, and — most importantly — the deadlines, because a browser tab that is not there must
+ * fail a tool call with a sentence rather than hang it until the model's turn times out.
+ *
+ * Three pieces of state, and each one exists for a distinct failure:
+ *
+ * - **A per-panel queue** of undelivered work, with a hard cap. A panel that never polls cannot make
+ *   the Host hold an unbounded backlog.
+ * - **The in-flight records**, keyed by command id. This is what `await`s a result.
+ * - **A liveness stamp** per panel, refreshed by every poll. Without it, "the tool is waiting" and
+ *   "nobody is looking at the panel" are indistinguishable, and the operator gets a timeout instead
+ *   of an explanation.
+ *
+ * Nothing here is model-facing and nothing here is trusted: the panel that posts a result is the
+ * operator's own browser, but the payload is validated by shape before it is handed to a tool.
+ * @module @achasoft/dsh-advanced-sidebar/host/ui-bridge
+ */
+import type { PreviewBindRequest, PreviewCommand, PreviewCommandResult, PreviewConsoleEntry, PreviewControlMessage, PreviewMessage } from './types.ts';
+/** Queue and liveness configuration, read from the settings section per call. */
+export interface BridgeOptions {
+    /** How long one command waits for its result before the tool reports a timeout. */
+    readonly commandTimeoutMs: number;
+    /** How long a bind is trusted after its last poll. */
+    readonly bindTtlMs: number;
+    /** Injected clock, so a test can move time without waiting for it. */
+    readonly now?: () => number;
+}
+/** Outcome of queueing a command: either an answer, or why there will not be one. */
+export type QueueOutcome = {
+    readonly ok: true;
+    readonly result: PreviewCommandResult;
+} | {
+    readonly ok: false;
+    readonly code: 'no-surface' | 'timeout';
+    readonly message: string;
+};
+/**
+ * The command queue, the panel registry, and the console buffer.
+ *
+ * Held by the Host service and disposed with it, so no timer survives an unload.
+ */
+export declare class PreviewBindings {
+    private readonly options;
+    private readonly panels;
+    /**
+     * Panels that said they were done, so a later bind cannot resurrect them.
+     *
+     * A closed dock's queued work must fail, and "closed" is a fact only the browser knows: without
+     * this, a bind request the Host never asked for would put a dead tab back on the roster and the
+     * model would wait on it. A fresh mount generates a fresh client id, so a reload is unaffected.
+     */
+    private readonly retired;
+    private readonly inFlight;
+    private closed;
+    /**
+     * @param options - reads the current deadlines; called per operation so an edited settings
+     * section reaches the next command with no registration to rebuild.
+     */
+    constructor(options: () => BridgeOptions);
+    /** How many panels have polled recently enough to be considered present. */
+    get livePanels(): number;
+    /**
+     * Record a panel's state. Called by every poll, so it doubles as the liveness heartbeat.
+     * @param bind - what the panel reported.
+     * @returns the panel's id, for a caller that wants to address it later.
+     */
+    bind(bind: PreviewBindRequest): string;
+    /**
+     * Take everything queued for one panel.
+     *
+     * The poll is also the heartbeat, so a stale panel is refreshed even when it has no work: what the
+     * tool needs to know is that the tab is alive, not that it is busy.
+     * @param clientId - the panel asking.
+     * @param mounted - whether a preview surface is actually rendered; false leaves the queue alone.
+     * @param console - entries the panel observed since its last report.
+     * @returns the work to execute and the interval after which this poll is stale.
+     */
+    poll(clientId: string, mounted: boolean, console?: readonly PreviewConsoleEntry[]): {
+        message: PreviewMessage;
+        bindTtlMs: number;
+    };
+    /**
+     * A panel's state, or the panel itself when it has never reported in.
+     *
+     * This is what lets a tool call wake a dock that has not polled yet — the operator opens the
+     * Preview panel and a model asks for a DOM reading in the same second. Only the FIRST bind is
+     * stored without a poll behind it: once a panel is known, its liveness rules, so a closed tab
+     * cannot be resurrected by a bind request it never sent.
+     * @param bind - what the panel reported.
+     * @returns nothing; the caller polls afterwards.
+     */
+    bindAt(bind: PreviewBindRequest): void;
+    /**
+     * Record what one command did, and append any console lines it carried.
+     *
+     * A result whose command already timed out is accepted and dropped: the deadline fired, the tool
+     * has its answer, and an operator's panel must not be told its report was invalid. A result of the
+     * WRONG KIND is a different matter — it means the two halves disagree about the command, which is
+     * a defect worth reporting rather than a late answer worth ignoring.
+     * @param clientId - the panel reporting.
+     * @param id - the command id.
+     * @param outcome - success with a result, or the reason it failed.
+     * @param console - entries the panel observed alongside the result.
+     * @returns true when the id matched an in-flight command.
+     */
+    post(clientId: string, id: string, outcome: {
+        ok: true;
+        result: PreviewCommandResult;
+    } | {
+        ok: false;
+        error: string;
+    }, console?: readonly PreviewConsoleEntry[]): boolean;
+    /**
+     * Forget a panel and fail everything it was holding.
+     * @param clientId - the panel that closed.
+     */
+    release(clientId: string): void;
+    /**
+     * Whether one panel is present and able to take a command.
+     * @param clientId - the panel id, or undefined to ask about any panel in a session.
+     * @param sessionId - the session the panel must belong to.
+     * @returns the live panel's id, or undefined.
+     */
+    active(sessionId?: string, clientId?: string): string | undefined;
+    /**
+     * The last thing one panel reported about itself.
+     * @param clientId - the panel id.
+     * @returns the bind, or undefined for a panel this Host has not heard from.
+     */
+    bindOf(clientId: string): PreviewBindRequest | undefined;
+    /**
+     * Queue one command against a live panel and wait for its answer.
+     *
+     * Every path out of here is bounded: a missing panel refuses immediately, a queue that is full
+     * refuses immediately, and a delivered command that is never answered fails on its own deadline.
+     * The one thing this must never do is wait for a browser that is not going to answer.
+     * @param sessionId - the session whose panel should execute it.
+     * @param command - the command body, without its id or its panel.
+     * @returns the result, or the reason there is none.
+     */
+    queue(sessionId: string, command: Omit<PreviewCommand, 'id' | 'clientId' | 'timeoutMs'> & {
+        timeoutMs?: number;
+    }): Promise<QueueOutcome>;
+    /**
+     * Queue one command against one known panel, without requiring it to be live.
+     *
+     * Used by `open`, which must be able to hand a mode change to a panel before that panel has had a
+     * chance to poll — the very first call against a freshly opened dock.
+     * @param clientId - the panel id.
+     * @param command - the command body.
+     * @returns the result, or the reason there is none.
+     */
+    send(clientId: string, command: Omit<PreviewCommand, 'id' | 'clientId' | 'timeoutMs'> & {
+        timeoutMs?: number;
+    }): Promise<QueueOutcome>;
+    /**
+     * Queue a mode change that needs no answer.
+     * @param clientId - the panel to change.
+     * @param control - what to change.
+     * @returns false when the panel is unknown.
+     */
+    control(clientId: string, control: PreviewControlMessage): boolean;
+    /** Forget every panel and fail everything in flight. Called from the plugin's teardown. */
+    dispose(): void;
+    /**
+     * One panel's liveness.
+     * @param panel - the panel.
+     * @returns true when its last poll is inside the trust window.
+     */
+    private isLive;
+    /** The configured clock. */
+    private now;
+    /**
+     * Append console entries to a panel's window, dropping the oldest past the cap.
+     * @param panel - the panel.
+     * @param entries - entries observed since the last report.
+     */
+    private appendConsole;
+    /**
+     * Fail every command one panel is holding and drop its queue.
+     * @param clientId - the panel.
+     * @param reason - the sentence the tool reports.
+     */
+    private dropPanelWork;
+    /**
+     * Resolve one in-flight command and forget it.
+     * @param record - the record.
+     * @param outcome - what to resolve with.
+     */
+    private finish;
+}

package/types/host/ui-preview-tool.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `ui_preview` — the model's hands and eyes on the Preview panel.
+ *
+ * This is the point of the whole same-origin preview story. A page rendered in the panel is
+ * same-origin with the GUI, so a small driver in the panel can read its DOM, run an expression in
+ * it, and dispatch a real click — and the model can ask for exactly that through one tool. Without
+ * it, "look at your UI" means asking a person to describe a screenshot.
+ *
+ * One tool with an `action` discriminant is the right shape here, unlike this monorepo's own task
+ * tools: every action addresses the same one surface, the arguments genuinely differ per action, and
+ * the alternative — nine tools — would spend nine descriptions on one subject. The conditional
+ * argument requirements that shape normally costs are paid for with an explicit `require…` check per
+ * action, which returns a sentence naming the missing argument instead of a schema failure the model
+ * cannot read.
+ *
+ * **The trust boundary.** Everything this tool accepts is untrusted model input:
+ *
+ * - `open` with a `path` and every `file` argument are resolved through `resolveWorkspace` /
+ *   `resolveInside` before anything reads them, so a path cannot leave the session's workspace. A
+ *   missing workspace is a refusal, never a guess.
+ * - `open` with a `url` accepts any `http(s)` URL, which is the same latitude the panel gives a
+ *   person typing into its address bar. The Host's proxy that actually fetches a loopback target
+ *   refuses every non-loopback host on its own, so a model cannot use this tool to fetch an intranet
+ *   service through the GUI.
+ * - `eval` runs inside the preview frame's own origin, which the panel has already pointed at either
+ *   a same-origin route, a loopback dev server through the Host's proxy, or a URL a person typed.
+ *   It can therefore reach nothing the frame itself could not.
+ *
+ * Every call is bounded. The command queue refuses immediately when no panel is open, fails a
+ * delivered command on its own deadline, and returns the reason — a hung tool call would be worse
+ * than a failed one, because the model cannot tell the difference between "slow" and "gone".
+ * @module @achasoft/dsh-advanced-sidebar/host/ui-preview-tool
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { PreviewCommand } from './types.ts';
+/** Cordis plugin name for the model-facing tool. */
+export declare const name = "advanced-sidebar-ui-preview";
+/** The tool registry and the sidebar service both have to be present for this tool to mean anything. */
+export declare const inject: string[];
+/** Deployment configuration for the UI preview tool. */
+export interface Config {
+    /** How long one command waits for the panel to answer, in milliseconds. */
+    commandTimeoutMs: number;
+}
+/** Schemastery configuration for the tool. */
+export declare const Config: z<Config>;
+/**
+ * One command body, as the service accepts it: everything but the id, the panel, and the deadline,
+ * which the queue owns.
+ */
+export type PreviewCommandBody = Omit<PreviewCommand, 'id' | 'clientId' | 'timeoutMs'> & {
+    timeoutMs?: number;
+};
+/**
+ * Register the model-facing UI preview tool.
+ * @param ctx - registrant context carrying the tool registry and the sidebar service.
+ * @param config - the deployment's tool configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;

package/types/index.d.ts

@@ -1,6 +1,6 @@
 /**
- * `@achasoft/dsh-advanced-sidebar` root entry — two roles in one module, because the client module
- * system requires them together.
+ * `@achasoft/dsh-advanced-sidebar` root entry — three roles in one module, because the client module
+ * system requires two of them together.
  *
  * **As a plugin**, this is the advanced sidebar's node half. The apply is empty: the browser half
  * ships via `exports["./client"]` and is discovered through the package's `dsh.client` declaration.
@@ -10,6 +10,10 @@
  *
  * **As a library**, it re-exports the wire contract, so another package can type against the
  * `advancedSidebar` namespace without depending on the Host endpoint or the browser surface.
+ *
+ * The agent-facing `ui_preview` tool ships as its own entry (`exports["./ui-preview"]`) and its own
+ * composition row, so a deployment that wants the sidebar but not a model-facing verb simply leaves
+ * that row out — and the row's own `inject` is what makes the tool wait for the service it calls.
  * @module @achasoft/dsh-advanced-sidebar
  */
 export type * from './host/types.ts';

package/types/ui-preview.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@achasoft/dsh-advanced-sidebar/ui-preview` — the row the agent-facing `ui_preview` tool mounts on.
+ *
+ * It is a separate entry, and a separate composition row, for one reason: the tool calls the
+ * `advancedSidebar` service, and a row's `inject` is what makes Cordis wait for a service instead of
+ * handing the plugin a context that cannot reach it. Re-exporting here rather than registering from
+ * the root entry also keeps the tool out of a deployment that composes the sidebar surface without
+ * wanting a model-facing verb on it: leave the row out, and the tool does not exist.
+ * @module @achasoft/dsh-advanced-sidebar/ui-preview
+ */
+export { Config, apply, inject, name } from './host/ui-preview-tool.ts';