dsh-surface-bridge 0.1.0-alpha.1

package/src/host/store.ts

@@ -0,0 +1,236 @@
+/**
+ * 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, SurfaceSelection } from '../contract.ts'
+import { READ_SELECTION_OP } from '../contract.ts'
+
+/** 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
+
+/** Per-Session bridge state. */
+interface SessionState {
+  /** Operations awaiting a poll. */
+  readonly queued: SurfaceOperation[]
+  /** Settled results by operation id. */
+  readonly settled: Map<string, SurfaceOperationResult>
+  /** Waiters woken when the queue or a settled result changes. */
+  readonly waiters: Set<() => void>
+  /** Host clock of the most recent poll; the surface's liveness stamp. */
+  lastPollAt: number
+  /** Monotonic operation counter for this Session. */
+  operationSeq: number
+  /** Set by {@link SurfaceBridgeStore.forget} so waiters stop holding a dead Session. */
+  released: boolean
+}
+
+/** The bridge's Host state, keyed by Session id. */
+export class SurfaceBridgeStore {
+  private readonly sessions = new Map<string, SessionState>()
+
+  /** Resolve one Session's state, creating it on first use. */
+  private stateOf(sessionId: string): SessionState {
+    const existing = this.sessions.get(sessionId)
+    if (existing !== undefined) return existing
+    const created: SessionState = {
+      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. */
+  private wake(state: SessionState): void {
+    for (const waiter of [...state.waiters]) waiter()
+  }
+
+  /** Whether any surface of one Session has polled recently enough to be considered open. */
+  isSurfaceLive(sessionId: string, now = Date.now()): boolean {
+    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: string, source: string, op: string, payload: unknown): SurfaceOperation {
+    const state = this.stateOf(sessionId)
+    state.operationSeq += 1
+    const operation: SurfaceOperation = {
+      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: string,
+    timeoutMs: number,
+    signal?: AbortSignal,
+    consume = false,
+  ): Promise<readonly unknown[] | undefined> {
+    // 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 as readonly unknown[] : []
+  }
+
+  /**
+   * 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: string, holdMs: number, signal?: AbortSignal): Promise<readonly SurfaceOperation[]> {
+    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<void>((resolve) => {
+      let settled = false
+      const finish = (): void => {
+        if (settled) return
+        settled = true
+        state.waiters.delete(onWake)
+        clearTimeout(timer)
+        signal?.removeEventListener('abort', onWake)
+        resolve()
+      }
+      const onWake = (): void => { 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: string, result: SurfaceOperationResult): boolean {
+    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: string,
+    operationId: string,
+    timeoutMs: number,
+    signal?: AbortSignal,
+  ): Promise<SurfaceOperationResult | undefined> {
+    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<SurfaceOperationResult | undefined>((resolve) => {
+      let settled = false
+      const finish = (result: SurfaceOperationResult | undefined): void => {
+        if (settled) return
+        settled = true
+        state.waiters.delete(onWake)
+        clearTimeout(timer)
+        signal?.removeEventListener('abort', onWake)
+        resolve(result)
+      }
+      const onWake = (): void => {
+        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: string): void {
+    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_(): readonly string[] {
+    return [...this.sessions.keys()]
+  }
+}

package/src/index.ts

@@ -0,0 +1,194 @@
+/**
+ * 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 type {} from '@deepseek-ai/dsh-client-connection'
+import type {} from '@deepseek-ai/dsh-attachment'
+import type {} from '@deepseek-ai/dsh-agent'
+import { createUserMessage, type ContentBlock, type ContextFormed } from '@deepseek-ai/dsh-llm'
+import type {
+  SurfaceBridgeHostFace,
+  SurfaceBridgeService,
+  SurfaceSelection,
+} from './contract.ts'
+import { renderSelectionChip, renderSelectionText } from './host/render.ts'
+import { registerSurfaceBridgeRoutes } from './host/routes.ts'
+import { SurfaceBridgeHost } from './host/service.ts'
+import { SurfaceBridgeStore } from './host/store.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 const name = 'dsh-surface-bridge'
+
+/** Route registration and image admission are the only Host capabilities this half needs. */
+export const inject = ['connection', 'attachments'] as const
+
+/** Decode a raster into the bytes the attachment service admits. */
+function decodeRaster(data: string): Uint8Array {
+  return new Uint8Array(Buffer.from(data, 'base64'))
+}
+
+/**
+ * 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 async function buildSelectionMessages(ctx: Context, selection: SurfaceSelection): Promise<readonly ReturnType<typeof createUserMessage>[]> {
+  const reference = `${selection.source}#${selection.revision}`
+  const detail = createUserMessage({
+    content: [{ type: 'text', text: renderSelectionText(selection, reference) }],
+    // A producer kind, on purpose: this is the row the transcript hides.
+    source: { kind: 'surface-selection' },
+  })
+
+  // One line, and nothing above it. An earlier version put a `file` block first, which the
+  // shell renders as a 240x64 card — two stacked blocks for one selection, and the card was a
+  // *snapshot* of the drawing that the model had to be told not to edit. The line alone says
+  // which drawing and how many elements, which is what the reader needs.
+  const visible: ContentBlock[] = []
+  const images = selection.images ?? []
+  if (images.length > 0) {
+    const refs = await ctx.attachments.saveImages(images.map((image, index) => ({
+      data: decodeRaster(image.data),
+      mediaType: image.mediaType,
+      name: image.name ?? `${selection.source}-${image.elementId ?? `image-${String(index + 1)}`}.png`,
+    })))
+    for (const ref of refs) visible.push({ type: 'image', attachment: ref })
+  }
+  visible.push({ type: 'text', text: renderSelectionChip(selection) })
+
+  const shown = createUserMessage({
+    content: visible,
+    // `user`, so the transcript shows it. Any other kind makes the row a `context` node,
+    // and the Chat view renders no row for those.
+    source: { kind: 'user' },
+  })
+  return [shown, detail]
+}
+
+/**
+ * Plugin body: provide the Host face, serve the bridge routes, and arm the
+ * pre-step injection.
+ *
+ * @param ctx - Registrant context; every registration is disposed with it.
+ */
+/**
+ * Last turn that read each Session's surface.
+ *
+ * A turn has several steps (a model call, then the tool results, then another). The
+ * selection is a property of the message that opened the turn, so it is read once
+ * per turn; without this the context would be re-injected on every step and the
+ * model would see the same drawing three times.
+ */
+const lastReadTurn = new Map<string, number>()
+
+export function apply(ctx: Context): void {
+  const store = new SurfaceBridgeStore()
+  const host = new SurfaceBridgeHost(store)
+  ctx.effect(() => ctx.reflect.provide('surfaceBridgeHost', host), 'dsh-surface-bridge: host face')
+  registerSurfaceBridgeRoutes(ctx, store)
+
+  ctx.on('agent/pre-step', async ({ agent, signal, turn, step }, next) => {
+    const decision = await next()
+    if (decision.kind === 'reject' || signal.aborted) return decision
+    // A selection belongs to the message that opened the turn, and that message is
+    // admitted at step 1. Gating on `step` rather than on the admitted message batch
+    // is deliberate: an empty batch at step 1 is a real case (a turn opened by
+    // something other than a typed prompt), and the batch is not a reliable signal
+    // for "the user just sent this". The whole point is also that the selection is
+    // read *here* — when the message is going out — not pushed while the user drew.
+    if (step !== 1) return decision
+    const sessionId = String(agent.id)
+    if (lastReadTurn.get(sessionId) === turn) return decision
+    // Consuming: this read exists to carry the selection into the message, so the
+    // surface drops it as it answers and the chip leaves the composer. A peek would
+    // leave it on screen and let the same drawing ride the next message too.
+    const selections = await host.consumeSelections(sessionId, signal)
+    if (selections === undefined || selections.length === 0) return decision
+    lastReadTurn.set(sessionId, turn)
+    const messages = [...decision.messages]
+    for (const selection of selections) {
+      messages.push(...await buildSelectionMessages(ctx, selection))
+    }
+    return { ...decision, messages }
+  }, { prepend: true })
+}