@100xprompt/brain 0.0.0-stage → 0.1.0

package/src/adapters/amazon-q-ide/writer.ts

@@ -0,0 +1,325 @@
+import { randomBytes, randomUUID } from "node:crypto"
+import { copyFileSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import { basename, join, resolve } from "node:path"
+import { toolLabel } from "../../brief.ts"
+import { exists, isDir } from "../../fsutil.ts"
+import type { Session, Turn } from "../../session/types.ts"
+import { countTurns, firstUserText, unpaired } from "../../session/util.ts"
+import type { Readiness, WriteOptions, WriteResult, Writer } from "../types.ts"
+import { type LokiDb, amazonQReader, tabsOf } from "./reader.ts"
+import {
+  DUMMY_ANSWER, LABEL, SUMMARY_PREFIX, TESTED_SERVERS, TOOL,
+  asQCall, continuedNote, dbName, editors, historyDir, serverRunning, serverVersion, workspaceId,
+} from "./records.ts"
+
+// Continues a portable session in Amazon Q's IDE chat as a new conversation (tab) in the workspace's
+// history database, the document ChatDatabase.addMessage builds: prompts and answers alternating, each
+// answer's toolUses answered by the next prompt's toolResults, ids in Q's style. The tab is marked open,
+// so Amazon Q restores it when the editor next opens the folder (tabBarController.loadChats); it is also
+// in Amazon Q's History list. Its messages are the conversation history the agent sends with the next
+// request, so the model has the whole conversation.
+//
+// The database holds the workspace's other conversations too, so the writer only adds a document and
+// never changes another, refuses while Amazon Q's language server runs (it keeps the database in memory
+// and saves it every second), and copies the file to ~/.brain/backups/amazon-q-ide/<time>/ first.
+//
+// Amazon Q's own conventions decide the rest: the note saying where the session came from is a prompt
+// the panel does not show (shouldDisplayMessage false) followed by Q's hidden "Working..." answer, the
+// pair Q itself stores to keep prompts and answers alternating; a compaction starts the conversation from
+// its summary, as Q's replaceWithSummary does. Reasoning has no place in Q's history and is dropped.
+
+type Row = Record<string, unknown>
+type Call = Extract<Turn, { kind: "tool_call" }>
+type Result = Extract<Turn, { kind: "tool_result" }>
+
+interface QMessage {
+  body: string
+  type: "prompt" | "answer"
+  timestamp: string
+  shouldDisplayMessage: boolean
+  origin?: "IDE"
+  userInputMessageContext?: { toolResults?: Row[] }
+  images?: unknown[]
+  toolUses?: Array<{ toolUseId: string; name: string; input: Record<string, unknown> }>
+}
+
+const ALNUM = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+/** Amazon Q's tool use ids: tooluse_ and 22 characters. */
+const toolUseId = () => `tooluse_${[...randomBytes(22)].map((b) => ALNUM[b % ALNUM.length]).join("")}`
+
+const shellQuote = (s: string) => (/^[\w./@%+=:,-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`)
+
+export interface QPlan {
+  tab: Row
+  lost: string[]
+  expect: { users: number; calls: number }
+}
+
+/** The tab document of a new Amazon Q conversation continuing `session` (without $loki and meta). Pure. */
+export function planTab(session: Session, opts: { historyId: string; conversationId: string; now: Date }): QPlan {
+  const drops = new Map<string, number>()
+  const drop = (what: string, n = 1) => drops.set(what, (drops.get(what) ?? 0) + n)
+  const label = toolLabel(session.header.tool)
+  const turns = session.turns
+  const lastCompaction = turns.map((t) => t.kind).lastIndexOf("compaction")
+  if (lastCompaction > 0) drop("turns before the last compaction (Amazon Q keeps only the summary)", turns.slice(0, lastCompaction).filter((t) => t.kind === "user" || t.kind === "assistant").length)
+
+  const results = new Map<string, Result>()
+  const callIds = new Set<string>()
+  for (const t of turns) {
+    if (t.kind === "tool_result" && !results.has(t.callId)) results.set(t.callId, t)
+    if (t.kind === "tool_call") callIds.add(t.id)
+  }
+  const ids = new Map<string, string>()
+  const qId = (id: string) => {
+    let v = ids.get(id)
+    if (!v) ids.set(id, (v = toolUseId()))
+    return v
+  }
+
+  const known = turns.map((t) => (t.at ? Date.parse(t.at) : Number.NaN)).find(Number.isFinite)
+  let clock = (known ?? opts.now.getTime()) - 1
+  const stamp = (at?: string) => {
+    const t = at ? Date.parse(at) : Number.NaN
+    clock = Number.isFinite(t) && t > clock ? t : clock + 1
+    return new Date(clock).toISOString()
+  }
+
+  const msgs: QMessage[] = []
+  const prompt = (body: string, shown: boolean, at?: string, toolResults?: Row[]): QMessage => ({
+    body,
+    type: "prompt",
+    origin: "IDE",
+    userInputMessageContext: toolResults ? { toolResults } : {},
+    shouldDisplayMessage: shown,
+    timestamp: stamp(at),
+    images: [],
+  })
+  const dummy = (): QMessage => ({ body: DUMMY_ANSWER, type: "answer", shouldDisplayMessage: false, timestamp: stamp() })
+  /** Appends keeping Q's invariant: prompts and answers alternate, starting with a prompt. */
+  const push = (m: QMessage) => {
+    const last = msgs[msgs.length - 1]
+    if (last?.type === "prompt" && m.type === "prompt") {
+      // A request typed right after tool results travels with them, as Q sends it; otherwise Q's hidden placeholder answer goes between.
+      if (!last.body && last.userInputMessageContext?.toolResults && !m.userInputMessageContext?.toolResults && m.shouldDisplayMessage) {
+        last.body = m.body
+        return
+      }
+      msgs.push(dummy())
+    } else if (last?.type === "answer" && m.type === "answer" && !last.toolUses?.length) {
+      last.body = [last.body, m.body].filter((b) => b.trim()).join("\n\n")
+      last.toolUses = m.toolUses ?? []
+      return
+    }
+    msgs.push(m)
+  }
+
+  push(prompt(continuedNote(label, session.header.id, opts.now.toISOString().slice(0, 10)), false))
+
+  let cur: { text: string; at?: string; calls: Call[] } | undefined
+  const flush = () => {
+    if (!cur) return
+    const a = cur
+    cur = undefined
+    if (!a.text.trim() && !a.calls.length) return
+    push({
+      body: a.text,
+      type: "answer",
+      toolUses: a.calls.map((c) => {
+        const q = asQCall(c.toolKind, c.name, c.input)
+        return { toolUseId: qId(c.id), name: q.name, input: q.input }
+      }),
+      shouldDisplayMessage: true,
+      timestamp: stamp(a.at),
+    })
+    if (!a.calls.length) return
+    const toolResults = a.calls.map((c) => {
+      const r = results.get(c.id)
+      if (!r) drop("tool calls without a result (closed as errors)")
+      const text = r ? r.output + (r.fullPath ? `\n\n[Full output: ${r.fullPath}]` : "") : "No result was recorded for this call."
+      return { toolUseId: qId(c.id), status: r?.ok ? "success" : "error", content: [{ text: text || "(no output)" }] }
+    })
+    push(prompt("", true, results.get(a.calls[a.calls.length - 1]!.id)?.at, toolResults))
+  }
+
+  const expect = { users: 0, calls: 0 }
+  const seen = new Set<string>()
+  for (const [i, t] of turns.entries()) {
+    if (i < lastCompaction) continue
+    switch (t.kind) {
+      case "compaction":
+        push(prompt(`${SUMMARY_PREFIX} in ${label}, which replaced the turns before it]\n\n${t.summary}`, true, t.at))
+        break
+      case "user":
+        if (t.attachments?.length) drop("attachments", t.attachments.length)
+        if (!t.text.trim()) break
+        flush()
+        push(prompt(t.text, true, t.at))
+        expect.users++
+        break
+      case "assistant":
+        if (!t.text.trim()) break
+        // Text after a call is a new answer: it was written after the call's result came back.
+        if (cur?.calls.length) flush()
+        cur ??= { text: "", ...(t.at ? { at: t.at } : {}), calls: [] }
+        cur.text = cur.text ? `${cur.text}\n\n${t.text}` : t.text
+        break
+      case "tool_call":
+        if (seen.has(t.id)) {
+          drop("repeated tool call ids")
+          break
+        }
+        seen.add(t.id)
+        cur ??= { text: "", ...(t.at ? { at: t.at } : {}), calls: [] }
+        cur.calls.push(t)
+        expect.calls++
+        break
+      case "tool_result":
+        if (!callIds.has(t.callId)) drop("tool results without a call")
+        // A result closes the answer it belongs to, so a call made after it starts a new answer.
+        else if (cur?.calls.some((c) => c.id === t.callId)) flush()
+        break
+      case "reasoning":
+        drop("reasoning")
+        break
+      case "file_edit":
+        if (!t.callId || !callIds.has(t.callId)) drop("file edits outside a tool call")
+        break
+      case "subagent":
+        drop("subagent sessions")
+        break
+    }
+  }
+  flush()
+  // Q ends a stored conversation on an answer; a trailing request gets its hidden placeholder, as Q adds one.
+  if (msgs[msgs.length - 1]?.type === "prompt") msgs.push(dummy())
+
+  const title = session.header.title ?? firstUserText(session)?.replace(/\s+/g, " ").trim().slice(0, 60) ?? "Session"
+  const tab: Row = {
+    historyId: opts.historyId,
+    // LokiJS stores a top-level Date as epoch milliseconds; nested ones as ISO strings.
+    updatedAt: opts.now.getTime(),
+    isOpen: true,
+    tabType: "cwc",
+    title: `${title} (from ${label})`,
+    conversations: [{ conversationId: opts.conversationId, clientType: "vscode", updatedAt: opts.now.toISOString(), messages: msgs }],
+  }
+  return { tab, lost: [...drops].map(([what, n]) => `${what} (${n})`), expect }
+}
+
+/** A database file as LokiJS 1.5 writes one for a workspace whose history is still empty (copied from Q's own). */
+export function emptyDb(file: string, now: Date): LokiDb {
+  const events = { insert: [], update: [], "pre-insert": [], "pre-update": [], close: [], flushbuffer: [], error: [], delete: [null], warning: [null] }
+  const collection = (name: string, extra: Row) => ({
+    name, data: [], idIndex: null, binaryIndices: {}, constraints: null, uniqueNames: [], transforms: {}, objType: name, dirty: false, cachedIndex: null,
+    cachedBinaryIndex: null, cachedData: null, adaptiveBinaryIndices: true, transactional: false, cloneObjects: false, cloneMethod: "parse-stringify",
+    asyncListeners: false, disableMeta: false, disableChangesApi: true, disableDeltaChangesApi: true, autoupdate: false, serializableIndices: true,
+    disableFreeze: true, ttl: null, maxId: 0, DynamicViews: [], events, changes: [], dirtyIds: [], isIncremental: false, ...extra,
+  })
+  return {
+    filename: basename(file),
+    collections: [
+      collection("tabs", { binaryIndices: { updatedAt: { name: "updatedAt", dirty: false, values: [] }, isOpen: { name: "isOpen", dirty: false, values: [] } }, uniqueNames: ["historyId"] }),
+      collection("settings", {}),
+    ],
+    databaseVersion: 1.5,
+    engineVersion: 1.5,
+    autosave: true,
+    autosaveInterval: 1000,
+    autosaveHandle: null,
+    throttledSaves: true,
+    options: { adapter: null, autosave: true, autoload: true, autosaveInterval: 1000, persistenceMethod: "fs", serializationMethod: "normal", destructureDelimiter: "$<\n", recursiveWait: true, recursiveWaitLimit: false, recursiveWaitLimitDuration: 2000, started: now.getTime() },
+    persistenceMethod: "adapter",
+    persistenceAdapter: null,
+    verbose: false,
+    events: { init: [null], loaded: [], flushChanges: [], close: [], changes: [], warning: [] },
+    ENV: "NODEJS",
+    isIncremental: false,
+  }
+}
+
+/** Adds `tab` to the database as LokiJS's insert would: the next $loki id, fresh meta, indices left for LokiJS to rebuild. */
+export function insertTab(db: LokiDb, tab: Row, now: Date): void {
+  const tabs = db.collections.find((c) => c.name === "tabs")
+  if (!tabs) throw new Error("the history file has no tabs collection")
+  const id = (tabs.maxId ?? 0) + 1
+  tabs.maxId = id
+  tabs.data.push({ ...tab, meta: { revision: 0, created: now.getTime(), version: 0 }, $loki: id })
+  if (Array.isArray(tabs.idIndex)) tabs.idIndex.push(id)
+  // Marked dirty, LokiJS rebuilds a binary index before its next use, as it does after its own inserts.
+  for (const index of Object.values(tabs.binaryIndices ?? {})) index.dirty = true
+}
+
+/** The Amazon Q writer; `server` and `running` are for tests, which must not depend on this machine. */
+export function amazonQWriter(opts: { server?: string; running?: () => boolean } = {}): Writer {
+  const installed = (home: string) => opts.server ?? serverVersion(home)
+  const running = opts.running ?? serverRunning
+  return {
+    tool: TOOL,
+    label: LABEL,
+    way: "native",
+
+    async ready(w: WriteOptions): Promise<Readiness> {
+      const v = installed(w.home)
+      if (!v) return { ok: false, why: "Amazon Q's language server was not found (it is downloaded when the Amazon Q extension first starts)" }
+      if (!TESTED_SERVERS.includes(v)) return { ok: false, why: `Amazon Q language server ${v} is not a version this writer was checked against (${TESTED_SERVERS.join(", ")})` }
+      if (running()) return { ok: false, why: "Amazon Q is running (its language server keeps the chat history in memory and would overwrite the new conversation); close VS Code, Cursor or the JetBrains IDE first" }
+      if (!isDir(w.cwd)) return { ok: false, why: `${w.cwd} is not a folder; Amazon Q keeps chat history per workspace folder` }
+      return { ok: true }
+    },
+
+    async write(session: Session, w: WriteOptions): Promise<WriteResult> {
+      const cwd = resolve(w.cwd)
+      const now = new Date()
+      const file = join(historyDir(w.home), dbName(workspaceId(cwd)))
+      const backupDir = join(w.home, ".brain", "backups", TOOL, now.toISOString().replace(/[:.]/g, "-"))
+      const had = exists(file)
+      let db: LokiDb
+      if (had) {
+        try {
+          db = JSON.parse(readFileSync(file, "utf8")) as LokiDb
+        } catch {
+          throw new Error(`${file} is not a readable Amazon Q history file; nothing was changed`)
+        }
+      } else db = emptyDb(file, now)
+      let historyId = randomUUID()
+      while (tabsOf(db).some((t) => t.historyId === historyId)) historyId = randomUUID()
+      const plan = planTab(session, { historyId, conversationId: randomUUID(), now })
+      insertTab(db, plan.tab, now)
+
+      if (!w.dryRun) {
+        mkdirSync(historyDir(w.home), { recursive: true })
+        if (had) {
+          mkdirSync(backupDir, { recursive: true })
+          copyFileSync(file, join(backupDir, basename(file)))
+        }
+        const tmp = `${file}.brain-${process.pid}`
+        writeFileSync(tmp, JSON.stringify(db), { mode: 0o600 })
+        renameSync(tmp, file)
+        try {
+          const back = await amazonQReader.read({ tool: TOOL, sourceId: historyId, path: file }, w.home)
+          const n = countTurns(back)
+          const pairs = unpaired(back)
+          if (n.user !== plan.expect.users || n.tool_call !== plan.expect.calls || pairs.calls.length || pairs.results.length)
+            throw new Error(`the new Amazon Q conversation did not read back intact (requests ${n.user}/${plan.expect.users}, tool calls ${n.tool_call}/${plan.expect.calls}, unpaired ${pairs.calls.length + pairs.results.length})`)
+        } catch (e) {
+          if (had) copyFileSync(join(backupDir, basename(file)), file)
+          else rmSync(file, { force: true })
+          throw new Error(`${(e as Error).message}; the history file was restored`)
+        }
+      }
+      const editor = editors(w.home)[0] ?? "code"
+      return {
+        tool: TOOL,
+        way: "native",
+        sessionId: historyId,
+        written: had ? [file, join(backupDir, basename(file))] : [file],
+        open: `${editor} ${shellQuote(cwd)}   # Amazon Q reopens "${plan.tab.title as string}" when the folder opens; it is also in Amazon Q's History`,
+        lost: plan.lost,
+        dryRun: !!w.dryRun,
+      }
+    },
+  }
+}
+
+export const amazonQNativeWriter = amazonQWriter()

package/src/adapters/antigravity/index.ts

@@ -0,0 +1,9 @@
+import type { Reader, Writer } from "../types.ts"
+import { antigravityReader } from "./reader.ts"
+import { antigravityWriter } from "./writer.ts"
+
+// Antigravity (Google): reads the CLI's conversations and the IDE's SQLite ones under ~/.gemini, and continues
+// any session as a new native conversation of the Antigravity CLI (1.1.16). The IDE has no native writer; it is a
+// target through the continuation brief.
+export const readers: Reader[] = [antigravityReader]
+export const writers: Writer[] = [antigravityWriter]

package/src/adapters/antigravity/proto.ts

@@ -0,0 +1,194 @@
+// A small, bounded protobuf wire codec: enough to read and write the few Antigravity messages brain needs,
+// with no generated classes and no descriptors. It takes varints (canonical, at most 64 bits), fixed64,
+// length-delimited values and fixed32; it rejects groups and unknown wire types, caps every length and the
+// number of fields in one message, and never recurses on its own (callers decode nested messages they know).
+// Ported from the wire subset session-migrate (MIT, xhluca) pins for Antigravity CLI 1.1.16.
+
+export const WIRE = { varint: 0, fixed64: 1, bytes: 2, fixed32: 5 } as const
+
+export interface Field {
+  no: number
+  wire: 0 | 1 | 2 | 5
+  /** A varint as a number when it is a safe integer, else a bigint; raw bytes for the other wire types. */
+  value: number | bigint | Uint8Array
+}
+
+export interface Limits {
+  /** Longest length-delimited value, and longest message. */
+  maxBytes: number
+  /** Most fields in one message. */
+  maxFields: number
+}
+
+export const LIMITS: Limits = { maxBytes: 64 * 1024 * 1024, maxFields: 100_000 }
+
+export class ProtoError extends Error {
+  constructor(why: string) {
+    super(`protobuf: ${why}`)
+  }
+}
+
+const MAX_FIELD_NO = 536_870_911
+
+/** A varint at `at`: its value and where the next byte is. Rejects truncated, over-long and non-canonical encodings. */
+function readVarint(b: Uint8Array, at: number): [bigint, number] {
+  let v = 0n
+  for (let i = 0; i < 10; i++) {
+    if (at >= b.length) throw new ProtoError("varint is truncated")
+    const byte = b[at++]!
+    if (i === 9 && byte > 1) throw new ProtoError("varint exceeds 64 bits")
+    v |= BigInt(byte & 0x7f) << BigInt(7 * i)
+    if (byte < 0x80) {
+      // Canonical: no trailing zero byte (0x80 0x00 is 0 written long).
+      if (i > 0 && byte === 0) throw new ProtoError("varint is not canonical")
+      return [v, at]
+    }
+  }
+  throw new ProtoError("varint exceeds 64 bits")
+}
+
+const small = (v: bigint): number | bigint => (v <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(v) : v)
+
+/** The fields of one message, in wire order. Throws ProtoError on anything outside the subset or the limits. */
+export function decode(b: Uint8Array, limits: Limits = LIMITS): Field[] {
+  if (b.length > limits.maxBytes) throw new ProtoError("message exceeds the size limit")
+  const out: Field[] = []
+  let at = 0
+  while (at < b.length) {
+    if (out.length >= limits.maxFields) throw new ProtoError("message has too many fields")
+    const [key, next] = readVarint(b, at)
+    at = next
+    const no = Number(key >> 3n)
+    const wire = Number(key & 7n)
+    if (no <= 0 || no > MAX_FIELD_NO) throw new ProtoError(`invalid field number ${no}`)
+    switch (wire) {
+      case 0: {
+        const [v, n] = readVarint(b, at)
+        at = n
+        out.push({ no, wire: 0, value: small(v) })
+        break
+      }
+      case 1:
+      case 5: {
+        const size = wire === 1 ? 8 : 4
+        if (at + size > b.length) throw new ProtoError(`fixed${size * 8} value is truncated`)
+        out.push({ no, wire, value: b.slice(at, at + size) })
+        at += size
+        break
+      }
+      case 2: {
+        const [len, n] = readVarint(b, at)
+        at = n
+        if (len > BigInt(limits.maxBytes)) throw new ProtoError("value exceeds the size limit")
+        const end = at + Number(len)
+        if (end > b.length) throw new ProtoError("length-delimited value is truncated")
+        out.push({ no, wire: 2, value: b.slice(at, end) })
+        at = end
+        break
+      }
+      case 3:
+      case 4:
+        throw new ProtoError("groups are not supported")
+      default:
+        throw new ProtoError(`unknown wire type ${wire}`)
+    }
+  }
+  return out
+}
+
+// Encoding.
+
+function varintBytes(v: number | bigint): Uint8Array {
+  if (typeof v === "number" && (!Number.isSafeInteger(v) || v < 0)) throw new ProtoError("cannot encode a negative, fractional or unsafe varint")
+  let n = typeof v === "bigint" ? v : BigInt(v)
+  if (n < 0n || n >= 1n << 64n) throw new ProtoError("varint out of range")
+  const out: number[] = []
+  while (n >= 0x80n) {
+    out.push(Number(n & 0x7fn) | 0x80)
+    n >>= 7n
+  }
+  out.push(Number(n))
+  return Uint8Array.from(out)
+}
+
+export function concat(parts: Uint8Array[]): Uint8Array {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0))
+  let at = 0
+  for (const p of parts) {
+    out.set(p, at)
+    at += p.length
+  }
+  return out
+}
+
+const key = (no: number, wire: number) => {
+  if (!Number.isInteger(no) || no <= 0 || no > MAX_FIELD_NO) throw new ProtoError(`invalid field number ${no}`)
+  return varintBytes(BigInt(no) * 8n + BigInt(wire))
+}
+
+export const varintField = (no: number, v: number | bigint) => concat([key(no, 0), varintBytes(v)])
+
+export function bytesField(no: number, v: Uint8Array, limits: Limits = LIMITS): Uint8Array {
+  if (v.length > limits.maxBytes) throw new ProtoError("value exceeds the size limit")
+  return concat([key(no, 2), varintBytes(v.length), v])
+}
+
+export const textField = (no: number, s: string) => bytesField(no, new TextEncoder().encode(s))
+
+/** A nested message as a length-delimited field. */
+export const messageField = (no: number, parts: Uint8Array[]) => bytesField(no, concat(parts))
+
+export function fixedField(no: number, v: Uint8Array): Uint8Array {
+  if (v.length !== 4 && v.length !== 8) throw new ProtoError("a fixed value is 4 or 8 bytes")
+  return concat([key(no, v.length === 8 ? 1 : 5), v])
+}
+
+/** Decoded fields back to bytes: encode(decode(b)) is b for any canonical message. */
+export function encode(fields: Field[]): Uint8Array {
+  return concat(
+    fields.map((f) => {
+      if (f.wire === 0) return varintField(f.no, f.value as number | bigint)
+      if (f.wire === 2) return bytesField(f.no, f.value as Uint8Array)
+      return fixedField(f.no, f.value as Uint8Array)
+    }),
+  )
+}
+
+// Reading fields. Protobuf lets a singular field repeat (the last one wins), so these take the last.
+
+const last = (fields: Field[], no: number, wire: number) => {
+  for (let i = fields.length - 1; i >= 0; i--) if (fields[i]!.no === no && fields[i]!.wire === wire) return fields[i]!
+  return undefined
+}
+
+/** Every length-delimited value of a repeated field, in order. */
+export const allBytes = (fields: Field[], no: number): Uint8Array[] => fields.filter((f) => f.no === no && f.wire === 2).map((f) => f.value as Uint8Array)
+
+export const bytesOf = (fields: Field[], no: number): Uint8Array | undefined => last(fields, no, 2)?.value as Uint8Array | undefined
+
+export function numberOf(fields: Field[], no: number): number | undefined {
+  const v = last(fields, no, 0)?.value
+  return v === undefined ? undefined : Number(v)
+}
+
+const utf8 = new TextDecoder("utf-8", { fatal: true })
+
+/** A value as UTF-8 text; undefined when absent or not valid UTF-8. */
+export function textOf(fields: Field[], no: number): string | undefined {
+  const b = bytesOf(fields, no)
+  return b === undefined ? undefined : asText(b)
+}
+
+export function asText(b: Uint8Array): string | undefined {
+  try {
+    return utf8.decode(b)
+  } catch {
+    return undefined
+  }
+}
+
+/** A nested message, decoded; undefined when absent. */
+export function messageOf(fields: Field[], no: number, limits: Limits = LIMITS): Field[] | undefined {
+  const b = bytesOf(fields, no)
+  return b === undefined ? undefined : decode(b, limits)
+}