@huynle/hub 0.8.7 → 0.9.0

package/src/spoke/media.ts

@@ -0,0 +1,189 @@
+// (S4 M2) The spoke's timelineMedia op: one image of a timeline row by its ref (packages/protocol/src/media.ts),
+// checked (path policy, magic bytes, MEDIA_LIMITS) and answered in chunks. The decoded bytes of an image stay in a
+// small per-session LRU for a minute, so the following chunks do not read the session's whole history again.
+import { createHash } from "node:crypto"
+import { MEDIA_LIMITS, parseMediaRef, type MediaInfo, type MediaRef, type TimelineMediaResult } from "../protocol"
+import { base64Bytes, checkImage, mediaMime, mimeOfPath, parseDataURI } from "./media-bytes"
+import { readMediaPath, touchedPaths } from "./media-policy"
+
+const record = (value: unknown): Record<string, any> => (value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, any>) : {})
+
+/** A session's messages: all of them, those a staged revert leaves shown, and the message of a committed revert. */
+export interface MediaMessages {
+  readonly all: readonly unknown[]
+  readonly shown: readonly unknown[]
+  readonly committed?: string
+}
+
+/** Bytes of OpenCode's media store (`media:<sha256>` URIs), from the own server; undefined when unknown. */
+export type FetchMedia = (hash: string) => Promise<{ bytes: Uint8Array; mime?: string } | undefined>
+
+export interface CachedMedia {
+  readonly info: MediaInfo
+  readonly data: Uint8Array
+}
+
+/** Decoded images by session and key, least recently used first; entries expire after `ttlMs`. */
+export class MediaCache {
+  private readonly entries = new Map<string, CachedMedia & { readonly session: string; readonly at: number }>()
+  private total = 0
+  private readonly ttlMs: number
+  private readonly maxBytes: number
+  private readonly now: () => number
+
+  constructor(options: { ttlMs?: number; maxBytes?: number; now?: () => number } = {}) {
+    this.ttlMs = options.ttlMs ?? 60_000
+    this.maxBytes = options.maxBytes ?? 32 * 1024 * 1024
+    this.now = options.now ?? Date.now
+  }
+
+  /** Bytes held. */
+  get bytes(): number {
+    return this.total
+  }
+
+  get(session: string, key: string): CachedMedia | undefined {
+    const id = `${session}\u0000${key}`
+    const entry = this.entries.get(id)
+    if (!entry) return undefined
+    this.entries.delete(id)
+    if (this.now() - entry.at >= this.ttlMs) {
+      this.total -= entry.data.length
+      return undefined
+    }
+    this.entries.set(id, entry)
+    return entry
+  }
+
+  set(session: string, key: string, media: CachedMedia): void {
+    const id = `${session}\u0000${key}`
+    this.drop(id)
+    if (media.data.length > this.maxBytes) return
+    this.entries.set(id, { ...media, session, at: this.now() })
+    this.total += media.data.length
+    while (this.total > this.maxBytes) this.drop(this.entries.keys().next().value!)
+  }
+
+  /** Forget a session's images (a revert hides messages; their bytes must not be served from here). */
+  invalidate(session: string): void {
+    for (const [id, entry] of this.entries) if (entry.session === session) this.drop(id)
+  }
+
+  private drop(id: string): void {
+    const entry = this.entries.get(id)
+    if (!entry) return
+    this.entries.delete(id)
+    this.total -= entry.data.length
+  }
+}
+
+export interface TimelineMediaInput {
+  readonly sessionID: string
+  readonly messageID: string
+  readonly ref: string
+  readonly offset?: number
+  readonly cache: MediaCache
+  /** The session's messages (read only when the answer is not a later chunk still cached). */
+  readonly load: () => Promise<MediaMessages>
+  /** The session's directory (relative image paths, the path policy). */
+  readonly directory: string
+  readonly fetchMedia?: FetchMedia
+}
+
+/**
+ * The answer to timelineMedia: the chunk at `offset` of the image (with its metadata), `tooLarge`, `refused`, or
+ * nothing when there is no such image. The first chunk (offset 0) always reads the session again (so access is
+ * checked again); later chunks reuse the cached bytes. Throws for an offset at or past the end.
+ */
+export async function timelineMedia(input: TimelineMediaInput): Promise<TimelineMediaResult> {
+  const ref = parseMediaRef(input.ref)
+  if (!ref) return {}
+  const offset = input.offset ?? 0
+  const key = `${input.messageID}\u0000${input.ref}`
+  const cached = offset > 0 ? input.cache.get(input.sessionID, key) : undefined
+  if (cached) return chunkOf(cached, offset)
+  const messages = await input.load()
+  const message = messages.all.map(record).find((m) => m.id === input.messageID)
+  if (!message) return input.messageID === messages.committed ? { refused: "hidden" } : {}
+  if (!messages.shown.some((m) => record(m).id === input.messageID)) return { refused: "hidden" }
+  const source = await sourceOf(message, ref, messages.shown, input)
+  if (!("bytes" in source)) return source
+  const check = checkImage(source.bytes, source.claim)
+  if ("refused" in check) return check
+  const media: CachedMedia = {
+    info: { ...check.ok, bytes: source.bytes.length, sha256: createHash("sha256").update(source.bytes).digest("hex") },
+    data: source.bytes,
+  }
+  input.cache.set(input.sessionID, key, media)
+  return chunkOf(media, offset)
+}
+
+function chunkOf(media: CachedMedia, offset: number): TimelineMediaResult {
+  if (offset >= media.data.length) throw new Error("Media offset is past the end of the image")
+  const end = Math.min(media.data.length, offset + MEDIA_LIMITS.chunkBytes)
+  const data = Buffer.from(media.data.buffer, media.data.byteOffset + offset, end - offset).toString("base64")
+  return { media: media.info, chunk: { offset, data, last: end >= media.data.length } }
+}
+
+type Source = { readonly bytes: Uint8Array; readonly claim: string } | TimelineMediaResult
+
+const tooLarge = (bytes: number): TimelineMediaResult => ({ tooLarge: { bytes, max: MEDIA_LIMITS.maxBytes } })
+
+/** Decoded base64 (bare or a `data:` URI), unless it is too large. */
+function fromBase64(data: string, claim: string): Source {
+  const base64 = parseDataURI(data)?.base64 ?? data
+  const size = base64Bytes(base64)
+  if (size > MEDIA_LIMITS.maxBytes) return tooLarge(size)
+  return { bytes: Uint8Array.from(Buffer.from(base64, base64.includes("-") || base64.includes("_") ? "base64url" : "base64")), claim }
+}
+
+async function sourceOf(message: Record<string, any>, ref: MediaRef, shown: readonly unknown[], input: TimelineMediaInput): Promise<Source> {
+  switch (ref.kind) {
+    case "file": {
+      if (message.type !== "user" || !Array.isArray(message.files)) return {}
+      const file = record(message.files[ref.index])
+      if (typeof file.data !== "string" || !file.data || typeof file.mime !== "string") return {}
+      if (!mediaMime(file.mime)) return { refused: "type" }
+      return fromBase64(file.data, file.mime)
+    }
+    case "tool": {
+      if (message.type !== "assistant" || !Array.isArray(message.content)) return {}
+      const part = record(message.content[ref.part])
+      const content = record(part.state).content
+      if (part.type !== "tool" || !Array.isArray(content)) return {}
+      const item = record(content[ref.item])
+      if (item.type !== "file" || typeof item.mime !== "string") return {}
+      if (!mediaMime(item.mime)) return { refused: "type" }
+      // OpenCode's ToolFileContent: `uri` a data: or media: URI (raw base64 `data` from other harnesses' shapes).
+      if (typeof item.uri === "string") {
+        if (item.uri.startsWith("media:")) return fromStore(item.uri.slice("media:".length), item.mime, input.fetchMedia)
+        return item.uri.startsWith("data:") ? fromBase64(item.uri, item.mime) : {}
+      }
+      return typeof item.data === "string" && item.data ? fromBase64(item.data, item.mime) : {}
+    }
+    case "path": {
+      if (message.type !== "assistant" || !Array.isArray(message.content)) return {}
+      const text = message.content
+        .filter((p: any) => p?.type === "text" && typeof p.text === "string")
+        .map((p: any) => p.text as string)
+        .join("\n\n")
+      const read = await readMediaPath({ src: ref.path, text, directory: input.directory, touched: touchedPaths(shown, input.directory), max: MEDIA_LIMITS.maxBytes })
+      if ("refused" in read) return read
+      if ("tooLarge" in read) return tooLarge(read.tooLarge)
+      const claim = mimeOfPath(read.path)
+      return claim ? { bytes: read.bytes, claim } : { refused: "type" }
+    }
+  }
+}
+
+/** OpenCode media hashes: lowercase hex SHA-256 (MediaHash). */
+const HASH = /^[0-9a-f]{64}$/
+
+/** An item in OpenCode's media store; none when the store cannot be reached or does not have it. */
+async function fromStore(hash: string, claim: string, fetchMedia: FetchMedia | undefined): Promise<Source> {
+  if (!fetchMedia || !HASH.test(hash)) return {}
+  const found = await fetchMedia(hash).catch(() => undefined)
+  if (!found) return {}
+  if (found.bytes.length > MEDIA_LIMITS.maxBytes) return tooLarge(found.bytes.length)
+  return { bytes: found.bytes, claim }
+}

package/src/spoke/own-server.ts

@@ -2,6 +2,7 @@
 // forms). The background service is found with Service.discover; a foreground `opencode serve` from its
 // command line and password variable. A standalone server started by a TUI (`serve --stdio --port 0`)
 // keeps its password to itself: its forms are relayed through the TUI instead (Spoke.formActions).
+import { MEDIA_LIMITS } from "../protocol"
 
 /** URL and Authorization header of a foreground `opencode serve` this process is, when knowable. */
 export function foregroundEndpoint(
@@ -30,3 +31,32 @@ export function formOutcome(cause: unknown): "gone" | undefined {
   const message = cause instanceof Error ? cause.message : String(cause)
   return /form (not found|already settled)/i.test(message) ? "gone" : undefined
 }
+
+
+/** OpenCode media hashes: lowercase hex SHA-256 (its MediaHash). */
+const MEDIA_HASH = /^[0-9a-f]{64}$/
+const MEDIA_TIMEOUT_MS = 10_000
+
+/**
+ * (S4 M2) A blob of OpenCode's media store (`media:<sha256>` URIs in tool output) read from the own server
+ * (GET /api/experimental/media/:hash, experimental). Undefined when there is no endpoint, the server cannot be
+ * reached or does not have it, or it is larger than MEDIA_LIMITS.maxBytes.
+ */
+export async function fetchOwnMedia(
+  endpoint: { url: string; headers: Record<string, string> } | undefined,
+  hash: string,
+  fetcher: typeof fetch = fetch,
+): Promise<{ bytes: Uint8Array; mime?: string } | undefined> {
+  if (!endpoint || !MEDIA_HASH.test(hash)) return undefined
+  try {
+    const res = await fetcher(`${endpoint.url}/api/experimental/media/${hash}`, { headers: endpoint.headers, signal: AbortSignal.timeout(MEDIA_TIMEOUT_MS) })
+    if (!res.ok) return undefined
+    if (Number(res.headers.get("content-length") ?? 0) > MEDIA_LIMITS.maxBytes) return undefined
+    const bytes = new Uint8Array(await res.arrayBuffer())
+    if (bytes.length > MEDIA_LIMITS.maxBytes) return undefined
+    const mime = res.headers.get("content-type")?.split(";")[0]?.trim()
+    return { bytes, ...(mime ? { mime } : {}) }
+  } catch {
+    return undefined
+  }
+}