golem-kit 0.1.0 → 0.2.0

package/src/backend/app.ts

@@ -0,0 +1,269 @@
+import { EventEmitter } from 'node:events'
+import type { IncomingMessage } from 'node:http'
+import {
+  anonymous, defineOperation, ForbiddenError, InvalidError, NotFoundError, UnauthorizedError, validCollection, z,
+  type Authorize, type FileStore, type JobContext, type Operation, type Principal, type RecordStore, type Row, type Via,
+} from '../operations.ts'
+import { FILES_COLLECTION } from './files.ts'
+import { knowledgeOperations, type KnowledgeRoots } from './knowledge.ts'
+import { createViews, type Views } from './views.ts'
+import { createJobs, JOBS_CHANGE, type JobDefinition } from './jobs.ts'
+import type { ModelConfig } from '../config.ts'
+import { openModel } from './model.ts'
+
+/** What an app's src/server/index.ts may default-export. Every field is optional. */
+export type AppServerModule = {
+  operations?: Operation[]
+  /** Defaults to allowing everything: the local anonymous mode every existing app runs in. */
+  authorize?: Authorize
+  /** Trusted server-side identity for an HTTP request. Defaults to `anonymous`. */
+  resolvePrincipal?: (request: IncomingMessage) => Principal | Promise<Principal>
+  /** Markdown knowledge roots: name → directory relative to the app root. Adds the `knowledge.*` operations. */
+  knowledge?: KnowledgeRoots
+  /** Server-side runs of these operations, started or scheduled through the `jobs.*` operations. */
+  jobs?: JobDefinition[]
+}
+
+export type AgentTool = { name: string; description: string; inputSchema: unknown; call(input: unknown): Promise<unknown> }
+
+export type App = {
+  readonly operations: Operation[]
+  /** Swaps in a new server module's operations and hooks; stores, change stream and callers stay. */
+  use(module: AppServerModule): void
+  invoke(name: string, input: unknown, principal: Principal, via: Via): Promise<unknown>
+  /** Stops job timers; call before closing the store. */
+  close(): void
+  /**
+   * The operations as tools for an in-process agent acting for `principal`. Each call first
+   * refreshes the principal, so a signed-out session or a changed role takes effect at once.
+   */
+  agentTools(principal: Principal, context?: { owner: string; conversation: string; view?: string }): AgentTool[]
+  /** Session-scoped view actions: agents offer, the person accepts in one browser view. */
+  views: Views
+  resolvePrincipal(request: IncomingMessage): Promise<Principal>
+  /** Re-reads a principal from trusted state; throws once its session has ended. Identity for anonymous-only apps. */
+  refresh(principal: Principal): Promise<Principal>
+  /** Server-owned work acting for a stored account (a scheduled job): its current roles and groups. */
+  resolveAccount(id: string): Promise<Principal>
+  /** Emits `change` with a collection name after every record write, files included (`_files`). */
+  changes: EventEmitter
+}
+
+const allowAll: Authorize = () => true
+
+/** Where principals come from when the app has local accounts; replaces the module's `resolvePrincipal`. */
+export type Identity = {
+  /** guests: false — anonymous callers are refused on every path, HTTP, agent and server alike. */
+  requireUser: boolean
+  resolve(request: IncomingMessage): Promise<Principal>
+  refresh(principal: Principal): Promise<Principal>
+  resolveAccount(id: string): Promise<Principal>
+}
+
+export function createApp(stores: { records: RecordStore; files: (records: RecordStore) => FileStore; root?: string; model?: ModelConfig }, module: AppServerModule = {}, identity?: Identity): App {
+  const changes = new EventEmitter().setMaxListeners(0)
+  const records = watched(stores.records, (collection) => changes.emit('change', collection))
+  const files = stores.files(records)
+  // Job state lives in reserved collections of the raw store: only the `_jobs` name reaches the change stream.
+  const jobs = createJobs({
+    store: stores.records,
+    definitions: () => current.module.jobs ?? [],
+    hasAccounts: Boolean(identity),
+    resolveAccount: (id) => resolveAccount(id),
+    invoke: (name, input, principal, job) => invoke(name, input, principal, 'server', job),
+    emit: () => changes.emit('change', JOBS_CHANGE),
+  })
+  const model = openModel(stores.model)
+  const load = (next: AppServerModule) => compile(next, jobs.operations, stores.root)
+  let current = load(module)
+
+  async function resolveAccount(id: string): Promise<Principal> {
+    if (!identity) throw new ForbiddenError('This app has no accounts')
+    return identity.resolveAccount(id)
+  }
+
+  async function invoke(name: string, raw: unknown, principal: Principal, via: Via, job?: JobContext): Promise<unknown> {
+    const { byName, authorize } = current
+    if (identity?.requireUser && principal.kind === 'anonymous') throw new UnauthorizedError('Sign in to use this app.')
+    const operation = byName.get(name)
+    if (!operation) throw new NotFoundError(`Unknown operation: ${name}`)
+    const parsed = operation.input.safeParse(raw)
+    if (!parsed.success) throw new InvalidError(`${name}: ${z.prettifyError(parsed.error)}`)
+    const input = parsed.data
+    const target = operation.record?.(input)
+    const record = !target ? null : 'row' in target ? target.row : await records.get(target.collection, target.id)
+    const request = { operation: name, input, principal, via }
+    if (!(await authorize({ ...request, record }))) throw new ForbiddenError(`Not allowed: ${name}`)
+    const permits = async (row: Row) => Boolean(await authorize({ ...request, record: row }))
+    return operation.output.parse(await operation.run(input, { principal, via, records, files, model, permits, ...(job ? { job } : {}) }))
+  }
+
+  const views = createViews({
+    invoke,
+    refresh: async (principal) => identity ? identity.refresh(principal) : principal,
+    has: (name) => current.byName.has(name),
+  })
+
+  return {
+    get operations() { return [...current.byName.values()] },
+    invoke,
+    changes,
+    use(next) { current = load(next) },
+    close: () => jobs.close(),
+    resolvePrincipal: async (request) => identity ? identity.resolve(request) : (await current.module.resolvePrincipal?.(request)) ?? anonymous,
+    refresh: async (principal) => identity ? identity.refresh(principal) : principal,
+    resolveAccount,
+    views,
+    agentTools: (principal, context) => {
+      const fresh = async () => identity ? identity.refresh(principal) : principal
+      const tools: AgentTool[] = [...current.byName.values()].map((operation) => ({
+        name: operation.name,
+        description: operation.description,
+        inputSchema: z.toJSONSchema(operation.input, { unrepresentable: 'any' }),
+        call: async (input: unknown) => invoke(operation.name, input, await fresh(), 'agent'),
+      }))
+      if (!context || !views.actions().length) return tools
+      const { owner, conversation, view } = context
+      return [...tools, {
+        name: 'view.actions',
+        description: 'List what you can offer to show in the person\'s view of this conversation, with each action\'s input.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        call: async () => views.actions(),
+      }, {
+        name: 'view.request',
+        description: 'Offer one view action (see view.actions) in this conversation. The person accepts or dismisses it; nothing opens until they accept.',
+        inputSchema: { type: 'object', properties: { action: { type: 'string' }, input: { type: 'object' } }, required: ['action', 'input'], additionalProperties: false },
+        call: async (raw: unknown) => {
+          const { action, input } = (raw ?? {}) as { action?: unknown; input?: unknown }
+          if (typeof action !== 'string') throw new InvalidError('view.request needs an action name')
+          return views.request({ principal: await fresh(), owner, conversation, view }, action, input)
+        },
+      }]
+    },
+  }
+}
+
+/** Validates a server module into the lookup `invoke` reads; throws before anything is swapped. */
+function compile(module: AppServerModule, jobOperations: Operation[], root?: string) {
+  if (!module || typeof module !== 'object') throw new Error('src/server/index.ts must default-export an object')
+  if (module.knowledge !== undefined && !root) throw new Error('knowledge roots need the app root')
+  const knowledge = module.knowledge === undefined ? [] : knowledgeOperations(root!, module.knowledge)
+  for (const hook of ['authorize', 'resolvePrincipal'] as const) {
+    if (module[hook] !== undefined && typeof module[hook] !== 'function') throw new Error(`${hook} must be a function`)
+  }
+  for (const list of ['operations', 'jobs'] as const) {
+    if (module[list] !== undefined && !Array.isArray(module[list])) throw new Error(`${list} must be an array`)
+  }
+  const byName = new Map<string, Operation>()
+  for (const operation of [...builtins, ...jobOperations, ...knowledge, ...(module.operations ?? [])]) {
+    const schemas = [operation?.input, operation?.output].every((schema) => typeof (schema as { safeParse?: unknown })?.safeParse === 'function')
+    if (typeof operation?.name !== 'string' || !operation.name || typeof operation.run !== 'function' || !schemas) {
+      throw new Error(`Operation ${operation?.name ?? '(unnamed)'} needs a name, input and output schemas, and a run function`)
+    }
+    if (byName.has(operation.name)) throw new Error(`Operation ${operation.name} is defined twice`)
+    byName.set(operation.name, operation)
+  }
+  const jobNames = new Set<string>()
+  for (const job of module.jobs ?? []) {
+    if (typeof job?.name !== 'string' || !job.name || typeof job.description !== 'string') throw new Error(`Job ${job?.name ?? '(unnamed)'} needs a name and a description`)
+    if (jobNames.has(job.name)) throw new Error(`Job ${job.name} is defined twice`)
+    if (!byName.has(job.operation) || job.operation.startsWith('jobs.')) throw new Error(`Job ${job.name} runs ${job.operation}, which is not an app operation`)
+    if (job.missed !== undefined && job.missed !== 'skip' && job.missed !== 'once') throw new Error(`Job ${job.name}: missed must be 'skip' or 'once'`)
+    jobNames.add(job.name)
+  }
+  return { module, byName, authorize: module.authorize ?? allowAll }
+}
+
+function watched(store: RecordStore, emit: (collection: string) => void): RecordStore {
+  const after = <T>(collection: string, result: Promise<T>) => result.then((value) => { emit(collection); return value })
+  return {
+    native: store.native,
+    list: (collection, query) => store.list(collection, query),
+    get: (collection, id) => store.get(collection, id),
+    create: (collection, data) => after(collection, store.create(collection, data)),
+    update: (collection, id, patch, options) => after(collection, store.update(collection, id, patch, options)),
+    remove: (collection, id) => after(collection, store.remove(collection, id)),
+    close: () => store.close(),
+  }
+}
+
+// Builtin operations: the records and files adapters, over the same invoke/authorize path as app operations.
+const collection = z.string().refine((value) => !value.startsWith('_') && Boolean(validCollection(value)), 'must be a public collection name')
+const id = z.string().min(1)
+const bytes = z.custom<Uint8Array>((value) => value instanceof Uint8Array, 'must be bytes')
+const row = z.looseObject({ id: z.string(), version: z.number() })
+const scalar = z.union([z.string(), z.number(), z.boolean(), z.null()])
+const query = z.object({
+  filter: z.record(z.string(), z.union([scalar, z.array(scalar)])).optional(),
+  sort: z.object({ field: z.string(), direction: z.enum(['asc', 'desc']) }).optional(),
+  search: z.object({ text: z.string(), fields: z.array(z.string()) }).optional(),
+  cursor: z.string().nullable().optional(),
+  limit: z.number().int().optional(),
+})
+const fileRef = z.object({ id: z.string(), name: z.string(), contentType: z.string(), size: z.number(), folder: z.string(), uploadedAt: z.string(), caption: z.string().optional() })
+const fileRecord = (input: { id: string }) => ({ collection: FILES_COLLECTION, id: input.id })
+
+const builtins: Operation[] = [
+  defineOperation({
+    name: 'records.list', description: 'List records in a collection with optional equality filter, sort, search and paging.',
+    input: z.object({ collection, query: query.optional() }), output: z.object({ rows: z.array(row), nextCursor: z.string().nullable() }),
+    async run(input, { records, permits }) {
+      const page = await records.list(input.collection, input.query)
+      const visible = await Promise.all(page.rows.map(permits))
+      // Hidden rows make a page short; nextCursor still continues correctly.
+      return { rows: page.rows.filter((_, index) => visible[index]), nextCursor: page.nextCursor }
+    },
+  }),
+  defineOperation({
+    name: 'records.get', description: 'Read one record by id; null when it does not exist.',
+    input: z.object({ collection, id }), output: row.nullable(), record: (input) => input,
+    run: (input, { records }) => records.get(input.collection, input.id),
+  }),
+  defineOperation({
+    name: 'records.create', description: 'Create a record. The store mints id, version, createdAt and updatedAt unless id is given.',
+    input: z.object({ collection, data: z.record(z.string(), z.unknown()) }), output: row,
+    run: (input, { records }) => records.create(input.collection, input.data),
+  }),
+  defineOperation({
+    name: 'records.update', description: 'Merge a patch into a record. With expectedVersion, a record changed since it was read is refused.',
+    input: z.object({ collection, id, patch: z.record(z.string(), z.unknown()), expectedVersion: z.number().int().optional(), versionField: z.string().optional() }),
+    output: row, record: (input) => input,
+    run: (input, { records }) => records.update(input.collection, input.id, input.patch,
+      input.expectedVersion === undefined ? undefined : { expectedVersion: input.expectedVersion, versionField: input.versionField }),
+  }),
+  defineOperation({
+    name: 'records.remove', description: 'Delete a record by id.',
+    input: z.object({ collection, id }), output: z.null(), record: (input) => input,
+    run: async (input, { records }) => { await records.remove(input.collection, input.id); return null },
+  }),
+  defineOperation({
+    name: 'files.list', description: 'List stored files in a folder, newest first.',
+    input: z.object({ folder: z.string() }), output: z.array(fileRef),
+    async run(input, { files, records, permits }) {
+      const refs = await files.list(input.folder)
+      const rows = await Promise.all(refs.map((ref) => records.get(FILES_COLLECTION, ref.id)))
+      const visible = await Promise.all(rows.map((one) => one ? permits(one) : false))
+      return refs.filter((_, index) => visible[index])
+    },
+  }),
+  defineOperation({
+    name: 'files.upload', description: 'Store bytes in a folder and return the file reference.',
+    input: z.object({ folder: z.string(), name: z.string(), contentType: z.string(), bytes: bytes }), output: fileRef,
+    run: (input, { files }) => files.put(input),
+  }),
+  defineOperation({
+    name: 'files.read', description: 'Read a stored file reference and its bytes.',
+    input: z.object({ id }), output: z.object({ ref: fileRef, bytes: bytes }), record: fileRecord,
+    run: (input, { files }) => files.read(input.id),
+  }),
+  defineOperation({
+    name: 'files.caption', description: 'Write the caption on a stored file.',
+    input: z.object({ id, caption: z.string().max(2000) }), output: fileRef, record: fileRecord,
+    run: (input, { files }) => files.caption(input.id, input.caption),
+  }),
+  defineOperation({
+    name: 'files.remove', description: 'Delete a stored file.',
+    input: z.object({ id }), output: z.null(), record: fileRecord,
+    run: async (input, { files }) => { await files.remove(input.id); return null },
+  }),
+]

package/src/backend/files.ts

@@ -0,0 +1,68 @@
+import { randomUUID } from 'node:crypto'
+import { mkdirSync } from 'node:fs'
+import { readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { InvalidError, NotFoundError, validFolder, validId, type FileRef, type FileStore, type RecordStore, type Row } from '../operations.ts'
+
+/** Record collection holding file metadata; the leading underscore keeps it off the public records routes. */
+export const FILES_COLLECTION = '_files'
+
+/** Bytes named by id under one root directory, so no caller-supplied string ever becomes a path. */
+export function diskFiles(directory: string, records: RecordStore): FileStore {
+  mkdirSync(directory, { recursive: true })
+  const path = (id: string) => join(directory, validId(id))
+  const meta = async (id: string) => {
+    const row = await records.get(FILES_COLLECTION, id)
+    if (!row) throw new NotFoundError(`No file ${id}`)
+    return toRef(row)
+  }
+  return {
+    async put({ folder, name, contentType, bytes }) {
+      validFolder(folder)
+      if (!name || name.length > 255 || /[/\\\0]/.test(name)) throw new InvalidError(`Invalid file name: ${JSON.stringify(name)}`)
+      const id = randomUUID()
+      const temporary = `${path(id)}.upload`
+      await writeFile(temporary, bytes, { flush: true })
+      await rename(temporary, path(id))
+      try {
+        return toRef(await records.create(FILES_COLLECTION, { id, name, contentType: mediaType(contentType), size: bytes.byteLength, folder, uploadedAt: new Date().toISOString() }))
+      } catch (error) {
+        await unlink(path(id)).catch(() => {})
+        throw error
+      }
+    },
+    async read(id) {
+      const ref = await meta(id)
+      return { ref, bytes: await readFile(path(id)) }
+    },
+    async list(folder) {
+      const refs: FileRef[] = []
+      let cursor: string | null = null
+      do {
+        const found: Awaited<ReturnType<RecordStore['list']>> = await records.list(FILES_COLLECTION, { filter: { folder: validFolder(folder) }, sort: { field: 'uploadedAt', direction: 'desc' }, cursor, limit: 500 })
+        refs.push(...found.rows.map(toRef))
+        cursor = found.nextCursor
+      } while (cursor)
+      return refs
+    },
+    async caption(id, caption) {
+      await meta(id)
+      return toRef(await records.update(FILES_COLLECTION, id, { caption }))
+    },
+    async remove(id) {
+      await records.remove(FILES_COLLECTION, validId(id))
+      await unlink(path(id)).catch((error: NodeJS.ErrnoException) => { if (error.code !== 'ENOENT') throw error })
+    },
+  }
+}
+
+export function toRef(row: Row): FileRef {
+  const { id, name, contentType, size, folder, uploadedAt, caption } = row as Row & FileRef
+  return { id, name, contentType, size, folder, uploadedAt, ...(caption === undefined ? {} : { caption }) }
+}
+
+/** Only a bare `type/subtype` is kept; anything else is served as opaque bytes. */
+function mediaType(value: string): string {
+  const type = value.split(';')[0].trim().toLowerCase()
+  return /^[\w.+-]+\/[\w.+-]+$/.test(type) ? type : 'application/octet-stream'
+}

package/src/backend/http.ts

@@ -0,0 +1,276 @@
+import { existsSync } from 'node:fs'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { isAbsolute, join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { loadAppConfig, type AppConfig } from '../config.ts'
+import { build } from 'vite'
+import { AppError, InvalidError, UnauthorizedError, type Principal, type RecordStore } from '../operations.ts'
+import { createAccounts, type Accounts } from './accounts.ts'
+import { createApp, type App, type AppServerModule } from './app.ts'
+import { diskFiles } from './files.ts'
+import { jsonlStore } from './jsonl.ts'
+import { resolveSourceModule } from '../source-mode.ts'
+
+const maxJson = 1_000_000
+// Uploads are buffered in memory; stream to disk if apps need files past this size.
+const maxUpload = 25_000_000
+
+export type AppBackend = {
+  app: App
+  config: AppConfig
+  /** Present when golem.config.ts turns on local accounts. */
+  accounts?: Accounts
+  /** Serves /api/app/* and /api/auth/*. */
+  handle(request: IncomingMessage, response: ServerResponse): Promise<void>
+  /** The configured `origin` when set, else same-origin by Host; requests without Origin are not from a browser page. */
+  mutationAllowed(request: IncomingMessage): boolean
+  /** Where links handed out by this server point: the configured origin, else this Host authority. */
+  origin(authority?: string): string
+  /** Re-reads src/server/index.ts and its local imports; on failure the running module stays. */
+  reload(): Promise<void>
+  close(): Promise<void>
+}
+
+/** Loads golem.config.ts storage and the optional app-owned src/server/index.ts, and serves /api/app/*. */
+export async function createAppBackend(appRoot: string, dataDirectory: string): Promise<AppBackend> {
+  const config = await loadAppConfig(appRoot)
+  const { storage } = config
+  const records: RecordStore = storage === 'sqlite'
+    ? (await import('./sqlite.ts')).sqliteStore(join(dataDirectory, 'records.sqlite'))
+    : await jsonlStore(join(dataDirectory, 'records'))
+  // One load at a time: each rebuilds the same output directory.
+  let loading: Promise<unknown> = Promise.resolve()
+  const load = () => {
+    const next = loading.then(() => loadServerModule(appRoot, join(dataDirectory, '..', 'server')))
+    loading = next.catch(() => {})
+    return next
+  }
+  // Accounts write the raw store, so nothing about them reaches the public change stream.
+  const accounts = config.accounts ? createAccounts(records, config.accounts) : undefined
+  const cookie = `${config.origin?.startsWith('https:') ? '__Host-' : ''}golem-session-${config.port}`
+  const identity = accounts && {
+    requireUser: !accounts.config.guests,
+    resolve: (request: IncomingMessage) => accounts.fromToken(readCookie(request, cookie)),
+    refresh: accounts.refresh,
+    resolveAccount: accounts.resolveAccount,
+  }
+  // FileStore writes metadata through the app's watched store, so file changes reach subscribers.
+  const app = createApp({ records, files: (watched) => diskFiles(join(dataDirectory, 'files'), watched), root: appRoot, ...(config.model ? { model: config.model } : {}) }, await load(), identity)
+  const server = { app, accounts, config, cookie }
+  return {
+    app,
+    config,
+    accounts,
+    handle: (request, response) => handle(server, request, response),
+    mutationAllowed: (request) => mutationAllowed(request, config.origin),
+    origin: (authority) => originOf(config, authority),
+    reload: async () => app.use(await load()),
+    close: () => { app.close(); return records.close() },
+  }
+}
+
+let generation = 0
+
+/**
+ * Bundles the app's own server files into one module and imports it under a fresh URL, so an edit
+ * to any local file is picked up. Packages stay external and shared with the running server.
+ */
+async function loadServerModule(appRoot: string, outDir: string): Promise<AppServerModule> {
+  const entry = join(appRoot, 'src/server/index.ts')
+  if (!existsSync(entry)) return {}
+  await build({
+    configFile: false, root: appRoot, logLevel: 'silent',
+    // Source mode: the app's `golem-kit/server` is the checkout's file, and stays external so the
+    // app and the running server share one module instance and `instanceof` still holds. A plugin
+    // rather than `resolve.alias` because rollup asks `external` about a bare specifier first.
+    plugins: [{ name: 'golem-source-modules', enforce: 'pre', resolveId: (source: string) => {
+      const file = resolveSourceModule(source)
+      return file ? { id: file, external: true } : undefined
+    } }],
+    build: {
+      ssr: entry, outDir, emptyOutDir: true, minify: false,
+      rollupOptions: { external: (id) => !resolveSourceModule(id) && !id.startsWith('.') && !isAbsolute(id) && !id.startsWith('\0'), output: { entryFileNames: 'index.mjs' } },
+    },
+  })
+  const loaded = (await import(`${pathToFileURL(join(outDir, 'index.mjs')).href}?generation=${++generation}`)).default as unknown
+  if (!loaded || typeof loaded !== 'object') throw new Error('src/server/index.ts must default-export an object')
+  return loaded as AppServerModule
+}
+
+type Server = { app: App; accounts?: Accounts; config: AppConfig; cookie: string }
+
+async function handle({ app, accounts, config, cookie }: Server, request: IncomingMessage, response: ServerResponse): Promise<void> {
+  try {
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1')
+    if (request.method !== 'GET' && !mutationAllowed(request, config.origin)) return send(response, 403, { error: 'Cross-origin mutations are not allowed' })
+    const principal = await app.resolvePrincipal(request)
+    if (url.pathname.startsWith('/api/auth/')) return await handleAuth({ app, accounts, config, cookie }, principal, request, response, url.pathname.slice('/api/auth/'.length))
+    // guests: false keeps every signed-out caller out of app data; guests: true sends them through authorize as anonymous.
+    if (accounts && !accounts.config.guests && principal.kind === 'anonymous') throw new UnauthorizedError('Sign in to use this app.')
+    const operation = url.pathname.match(/^\/api\/app\/operations\/([A-Za-z0-9_.-]+)$/)
+    if (request.method === 'POST' && operation) {
+      const text = (await read(request, maxJson)).toString('utf8')
+      let input: unknown
+      try { input = JSON.parse(text || '{}') } catch { return send(response, 400, { error: 'Request body must be valid JSON' }) }
+      return send(response, 200, { result: await app.invoke(operation[1], input, principal, 'http') })
+    }
+    if (request.method === 'PUT' && url.pathname === '/api/app/files') {
+      const bytes = await read(request, maxUpload)
+      const input = { folder: url.searchParams.get('folder') ?? '', name: url.searchParams.get('name') ?? '', contentType: request.headers['content-type'] ?? 'application/octet-stream', bytes }
+      return send(response, 201, { result: await app.invoke('files.upload', input, principal, 'http') })
+    }
+    const file = url.pathname.match(/^\/api\/app\/files\/([^/]+)$/)
+    if (request.method === 'GET' && file) {
+      const { ref, bytes } = await app.invoke('files.read', { id: decodeURIComponent(file[1]) }, principal, 'http') as { ref: { name: string; contentType: string }; bytes: Uint8Array }
+      response.writeHead(200, {
+        'Content-Type': ref.contentType,
+        'Content-Length': bytes.byteLength,
+        'Content-Disposition': `${url.searchParams.has('download') ? 'attachment' : 'inline'}; filename*=UTF-8''${encodeURIComponent(ref.name)}`,
+        // Uploaded bytes are untrusted: never let them run as a page on this origin.
+        'Content-Security-Policy': 'sandbox',
+        'X-Content-Type-Options': 'nosniff',
+        'Cache-Control': 'no-store',
+      })
+      response.end(bytes)
+      return
+    }
+    if (request.method === 'POST' && url.pathname === '/api/app/views') {
+      const { conversation } = await readJson(request) as { conversation?: unknown }
+      return send(response, 201, { result: await app.views.open(request, principal, conversation as string) })
+    }
+    const view = url.pathname.match(/^\/api\/app\/views\/([A-Za-z0-9_-]+)(\/answer)?$/)
+    if (view && request.method === 'POST' && view[2]) {
+      const { offer, accept } = await readJson(request) as { offer?: unknown; accept?: unknown }
+      if (typeof offer !== 'string' || typeof accept !== 'boolean') throw new InvalidError('An answer needs { offer, accept }')
+      await app.views.answer(request, principal, view[1], offer, accept)
+      return send(response, 200, { result: null })
+    }
+    if (view && request.method === 'GET' && !view[2]) {
+      // Throws before any header when this view is not the caller's; events only arrive on later ticks.
+      const close = await app.views.connect(request, principal, view[1], (event) => response.write(`data: ${JSON.stringify(event)}\n\n`))
+      response.writeHead(200, { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-cache', Connection: 'keep-alive' })
+      response.flushHeaders()
+      // A signed-out or removed reader loses the view at once.
+      const recheck = (accountId: string) => {
+        if (principal.kind === 'user' && accountId === principal.id) void app.refresh(principal).catch(() => response.end())
+      }
+      accounts?.changes.on('change', recheck)
+      request.on('close', () => { close(); accounts?.changes.off('change', recheck) })
+      return
+    }
+    if (request.method === 'GET' && url.pathname === '/api/app/changes') {
+      response.writeHead(200, { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-cache', Connection: 'keep-alive' })
+      response.flushHeaders()
+      const write = (collection: string) => response.write(`data: ${JSON.stringify({ collection })}\n\n`)
+      // When this reader's account changes, re-resolve the same request: a signed-out reader
+      // loses the stream, everyone else is told to re-read who they are and what they may see.
+      const recheck = (accountId: string) => {
+        if (principal.kind !== 'user' || accountId !== principal.id) return
+        void app.resolvePrincipal(request).then((now) => {
+          // Tell the page first, so a signed-out tab drops what it shows instead of waiting for a reload.
+          response.write(`data: ${JSON.stringify({ identity: true })}\n\n`)
+          if (now.kind === 'anonymous' && !accounts?.config.guests) response.end()
+        }, () => response.end())
+      }
+      app.changes.on('change', write)
+      accounts?.changes.on('change', recheck)
+      request.on('close', () => { app.changes.off('change', write); accounts?.changes.off('change', recheck) })
+      return
+    }
+    send(response, 404, { error: 'Unknown API route' })
+  } catch (error) {
+    const status = error instanceof Error ? statuses[error.name] ?? (error instanceof AppError && error.status === 413 ? 413 : undefined) : undefined
+    if (status) {
+      const { current, fields } = error as Error & { current?: unknown; fields?: unknown }
+      return send(response, status, { error: (error as Error).message, name: (error as Error).name, current, fields })
+    }
+    console.error(error)
+    send(response, 500, { error: 'The operation failed on the server; see the server log.' })
+  }
+}
+
+async function handleAuth({ accounts, config, cookie }: Server, principal: Principal, request: IncomingMessage, response: ServerResponse, route: string): Promise<void> {
+  if (request.method === 'GET' && route === 'me') {
+    const settings = accounts && { guests: accounts.config.guests, allowSignUp: accounts.config.allowSignUp, roles: accounts.config.roles }
+    return send(response, 200, { result: { user: accounts ? await accounts.me(principal) : null, canBuild: accounts ? accounts.canBuild(principal) : true, accounts: settings ?? null } })
+  }
+  if (!accounts) return send(response, 404, { error: 'This app has no accounts' })
+  const secure = config.origin?.startsWith('https:') ? '; Secure' : ''
+  const session = (token: string, maxAge: number) => ({ 'Set-Cookie': `${cookie}=${token}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAge}${secure}` })
+  if (request.method === 'GET' && route === 'members') return send(response, 200, { result: await accounts.members(principal) })
+  if (request.method !== 'POST') return send(response, 404, { error: 'Unknown API route' })
+  const input = await readJson(request)
+  if (route === 'sign-in' || route === 'sign-up') {
+    const { user, token } = route === 'sign-in' ? await accounts.signIn(input, request.socket.remoteAddress ?? 'unknown') : await accounts.signUp(input)
+    return send(response, 200, { result: user }, session(token, 14 * 86_400))
+  }
+  if (route === 'sign-out') {
+    await accounts.signOut(principal)
+    return send(response, 200, { result: null }, session('', 0))
+  }
+  if (route === 'invites') return send(response, 200, { result: await accounts.invite(principal, input, originOf(config, request.headers.host)) })
+  const member = route.match(/^members\/([^/]+)\/(role|groups|remove)$/)
+  if (!member) return send(response, 404, { error: 'Unknown API route' })
+  const id = decodeURIComponent(member[1])
+  if (member[2] === 'role') await accounts.setRole(principal, id, input)
+  else if (member[2] === 'groups') await accounts.setGroups(principal, id, input)
+  else await accounts.remove(principal, id)
+  send(response, 200, { result: null })
+}
+
+async function readJson(request: IncomingMessage): Promise<unknown> {
+  const text = (await read(request, maxJson)).toString('utf8')
+  try { return JSON.parse(text || '{}') } catch { throw new InvalidError('Request body must be valid JSON') }
+}
+
+export function readCookie(request: IncomingMessage, name: string): string | undefined {
+  for (const part of (request.headers.cookie ?? '').split(';')) {
+    const [key, ...value] = part.trim().split('=')
+    if (key === name) return value.join('=') || undefined
+  }
+  return undefined
+}
+
+function originOf(config: AppConfig, authority?: string): string {
+  if (config.origin) return config.origin
+  try { if (authority) return new URL(`http://${authority}`).origin } catch {}
+  return new URL(`http://${config.host.includes(':') ? `[${config.host}]` : config.host}:${config.port}`).origin
+}
+
+// By name, not class: app code bundled at reload has its own copies of these error classes.
+const statuses: Record<string, number> = { UnauthorizedError: 401, RateLimitedError: 429, InvalidError: 400, ForbiddenError: 403, NotFoundError: 404, VersionConflictError: 409, RecordRefusedError: 422 }
+
+export function mutationAllowed(request: IncomingMessage, configured?: string): boolean {
+  const origin = request.headers.origin
+  if (!origin) return true
+  // Behind a proxy the Host header is the proxy's business, so a configured origin is the only one accepted.
+  if (configured) return origin === configured
+  const authority = request.headers.host
+  if (!authority) return false
+  try {
+    return origin === new URL(origin).origin && origin === new URL(`http://${authority}`).origin
+  } catch {
+    return false
+  }
+}
+
+async function read(request: IncomingMessage, limit: number): Promise<Buffer> {
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of request as AsyncIterable<Buffer>) {
+    size += chunk.length
+    if (size > limit) throw Object.assign(new AppError(`Request body is larger than ${limit} bytes`), { status: 413 })
+    chunks.push(chunk)
+  }
+  return Buffer.concat(chunks)
+}
+
+function send(response: ServerResponse, status: number, body: unknown, headers: Record<string, string> = {}): void {
+  if (response.headersSent) { response.destroy(); return }
+  response.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', ...headers })
+  // Bytes cross JSON as base64, so an HTTP caller of files.read gets them intact.
+  response.end(JSON.stringify(body, function (this: Record<string, unknown>, key, value) {
+    const raw = this[key]
+    return raw instanceof Uint8Array ? Buffer.from(raw).toString('base64') : value
+  }))
+}

package/src/backend/index.ts

@@ -0,0 +1,10 @@
+// golem-kit/server: server-only. Import from an app's src/server/ only.
+export { createApp, type AgentTool, type App, type AppServerModule } from './app.ts'
+export { diskFiles } from './files.ts'
+export type { JobDefinition } from './jobs.ts'
+export { jsonlStore } from './jsonl.ts'
+export { knowledgeOperations, validPath, type KnowledgeFile, type KnowledgeRoots } from './knowledge.ts'
+export { openModel } from './model.ts'
+export type { Conversations, ViewActionDoc, ViewBinding, ViewEvent, ViewOffer, Views } from './views.ts'
+export { sqliteStore } from './sqlite.ts'
+export * from '../operations.ts'