dsh-browser-application 0.37.0

package/src/event-generation.ts

@@ -0,0 +1,385 @@
+/**
+ * One authenticated extension connection's event streams, its active Session
+ * follower, and the forwarded Host waterfalls it answers.
+ *
+ * @module dsh-browser-application/src/event-generation
+ */
+
+import type { RespondResult } from '@dsh-browser/protocol'
+import { openWireStream, type TypertGatewayLike } from './dsh-gateway.ts'
+import { isSessionSnapshot, type SessionSnapshot } from './session-history.ts'
+import type { HostEventFrame } from './host-api.ts'
+import { isRecord } from './host-api.ts'
+import { ExtensionSessionRegistry, shouldBridgeOwnQuestion } from './extension-sessions.ts'
+
+interface PendingQuestion {
+  readonly sessionId: string
+  settled: boolean
+}
+
+export type SendRemoteEventResult = (
+  clientId: string,
+  eventId: string,
+  outcome: RemoteEventOutcome,
+  signal: AbortSignal,
+) => Promise<void>
+
+export type RemoteEventOutcome =
+  | { readonly kind: 'next' }
+  | { readonly kind: 'result'; readonly value?: unknown }
+  | {
+    readonly kind: 'rejected'
+    readonly error: {
+      readonly name: string
+      readonly message: string
+      readonly code?: string
+      readonly details?: unknown
+    }
+  }
+
+/** One authenticated extension connection's event streams and active Session follower. */
+export class EventGeneration {
+  private readonly lifetime = new AbortController()
+  private readonly signal: AbortSignal
+  private readonly queue = new AsyncEventQueue()
+  private readonly tasks = new Set<Promise<void>>()
+  private readonly pendingQuestions = new Map<string, PendingQuestion>()
+  private clientId: string | undefined
+  private followAbort: AbortController | undefined
+  private followedSessionId: string | undefined
+  private followRevision = 0
+  private disposed = false
+
+  constructor(
+    private readonly gateway: TypertGatewayLike,
+    private readonly sendResult: SendRemoteEventResult,
+    private readonly extensionSessions: ExtensionSessionRegistry,
+    private readonly onHistoryCursor: (sessionId: string, cursor: number) => void,
+    outerSignal: AbortSignal,
+  ) {
+    this.signal = AbortSignal.any([outerSignal, this.lifetime.signal])
+  }
+
+  start(): void {
+    this.track(this.pumpRemoteEvents())
+  }
+
+  events(): AsyncIterable<HostEventFrame> {
+    return this.queue.iterate(this.signal)
+  }
+
+  async openSessionHistory(
+    sessionId: string,
+    callSignal: AbortSignal,
+    maxMessages?: number,
+  ): Promise<SessionSnapshot> {
+    return this.openSessionFollow(sessionId, callSignal, maxMessages)
+  }
+
+  async ensureSessionFollow(sessionId: string, callSignal: AbortSignal): Promise<void> {
+    if (this.followedSessionId === sessionId && this.followAbort?.signal.aborted === false) return
+    await this.openSessionFollow(sessionId, callSignal)
+  }
+
+  async respond(rpcId: string, result: RespondResult, signal: AbortSignal): Promise<unknown> {
+    const pending = this.pendingQuestions.get(rpcId)
+    const clientId = this.clientId
+    if (pending === undefined || pending.settled || clientId === undefined) {
+      return { accepted: false, reason: 'not-pending' }
+    }
+    pending.settled = true
+    try {
+      await this.sendResult(clientId, rpcId, respondOutcome(result), AbortSignal.any([this.signal, signal]))
+      return { accepted: true }
+    } catch (error: unknown) {
+      pending.settled = false
+      throw error
+    }
+  }
+
+  async dispose(): Promise<void> {
+    if (this.disposed) return
+    this.disposed = true
+    this.followAbort?.abort(new Error('browser bridge event generation closed'))
+    this.lifetime.abort(new Error('browser bridge event generation closed'))
+    this.queue.end()
+    await Promise.all(this.tasks)
+  }
+
+  private async openSessionFollow(
+    sessionId: string,
+    callSignal: AbortSignal,
+    maxMessages?: number,
+  ): Promise<SessionSnapshot> {
+    const revision = ++this.followRevision
+    this.followAbort?.abort(new Error('browser bridge Session follower replaced'))
+    const controller = new AbortController()
+    this.followAbort = controller
+    this.followedSessionId = sessionId
+    const signal = AbortSignal.any([this.signal, callSignal, controller.signal])
+    try {
+      const source = await openWireStream(this.gateway,
+        'session/follow',
+        {
+          args: {
+            request: {
+              address: { kind: 'session', sessionId },
+              assistantStream: true,
+              ...(maxMessages === undefined ? {} : { maxMessages }),
+            },
+          },
+        },
+        signal,
+      )
+      const iterator = source[Symbol.asyncIterator]()
+      const first = await iterator.next()
+      if (first.done || !isSessionSnapshot(first.value)) {
+        await iterator.return?.()
+        throw new TypeError('session/follow did not begin with a snapshot')
+      }
+      if (revision !== this.followRevision || signal.aborted) {
+        await iterator.return?.()
+        signal.throwIfAborted()
+        throw new Error('browser bridge Session follower was replaced while opening')
+      }
+      this.onHistoryCursor(sessionId, first.value.cursor)
+      const snapshotId = first.value.assistantStream === undefined ? undefined : crypto.randomUUID()
+      // Publish the reconnect prefix before any suffix chunks. RPC responses
+      // and pushed events can otherwise race, dropping the beginning of an
+      // already-running attempt when the panel reopens its history.
+      if (first.value.assistantStream !== undefined) {
+        this.queue.push({
+          rpcId: crypto.randomUUID(),
+          method: 'session/assistant-stream',
+          payload: {
+            sessionId,
+            snapshotId,
+            frame: { type: 'snapshot', baseline: first.value.assistantStream },
+          },
+        })
+      }
+      this.track(this.pumpSessionEvents(sessionId, revision, iterator, signal))
+      return {
+        cursor: first.value.cursor,
+        records: first.value.records,
+        hasMore: first.value.hasMore,
+        ...(first.value.projections === undefined ? {} : { projections: first.value.projections }),
+        ...(first.value.assistantStream === undefined ? {} : { assistantStream: first.value.assistantStream }),
+        ...(snapshotId === undefined ? {} : { snapshotId }),
+      }
+    } catch (error: unknown) {
+      if (revision === this.followRevision) {
+        this.followedSessionId = undefined
+        this.followAbort = undefined
+      }
+      throw error
+    }
+  }
+
+  private async pumpSessionEvents(
+    sessionId: string,
+    revision: number,
+    iterator: AsyncIterator<unknown>,
+    signal: AbortSignal,
+  ): Promise<void> {
+    try {
+      while (!signal.aborted) {
+        const next = await iterator.next()
+        // Abort is advisory to an AsyncIterator: a buffered frame may still
+        // resolve after this follower was replaced. Never let that stale
+        // generation update the extension's active/recent session state.
+        if (signal.aborted || revision !== this.followRevision) break
+        if (next.done) break
+        if (isRecord(next.value) && next.value.type === 'assistant-stream' && isRecord(next.value.frame)) {
+          this.queue.push({
+            rpcId: crypto.randomUUID(),
+            method: 'session/assistant-stream',
+            payload: { sessionId, frame: next.value.frame },
+          })
+          continue
+        }
+        if (!isSessionEventEntry(next.value)) {
+          throw new TypeError('session/follow emitted an invalid incremental frame')
+        }
+        const seq = next.value.event.seq
+        if (typeof seq === 'number') this.onHistoryCursor(sessionId, seq)
+        this.queue.push({
+          rpcId: crypto.randomUUID(),
+          method: 'session/event',
+          payload: { type: 'session/event', sessionId, event: next.value.event },
+        })
+      }
+      if (!signal.aborted && revision === this.followRevision) {
+        throw new Error('session/follow ended unexpectedly')
+      }
+    } catch (error: unknown) {
+      if (!signal.aborted && revision === this.followRevision) this.queue.fail(error)
+    } finally {
+      await iterator.return?.()
+      if (revision === this.followRevision) {
+        this.followedSessionId = undefined
+        this.followAbort = undefined
+      }
+    }
+  }
+
+  private async pumpRemoteEvents(): Promise<void> {
+    try {
+      const source = await openWireStream(this.gateway, '$events', { args: {} }, this.signal)
+      let ready = false
+      for await (const value of source) {
+        if (!ready) {
+          if (!isRemoteEventReady(value)) throw new TypeError('$events did not begin with ready')
+          this.clientId = value.clientId
+          ready = true
+          continue
+        }
+        await this.handleRemoteEvent(value)
+      }
+      if (!this.signal.aborted) throw new Error('$events ended unexpectedly')
+    } catch (error: unknown) {
+      if (!this.signal.aborted) this.queue.fail(error)
+    }
+  }
+
+  private async handleRemoteEvent(value: unknown): Promise<void> {
+    if (!isRecord(value) || typeof value.type !== 'string') {
+      throw new TypeError('$events emitted an invalid frame')
+    }
+    if (value.type === 'emit') return
+    if (value.type === 'cancel' && typeof value.eventId === 'string') {
+      const pending = this.pendingQuestions.get(value.eventId)
+      if (pending === undefined) return
+      this.pendingQuestions.delete(value.eventId)
+      this.queue.push({
+        rpcId: crypto.randomUUID(),
+        method: 'question/resolved',
+        payload: {
+          type: 'question/resolved',
+          sessionId: pending.sessionId,
+          questionRpcId: value.eventId,
+        },
+      })
+      return
+    }
+    if (value.type !== 'waterfall'
+      || typeof value.event !== 'string'
+      || typeof value.eventId !== 'string'
+      || typeof value.agentId !== 'string'
+      || !isRecord(value.request)) {
+      throw new TypeError('$events emitted an invalid waterfall frame')
+    }
+    if (value.event !== 'user-questions/request' || !Array.isArray(value.request.questions)) {
+      const clientId = this.clientId
+      if (clientId !== undefined) {
+        await this.sendResult(clientId, value.eventId, { kind: 'next' }, this.signal)
+      }
+      return
+    }
+    // Desktop-owned sessions keep the native waterfall. Only forward questions
+    // for sessions the extension successfully created or prompted.
+    if (!shouldBridgeOwnQuestion({
+      hasExtensionConnection: true,
+      sessionId: value.agentId,
+      extensionSessions: this.extensionSessions,
+    })) {
+      const clientId = this.clientId
+      if (clientId !== undefined) {
+        await this.sendResult(clientId, value.eventId, { kind: 'next' }, this.signal)
+      }
+      return
+    }
+    this.pendingQuestions.set(value.eventId, { sessionId: value.agentId, settled: false })
+    this.queue.push({
+      rpcId: value.eventId,
+      method: 'question/requested',
+      payload: {
+        type: 'question/requested',
+        sessionId: value.agentId,
+        questions: value.request.questions,
+      },
+    })
+  }
+
+  private track(task: Promise<void>): void {
+    const tracked = task.catch((error: unknown) => {
+      if (!this.signal.aborted) this.queue.fail(error)
+    })
+    this.tasks.add(tracked)
+    void tracked.finally(() => { this.tasks.delete(tracked) })
+  }
+}
+
+class AsyncEventQueue {
+  private readonly frames: HostEventFrame[] = []
+  private wake: (() => void) | undefined
+  private failure: unknown
+  private closed = false
+
+  push(frame: HostEventFrame): void {
+    if (this.closed || this.failure !== undefined) return
+    this.frames.push(frame)
+    this.wake?.()
+  }
+
+  fail(error: unknown): void {
+    if (this.closed || this.failure !== undefined) return
+    this.failure = error
+    this.wake?.()
+  }
+
+  end(): void {
+    if (this.closed) return
+    this.closed = true
+    this.wake?.()
+  }
+
+  async *iterate(signal: AbortSignal): AsyncGenerator<HostEventFrame> {
+    const onAbort = (): void => { this.wake?.() }
+    signal.addEventListener('abort', onAbort, { once: true })
+    try {
+      while (true) {
+        while (this.frames.length > 0) yield this.frames.shift() as HostEventFrame
+        if (this.failure !== undefined) throw this.failure
+        if (this.closed || signal.aborted) return
+        await new Promise<void>((resolve) => { this.wake = resolve })
+        this.wake = undefined
+      }
+    } finally {
+      signal.removeEventListener('abort', onAbort)
+    }
+  }
+}
+
+function respondOutcome(result: RespondResult): RemoteEventOutcome {
+  if (result.ok) {
+    const value = isRecord(result.value) && isRecord(result.value.answer)
+      ? result.value.answer
+      : result.value
+    return value === undefined ? { kind: 'result' } : { kind: 'result', value }
+  }
+  return {
+    kind: 'rejected',
+    error: {
+      name: 'Error',
+      message: result.error.message,
+      code: result.error.code,
+      details: result.error.details,
+    },
+  }
+}
+
+function isSessionEventEntry(value: unknown): value is {
+  readonly type: 'event'
+  readonly event: Record<string, unknown>
+} {
+  return isRecord(value) && value.type === 'event' && isRecord(value.event)
+}
+
+function isRemoteEventReady(value: unknown): value is {
+  readonly type: 'ready'
+  readonly clientId: string
+} {
+  return isRecord(value) && value.type === 'ready'
+    && typeof value.clientId === 'string' && value.clientId.length > 0
+}

package/src/extension-sessions.ts

@@ -0,0 +1,40 @@
+/**
+ * Track session ids that the browser extension has driven through the bridge.
+ * Desktop-native sessions must keep the host userQuestions waterfall so the
+ * Desktop UI can render ask_user_question cards.
+ * @module dsh-browser-application/src/extension-sessions
+ */
+
+/** Mutable registry of extension-owned session ids. */
+export class ExtensionSessionRegistry {
+  private readonly ids = new Set<string>()
+
+  /** Remember a session the extension successfully created or prompted. */
+  note(sessionId: string | undefined): void {
+    if (typeof sessionId === 'string' && sessionId.length > 0) this.ids.add(sessionId)
+  }
+
+  /** Whether the extension has touched this session over the bridge. */
+  has(sessionId: string | undefined): boolean {
+    return typeof sessionId === 'string' && this.ids.has(sessionId)
+  }
+
+  /** Test helper: drop all tracked ids. */
+  clear(): void {
+    this.ids.clear()
+  }
+}
+
+/**
+ * Decide whether the bridge should own ask_user_question for this request.
+ * Desktop sessions must fall through to the native answerer waterfall.
+ */
+export function shouldBridgeOwnQuestion(input: {
+  hasExtensionConnection: boolean
+  sessionId: string | undefined
+  extensionSessions: Pick<ExtensionSessionRegistry, 'has'>
+}): boolean {
+  return input.hasExtensionConnection
+    && input.sessionId !== undefined
+    && input.extensionSessions.has(input.sessionId)
+}

package/src/host-api.ts

@@ -0,0 +1,64 @@
+/**
+ * Bridge-owned Host API consumed by the WebSocket carrier.
+ *
+ * This boundary keeps release-specific Host topology out of the browser wire
+ * server. dsh 0.1.5 implements it with Typert Remotes and Connection.
+ *
+ * @module
+ */
+
+import type { RespondResult } from '@dsh-browser/protocol'
+
+/** Stable failure envelope understood by the extension panel. */
+export interface HostRpcFailure {
+  readonly code: string
+  readonly message: string
+  readonly details: object
+}
+
+/** Business result returned by the active dsh Host adapter. */
+export type HostRpcResult<T = unknown> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: HostRpcFailure }
+
+/** One extension-originated unary call after WebSocket decoding. */
+export interface HostRpcCall {
+  readonly rpcId: string
+  readonly method: string
+  readonly payload: unknown
+  readonly signal: AbortSignal
+}
+
+/** Event retained as the private bridge-to-extension protocol. */
+export interface HostEventFrame {
+  readonly rpcId: string
+  readonly method: string
+  readonly payload: unknown
+}
+
+/** API surface the WebSocket carrier needs from a dsh Host. */
+export interface BrowserHostApi {
+  call(call: HostRpcCall): Promise<HostRpcResult>
+  events(signal: AbortSignal): AsyncIterable<HostEventFrame>
+  respond(rpcId: string, result: RespondResult, signal: AbortSignal): Promise<unknown>
+}
+
+/** Convert an arbitrary Host rejection to the open wire failure vocabulary. */
+export function hostFailure(error: unknown): HostRpcFailure {
+  if (isRecord(error)) {
+    const code = typeof error.code === 'string' ? error.code : 'internal'
+    const message = typeof error.message === 'string' ? error.message : String(error)
+    const details = isRecord(error.details) ? error.details : {}
+    return { code, message, details }
+  }
+  return {
+    code: 'internal',
+    message: error instanceof Error ? error.message : String(error),
+    details: {},
+  }
+}
+
+/** Narrow unknown JSON-like data without accepting arrays. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/image-relay.ts

@@ -0,0 +1,118 @@
+/**
+ * Serving the extension's image-recognition requests on the desktop side.
+ *
+ * The extension is asked for bytes first because only it carries the user's login
+ * state; when it could not fetch at all — its content-security policy, a host
+ * permission, or an enterprise rule — it sends the URL and the desktop tries with
+ * its own network stack instead. The two paths are complementary rather than
+ * redundant, which is why the frame carries a source rather than always one kind.
+ *
+ * The desktop has no image codec, so bytes it fetches itself are passed through
+ * unchanged once they are known to be an image and to be a sane size. Anything
+ * the extension already normalized arrives pre-scaled.
+ *
+ * @module
+ */
+
+import type { ImageRecognitionRequest, ImageSource } from '@dsh-browser/protocol'
+import type { VisionClient } from './vision.ts'
+
+export type ImageRelayResult =
+  | { ok: true; desc: string }
+  | { ok: false; code: string; message: string }
+
+/** Cap on bytes the desktop will pull from the network for one image. */
+const MAX_RELAY_BYTES = 12_000_000
+const RELAY_TIMEOUT_MS = 15_000
+
+export class ImageRelay {
+  private readonly vision: VisionClient | undefined
+  private readonly fetchImpl: typeof fetch
+
+  constructor(vision: VisionClient | undefined, fetchImpl: typeof fetch = fetch) {
+    this.vision = vision
+    this.fetchImpl = fetchImpl
+  }
+
+  /** Whether a vision model is configured, which is what `hello.ok` advertises. */
+  get available(): boolean {
+    return this.vision !== undefined
+  }
+
+  /**
+   * Recognize one image for the extension.
+   *
+   * @param request - the page context the extension gathered.
+   * @param source - normalized bytes, or a URL for the desktop to fetch.
+   * @returns a one-line description, or a classified failure.
+   */
+  async recognize(request: ImageRecognitionRequest, source: ImageSource): Promise<ImageRelayResult> {
+    const vision = this.vision
+    if (vision === undefined) {
+      return { ok: false, code: 'no-vision', message: 'no vision model is configured on the desktop' }
+    }
+
+    let bytes: { base64: string; mediaType: string }
+    if (source.kind === 'bytes') {
+      if (source.base64.length > MAX_RELAY_BYTES) {
+        return { ok: false, code: 'too-large', message: `${String(source.base64.length)} base64 characters` }
+      }
+      bytes = { base64: source.base64, mediaType: source.mediaType }
+    } else {
+      const fetched = await this.fetchByUrl(source.url)
+      if (!fetched.ok) return fetched
+      bytes = fetched
+    }
+
+    const result = await vision.describe({
+      base64: bytes.base64,
+      mediaType: bytes.mediaType,
+      context: {
+        alt: request.alt,
+        near: request.near,
+        heading: request.heading,
+        kind: request.kind,
+        // The tier travels with the request so the relayed call asks exactly what
+        // the extension's own call would have asked. Omitted rather than set to
+        // undefined, which `exactOptionalPropertyTypes` rejects.
+        ...request.tier === undefined ? {} : { tier: request.tier },
+      },
+    })
+    return result.ok
+      ? { ok: true, desc: result.desc }
+      : { ok: false, code: result.code, message: result.message }
+  }
+
+  /** The desktop's own attempt, for when the extension's fetch did not work. */
+  private async fetchByUrl(
+    url: string,
+  ): Promise<{ ok: true; base64: string; mediaType: string } | { ok: false; code: string; message: string }> {
+    if (!/^https?:/i.test(url)) return { ok: false, code: 'bad-url', message: `unsupported scheme: ${url.slice(0, 40)}` }
+    let response: Response
+    try {
+      response = await this.fetchImpl(url, {
+        redirect: 'follow',
+        signal: AbortSignal.timeout(RELAY_TIMEOUT_MS),
+      })
+    } catch (error: unknown) {
+      return { ok: false, code: 'relay-network', message: error instanceof Error ? error.message : String(error) }
+    }
+    if (!response.ok) return { ok: false, code: 'relay-http', message: String(response.status) }
+
+    const mediaType = (response.headers.get('content-type') ?? '').split(';')[0]?.trim().toLowerCase() ?? ''
+    if (!mediaType.startsWith('image/')) {
+      return { ok: false, code: 'not-an-image', message: mediaType === '' ? 'no content-type' : mediaType }
+    }
+
+    let buffer: ArrayBuffer
+    try {
+      buffer = await response.arrayBuffer()
+    } catch (error: unknown) {
+      return { ok: false, code: 'relay-network', message: error instanceof Error ? error.message : String(error) }
+    }
+    if (buffer.byteLength > MAX_RELAY_BYTES) {
+      return { ok: false, code: 'too-large', message: String(buffer.byteLength) }
+    }
+    return { ok: true, base64: Buffer.from(buffer).toString('base64'), mediaType }
+  }
+}