dsh-surface-bridge 0.1.0-alpha.1

package/lib/types/host/routes.js

@@ -0,0 +1,108 @@
+/**
+ * The bridge's Host HTTP surface.
+ *
+ * Two exact routes under `/api/data-canvas/`, registered on DSH's shared API
+ * channel so they inherit the platform's trust and authentication fence instead of
+ * opening a second server. Both serve one long poll: the surface asks for work and
+ * reports what happened. Nothing is pushed to the Host on a selection change, so
+ * there is no ingest route to validate — see `narrow.ts` for the validation that
+ * still guards a read answer.
+ *
+ * @module dsh-surface-bridge/host/routes
+ */
+import { OPS_PATH, SETTLE_PATH } from "../contract.js";
+import { DEFAULT_POLL_HOLD_MS } from "./store.js";
+export { OPS_PATH, SETTLE_PATH };
+/** Build a JSON failure body. */
+function fail(status, error) {
+    const body = { ok: false, error };
+    return Response.json(body, { status });
+}
+/** Read and parse a JSON body, answering the failure response the route should return. */
+async function readJson(request) {
+    const contentType = request.headers.get('content-type') ?? '';
+    if (!contentType.toLowerCase().startsWith('application/json')) {
+        return { ok: false, response: fail(415, '请求必须使用 application/json') };
+    }
+    try {
+        return { ok: true, value: await request.json() };
+    }
+    catch {
+        return { ok: false, response: fail(400, '请求体不是合法 JSON') };
+    }
+}
+/** Narrow one operation result reported by a surface. */
+function narrowResult(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    if (typeof raw.id !== 'string' || raw.id.length === 0)
+        return undefined;
+    if (typeof raw.ok !== 'boolean')
+        return undefined;
+    return {
+        id: raw.id,
+        ok: raw.ok,
+        ...(typeof raw.detail === 'string' ? { detail: raw.detail } : {}),
+        ...(typeof raw.error === 'string' ? { error: raw.error } : {}),
+        // A read answer rides here; the service validates it before anyone reads it.
+        ...(raw.value === undefined ? {} : { value: raw.value }),
+    };
+}
+/**
+ * Build every route the bridge serves.
+ *
+ * @param store - The bridge's Session-keyed state.
+ * @returns the exact Fetch routes to register on DSH's shared API channel.
+ */
+export function surfaceBridgeRoutes(store) {
+    return [
+        {
+            path: OPS_PATH,
+            methods: ['GET'],
+            requestBody: 'buffered',
+            fetch: async (request) => {
+                const url = new URL(request.url);
+                const sessionId = url.searchParams.get('sessionId');
+                if (sessionId === null || sessionId.length === 0)
+                    return fail(400, 'sessionId 必填');
+                const holdParam = url.searchParams.get('hold');
+                const hold = holdParam === null ? DEFAULT_POLL_HOLD_MS : Math.max(0, Math.min(DEFAULT_POLL_HOLD_MS, Number(holdParam) || 0));
+                const operations = await store.poll(sessionId, hold, request.signal);
+                const response = { operations };
+                return Response.json(response, { headers: { 'cache-control': 'no-store' } });
+            },
+        },
+        {
+            path: SETTLE_PATH,
+            methods: ['POST'],
+            requestBody: 'buffered',
+            fetch: async (request) => {
+                const body = await readJson(request);
+                if (!body.ok)
+                    return body.response;
+                const payload = body.value;
+                if (typeof payload !== 'object' || payload === null || typeof payload.sessionId !== 'string' || payload.sessionId.length === 0) {
+                    return fail(400, 'sessionId 必填');
+                }
+                const result = narrowResult(payload.result);
+                if (result === undefined)
+                    return fail(400, 'result 缺字段');
+                const accepted = store.settle(payload.sessionId, result);
+                const response = { accepted };
+                return Response.json(response);
+            },
+        },
+    ];
+}
+/**
+ * Register every bridge route for the lifetime of `ctx`.
+ *
+ * @param ctx - Plugin context; registrations are disposed with it.
+ * @param store - The bridge's Session-keyed state.
+ */
+export function registerSurfaceBridgeRoutes(ctx, store) {
+    for (const route of surfaceBridgeRoutes(store)) {
+        ctx.effect(() => ctx.connection.fetch.register(route), `dsh-surface-bridge: ${route.path}`);
+    }
+}

package/lib/types/host/service.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The bridge's Host service face: what a business plugin's tools call.
+ *
+ * A business plugin never touches the store or the routes. It asks three
+ * questions — "what is selected", "is the surface open", "please do this" — and
+ * the bridge owns how each is answered. "What is selected" is a *question*, not a
+ * cached value: nothing is remembered between steps. Keeping the face this small is what makes
+ * a second surface adoptable: nothing in it is canvas-shaped.
+ *
+ * @module dsh-surface-bridge/host/service
+ */
+import type { SurfaceApplyOperation, SurfaceBridgeHostFace, SurfaceOperationResult, SurfaceSelection } from '../contract.ts';
+import { SurfaceBridgeStore } from './store.ts';
+export type { SurfaceApplyOperation, SurfaceBridgeHostFace } from '../contract.ts';
+/** The bridge's Host service implementation. */
+export declare class SurfaceBridgeHost implements SurfaceBridgeHostFace {
+    private readonly store;
+    /** @param store - Shared Session-keyed bridge state. */
+    constructor(store: SurfaceBridgeStore);
+    /** @inheritdoc */
+    readSelections(sessionId: string, signal?: AbortSignal): Promise<readonly SurfaceSelection[] | undefined>;
+    /** @inheritdoc */
+    consumeSelections(sessionId: string, signal?: AbortSignal): Promise<readonly SurfaceSelection[] | undefined>;
+    /**
+     * One read, peeking or consuming.
+     *
+     * @param sessionId - Session whose surfaces are asked.
+     * @param signal - Aborts the wait when the turn is cancelled.
+     * @param consume - Whether the surface should spend its selection answering.
+     * @returns the valid selections that came back.
+     */
+    private readInternal;
+    /** @inheritdoc */
+    readSelection(sessionId: string, source: string, signal?: AbortSignal): Promise<SurfaceSelection | null | undefined>;
+    /** @inheritdoc */
+    isSurfaceLive(sessionId: string): boolean;
+    /** @inheritdoc */
+    apply(sessionId: string, source: string, operations: readonly SurfaceApplyOperation[], signal?: AbortSignal): Promise<readonly SurfaceOperationResult[]>;
+    /** Release one Session's state. */
+    forget(sessionId: string): void;
+}

package/lib/types/host/service.js

@@ -0,0 +1,93 @@
+/**
+ * The bridge's Host service face: what a business plugin's tools call.
+ *
+ * A business plugin never touches the store or the routes. It asks three
+ * questions — "what is selected", "is the surface open", "please do this" — and
+ * the bridge owns how each is answered. "What is selected" is a *question*, not a
+ * cached value: nothing is remembered between steps. Keeping the face this small is what makes
+ * a second surface adoptable: nothing in it is canvas-shaped.
+ *
+ * @module dsh-surface-bridge/host/service
+ */
+import { narrowSelection } from "./narrow.js";
+import { DEFAULT_OPERATION_TIMEOUT_MS, DEFAULT_READ_TIMEOUT_MS } from "./store.js";
+/** The bridge's Host service implementation. */
+export class SurfaceBridgeHost {
+    store;
+    /** @param store - Shared Session-keyed bridge state. */
+    constructor(store) {
+        this.store = store;
+    }
+    /** @inheritdoc */
+    async readSelections(sessionId, signal) {
+        return await this.readInternal(sessionId, signal, false);
+    }
+    /** @inheritdoc */
+    async consumeSelections(sessionId, signal) {
+        return await this.readInternal(sessionId, signal, true);
+    }
+    /**
+     * One read, peeking or consuming.
+     *
+     * @param sessionId - Session whose surfaces are asked.
+     * @param signal - Aborts the wait when the turn is cancelled.
+     * @param consume - Whether the surface should spend its selection answering.
+     * @returns the valid selections that came back.
+     */
+    async readInternal(sessionId, signal, consume) {
+        const answer = await this.store.readSelections(sessionId, DEFAULT_READ_TIMEOUT_MS, signal, consume);
+        // Nothing answered: that is not the same fact as "nothing is selected", and the
+        // callers that can tell the user the difference must be able to.
+        if (answer === undefined)
+            return undefined;
+        const out = [];
+        for (const entry of answer) {
+            // The surface is trusted code, but it is still a browser boundary: a shape
+            // the renderer does not expect must not reach a model, and one bad member
+            // must not discard the rest of the answer.
+            const narrowed = narrowSelection(entry);
+            if (narrowed.ok && narrowed.selection.count > 0)
+                out.push(narrowed.selection);
+        }
+        return out;
+    }
+    /** @inheritdoc */
+    async readSelection(sessionId, source, signal) {
+        const all = await this.readSelections(sessionId, signal);
+        if (all === undefined)
+            return undefined;
+        return all.find(selection => selection.source === source) ?? null;
+    }
+    /** @inheritdoc */
+    isSurfaceLive(sessionId) {
+        return this.store.isSurfaceLive(sessionId);
+    }
+    /** @inheritdoc */
+    async apply(sessionId, source, operations, signal) {
+        if (operations.length === 0)
+            return [];
+        if (!this.store.isSurfaceLive(sessionId)) {
+            return operations.map(() => ({
+                id: '',
+                ok: false,
+                error: '画布未打开：请在右侧栏打开该画布标签页后重试。',
+            }));
+        }
+        const queued = operations.map(operation => this.store.enqueue(sessionId, source, operation.op, operation.payload));
+        return await Promise.all(queued.map(async (operation) => {
+            const result = await this.store.awaitResult(sessionId, operation.id, DEFAULT_OPERATION_TIMEOUT_MS, signal);
+            if (result === undefined) {
+                return {
+                    id: operation.id,
+                    ok: false,
+                    error: '画布未在超时内回传执行结果（可能已关闭或正在重绘）。',
+                };
+            }
+            return result;
+        }));
+    }
+    /** Release one Session's state. */
+    forget(sessionId) {
+        this.store.forget(sessionId);
+    }
+}

package/lib/types/host/store.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Host-side state of the surface bridge: one pending selection and one operation
+ * queue per Session, plus the liveness stamp that lets a write-back tool fail
+ * loudly instead of pretending a closed surface accepted its edit.
+ *
+ * Everything here is in-memory and process-local by design. A selection is a
+ * snapshot of what the user is looking at right now; persisting it across a
+ * restart would resurrect a context the user never chose in this process. The
+ * operation queue is a handoff channel between two halves of one running app,
+ * so it has no meaning once either half is gone.
+ *
+ * @module dsh-surface-bridge/host/store
+ */
+import type { SurfaceOperation, SurfaceOperationResult } from '../contract.ts';
+/** How long a poll may hold before it answers empty, in milliseconds. */
+export declare const DEFAULT_POLL_HOLD_MS = 20000;
+/** How long after the last poll a surface is still considered open. */
+export declare const SURFACE_LIVENESS_MS = 45000;
+/** How long a write-back tool waits for the surface to report a result. */
+export declare const DEFAULT_OPERATION_TIMEOUT_MS = 25000;
+/**
+ * How long a model step waits for a surface to answer a read.
+ *
+ * Short on purpose: a live surface is already parked on a poll, so an answer is a
+ * round trip on an idle connection. If it does not come, the step proceeds without
+ * the selection rather than delaying the user's message.
+ */
+export declare const DEFAULT_READ_TIMEOUT_MS = 600;
+/** The bridge's Host state, keyed by Session id. */
+export declare class SurfaceBridgeStore {
+    private readonly sessions;
+    /** Resolve one Session's state, creating it on first use. */
+    private stateOf;
+    /** Wake every waiter of one Session. */
+    private wake;
+    /** Whether any surface of one Session has polled recently enough to be considered open. */
+    isSurfaceLive(sessionId: string, now?: number): boolean;
+    /** Queue one operation for a surface and return it with its minted id. */
+    enqueue(sessionId: string, source: string, op: string, payload: unknown): SurfaceOperation;
+    /**
+     * Ask a live surface what it has selected, and wait for its answer.
+     *
+     * Implemented on the operation queue rather than as its own channel: the browser
+     * already holds a poll open, so a read is one enqueue plus the answer the loop
+     * sends back. A surface that is closed answers nothing, and the read gives up
+     * rather than holding a model step open.
+     *
+     * @param sessionId - Session whose surfaces are asked.
+     * @param timeoutMs - Bound on the wait.
+     * @param signal - Aborts the wait when the turn is cancelled.
+     * @param consume - Whether the surface should spend its selection answering this.
+     * @returns the raw answer (an array of selections), or `undefined` when nothing answered.
+     */
+    readSelections(sessionId: string, timeoutMs: number, signal?: AbortSignal, consume?: boolean): Promise<readonly unknown[] | undefined>;
+    /**
+     * Take the operations waiting for one Session, holding the request open until
+     * something arrives or the hold expires.
+     *
+     * A long poll rather than a socket: the surface already runs a fetch loop, and
+     * a held request is one line of client code with no reconnect protocol of its
+     * own. The hold is bounded so a broken connection cannot pin a handler forever.
+     *
+     * @param sessionId - Session whose surface is polling.
+     * @param holdMs - Maximum time to hold before answering empty.
+     * @param signal - Aborts the hold when the browser goes away.
+     * @returns the queued operations, oldest first.
+     */
+    poll(sessionId: string, holdMs: number, signal?: AbortSignal): Promise<readonly SurfaceOperation[]>;
+    /** Record a surface-reported result and wake whoever is waiting for it. */
+    settle(sessionId: string, result: SurfaceOperationResult): boolean;
+    /**
+     * Wait for one operation's result.
+     *
+     * @param sessionId - Session that owns the operation.
+     * @param operationId - Operation to await.
+     * @param timeoutMs - Bound on the wait; a timeout is a real failure the caller reports.
+     * @param signal - Aborts the wait when the Agent turn is cancelled.
+     * @returns the result, or `undefined` when the surface never reported.
+     */
+    awaitResult(sessionId: string, operationId: string, timeoutMs: number, signal?: AbortSignal): Promise<SurfaceOperationResult | undefined>;
+    /** Forget one Session's whole bridge state (Session teardown). */
+    forget(sessionId: string): void;
+    /** Every Session currently holding bridge state; used by teardown sweeps. */
+    sessions_(): readonly string[];
+}

package/lib/types/host/store.js

@@ -0,0 +1,206 @@
+/**
+ * Host-side state of the surface bridge: one pending selection and one operation
+ * queue per Session, plus the liveness stamp that lets a write-back tool fail
+ * loudly instead of pretending a closed surface accepted its edit.
+ *
+ * Everything here is in-memory and process-local by design. A selection is a
+ * snapshot of what the user is looking at right now; persisting it across a
+ * restart would resurrect a context the user never chose in this process. The
+ * operation queue is a handoff channel between two halves of one running app,
+ * so it has no meaning once either half is gone.
+ *
+ * @module dsh-surface-bridge/host/store
+ */
+import { READ_SELECTION_OP } from "../contract.js";
+/** How long a poll may hold before it answers empty, in milliseconds. */
+export const DEFAULT_POLL_HOLD_MS = 20_000;
+/** How long after the last poll a surface is still considered open. */
+export const SURFACE_LIVENESS_MS = 45_000;
+/** How long a write-back tool waits for the surface to report a result. */
+export const DEFAULT_OPERATION_TIMEOUT_MS = 25_000;
+/**
+ * How long a model step waits for a surface to answer a read.
+ *
+ * Short on purpose: a live surface is already parked on a poll, so an answer is a
+ * round trip on an idle connection. If it does not come, the step proceeds without
+ * the selection rather than delaying the user's message.
+ */
+export const DEFAULT_READ_TIMEOUT_MS = 600;
+/** The bridge's Host state, keyed by Session id. */
+export class SurfaceBridgeStore {
+    sessions = new Map();
+    /** Resolve one Session's state, creating it on first use. */
+    stateOf(sessionId) {
+        const existing = this.sessions.get(sessionId);
+        if (existing !== undefined)
+            return existing;
+        const created = {
+            queued: [],
+            settled: new Map(),
+            waiters: new Set(),
+            lastPollAt: 0,
+            operationSeq: 0,
+            released: false,
+        };
+        this.sessions.set(sessionId, created);
+        return created;
+    }
+    /** Wake every waiter of one Session. */
+    wake(state) {
+        for (const waiter of [...state.waiters])
+            waiter();
+    }
+    /** Whether any surface of one Session has polled recently enough to be considered open. */
+    isSurfaceLive(sessionId, now = Date.now()) {
+        const state = this.sessions.get(sessionId);
+        if (state === undefined)
+            return false;
+        return now - state.lastPollAt <= SURFACE_LIVENESS_MS;
+    }
+    /** Queue one operation for a surface and return it with its minted id. */
+    enqueue(sessionId, source, op, payload) {
+        const state = this.stateOf(sessionId);
+        state.operationSeq += 1;
+        const operation = {
+            id: `${sessionId}:${state.operationSeq}`,
+            source,
+            op,
+            payload,
+        };
+        state.queued.push(operation);
+        this.wake(state);
+        return operation;
+    }
+    /**
+     * Ask a live surface what it has selected, and wait for its answer.
+     *
+     * Implemented on the operation queue rather than as its own channel: the browser
+     * already holds a poll open, so a read is one enqueue plus the answer the loop
+     * sends back. A surface that is closed answers nothing, and the read gives up
+     * rather than holding a model step open.
+     *
+     * @param sessionId - Session whose surfaces are asked.
+     * @param timeoutMs - Bound on the wait.
+     * @param signal - Aborts the wait when the turn is cancelled.
+     * @param consume - Whether the surface should spend its selection answering this.
+     * @returns the raw answer (an array of selections), or `undefined` when nothing answered.
+     */
+    async readSelections(sessionId, timeoutMs, signal, consume = false) {
+        // No answer can come if nothing is polling: the surface is closed, or its tab
+        // was never opened in this Session.
+        if (!this.isSurfaceLive(sessionId))
+            return undefined;
+        const request = this.enqueue(sessionId, '*', READ_SELECTION_OP, { consume });
+        const result = await this.awaitResult(sessionId, request.id, timeoutMs, signal);
+        if (result === undefined || !result.ok)
+            return undefined;
+        return Array.isArray(result.value) ? result.value : [];
+    }
+    /**
+     * Take the operations waiting for one Session, holding the request open until
+     * something arrives or the hold expires.
+     *
+     * A long poll rather than a socket: the surface already runs a fetch loop, and
+     * a held request is one line of client code with no reconnect protocol of its
+     * own. The hold is bounded so a broken connection cannot pin a handler forever.
+     *
+     * @param sessionId - Session whose surface is polling.
+     * @param holdMs - Maximum time to hold before answering empty.
+     * @param signal - Aborts the hold when the browser goes away.
+     * @returns the queued operations, oldest first.
+     */
+    async poll(sessionId, holdMs, signal) {
+        const state = this.stateOf(sessionId);
+        state.lastPollAt = Date.now();
+        if (state.queued.length > 0)
+            return state.queued.splice(0, state.queued.length);
+        if (holdMs <= 0 || signal?.aborted === true)
+            return [];
+        await new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                state.waiters.delete(onWake);
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onWake);
+                resolve();
+            };
+            const onWake = () => { finish(); };
+            const timer = setTimeout(finish, holdMs);
+            state.waiters.add(onWake);
+            signal?.addEventListener('abort', onWake, { once: true });
+        });
+        return state.queued.splice(0, state.queued.length);
+    }
+    /** Record a surface-reported result and wake whoever is waiting for it. */
+    settle(sessionId, result) {
+        const state = this.sessions.get(sessionId);
+        if (state === undefined)
+            return false;
+        state.settled.set(result.id, result);
+        this.wake(state);
+        return true;
+    }
+    /**
+     * Wait for one operation's result.
+     *
+     * @param sessionId - Session that owns the operation.
+     * @param operationId - Operation to await.
+     * @param timeoutMs - Bound on the wait; a timeout is a real failure the caller reports.
+     * @param signal - Aborts the wait when the Agent turn is cancelled.
+     * @returns the result, or `undefined` when the surface never reported.
+     */
+    async awaitResult(sessionId, operationId, timeoutMs, signal) {
+        const state = this.stateOf(sessionId);
+        const immediate = state.settled.get(operationId);
+        if (immediate !== undefined) {
+            state.settled.delete(operationId);
+            return immediate;
+        }
+        if (signal?.aborted === true)
+            return undefined;
+        return await new Promise((resolve) => {
+            let settled = false;
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                state.waiters.delete(onWake);
+                clearTimeout(timer);
+                signal?.removeEventListener('abort', onWake);
+                resolve(result);
+            };
+            const onWake = () => {
+                if (signal?.aborted === true || state.released) {
+                    finish(undefined);
+                    return;
+                }
+                const result = state.settled.get(operationId);
+                if (result === undefined)
+                    return;
+                state.settled.delete(operationId);
+                finish(result);
+            };
+            const timer = setTimeout(() => { finish(undefined); }, timeoutMs);
+            state.waiters.add(onWake);
+            signal?.addEventListener('abort', onWake, { once: true });
+        });
+    }
+    /** Forget one Session's whole bridge state (Session teardown). */
+    forget(sessionId) {
+        const state = this.sessions.get(sessionId);
+        if (state === undefined)
+            return;
+        // Mark before waking: a waiter must see the release and stop waiting, not
+        // look up a result that will never arrive.
+        state.released = true;
+        this.sessions.delete(sessionId);
+        this.wake(state);
+    }
+    /** Every Session currently holding bridge state; used by teardown sweeps. */
+    sessions_() {
+        return [...this.sessions.keys()];
+    }
+}

package/lib/types/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Node half of dsh-surface-bridge.
+ *
+ * The bridge exists so a right-Sidebar business surface can hand a selection to
+ * the composer once, and have it arrive in the model step as real context. This
+ * half owns the two things that must be unique per process: the Session-keyed
+ * selection/operation state, and the `agent/pre-step` listener that turns a read
+ * selection into **two** durable messages — one visible row the person can see (a
+ * file chip for the drawing, plus a one-line summary) and one hidden row carrying
+ * the element table the model works from.
+ *
+ * Why a mounted bundle rather than a shared library: a library would be inlined
+ * into each consuming plugin's own bundle, giving every consumer its own service
+ * instance and its own composer chip. The uniqueness the seam needs — one chip,
+ * one injection point — can only be guaranteed by the Loader mounting one bundle.
+ *
+ * @module dsh-surface-bridge
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { createUserMessage, type ContextFormed } from '@deepseek-ai/dsh-llm';
+import type { SurfaceBridgeHostFace, SurfaceBridgeService, SurfaceSelection } from './contract.ts';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /**
+         * The hidden half of one surface selection: the element table the model reads.
+         *
+         * Deliberately a producer kind, because that is what makes it *invisible*: the Chat
+         * view projects any source whose kind is not `user` into a `context` node, and renders
+         * no row for those. The visible half is a plain user message; see
+         * {@link buildSelectionMessages}.
+         */
+        'surface-selection': {
+            kind: 'surface-selection';
+        } & ContextFormed;
+    }
+}
+/**
+ * The whole shared vocabulary, re-exported from the entry consumers already use.
+ *
+ * A surface plugin calls `ctx.surfaceBridge`/`ctx.surfaceBridgeHost` at runtime and
+ * never imports either half, but it must be able to *name* the faces and the
+ * descriptor it registers. Type-only, so neither half gains a runtime dependency
+ * on the other — and this module is also what carries the `Context` augmentation
+ * below, which is why a consumer should import the bridge by its package name
+ * rather than reaching for `./contract` alone.
+ */
+export type * from './contract.ts';
+/**
+ * The two services this bundle provides.
+ *
+ * This block MUST stay in the package entry module. TypeScript merges an
+ * `interface Context` augmentation into the cordis class only when the augmenting
+ * file is reached as a program root through a non-empty import; placed in
+ * `contract.ts` (or any module that also carries the shared types) the same block
+ * degrades into an *ambient* declaration that REPLACES cordis's `Context`, and
+ * every `ctx.effect`/`ctx.on` in the graph stops type-checking. The build guard in
+ * `tests/context-augmentation.test.mjs` fails if it moves.
+ */
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Browser face of the surface bridge; the seam a business surface publishes into. */
+        surfaceBridge: SurfaceBridgeService;
+        /** Host face of the surface bridge; the seam a business plugin's tools call. */
+        surfaceBridgeHost: SurfaceBridgeHostFace;
+    }
+}
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "dsh-surface-bridge";
+/** Route registration and image admission are the only Host capabilities this half needs. */
+export declare const inject: readonly ["connection", "attachments"];
+/**
+ * Build the two durable messages one selection travels in.
+ *
+ * **Two messages, one visible.** The person who sent a selection must be able to see what
+ * went out; the model needs the whole element table. Those are different appetites, and one
+ * message cannot satisfy both:
+ *
+ * · the **visible** row is a plain user message carrying one line — `画布选区 · main.excalidraw ·
+ *   3 个元素` — because the Chat view renders no row at all for a producer-tagged context node
+ *   (`isVisibleChatNode` excludes ordinary Context, keeping only tool changes). Before this,
+ *   the selection reached the model and appeared nowhere in the transcript.
+ * · the **detail** row is producer-tagged, and therefore hidden: it carries the element ids,
+ *   coordinates and sizes the model edits from, plus the file path the write-back must name.
+ *
+ * Images ride in the visible row, so a person sees the pictures they sent. Bytes never enter
+ * the text, and a surface with no image element pays for no image.
+ *
+ * @param ctx - Plugin context carrying the attachment service.
+ * @param selection - Selection to render.
+ * @returns the messages to append to the step, visible row first.
+ */
+export declare function buildSelectionMessages(ctx: Context, selection: SurfaceSelection): Promise<readonly ReturnType<typeof createUserMessage>[]>;
+export declare function apply(ctx: Context): void;