golem-kit 0.1.0 → 0.2.0

package/src/chat.ts

@@ -0,0 +1,74 @@
+import { createHash, randomBytes } from 'node:crypto'
+import type { IncomingMessage } from 'node:http'
+import Anthropic from '@anthropic-ai/sdk'
+import { readCookie, type AppBackend } from './backend/http.ts'
+import { ForbiddenError, type Principal } from './operations.ts'
+import { AssistantBackend, type TurnContext } from './runtime/assistant.ts'
+import type { SessionBackend } from './runtime/session.ts'
+
+/**
+ * Ordinary-use chat: an API agent limited to the operations golem.config.ts lists, acting as the
+ * person chatting. A conversation belongs to an account, or for a signed-out visitor to an opaque
+ * browser cookie this server issues; nobody else can read or continue it.
+ */
+export function ordinaryChat(backend: AppBackend) {
+  const profile = backend.config.agents?.ordinary
+  const cookie = `${backend.config.origin?.startsWith('https:') ? '__Host-' : ''}golem-chat-${backend.config.port}`
+  const secure = backend.config.origin?.startsWith('https:') ? '; Secure' : ''
+  const detail = !profile ? 'Chat is not turned on for this app.'
+    : !process.env.ANTHROPIC_API_KEY ? 'Chat needs ANTHROPIC_API_KEY in the server environment.'
+    : undefined
+
+  /** Operations as tools for one turn: only the listed ones, collections checked on parsed input. */
+  const tools = (context: TurnContext) => {
+    if (!profile) return []
+    const { collections, roots } = profile
+    return backend.app.agentTools(context.principal, context).filter((tool) => profile.operations.includes(tool.name)).map((tool) => {
+      const operation = backend.app.operations.find((one) => one.name === tool.name)
+      // The resource a call names, read from its parsed input; undefined when the profile does not scope it.
+      const scoped = (input: unknown): { value: unknown; allowed: string[] } | undefined => {
+        if (tool.name === 'view.request') {
+          const target = (input as { action?: unknown; input?: { root?: unknown } } | null)
+          return roots && target?.action === 'source.open' ? { value: target.input?.root, allowed: roots } : undefined
+        }
+        const parsed = operation?.input.safeParse(input)
+        if (!parsed?.success) return undefined
+        if (collections && tool.name.startsWith('records.')) return { value: (parsed.data as { collection: string }).collection, allowed: collections }
+        if (roots && tool.name.startsWith('knowledge.')) return { value: (parsed.data as { root: string }).root, allowed: roots }
+        return undefined
+      }
+      return {
+        ...tool,
+        call: async (input: unknown) => {
+          const scope = scoped(input)
+          if (scope && !scope.allowed.includes(scope.value as string)) throw new ForbiddenError(`Not allowed: ${tool.name}`)
+          return tool.call(input)
+        },
+      }
+    })
+  }
+
+  return {
+    available: !detail,
+    detail,
+    /** Whether the assistant may offer to open sources in a chat tab. */
+    views: () => Boolean(profile?.operations.includes('view.request') && backend.app.views.actions().length),
+    /** The trusted owner key for this request: the account, else this browser's cookie. Never from input. */
+    owner(request: IncomingMessage, principal: Principal): string | null {
+      if (principal.kind === 'user') return principal.id
+      const token = readCookie(request, cookie)
+      return token ? `browser:${createHash('sha256').update(token).digest('hex')}` : null
+    },
+    /** Issues the browser cookie a signed-out visitor's conversations belong to. */
+    issue(): { owner: string; header: string } {
+      const token = randomBytes(32).toString('base64url')
+      return { owner: `browser:${createHash('sha256').update(token).digest('hex')}`, header: `${cookie}=${token}; Path=/; HttpOnly; SameSite=Lax; Max-Age=31536000${secure}` }
+    },
+    backend(transcript?: unknown): SessionBackend {
+      const client = detail ? undefined : new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })
+      return new AssistantBackend(client ?? detail!, { model: profile?.model ?? '', instructions: profile?.instructions, tools }, Array.isArray(transcript) ? transcript : [])
+    },
+  }
+}
+
+export type OrdinaryChat = ReturnType<typeof ordinaryChat>

package/src/cli.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env tsx
 import { startDevServer } from './dev-server.ts';
+import { discoverAgents } from './runtime/discovery.ts';
 import { buildBrowser } from './browser-build.ts';
+import { loadAppConfig, serverUrl } from './config.ts';
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
@@ -12,18 +14,21 @@ Usage: ./golem <command>
 
   help    Show every command (also the default).
   init    Create a minimal app in the current directory.
-  dev     Serve the browser shell at http://127.0.0.1:3000/.
-          Stop with Ctrl+C. Uses the local Codex runtime from the browser.
+  dev     Serve the browser shell using golem.config.ts (127.0.0.1:3000 by default).
+          Restart after changing settings. Uses local Claude Code or Codex from the browser.
   build   Build the browser shell into dist/.
+  lint    Check the app's architecture rules from eslint.config.mjs.
   doctor  Report local shell and backend readiness.
+  say     <text> | --file <f>  Post a reply into the chat session that launched this agent
+          (GOLEM_SESSION and GOLEM_API are set in its tmux session).
 
-Requires Node.js >=22.18.0. Commands accept no additional arguments.
+Requires Node.js >=22.18.0. Only \`say\` takes arguments.
 Exit codes: 0 success/clean shutdown, 1 unavailable or failed, 2 invalid usage.
 `;
 
 const [command = 'help', ...args] = process.argv.slice(2);
 
-if (args.length || !['help', 'init', 'dev', 'build', 'doctor'].includes(command)) {
+if ((args.length && command !== 'say') || !['help', 'init', 'dev', 'build', 'lint', 'doctor', 'say'].includes(command)) {
   console.error('Invalid command or arguments. Run ./golem help.');
   process.exitCode = 2;
 } else {
@@ -42,10 +47,22 @@ if (args.length || !['help', 'init', 'dev', 'build', 'doctor'].includes(command)
       break;
     case 'doctor':
       console.log(`Golem shell readiness (Node ${process.version})
-Ready: local CLI, HTTP shell, golem-ui browser build and Codex session seam.
-Claude integration: not yet connected.
-Not implemented: Claude integration.
-No network exposure is enabled; the dev server binds to loopback.`);
+Ready: local CLI, HTTP shell, golem-ui browser build and agent session seam.
+${(await discoverAgents()).map(({ agent, status, runnable, detail }) => `${agent}: ${runnable ? 'runnable' : status === 'missing' ? 'not installed' : detail ?? status}`).join('\n')}
+Not implemented: domain storage, accounts, permissions.
+The dev server defaults to 127.0.0.1:3000 and uses optional host/port from golem.config.ts.`);
+      break;
+    case 'say':
+      try {
+        const text = args[0] === '--file' && args[1] ? readFileSync(args[1], 'utf8') : args.join(' ');
+        const { GOLEM_SESSION: session, GOLEM_API: api } = process.env;
+        if (!text.trim() || !session || !api) throw new Error('usage: golem say <text> | --file <f>, inside a Golem agent session (GOLEM_SESSION, GOLEM_API)');
+        const response = await fetch(`${api.replace(/\/$/, '')}/api/sessions/${session}/say`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ text }) });
+        if (!response.ok) throw new Error(`${response.status} ${((await response.json().catch(() => ({}))) as { error?: string }).error ?? ''}`.trim());
+      } catch (error) {
+        console.error(`Cannot say: ${error instanceof Error ? error.message : String(error)}${error instanceof Error && error.cause ? ` (${String(error.cause)})` : ""}`);
+        process.exitCode = 1;
+      }
       break;
     case 'build':
       try {
@@ -55,9 +72,25 @@ No network exposure is enabled; the dev server binds to loopback.`);
         process.exitCode = 1;
       }
       break;
+    case 'lint':
+      try {
+        const { ESLint } = await import('eslint');
+        const eslint = new ESLint();
+        const results = await eslint.lintFiles(['.']);
+        const report = await (await eslint.loadFormatter('stylish')).format(results);
+        if (report) console.log(report);
+        if (results.some((result) => result.errorCount)) process.exitCode = 1;
+        else console.log('Architecture lint passed.');
+      } catch (error) {
+        console.error(`Cannot lint Golem app: ${error instanceof Error ? error.message : String(error)}
+See node_modules/golem-kit/docs/architecture.md to add eslint.config.mjs.`);
+        process.exitCode = 1;
+      }
+      break;
     case 'dev':
       try {
-        const server = await startDevServer();
+        const config = await loadAppConfig();
+        const server = await startDevServer(config.port, undefined, undefined, config.host);
         const stop = () => {
           server.close((error) => {
             process.removeListener('SIGINT', stop);
@@ -73,7 +106,7 @@ No network exposure is enabled; the dev server binds to loopback.`);
         };
         process.once('SIGINT', stop);
         process.once('SIGTERM', stop);
-        console.log('Golem shell: http://127.0.0.1:3000/ (Ctrl+C to stop)');
+        console.log(`Golem shell: ${serverUrl(config.host, config.port)} (Ctrl+C to stop)`);
       } catch (error) {
         console.error(`Cannot start Golem dev server: ${error instanceof Error ? error.message : String(error)}`);
         process.exitCode = 1;
@@ -83,7 +116,7 @@ No network exposure is enabled; the dev server binds to loopback.`);
 
 function initProject(): void {
   const root = resolve(process.cwd());
-  const files = ['golem.config.ts', 'src/app.tsx', 'docs/domain.md', 'golem'];
+  const files = ['golem.config.ts', 'eslint.config.mjs', 'src/app.tsx', 'docs/domain.md', 'AGENTS.md', 'CLAUDE.md', 'golem', 'brain/index.md', 'brain/log.md'];
   const existing = files.filter((file) => existsSync(resolve(root, file)));
   if (existing.length) throw new Error(`refusing to overwrite existing files: ${existing.join(', ')}`);
   const packagePath = resolve(root, 'package.json');
@@ -93,9 +126,10 @@ function initProject(): void {
     if (!current.dependencies?.['golem-kit']) throw new Error('refusing to overwrite existing package.json');
   }
   const frameworkRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-  const framework = JSON.parse(readFileSync(resolve(frameworkRoot, 'package.json'), 'utf8')) as { version: string };
+  const framework = JSON.parse(readFileSync(resolve(frameworkRoot, 'package.json'), 'utf8')) as { version: string; dependencies: Record<string, string> };
   mkdirSync(resolve(root, 'src'), { recursive: true });
   mkdirSync(resolve(root, 'docs'), { recursive: true });
+  mkdirSync(resolve(root, 'brain'), { recursive: true });
   if (!existsSync(packagePath)) {
     writeFileSync(packagePath, JSON.stringify({
       name: 'golem-app', private: true, type: 'module', packageManager: 'pnpm@10.28.2',
@@ -103,7 +137,15 @@ function initProject(): void {
       ...(process.env.GOLEM_KIT_TARBALL ? {} : { dependencies: { 'golem-kit': framework.version } }),
     }, null, 2) + '\n');
   }
-  writeFileSync(resolve(root, 'golem.config.ts'), "export default { title: 'Golem' }\n");
+  writeFileSync(resolve(root, 'golem.config.ts'), "export default { title: 'Golem', brain: true }\n");
+  writeFileSync(resolve(root, 'brain/index.md'), `---
+okf_version: "0.2"
+---
+# Brain
+
+This folder is an Open Knowledge Format bundle: one concept per markdown file with \`type\` front matter, this \`index.md\` listing them one \`* [Title](path) - description\` line each, and \`log.md\` recording changes newest first.
+`);
+  writeFileSync(resolve(root, 'brain/log.md'), '# Log\n');
   writeFileSync(resolve(root, 'src/app.tsx'), `export default function App() {
   return (
     <section className="flex h-full min-h-64 items-center justify-center bg-neutral-50 p-6 text-center">
@@ -115,13 +157,45 @@ function initProject(): void {
   )
 }
 `);
-  writeFileSync(resolve(root, 'docs/domain.md'), '# Golem app\n\nA minimal editable app entrypoint.\n');
+  writeFileSync(resolve(root, 'eslint.config.mjs'), `import golem from 'golem-kit/eslint'
+
+// Architecture checks for \`./golem lint\`. To adapt or disable them, see
+// node_modules/golem-kit/docs/architecture.md.
+export default golem()
+`);
+  writeFileSync(resolve(root, 'docs/domain.md'), `# App DNA
+
+What this app is for and the rules its code must honor. Update it in the same change as the code it describes.
+
+## Purpose
+
+Who the app helps and the problem it solves.
+
+## Concepts
+
+The words people use for the things this app manages, what each means, and how they relate.
+
+## Operations
+
+What people and the system do: each operation's inputs, result, and the rules it enforces.
+
+## Decisions
+
+Choices already made and why, so later changes keep them or revisit them on purpose.
+`);
+  writeFileSync(resolve(root, 'AGENTS.md'), `# Golem app
+
+Before changing this app, read \`docs/domain.md\` (this app's DNA) and the installed framework guide \`node_modules/golem-kit/docs/builder.md\`.
+`);
+  writeFileSync(resolve(root, 'CLAUDE.md'), '@AGENTS.md\n');
   const ignorePath = resolve(root, '.gitignore');
   const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, 'utf8') : '';
-  if (!ignore.split(/\r?\n/).includes('.golem/')) writeFileSync(ignorePath, `${ignore}${ignore && !ignore.endsWith('\n') ? '\n' : ''}.golem/\n`);
+  const additions = ['.golem/', '.env.local'].filter((entry) => !ignore.split(/\r?\n/).includes(entry));
+  if (additions.length) writeFileSync(ignorePath, `${ignore}${ignore && !ignore.endsWith('\n') ? '\n' : ''}${additions.join('\n')}\n`);
   if (!packageExisted) {
     const packageSpec = process.env.GOLEM_KIT_TARBALL ?? `golem-kit@${framework.version}`;
-    execFileSync('pnpm', ['add', '--save-exact', packageSpec], { cwd: root, stdio: 'inherit' });
+    // App code imports golem-ui directly, so pin the same version golem-kit builds with.
+    execFileSync('pnpm', ['add', '--save-exact', packageSpec, `golem-ui@${framework.dependencies['golem-ui']}`], { cwd: root, stdio: 'inherit' });
   }
-  writeFileSync(resolve(root, 'golem'), '#!/bin/sh\nset -eu\ncd -- "$(dirname -- "$0")"\nif [ -n "${GOLEM_SOURCE:-}" ]; then\n  exec node "$GOLEM_SOURCE/src/cli.ts" "$@"\nfi\nexec node_modules/.bin/golem-kit "$@"\n', { mode: 0o755 });
+  writeFileSync(resolve(root, 'golem'), "#!/bin/sh\nset -eu\ncd -- \"$(dirname -- \"$0\")\"\n# An exported GOLEM_SOURCE launches from the checkout, so source mode does not depend on what\n# node_modules/golem-kit happens to hold. Anything else (including a bad path, and GOLEM_SOURCE\n# set in .env.local, which only node reads) goes through the installed entry and its errors.\nentry=node_modules/golem-kit/src/entry.mjs\n[ -f \"${GOLEM_SOURCE:-}/src/entry.mjs\" ] && entry=\"$GOLEM_SOURCE/src/entry.mjs\" || true\nexec node --env-file-if-exists=.env.local \"$entry\" \"$@\"\n", { mode: 0o755 });
 }

package/src/client.ts

@@ -0,0 +1,205 @@
+/**
+ * golem-kit/client: the browser binding. golem-ui `Records`, `Files` and `Identity` adapters plus
+ * `invoke`, all over the app server's HTTP routes — no storage driver or server module reaches the bundle.
+ */
+import { fileId, RecordRefusedError, VersionConflictError, type FileRef, type FilesAdapter, type IdentityAdapter, type RecordsAdapter, type User } from 'golem-ui'
+
+/** Calls an app operation by name, as the signed-in principal the server resolves. */
+export function invoke<T = unknown>(operation: string, input: unknown = {}): Promise<T> {
+  return call<T>(fetch(`/api/app/operations/${encodeURIComponent(operation)}`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(input),
+  }))
+}
+
+async function call<T>(request: Promise<Response>): Promise<T> {
+  const response = await request
+  const body = await response.json().catch(() => ({ error: `${response.status} ${response.statusText}` })) as { result?: T; error?: string; name?: string; current?: Record<string, unknown>; fields?: Array<{ field: string; message: string }> }
+  if (response.ok) return body.result as T
+  if (body.name === 'VersionConflictError') throw new VersionConflictError(body.error ?? 'Changed since it was read', body.current ?? null)
+  if (body.name === 'RecordRefusedError') throw new RecordRefusedError(body.error ?? 'Refused', body.fields ?? [])
+  throw Object.assign(new Error(body.error ?? `Request failed (${response.status})`), { name: body.name ?? 'Error', status: response.status })
+}
+
+const listeners = new Map<string, Set<() => void>>()
+let changes: EventSource | undefined
+
+function connect(): void {
+  changes?.close()
+  changes = Object.assign(new EventSource('/api/app/changes'), {
+    onmessage: (event: MessageEvent) => {
+      const data = JSON.parse(event.data) as { collection?: string; identity?: true }
+      if (data.identity) void reloadIdentity()
+      else listeners.get(data.collection ?? '')?.forEach((one) => one())
+    },
+    // The server refused or ended the stream for good (e.g. signed out elsewhere): re-read identity
+    // once. No reconnect here, so a 401 cannot loop; a new identity reconnects through reloadIdentity.
+    onerror: () => {
+      if (changes?.readyState === EventSource.CLOSED) void me?.then((known) => { if (known.user) void reloadIdentity(false) }, () => {})
+    },
+  })
+}
+
+function watch(collection: string, listener: () => void): () => void {
+  const set = listeners.get(collection) ?? new Set()
+  listeners.set(collection, set.add(listener))
+  if (!changes) connect()
+  return () => {
+    set.delete(listener)
+    if ([...listeners.values()].every((one) => one.size === 0)) { changes?.close(); changes = undefined }
+  }
+}
+
+export const records: RecordsAdapter = {
+  list: (collection, query) => invoke('records.list', { collection, query }),
+  get: (collection, id) => invoke('records.get', { collection, id }),
+  create: (collection, data) => invoke('records.create', { collection, data }),
+  update: (collection, id, patch, options) => invoke('records.update', { collection, id, patch, ...options }),
+  remove: async (collection, id) => { await invoke('records.remove', { collection, id }) },
+  subscribe: watch,
+}
+
+export const files: FilesAdapter = {
+  async upload(file, { folder, onProgress }) {
+    const ref = await call<FileRef>(fetch(`/api/app/files?${new URLSearchParams({ folder, name: file.name })}`, {
+      method: 'PUT', headers: { 'Content-Type': file.type || 'application/octet-stream' }, body: file,
+    }))
+    onProgress?.(1)
+    return ref
+  },
+  url: async (ref) => `/api/app/files/${encodeURIComponent(fileId(ref))}`,
+  remove: async (ref) => { await invoke('files.remove', { id: fileId(ref) }) },
+  list: (folder) => invoke('files.list', { folder }),
+  caption: (ref, caption) => invoke('files.caption', { id: fileId(ref), caption }),
+  subscribe: (_folder, listener) => watch('_files', listener),
+}
+
+/** A signed-in person as the server sees them: golem-ui's `User` plus the groups app rules may check. */
+export type Member = User & { email: string; groups: string[] }
+export type AccountsSettings = { guests: boolean; allowSignUp: boolean; roles: Array<{ id: string; label: string; manages: boolean }> }
+/** `accounts` is null when the app has no accounts; then everyone is anonymous and may build. */
+export type Me = { user: Member | null; canBuild: boolean; accounts: AccountsSettings | null }
+
+let me: Promise<Me> | undefined
+const identityListeners = new Set<(user: User | null) => void>()
+
+/** Who this browser is signed in as, and what the app's account settings are. Cached until identity changes. */
+export function currentSession(): Promise<Me> {
+  me ??= call<Me>(fetch('/api/auth/me')).catch((error) => { me = undefined; throw error })
+  return me
+}
+
+/** Re-reads the session after sign-in, sign-out or a role change; open lists re-read what they may now see. */
+async function reloadIdentity(reconnect = true): Promise<Me> {
+  me = undefined
+  const next = await currentSession()
+  identityListeners.forEach((listener) => listener(next.user))
+  if (changes && reconnect) connect()
+  listeners.forEach((set) => set.forEach((listener) => listener()))
+  return next
+}
+
+const auth = <T = null>(route: string, input: unknown = {}) => call<T>(fetch(`/api/auth/${route}`, {
+  method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(input),
+}))
+const signedIn = async () => {
+  const { user } = await reloadIdentity()
+  if (!user) throw new Error('Signing in did not stick. Allow cookies for this site and try again.')
+  return user
+}
+const passwordOnly = () => Promise.reject(new Error('This app signs in with a password.'))
+
+/** golem-ui `IdentityAdapter` over the server's local accounts. Sign-in takes the account's email and password. */
+export const identity: IdentityAdapter = {
+  currentUser: async () => (await currentSession()).user,
+  subscribe(listener) {
+    identityListeners.add(listener)
+    // Keeps the change stream open, which is where the server says this account changed.
+    const stop = watch('', () => {})
+    return () => { identityListeners.delete(listener); stop() }
+  },
+  signIn: async (email, password) => { await auth('sign-in', { email, password }); return signedIn() },
+  signUp: async (input) => { await auth('sign-up', input); return signedIn() },
+  requestCode: passwordOnly,
+  verifyCode: passwordOnly,
+  signOut: async () => { await auth('sign-out'); await reloadIdentity() },
+  listMembers: () => call<Member[]>(fetch('/api/auth/members')),
+  invite: (role) => auth<string>('invites', { role }),
+  removeMember: async (userId) => { await auth(`members/${encodeURIComponent(userId)}/remove`); await reloadIdentity() },
+  setRole: async (userId, role) => { await auth(`members/${encodeURIComponent(userId)}/role`, { role }); await reloadIdentity() },
+}
+
+/** Re-reads who is signed in and tells identity subscribers; for callers that saw a 401 or 403. */
+export async function refreshIdentity(): Promise<void> { await reloadIdentity() }
+
+/** Replaces a member's groups. Accounts that manage members only. */
+export async function setGroups(userId: string, groups: string[]): Promise<void> {
+  await auth(`members/${encodeURIComponent(userId)}/groups`, { groups })
+  await reloadIdentity()
+}
+
+/**
+ * golem-ui `RecordsAdapter` over the app's knowledge roots: `collection` is the root name, `id` the
+ * file path and `body` its markdown. Hand it to `Editor` (versioned saves, merged conflicts) or `RecordList`.
+ */
+export const knowledge: RecordsAdapter = {
+  list: (root, query) => invoke('knowledge.list', { root, ...(typeof query?.filter?.folder === 'string' ? { folder: query.filter.folder } : {}) }),
+  get: async (root, path) => {
+    try { return await invoke('knowledge.read', { root, path }) }
+    catch (error) { if ((error as Error).name === 'NotFoundError') return null; throw error }
+  },
+  create: (root, data) => invoke('knowledge.write', { root, path: data.path ?? data.id, body: data.body ?? '', expectedVersion: 0 }),
+  update: (root, path, patch, options) => invoke('knowledge.write', { root, path, body: patch.body, expectedVersion: options?.expectedVersion ?? (patch.version as number) }),
+  remove: () => Promise.reject(new Error('Knowledge files are removed in the app folder, not from the browser.')),
+  subscribe: (_root, listener) => watch('_knowledge', listener),
+}
+
+/** A knowledge passage an agent offered to show; `line` and `endLine` are 1-based and inclusive. */
+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 }
+
+/**
+ * Opens this tab's view of one conversation. `id` is the view to send with this tab's chat messages,
+ * so the agent's offers come here. An offer arrives as `offer` (or is shown by the chat); `answer` is
+ * the person's choice, and only an accepted offer comes back, to this tab alone, as `apply`.
+ */
+export function openView(conversation: string, listener: (event: ViewEvent) => void): { id: Promise<string>; answer(offer: string, accept: boolean): Promise<void>; close(): void } {
+  let source: EventSource | undefined
+  let closed = false
+  const id = call<{ id: string }>(fetch('/api/app/views', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ conversation }) })).then((view) => view.id)
+  void id.then((view) => {
+    if (closed) return
+    source = new EventSource(`/api/app/views/${view}`)
+    source.onmessage = (event) => listener(JSON.parse(event.data) as ViewEvent)
+  }, () => {})
+  return {
+    id,
+    answer: async (offer, accept) => {
+      await call(fetch(`/api/app/views/${await id}/answer`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ offer, accept }) }))
+    },
+    close: () => { closed = true; source?.close() },
+  }
+}
+
+/** A job run as its owner sees it through `jobs.runs`. */
+export type JobRun = {
+  id: string; job: string; status: 'running' | 'succeeded' | 'failed' | 'cancelled' | 'interrupted'
+  progress: { done?: number; total?: number; message?: string } | null; result?: unknown; error?: string
+  cancelRequested: boolean; resolution?: 'retried' | 'dismissed'; scheduleId: string | null; key: string; startedAt: string; finishedAt?: string
+}
+export type JobSchedule = { id: string; job: string; every?: number; cron?: string; timezone?: string; nextRunAt: string; lastRunAt?: string; lastSkippedAt?: string; error?: string | null }
+
+/** The app's server-side jobs. Runs keep going when this page closes; `subscribe` fires whenever one of them changes. */
+export const jobs = {
+  list: () => invoke<{ jobs: Array<{ name: string; description: string }>; schedules: JobSchedule[] }>('jobs.list'),
+  start: (job: string, input?: unknown) => invoke<JobRun>('jobs.start', { job, input }),
+  schedule: (job: string, when: { every: number } | { cron: string; timezone: string }, input?: unknown) => invoke<JobSchedule>('jobs.schedule', { job, input, ...when }),
+  unschedule: async (id: string) => { await invoke('jobs.unschedule', { id }) },
+  runs: (query: { job?: string; scheduleId?: string; limit?: number } = {}) => invoke<JobRun[]>('jobs.runs', query),
+  cancel: (id: string) => invoke<JobRun>('jobs.cancel', { id }),
+  resolve: (id: string, action: 'retry' | 'dismiss') => invoke<JobRun>('jobs.resolve', { id, action }),
+  subscribe: (listener: () => void) => watch('_jobs', listener),
+}

package/src/config.ts

@@ -0,0 +1,169 @@
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { toolNameProblem } from './runtime/tool-names.ts'
+
+/** Browser-visible settings: never put secrets in golem.config.ts. */
+export type AppConfig = { host: string; port: number; storage: 'jsonl' | 'sqlite'; origin?: string; accounts?: AccountsConfig; agents?: AgentsConfig; brain?: boolean; chat?: ChatConfig; model?: ModelConfig }
+/** Which local agent CLI answers `context.model`; absent, Claude Code as before. `name` is that runtime's model id. */
+export type ModelConfig = { runtime: 'claude' | 'codex'; name?: string }
+/**
+ * Normal-mode chat, the app's rule: `false` (or absent) means no chat column outside builder mode.
+ * `anthropic` is the API agent (same shape as `agents.ordinary`, which it fills); `tmux` is a
+ * terminal agent in the `chat` window of the app's tmux session, briefed from `docs/chat.md`.
+ * `roles` restricts chat to those account roles; absent, anyone signed in may chat.
+ */
+export type ChatConfig = ({ provider: 'anthropic' } | { provider: 'tmux'; agent?: 'codex' | 'claude' }) & { roles?: string[] }
+/** `brain: true` serves the app's `brain/` folder read-only and mounts the Brain reader beside the app. */
+
+/**
+ * `builder` is the agent build mode starts with. `ordinary` turns on everyday chat: an API agent
+ * whose only tools are the listed app operations, run as the person chatting.
+ */
+export type AgentsConfig = { builder?: 'codex' | 'claude'; ordinary?: OrdinaryAgentConfig }
+export type OrdinaryAgentConfig = { backend: 'anthropic'; model: string; operations: string[]; collections?: string[]; roots?: string[]; instructions?: string }
+
+/** golem-ui's Auth role shape: `manages` roles run accounts and may build; `builder` may build. */
+export type AccountRole = { id: string; label: string; manages: boolean }
+export type AccountsConfig = { guests: boolean; allowSignUp: boolean; roles: AccountRole[] }
+
+const defaultRoles: AccountRole[] = [
+  { id: 'member', label: 'Member', manages: false },
+  { id: 'builder', label: 'Builder', manages: false },
+  { id: 'admin', label: 'Admin', manages: true },
+]
+
+export async function loadAppConfig(root = process.cwd()): Promise<AppConfig> {
+  const path = resolve(root, 'golem.config.ts')
+  let value: unknown
+  try {
+    value = (await import(pathToFileURL(path).href)).default
+  } catch (error) {
+    throw new Error(`Cannot load golem.config.ts: ${message(error)}`)
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('golem.config.ts must default-export an object')
+  }
+  const configured = value as { host?: unknown; port?: unknown; storage?: unknown; origin?: unknown; accounts?: unknown; agents?: unknown; brain?: unknown; chat?: unknown; model?: unknown }
+  if (configured.brain !== undefined && typeof configured.brain !== 'boolean') throw new Error('golem.config.ts brain must be a boolean')
+  const host: unknown = configured.host === undefined ? '127.0.0.1' : configured.host
+  const port: unknown = configured.port === undefined ? 3000 : configured.port
+  if (typeof host !== 'string' || !host.trim()) {
+    throw new Error('golem.config.ts host must be a nonempty string')
+  }
+  if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error('golem.config.ts port must be an integer from 1 to 65535')
+  }
+  const storage = configured.storage ?? 'jsonl'
+  if (storage !== 'jsonl' && storage !== 'sqlite') {
+    throw new Error("golem.config.ts storage must be 'jsonl' or 'sqlite'")
+  }
+  const origin = configured.origin
+  if (origin !== undefined && (typeof origin !== 'string' || !/^https?:$/.test(safeUrl(origin)?.protocol ?? '') || safeUrl(origin)?.origin !== origin)) {
+    throw new Error("golem.config.ts origin must be an exact origin like 'https://notes.example.com'")
+  }
+  const config: AppConfig = { host, port, storage, ...(origin === undefined ? {} : { origin }), ...(configured.accounts === undefined ? {} : { accounts: accounts(configured.accounts) }), ...(configured.agents === undefined ? {} : { agents: agents(configured.agents) }), ...(configured.brain ? { brain: true } : {}), ...(configured.model === undefined ? {} : { model: modelConfig(configured.model) }) }
+  if (configured.chat !== undefined && configured.chat !== false) {
+    if (!configured.chat || typeof configured.chat !== 'object' || Array.isArray(configured.chat)) throw new Error('golem.config.ts chat must be false or { provider, ... }')
+    const { provider, roles, ...rest } = configured.chat as Record<string, unknown>
+    const chatRoles = roles === undefined ? {} : { roles: chatRolesOf(roles, config.accounts) }
+    if (provider === 'anthropic') {
+      config.agents = { ...config.agents, ordinary: ordinaryAgent({ backend: 'anthropic', ...rest }) }
+      config.chat = { provider, ...chatRoles }
+    } else if (provider === 'tmux') {
+      const { agent, ...unknown } = rest
+      if (Object.keys(unknown).length) throw new Error(`golem.config.ts chat has unknown fields: ${Object.keys(unknown).join(', ')}`)
+      if (agent !== undefined && agent !== 'codex' && agent !== 'claude') throw new Error("golem.config.ts chat.agent must be 'codex' or 'claude'")
+      config.chat = { provider, ...(agent ? { agent } : {}), ...chatRoles }
+    } else throw new Error("golem.config.ts chat.provider must be 'anthropic' or 'tmux'")
+  } else if (config.agents?.ordinary) config.chat = { provider: 'anthropic' }
+  return config
+}
+
+function modelConfig(value: unknown): ModelConfig {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('golem.config.ts model must be { runtime, name? }')
+  const { runtime, name, ...unknown } = value as Record<string, unknown>
+  if (Object.keys(unknown).length) throw new Error(`golem.config.ts model has unknown fields: ${Object.keys(unknown).join(', ')}`)
+  if (runtime !== 'claude' && runtime !== 'codex') throw new Error("golem.config.ts model.runtime must be 'claude' or 'codex'")
+  if (name !== undefined && (typeof name !== 'string' || !name)) throw new Error('golem.config.ts model.name must be a nonempty string')
+  return { runtime, ...(name ? { name } : {}) }
+}
+
+function accounts(value: unknown): AccountsConfig {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('golem.config.ts accounts must be an object')
+  const { guests = false, allowSignUp = false, roles = defaultRoles, ...unknown } = value as Record<string, unknown>
+  if (Object.keys(unknown).length) throw new Error(`golem.config.ts accounts has unknown fields: ${Object.keys(unknown).join(', ')}`)
+  if (typeof guests !== 'boolean' || typeof allowSignUp !== 'boolean') throw new Error('golem.config.ts accounts guests and allowSignUp must be booleans')
+  if (!Array.isArray(roles) || !roles.length) throw new Error('golem.config.ts accounts roles must be a nonempty list')
+  const parsed = roles.map((role: { id?: unknown; label?: unknown; manages?: unknown }) => {
+    if (typeof role?.id !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(role.id) || typeof role.label !== 'string' || (role.manages !== undefined && typeof role.manages !== 'boolean')) {
+      throw new Error('golem.config.ts accounts roles need { id, label, manages? }')
+    }
+    return { id: role.id, label: role.label, manages: role.manages === true }
+  })
+  if (new Set(parsed.map((role) => role.id)).size !== parsed.length) throw new Error('golem.config.ts accounts role ids must be unique')
+  if (!parsed.some((role) => role.manages)) throw new Error('golem.config.ts accounts roles need one role with manages: true')
+  if (allowSignUp && !parsed.some(isPlain)) throw new Error("golem.config.ts accounts allowSignUp needs a role that neither manages nor is 'builder'")
+  return { guests, allowSignUp, roles: parsed }
+}
+
+/** A typo here would lock everyone out of chat, so every named role must be one the app declares. */
+function chatRolesOf(value: unknown, accounts: AccountsConfig | undefined): string[] {
+  if (!Array.isArray(value) || !value.length || !value.every((role) => typeof role === 'string' && role)) throw new Error('golem.config.ts chat.roles must be a nonempty list of role ids')
+  if (!accounts) throw new Error('golem.config.ts chat.roles needs accounts: without them nobody has a role')
+  const unknown = (value as string[]).filter((role) => !accounts.roles.some((one) => one.id === role))
+  if (unknown.length) throw new Error(`golem.config.ts chat.roles names roles the app does not declare: ${unknown.join(', ')}`)
+  return value as string[]
+}
+
+function agents(value: unknown): AgentsConfig {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('golem.config.ts agents must be an object')
+  const { builder, ordinary, ...unknown } = value as Record<string, unknown>
+  if (Object.keys(unknown).length) throw new Error(`golem.config.ts agents has unknown fields: ${Object.keys(unknown).join(', ')}`)
+  if (builder !== undefined && builder !== 'codex' && builder !== 'claude') throw new Error("golem.config.ts agents.builder must be 'codex' or 'claude'")
+  return { ...(builder ? { builder } : {}), ...(ordinary === undefined ? {} : { ordinary: ordinaryAgent(ordinary) }) }
+}
+
+// Operations whose input or output is raw bytes, which a chat tool cannot carry.
+const byteOperations = ['files.upload', 'files.read']
+
+function ordinaryAgent(value: unknown): OrdinaryAgentConfig {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('golem.config.ts agents.ordinary must be an object')
+  const { backend, model = 'claude-opus-5', operations, collections, roots, instructions, ...unknown } = value as Record<string, unknown>
+  if (Object.keys(unknown).length) throw new Error(`golem.config.ts agents.ordinary has unknown fields: ${Object.keys(unknown).join(', ')}`)
+  if (backend === 'codex' || backend === 'claude') {
+    throw new Error(`golem.config.ts agents.ordinary.backend '${backend}' is not supported: a terminal agent runs with this computer account's file access, which Golem cannot limit to the listed operations. Use 'anthropic'.`)
+  }
+  if (backend !== 'anthropic') throw new Error("golem.config.ts agents.ordinary.backend must be 'anthropic'")
+  if (typeof model !== 'string' || !model) throw new Error('golem.config.ts agents.ordinary.model must be a nonempty string')
+  const names = (list: unknown, field: string) => {
+    if (!Array.isArray(list) || !list.every((item) => typeof item === 'string' && item)) throw new Error(`golem.config.ts agents.ordinary.${field} must be a list of names`)
+    return list as string[]
+  }
+  const allowed = names(operations, 'operations')
+  const refused = allowed.filter((name) => byteOperations.includes(name))
+  if (refused.length) throw new Error(`golem.config.ts agents.ordinary.operations cannot include ${refused.join(', ')}: chat tools carry no file bytes`)
+  const problem = toolNameProblem(allowed)
+  if (problem) throw new Error(`golem.config.ts agents.ordinary.operations: ${problem}`)
+  if (instructions !== undefined && typeof instructions !== 'string') throw new Error('golem.config.ts agents.ordinary.instructions must be a string')
+  return {
+    backend, model, operations: allowed,
+    ...(collections === undefined ? {} : { collections: names(collections, 'collections') }),
+    ...(roots === undefined ? {} : { roots: names(roots, 'roots') }),
+    ...(instructions === undefined ? {} : { instructions }),
+  }
+}
+
+/** Neither manages accounts nor builds: what an open sign-up may receive. */
+export const isPlain = (role: AccountRole) => !role.manages && role.id !== 'builder'
+
+function safeUrl(value: string): URL | undefined {
+  try { return new URL(value) } catch { return undefined }
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export function serverUrl(host: string, port: number): string {
+  return `http://${host.includes(':') ? `[${host}]` : host}:${port}/`
+}