golem-kit 0.1.0 → 0.2.0

package/src/backend/model.ts

@@ -0,0 +1,129 @@
+import { spawn } from 'node:child_process'
+import { access, constants } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { basename, isAbsolute } from 'node:path'
+import type { ModelConfig } from '../config.ts'
+import { InvalidError, ModelUnavailableError, z, type Model } from '../operations.ts'
+
+/**
+ * `context.model`, over a local agent CLI: Claude Code (the default, haiku) or Codex, whichever
+ * `golem.config.ts` names in `model`. An app never learns which one answered — the runtime is the
+ * app owner's choice, not the operation's.
+ *
+ * The prompt goes in on stdin, never in argv where `ps` would show it, and the call runs in a
+ * temporary directory so nothing in the app's folder becomes part of it.
+ */
+const timeoutMs = 180_000
+
+const maxImages = 10
+
+type Runtime = {
+  executable: string
+  args(images: string[]): string[]
+  /** Whether the CLI can be handed image files at all. */
+  images: 'flag' | 'none'
+  /** The answer text out of the CLI's own stdout format, or a reason there is none. */
+  answer(out: string): { text: string } | { error: string }
+}
+
+const runtimes: Record<ModelConfig['runtime'], (name?: string) => Runtime> = {
+  claude: (name = 'haiku') => ({
+    executable: 'claude',
+    args: () => ['-p', '--output-format', 'json', '--model', name, '--allowed-tools', '', '--strict-mcp-config'],
+    images: 'none',
+    answer(out) {
+      const { is_error: failed, result } = JSON.parse(out) as { is_error?: boolean; result?: unknown }
+      if (failed || typeof result !== 'string') return { error: typeof result === 'string' ? result : 'The model runtime reported an error.' }
+      return { text: result }
+    },
+  }),
+  // `--ephemeral` keeps the call out of ~/.codex/sessions; `-` reads the prompt from stdin.
+  codex: (name) => ({
+    executable: 'codex',
+    // `-i <file>` attaches an image to the initial prompt; the CLI reads it, nothing is copied.
+    args: (images) => ['exec', ...(name ? ['-m', name] : []), ...images.flatMap((path) => ['-i', path]), '--skip-git-repo-check', '--ephemeral', '-s', 'read-only', '--json', '-'],
+    images: 'flag',
+    answer(out) {
+      // JSONL events; the answer is the last agent message, a failed turn carries its reason.
+      let text: string | undefined
+      let error: string | undefined
+      for (const line of out.split('\n')) {
+        if (!line.trim()) continue
+        const event = JSON.parse(line) as { type: string; item?: { type: string; text?: string }; error?: { message?: string } }
+        if (event.type === 'item.completed' && event.item?.type === 'agent_message' && typeof event.item.text === 'string') text = event.item.text
+        if (event.type === 'turn.failed') error = event.error?.message ?? 'The model runtime reported an error.'
+      }
+      return error ? { error } : text === undefined ? { error: 'The model gave no answer.' } : { text }
+    },
+  }),
+}
+
+export function openModel(config: ModelConfig = { runtime: 'claude' }): Model {
+  const runtime = runtimes[config.runtime](config.name)
+  return {
+    async extract({ schema, text, instructions, images = [] }) {
+      // Input problems first, runtime limits second, spawn last.
+      if (images.length > maxImages) throw new InvalidError(`At most ${maxImages} images per call.`)
+      for (const path of images) {
+        if (!isAbsolute(path)) throw new InvalidError(`Image not readable: ${basename(path)}`)
+        try {
+          await access(path, constants.R_OK)
+        } catch {
+          throw new InvalidError(`Image not readable: ${basename(path)}`)
+        }
+      }
+      if (images.length && runtime.images === 'none') throw new ModelUnavailableError('This model runtime reads no images.')
+      const prompt = [
+        instructions ?? 'Fill the schema from what the text actually says. Leave a field empty rather than guessing.',
+        'Answer with one JSON value this JSON Schema accepts, and nothing else:',
+        JSON.stringify(z.toJSONSchema(schema, { unrepresentable: 'any' })),
+        `Text:\n${text}`,
+        ...(images.length ? [`Images: ${images.length} attached, in the order given.`] : []),
+      ].join('\n\n')
+      const answer = await ask(runtime, prompt, images)
+      let value: unknown
+      try {
+        value = JSON.parse(unfence(answer))
+      } catch {
+        throw new ModelUnavailableError('The model did not answer with JSON.')
+      }
+      const parsed = schema.safeParse(value)
+      if (!parsed.success) throw new ModelUnavailableError(`The model's answer does not fit the schema: ${z.prettifyError(parsed.error)}`)
+      return parsed.data
+    },
+  }
+}
+
+/** The answer text, or `ModelUnavailableError` for every way the runtime can fail to give one. */
+function ask({ executable, args, answer }: Runtime, prompt: string, images: string[]): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, args(images), { cwd: tmpdir(), stdio: ['pipe', 'pipe', 'pipe'] })
+    let out = ''
+    let error = ''
+    const timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL') }, timeoutMs)
+    let timedOut = false
+    child.stdout.on('data', (chunk) => { out += chunk })
+    child.stderr.on('data', (chunk) => { error += chunk })
+    child.once('error', (cause: NodeJS.ErrnoException) => {
+      clearTimeout(timer)
+      reject(new ModelUnavailableError(cause.code === 'ENOENT' ? `No model runtime: ${executable} is not installed.` : `The model runtime failed to start: ${cause.message}`))
+    })
+    child.once('close', (code) => {
+      clearTimeout(timer)
+      if (timedOut) return reject(new ModelUnavailableError('The model did not answer in time.'))
+      if (code !== 0) return reject(new ModelUnavailableError(`The model runtime exited with code ${code}${error.trim() ? `: ${error.trim().slice(0, 200)}` : ''}`))
+      let result: ReturnType<Runtime['answer']>
+      try {
+        result = answer(out)
+      } catch {
+        return reject(new ModelUnavailableError('The model runtime did not answer in its own format.'))
+      }
+      if ('error' in result) return reject(new ModelUnavailableError(result.error.slice(0, 200)))
+      resolve(result.text)
+    })
+    child.stdin.end(prompt)
+  })
+}
+
+/** Models like to wrap JSON in a ``` fence whatever the instruction says. */
+const unfence = (text: string) => text.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '')

package/src/backend/rules.ts

@@ -0,0 +1,53 @@
+import { InvalidError, NotFoundError, VersionConflictError, validField, type RecordPage, type RecordQuery, type Row } from '../operations.ts'
+
+/** Shared update rule: the version check and the store-owned fields. */
+export function nextVersion(collection: string, id: string, current: Row | undefined, patch: Record<string, unknown>, options?: { expectedVersion: number; versionField?: string }): Row {
+  if (!current) throw new NotFoundError(`No ${collection} record ${id}`)
+  if (options && current[options.versionField ?? 'version'] !== options.expectedVersion) {
+    throw new VersionConflictError(`This ${collection} record changed since it was read`, current)
+  }
+  const { id: _id, version: _version, createdAt: _createdAt, updatedAt: _updatedAt, ...changes } = patch
+  return { ...current, ...json(changes), id: current.id, version: current.version + 1, createdAt: current.createdAt, updatedAt: new Date().toISOString() }
+}
+
+/** The query semantics both stores share: equality filters, case-insensitive search, stable sort, offset cursor. */
+export function page(rows: Row[], query: RecordQuery = {}): RecordPage<Row> {
+  const { offset, limit } = bounds(query)
+  let matched = rows
+  for (const [key, value] of Object.entries(query.filter ?? {})) {
+    validField(key)
+    const allowed = Array.isArray(value) ? value : [value]
+    matched = matched.filter((row) => allowed.some((one) => one === null ? row[key] == null : row[key] === one))
+  }
+  if (query.search?.text) {
+    const text = query.search.text.toLowerCase()
+    const fields = query.search.fields.map(validField)
+    matched = matched.filter((row) => fields.some((key) => row[key] != null && String(row[key]).toLowerCase().includes(text)))
+  }
+  if (query.sort) {
+    const { field, direction } = query.sort
+    validField(field)
+    const sign = direction === 'desc' ? -1 : 1
+    matched = matched.toSorted((left, right) => sign * compare(left[field], right[field]))
+  }
+  const slice = matched.slice(offset, offset + limit)
+  return { rows: slice, nextCursor: offset + limit < matched.length ? String(offset + limit) : null }
+}
+
+export function bounds(query: RecordQuery = {}): { offset: number; limit: number } {
+  const offset = query.cursor ? Number(query.cursor) : 0
+  const limit = query.limit ?? 50
+  if (!Number.isInteger(offset) || offset < 0) throw new InvalidError('Invalid cursor')
+  if (!Number.isInteger(limit) || limit < 1 || limit > 500) throw new InvalidError('limit must be an integer from 1 to 500')
+  return { offset, limit }
+}
+
+function compare(left: unknown, right: unknown): number {
+  if (left == null || right == null) return left == null ? (right == null ? 0 : -1) : 1
+  return left < right ? -1 : left > right ? 1 : 0
+}
+
+/** Stored values are JSON: what is kept in memory must equal what a restart reads back. */
+export function json<T>(value: T): T {
+  return JSON.parse(JSON.stringify(value)) as T
+}

package/src/backend/sqlite.ts

@@ -0,0 +1,73 @@
+import { randomUUID } from 'node:crypto'
+import { mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { DatabaseSync, type SQLInputValue } from 'node:sqlite'
+import { NotFoundError, RecordRefusedError, validCollection, validField, validId, type RecordStore, type Row } from '../operations.ts'
+import { bounds, json, nextVersion } from './rules.ts'
+
+/**
+ * Records as JSON documents in one SQLite table, queried with json_extract.
+ * `native` is the open `DatabaseSync` for app code in src/server/persistence that needs real SQL.
+ */
+export function sqliteStore(file: string): RecordStore & { native: DatabaseSync } {
+  mkdirSync(dirname(file), { recursive: true })
+  const db = new DatabaseSync(file)
+  db.exec(`PRAGMA journal_mode = WAL;
+    PRAGMA synchronous = FULL;
+    CREATE TABLE IF NOT EXISTS records (collection TEXT NOT NULL, id TEXT NOT NULL, data TEXT NOT NULL, PRIMARY KEY (collection, id));`)
+  const read = db.prepare('SELECT data FROM records WHERE collection = ? AND id = ?')
+  const insert = db.prepare('INSERT INTO records (collection, id, data) VALUES (?, ?, ?)')
+  const write = db.prepare('UPDATE records SET data = ? WHERE collection = ? AND id = ?')
+  const erase = db.prepare('DELETE FROM records WHERE collection = ? AND id = ?')
+  const get = (collection: string, id: string): Row | null => {
+    const found = read.get(validCollection(collection), validId(id)) as { data: string } | undefined
+    return found ? JSON.parse(found.data) as Row : null
+  }
+  // node:sqlite is synchronous, so each method below runs to completion without interleaving.
+  return {
+    native: db,
+    async list(collection, query = {}) {
+      const { offset, limit } = bounds(query)
+      const where = ['collection = ?']
+      const params: SQLInputValue[] = [validCollection(collection)]
+      const path = (field: string) => `'$.${validField(field)}'`
+      for (const [key, value] of Object.entries(query.filter ?? {})) {
+        const allowed = Array.isArray(value) ? value : [value]
+        const clauses = allowed.map((one) => {
+          if (one === null) return `json_extract(data, ${path(key)}) IS NULL`
+          params.push(typeof one === 'boolean' ? JSON.stringify(one) : one)
+          return typeof one === 'boolean'
+            ? `json_type(data, ${path(key)}) = ?`
+            : `(json_extract(data, ${path(key)}) = ? AND json_type(data, ${path(key)}) ${typeof one === 'string' ? "= 'text'" : "IN ('integer', 'real')"})`
+        })
+        where.push(clauses.length ? `(${clauses.join(' OR ')})` : '0')
+      }
+      if (query.search?.text) {
+        const text = query.search.text.toLowerCase()
+        where.push(`(${query.search.fields.map((field) => { params.push(text); return `instr(lower(CAST(json_extract(data, ${path(field)}) AS TEXT)), ?) > 0` }).join(' OR ') || '0'})`)
+      }
+      const order = query.sort ? `json_extract(data, ${path(query.sort.field)}) ${query.sort.direction === 'desc' ? 'DESC' : 'ASC'}, rowid` : 'rowid'
+      const rows = db.prepare(`SELECT data FROM records WHERE ${where.join(' AND ')} ORDER BY ${order} LIMIT ? OFFSET ?`)
+        .all(...params, limit + 1, offset) as Array<{ data: string }>
+      return { rows: rows.slice(0, limit).map((row) => JSON.parse(row.data) as Row), nextCursor: rows.length > limit ? String(offset + limit) : null }
+    },
+    async get(collection, id) { return get(collection, id) },
+    async create(collection, data) {
+      const id = data.id === undefined ? randomUUID() : validId(String(data.id))
+      if (get(collection, id)) throw new RecordRefusedError(`A record with id ${id} already exists`, [{ field: 'id', message: 'This id is already taken.' }])
+      const now = new Date().toISOString()
+      const row: Row = { ...json(data), id, version: 1, createdAt: now, updatedAt: now }
+      insert.run(collection, id, JSON.stringify(row))
+      return row
+    },
+    async update(collection, id, patch, options) {
+      const row = nextVersion(collection, id, get(collection, id) ?? undefined, patch, options)
+      write.run(JSON.stringify(row), collection, id)
+      return row
+    },
+    async remove(collection, id) {
+      if (!erase.run(validCollection(collection), validId(id)).changes) throw new NotFoundError(`No ${collection} record ${id}`)
+    },
+    async close() { if (db.isOpen) db.close() },
+  }
+}

package/src/backend/views.ts

@@ -0,0 +1,216 @@
+import { randomBytes, randomUUID } from 'node:crypto'
+import type { IncomingMessage } from 'node:http'
+import { ForbiddenError, InvalidError, NotFoundError, UnauthorizedError, VersionConflictError, z, type Principal, type Via } from '../operations.ts'
+
+/** Something an agent offered to show; the person accepts it in one browser view, where alone it is applied. */
+export type ViewOffer = { id: string; conversation: string; action: 'source.open'; input: { root: string; path: string; line: number; endLine: number } }
+/**
+ * `apply` carries the file `version` its lines were counted in and the `text` of those lines: show them
+ * once the editor has that version, and look for `text` instead when the editor shows an unsaved draft.
+ */
+export type ViewEvent = { type: 'offer'; offer: ViewOffer } | { type: 'apply'; offer: ViewOffer; version: number; text: string } | { type: 'withdrawn'; id: string }
+
+/** What an agent can discover: names, when to use them and their input, never data. */
+export type ViewActionDoc = { name: string; description: string; inputSchema: unknown }
+
+/**
+ * The agent runtime owns conversations and the browser identity of anonymous visitors, so it supplies
+ * both checks. `owner` derives a trusted key from the actual request and its server-resolved principal
+ * (an account id, or a key for the runtime's browser cookie), never from request input; `null` refuses.
+ * `owns` says whether that key owns the conversation.
+ */
+export type Conversations = {
+  owner(request: IncomingMessage, principal: Principal): Promise<string | null> | string | null
+  owns(conversation: string, owner: string): Promise<boolean> | boolean
+}
+
+/** Trusted context the runtime holds for one message: who, which conversation, and the view it came from. */
+export type ViewBinding = { principal: Principal; owner: string; conversation: string }
+
+export type Views = {
+  /** The actions an agent may request in this app. Empty until the app configures knowledge roots. */
+  actions(): ViewActionDoc[]
+  /** Installs the runtime's checks. Until then no view opens and no offer is made. */
+  useConversations(conversations: Conversations): void
+  /** A browser tab opens one view of a conversation it owns; the returned id is that tab's capability. */
+  open(request: IncomingMessage, principal: Principal, conversation: string): Promise<{ id: string }>
+  /** Whether `view` is a live view of this binding's conversation, held by the same person, session and owner. The runtime checks a message's view with it before accepting the message. */
+  bound(view: string, binding: ViewBinding): Promise<boolean>
+  /** Delivers this view's events until the returned function is called. */
+  connect(request: IncomingMessage, principal: Principal, id: string, send: (event: ViewEvent) => void): Promise<() => void>
+  /**
+   * An agent acting in `binding` offers an action. The source is authorized as the principal first.
+   * With `view` (the tab the message came from) the offer is sent to that view; without one it is only
+   * returned, for the chat to show. Either way it is applied only after the person accepts it.
+   */
+  request(binding: ViewBinding & { view?: string }, action: string, input: unknown): Promise<{ offer: ViewOffer; delivered: boolean }>
+  /** The person's answer from one of their views. Accepting re-authorizes and applies to that view only. */
+  answer(request: IncomingMessage, principal: Principal, id: string, offer: string, accept: boolean): Promise<void>
+}
+
+type Channel = { holder: Principal; owner: string; conversation: string; send?: (event: ViewEvent) => void }
+/** `sha256` and `passage` are what the offer pointed at, so acceptance can find the same text in a changed file. */
+type Pending = { offer: ViewOffer; holder: Principal; owner: string; view?: string; sha256: string; passage: string }
+
+const offerLifetime = 10 * 60_000
+const connectWithin = 60_000
+
+const sourceOpen = z.object({
+  root: z.string().min(1),
+  path: z.string().min(1),
+  quote: z.string().min(1).max(2000).optional().describe('Text copied from the source; the lines containing it are highlighted.'),
+  line: z.number().int().min(1).optional().describe('1-based first line to highlight, when there is no quote.'),
+  endLine: z.number().int().min(1).optional(),
+}).strict()
+
+const catalog: ViewActionDoc[] = [{
+  name: 'source.open',
+  description: 'Offer to open a knowledge file beside the conversation with a passage highlighted and the rest of the file around it. The person sees the offer and chooses whether to open it.',
+  inputSchema: z.toJSONSchema(sourceOpen),
+}]
+
+/** Same person in the same signed-in session, or both anonymous (then the owner key tells visitors apart). */
+const same = (a: Principal, b: Principal) => a.kind === b.kind && (a.kind === 'anonymous' || (b.kind === 'user' && a.id === b.id && a.session === b.session))
+const refused = () => new ForbiddenError('Cannot open that source')
+const noView = () => new NotFoundError('No such view')
+
+export function createViews(app: {
+  invoke(name: string, input: unknown, principal: Principal, via: Via): Promise<unknown>
+  refresh(principal: Principal): Promise<Principal>
+  has(operation: string): boolean
+}): Views {
+  const channels = new Map<string, Channel>()
+  const offers = new Map<string, Pending>()
+  let conversations: Conversations | undefined
+
+  /** The binding as it stands now: a live principal whose owner key still owns the conversation. */
+  async function check({ principal, owner, conversation }: ViewBinding): Promise<Principal> {
+    const now = await app.refresh(principal)
+    if (!conversations || typeof owner !== 'string' || !owner || typeof conversation !== 'string' || !conversation || !(await conversations.owns(conversation, owner))) {
+      throw new NotFoundError('No such conversation')
+    }
+    return now
+  }
+
+  async function ownerOf(request: IncomingMessage, principal: Principal): Promise<string> {
+    const owner = conversations ? await conversations.owner(request, principal) : null
+    if (!owner) throw new NotFoundError('No such conversation')
+    return owner
+  }
+
+  /** A browser call on a view: the capability, the principal and session it was opened with, and the same owner. */
+  async function owned(request: IncomingMessage, principal: Principal, id: string): Promise<Channel> {
+    const channel = channels.get(id)
+    if (!channel || !same(channel.holder, principal) || (await ownerOf(request, principal)) !== channel.owner) throw noView()
+    await check({ principal, owner: channel.owner, conversation: channel.conversation })
+    return channel
+  }
+
+  function withdraw(id: string) {
+    const pending = offers.get(id)
+    offers.delete(id)
+    for (const channel of channels.values()) {
+      if (pending && channel.conversation === pending.offer.conversation && channel.owner === pending.owner) channel.send?.({ type: 'withdrawn', id })
+    }
+  }
+
+  /** Reads the file as `principal`; any failure is the same refusal, so a view never tells what exists. */
+  async function readable(principal: Principal, root: string, path: string): Promise<{ body: string; sha256: string; version: number }> {
+    try {
+      return (await app.invoke('knowledge.read', { root, path }, principal, 'agent')) as { body: string; sha256: string; version: number }
+    } catch (error) {
+      if ((error as Error).name === 'UnauthorizedError') throw error
+      throw refused()
+    }
+  }
+
+  return {
+    actions: () => app.has('knowledge.read') ? catalog : [],
+    useConversations(next) { conversations = next },
+    async open(request, principal, conversation) {
+      const owner = await ownerOf(request, principal)
+      const holder = await check({ principal, owner, conversation })
+      const id = randomBytes(24).toString('base64url')
+      channels.set(id, { holder, owner, conversation })
+      setTimeout(() => { if (!channels.get(id)?.send) channels.delete(id) }, connectWithin).unref()
+      return { id }
+    },
+    async bound(view, binding) {
+      const channel = channels.get(view)
+      if (!channel?.send || channel.conversation !== binding.conversation || channel.owner !== binding.owner) return false
+      const now = await check(binding).catch(() => null)
+      return Boolean(now && same(channel.holder, now))
+    },
+    async connect(request, principal, id, send) {
+      const channel = await owned(request, principal, id)
+      channel.send = send
+      return () => { channels.delete(id) }
+    },
+    async request(binding, action, raw) {
+      if (action !== 'source.open' || !app.has('knowledge.read')) throw new NotFoundError(`Unknown view action: ${action}`)
+      const parsed = sourceOpen.safeParse(raw)
+      if (!parsed.success) throw new InvalidError(`${action}: ${z.prettifyError(parsed.error)}`)
+      const { root, path, quote, line, endLine } = parsed.data
+      const { owner, conversation, view } = binding
+      const holder = await check(binding)
+      const source = await readable(holder, root, path)
+      const lines = source.body.split('\n')
+      let first = line ?? 1
+      let last = endLine ?? first
+      if (quote) {
+        const at = locate(lines, quote)
+        if (!at) throw new InvalidError('That passage is not in the source')
+        ;[first, last] = at
+      }
+      first = Math.min(first, lines.length)
+      last = Math.min(Math.max(last, first), lines.length)
+      const offer: ViewOffer = { id: randomUUID(), conversation, action, input: { root, path, line: first, endLine: last } }
+      const channel = view === undefined ? undefined : channels.get(view)
+      const target = channel?.send && channel.conversation === conversation && channel.owner === owner && same(channel.holder, holder) ? view : undefined
+      offers.set(offer.id, { offer, holder, owner, view: target, sha256: source.sha256, passage: lines.slice(first - 1, last).join('\n') })
+      setTimeout(() => { if (offers.has(offer.id)) withdraw(offer.id) }, offerLifetime).unref()
+      if (target) channel!.send!({ type: 'offer', offer })
+      return { offer, delivered: Boolean(target) }
+    },
+    async answer(request, principal, id, offerId, accept) {
+      const channel = await owned(request, principal, id)
+      const pending = offers.get(offerId)
+      // An offer sent to one view is answered there; one shown only in the chat may be answered from any view of it.
+      if (!pending || pending.offer.conversation !== channel.conversation || pending.owner !== channel.owner || !same(pending.holder, channel.holder) || (pending.view && pending.view !== id)) {
+        throw new NotFoundError('That offer is no longer open')
+      }
+      withdraw(offerId)
+      if (!accept) return
+      // Access may have changed since the offer: check again as the person now is.
+      const now = await app.refresh(principal).catch(() => { throw new UnauthorizedError('Sign in again to open this source.') })
+      const source = await readable(now, pending.offer.input.root, pending.offer.input.path)
+      const lines = source.body.split('\n')
+      let offer = pending.offer
+      if (source.sha256 !== pending.sha256) {
+        // The file changed since the offer: highlight the same passage where it now is, or say it is gone.
+        const at = pending.passage.trim() ? locate(lines, pending.passage) : null
+        if (!at) throw new VersionConflictError('That passage changed since it was offered; ask for it again', null)
+        offer = { ...offer, input: { ...offer.input, line: at[0], endLine: at[1] } }
+      }
+      const { line, endLine } = offer.input
+      channel.send?.({ type: 'apply', offer, version: source.version, text: lines.slice(line - 1, endLine).join('\n') })
+    },
+  }
+}
+
+/** First and last 1-based line of the first place `quote` appears, ignoring case and runs of whitespace. */
+function locate(lines: string[], quote: string): [number, number] | null {
+  let flat = ''
+  const lineOf: number[] = []
+  lines.forEach((text, index) => {
+    for (const char of `${text}\n`) {
+      const space = /\s/.test(char)
+      if (space && flat.endsWith(' ')) continue
+      flat += space ? ' ' : char.toLowerCase()
+      lineOf.push(index + 1)
+    }
+  })
+  const needle = quote.replace(/\s+/g, ' ').trim().toLowerCase()
+  const at = needle ? flat.indexOf(needle) : -1
+  return at < 0 ? null : [lineOf[at], lineOf[at + needle.length - 1]]
+}

package/src/brain.ts

@@ -0,0 +1,94 @@
+import { watch } from 'node:fs'
+import { readdir, readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * A Golem app's brain: the `brain/` folder at the app root, an OKF bundle (root `index.md` with
+ * `okf_version`, concepts with `type` front matter, optional `log.md`), served read-only to the
+ * golem-ui Brain adapter. Paths are `/`-separated and relative to `brain/`.
+ */
+export type BrainEntry = { path: string; kind: 'file' | 'dir' }
+export type BrainHit = { path: string; line: number; excerpt: string }
+
+const segment = /^[^/\\\0.][^/\\\0]{0,127}$/
+/** A relative path inside the bundle: no `..`, no hidden segments, no backslashes. Empty is the root. */
+function clean(value: string): string {
+  const path = value.replace(/\/$/, '')
+  if (path && !path.split('/').every((part) => segment.test(part))) throw new Error(`Invalid brain path: ${JSON.stringify(value)}`)
+  return path
+}
+
+export function openBrain(dir: string) {
+  const list = async (dir_ = ''): Promise<BrainEntry[]> => {
+    const folder = clean(dir_)
+    const entries = await readdir(join(dir, folder), { withFileTypes: true }).catch(() => [])
+    return entries
+      .filter((entry) => !entry.name.startsWith('.') && (entry.isDirectory() || entry.name.endsWith('.md')))
+      .map((entry): BrainEntry => ({ path: folder ? `${folder}/${entry.name}` : entry.name, kind: entry.isDirectory() ? 'dir' : 'file' }))
+      .sort((a, b) => (a.kind === b.kind ? a.path.localeCompare(b.path) : a.kind === 'dir' ? -1 : 1))
+  }
+  const read = async (path: string): Promise<string> => {
+    const file = clean(path)
+    if (!file.endsWith('.md')) throw new Error(`Not a markdown file: ${path}`)
+    return readFile(join(dir, file), 'utf8')
+  }
+  async function* walk(folder = ''): AsyncGenerator<string> {
+    for (const entry of await list(folder)) {
+      if (entry.kind === 'dir') yield* walk(entry.path)
+      else yield entry.path
+    }
+  }
+  return {
+    list,
+    read,
+    /** That folder's `index.md`, or the OKF fallback: one bullet per entry, its `description` from front matter. */
+    async index(dir_ = ''): Promise<string> {
+      const folder = clean(dir_)
+      const own = await read(folder ? `${folder}/index.md` : 'index.md').catch(() => undefined)
+      if (own !== undefined) return own
+      const lines = []
+      for (const entry of await list(folder)) {
+        const name = entry.path.slice(folder ? folder.length + 1 : 0)
+        if (entry.kind === 'file' && (name === 'index.md' || name === 'log.md')) continue
+        const description = entry.kind === 'file' ? /^description:\s*(.*)$/m.exec((await read(entry.path)).split(/^---$/m)[1] ?? '')?.[1]?.replace(/^["']|["']$/g, '') : ''
+        lines.push(`* [${name}](${name}${entry.kind === 'dir' ? '/' : ''})${description ? ` - ${description}` : ''}`)
+      }
+      return `# ${folder || 'Index'}\n\n${lines.join('\n')}\n`
+    },
+    // ponytail: substring scan of every file per query; an index if a brain outgrows a few MB.
+    async search(query: string, limit = 50): Promise<BrainHit[]> {
+      const needle = query.trim().toLowerCase()
+      const hits: BrainHit[] = []
+      if (!needle) return hits
+      for await (const path of walk()) {
+        const lines = (await read(path)).split('\n')
+        for (let i = 0; i < lines.length && hits.length < limit; i++) {
+          if (lines[i]!.toLowerCase().includes(needle)) hits.push({ path, line: i + 1, excerpt: lines[i]!.trim().slice(0, 200) })
+        }
+        if (hits.length >= limit) break
+      }
+      return hits
+    },
+    /** Fires on any change under the folder; the browser re-reads what it shows. */
+    watch(listener: () => void): () => void {
+      let watcher: ReturnType<typeof watch> | undefined
+      try { watcher = watch(dir, { recursive: true }, () => listener()) } catch { /* No folder yet: nothing to watch. */ }
+      watcher?.on('error', () => {})
+      return () => watcher?.close()
+    },
+  }
+}
+
+export type Brain = ReturnType<typeof openBrain>
+
+/**
+ * Source locations cited in an agent's reply, `path#L<start>-L<end>` relative to `brain/` (a leading
+ * `brain/` is dropped), in order of first mention. What becomes `sources` on the chat event.
+ */
+export function citations(text: string): string[] {
+  const found = new Set<string>()
+  for (const match of text.matchAll(/(?<![\w/.-])(?:brain\/)?([\w][\w./-]*\.md)#L(\d+)(?:-L?(\d+))?/g)) {
+    found.add(`${match[1]}#L${match[2]}-L${match[3] ?? match[2]}`)
+  }
+  return [...found]
+}