golem-kit 0.1.1 → 0.2.0

package/src/browser/app.tsx

@@ -1,63 +1,191 @@
-import { useEffect, useRef, useState } from 'react'
-import { Chat, Shell } from 'golem-ui'
-import UserApp from '@golem/app'
+import { useEffect, useRef, useState, type ComponentProps, type ComponentType, type ReactNode } from 'react'
+import * as GolemUI from 'golem-ui'
+import { Auth, Chat, Shell } from 'golem-ui'
+import * as AppModule from '@golem/app'
 import projectConfig from '@golem/config'
-import { anonymousIdentity, chat, interruptBrowserSession, navigation, restoreBrowserSession, startBrowserSession, subscribeBrowserStatus } from './adapters'
+import { currentSession, identity, type Me } from '../client'
+import { anonymousIdentity, brain, chat, currentBrowserBackend, leaveBrowserSession, forgetBrowserSession, navigation, restoreBrowserSession, startBrowserSession, subscribeBrowserSession, subscribeBrowserStatus, type SessionKind } from './adapters'
+import { Groups } from './groups'
+import { SourcePanel, SourceReturn, useSourceView, type OpenSource } from './sources'
+import { Terminal } from './terminal'
 
-const shellAdapters = { identity: anonymousIdentity, navigation }
 const chatAdapters = { chat }
+// `Brain` is in golem-ui after 0.1.1; with 0.1.1 installed the panel says so instead of rendering it.
+const Brain = (GolemUI as unknown as { Brain?: (props: { config: { title: string; openLocation?: string }; adapters: { brain: typeof brain } }) => ReactNode }).Brain
+// The Shell chrome after golem-ui 29acbd5: a menu row, a settings dropdown, the chat behind a toggle. 0.1.1's
+// strict schema would reject the keys, so they go in only when `Shell.Setting` (same vintage) is there.
+type ShellSetting = (props: { icon: ReactNode; label: string; on?: boolean; onClick: () => void }) => ReactNode
+type ShellIcon = (props: { name: 'user' | 'wrench' }) => ReactNode
+const { Setting: ShellSetting, Icon: ShellIcon } = Shell as unknown as { Setting?: ShellSetting; Icon?: ShellIcon }
+const ShellFrame = Shell as unknown as (props: Omit<ComponentProps<typeof Shell>, 'config'> & {
+  config: ComponentProps<typeof Shell>['config'] & { menu?: { id: string; label: string; icon?: string }[]; activeId?: string; chatOpen?: boolean }
+  settings?: ReactNode
+  onSelect?: (id: string) => void
+}) => ReactNode
+// An app with more than one screen lists them (`export const screens`); each becomes an item in the
+// menu row, and the chosen one's id goes to the app as `screen`. Read through a cast, like the other
+// optional things here, because an app that lists none is the single-screen app it always was.
+const UserApp = AppModule.default as ComponentType<{ screen?: string }>
+type AppScreen = { id: string; label: string; icon?: string }
+const appScreens = (AppModule as { screens?: AppScreen[] }).screens ?? []
+/** The `?screen=` route param: which of the app's own screens is showing. */
+const screenParam = () => new URLSearchParams(window.location.search).get('screen') ?? undefined
+const screenUrl = (id?: string) => (id ? `${window.location.pathname}?screen=${encodeURIComponent(id)}` : window.location.pathname)
+/** The `?brain=` route param: the location the Brain panel shows, or undefined when the app is showing. */
+const brainParam = () => new URLSearchParams(window.location.search).get('brain') ?? undefined
+const brainUrl = (location: string) => `${window.location.pathname}?brain=${encodeURIComponent(location)}`
+// What the reader opens on its own goes into the URL, so a reload (a Builder rebuild, a sign-in
+// change) lands on the same document instead of the root index.
+const brainAdapters = { brain: { ...brain, open: (location: string) => navigation.go(brainUrl(location)) } }
+const authAdapters = { identity, navigation }
+const agentNames: Record<string, string> = { codex: 'Codex', claude: 'Claude Code' }
+type Discovery = { agent: string; status: string; runnable?: boolean; detail?: string }
 
 export function App() {
-  const [mode, setMode] = useState(false)
+  // Builder mode is app state, kept on the server (`.golem/builder.json`) so a reload comes back in it.
+  const [builder, setBuilder] = useState<boolean>()
   const [session, setSession] = useState<string>()
   const [sessionStatus, setSessionStatus] = useState('starting')
-  const [enteringBuildMode, setEnteringBuildMode] = useState(false)
-  const enteringBuildModeRef = useRef(false)
-  const [runtime, setRuntime] = useState<{ codex: boolean; claude: boolean }>({ codex: false, claude: false })
+  const [sessionBackend, setSessionBackend] = useState<string>()
   const [error, setError] = useState<string>()
+  const [chatInfo, setChatInfo] = useState<{ provider: 'tmux' | 'anthropic' | null; agent?: string; available: boolean; detail?: string; views?: boolean }>()
+  const [source, setSource] = useState<OpenSource>()
+  const [sourceShown, setSourceShown] = useState(false)
+  const [me, setMe] = useState<Me>()
+  // The Admin screen is app state; any navigation (the title, a Brain item, a chip) leaves it.
+  const [view, setView] = useState<'app' | 'account'>('app')
+  const [brainAt, setBrainAt] = useState(brainParam)
+  const [screenAt, setScreenAt] = useState(screenParam)
+  useEffect(() => navigation.subscribe(() => { setBrainAt(brainParam()); setScreenAt(screenParam()); setView('app') }), [])
+  const showBrain = (projectConfig as { brain?: boolean }).brain === true && brainAt !== undefined
+  // An unknown `?screen=` is the app's first screen, not an error.
+  const screen = appScreens.some((one) => one.id === screenAt) ? screenAt : undefined
+  const [terminal, setTerminal] = useState(false)
+  const signedInAs = useRef<string | null>(null)
   useEffect(() => {
-    fetch('/api/runtime').then((response) => response.json()).then((result) => {
-      const discoveries = result.discoveries as Array<{ agent: string; status: string; runnable: boolean }>
-      setRuntime({ codex: discoveries.some((item) => item.agent === 'codex' && item.status === 'available' && item.runnable), claude: false })
-    }).catch(() => setError('Runtime discovery unavailable.'))
+    currentSession().then((next) => { signedInAs.current = next.user?.id ?? null; setMe(next) }, () => setError('Account service unavailable.'))
+    // Another person on this browser starts clean: their own build conversation, their own view.
+    return identity.subscribe(() => void currentSession().then((next) => {
+      if (!next.accounts) return
+      if ((next.user?.id ?? null) !== signedInAs.current) {
+        // A used invite link must not reopen sign-up on the next load.
+        const url = new URL(window.location.href)
+        url.searchParams.delete('invite')
+        forgetBrowserSession()
+        window.location.replace(url)
+      }
+      else setMe(next)
+    }))
   }, [])
+  const canBuild = me?.canBuild === true
+  const chatting = sessionBackend === 'anthropic'
+  const offers = useSourceView(!builder && chatting && chatInfo?.views ? session : undefined, (next) => { setSource(next); setSourceShown(true) })
+  useEffect(() => {
+    if (!me) return
+    fetch('/api/chat').then(async (response) => { if (response.ok) setChatInfo(await response.json()) }).catch(() => {})
+    fetch('/api/builder').then(async (response) => setBuilder(response.ok ? Boolean((await response.json()).builder) : false)).catch(() => setBuilder(false))
+  }, [me])
+  useEffect(() => subscribeBrowserStatus(setSessionStatus), [])
+  useEffect(() => subscribeBrowserSession(setSession), [])
+  // What the chat column shows: the builder agent, or whatever the app defines for normal mode (maybe nothing).
+  const kind: SessionKind | undefined = builder === undefined || !chatInfo ? undefined : builder && canBuild ? 'builder' : chatInfo.provider === 'tmux' ? 'chat' : chatInfo.provider === 'anthropic' ? 'anthropic' : undefined
   useEffect(() => {
-    const unsubscribe = subscribeBrowserStatus(setSessionStatus)
-    restoreBrowserSession().then((restored) => {
-      if (restored) { setSession(window.sessionStorage.getItem('golem.browser.session') ?? undefined); setMode(true) }
-    }).catch((cause) => setError(cause instanceof Error ? cause.message : String(cause)))
-    return unsubscribe
-  }, [])
-  const enterBuildMode = async () => {
-    if (enteringBuildModeRef.current) return
-    enteringBuildModeRef.current = true
-    setEnteringBuildMode(true)
     setError(undefined)
-    try { const started = await startBrowserSession(); setSession(started.id); setMode(true) }
-    catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)) }
-    finally { enteringBuildModeRef.current = false; setEnteringBuildMode(false) }
+    setTerminal(false)
+    if (!kind) { leaveBrowserSession(); setSession(undefined); setSessionBackend(undefined); return }
+    let cancelled = false
+    const open = async () => {
+      // A terminal agent: the configured one, else what this computer has (the server picks per intent).
+      const runtime = kind === 'anthropic' ? undefined : await fetch('/api/runtime').then((response) => response.json()) as { discoveries: Discovery[]; builder?: string } | undefined
+      const ready = runtime?.discoveries?.filter((item) => item.status === 'available' && item.runnable).map((item) => item.agent) ?? []
+      const agent = kind === 'anthropic' ? undefined : [kind === 'chat' ? chatInfo?.agent : undefined, runtime?.builder, 'codex', 'claude'].find((one) => one && ready.includes(one))
+      if (await restoreBrowserSession(kind)) return
+      if (kind !== 'anthropic' && !agent) throw new Error(`No agent to chat with: ${runtime?.discoveries?.map((item) => `${agentNames[item.agent] ?? item.agent} ${item.status === 'missing' ? 'not installed' : item.detail ?? item.status}`).join(', ') || 'checking agents…'}`)
+      if (kind === 'anthropic' && !chatInfo?.available) throw new Error(chatInfo?.detail ?? 'Chat is not available.')
+      await startBrowserSession(agent, kind)
+    }
+    open().then(() => { if (!cancelled) { setSessionBackend(currentBrowserBackend()) } }, (cause) => { if (!cancelled) setError(cause instanceof Error ? cause.message : String(cause)) })
+    return () => { cancelled = true }
+  }, [kind])
+  const toggleBuilder = async (on: boolean) => {
+    setBuilder(on)
+    const response = await fetch('/api/builder', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ builder: on }) })
+    if (!response.ok) { setError((await response.json()).error ?? 'Unable to switch mode'); setBuilder(!on) }
   }
-  const interrupt = async () => {
-    try { await interruptBrowserSession() } catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)) }
+  const accounts = me?.accounts
+  const authConfig = accounts && { workspaceName: projectConfig.title, mode: 'password' as const, allowSignUp: accounts.allowSignUp, roles: accounts.roles }
+  const manages = Boolean(me?.user?.roles.some((role) => accounts?.roles.some((one) => one.id === role && one.manages)))
+  const invited = new URLSearchParams(window.location.search).has('invite')
+  const shellAdapters = { identity: accounts ? identity : anonymousIdentity, navigation }
+  const hasBrain = (projectConfig as { brain?: boolean }).brain === true
+  // The bottom menu bar: the app's own screens first, then Brain, then Admin for managers.
+  const menu = [
+    { id: 'app', label: projectConfig.title, icon: '🏠' },
+    ...appScreens.map((one) => ({ id: `screen:${one.id}`, label: one.label, ...(one.icon ? { icon: one.icon } : {}) })),
+    ...(hasBrain ? [{ id: 'brain', label: 'Brain', icon: '🧠' }] : []),
+    ...(manages ? [{ id: 'admin', label: 'Admin', icon: '🛠️' }] : []),
+  ]
+  // An app item leaves `?brain=` and the Admin view and carries its own `?screen=`; Brain opens its own.
+  const select = (id: string) => {
+    if (id === 'brain') { if (!showBrain) navigation.go(brainUrl('index.md')); return }
+    const target = id.startsWith('screen:') ? id.slice('screen:'.length) : undefined
+    if (showBrain || screenAt !== target) navigation.go(screenUrl(target))
+    setView(id === 'admin' ? 'account' : 'app')
   }
+  const barButton = 'golem-browser-bar-button flex size-8 items-center justify-center rounded-lg border'
   return (
-    <Shell
-      config={{ title: projectConfig.title, chatSide: 'left', breakpoint: 768 }}
+    <ShellFrame
+      config={{ title: projectConfig.title, chatSide: 'left', breakpoint: 768,
+        // Builder on raises the chat; a mode that is off leaves the chat where the reader left it.
+        ...(ShellSetting ? { menu, activeId: showBrain ? 'brain' : view === 'account' ? 'admin' : screen ? `screen:${screen}` : 'app', chatOpen: builder === true } : {}) }}
       adapters={shellAdapters}
-      chat={
+      onSelect={select}
+      settings={ShellSetting && canBuild && builder !== undefined && (
+        <ShellSetting icon={ShellIcon ? <ShellIcon name="wrench" /> : '🔧'} label="Builder" on={builder} onClick={() => void toggleBuilder(!builder)} />
+      )}
+      chat={!kind ? null : (
         <div className="flex h-full min-h-0 flex-col">
-          <div className="flex items-center justify-between border-b border-neutral-200 bg-white px-4 py-3 text-sm">
-            <span className="font-medium">{mode ? 'Build mode' : 'Conversation mode'}</span>
-            <span className={mode ? 'text-green-700' : 'text-neutral-500'}>{mode ? `${sessionStatus} · ${session}` : 'Not connected'}</span>
-            {mode && (sessionStatus === 'ready' || sessionStatus === 'starting') && <button className="rounded border border-red-300 px-2 py-1 text-red-700" onClick={interrupt}>Interrupt</button>}
+          <div className="golem-browser-header flex items-center gap-1 whitespace-nowrap border-b border-neutral-200 bg-white px-2 py-2 text-xs">
+            <span className="font-medium">{kind === 'builder' ? 'Builder' : 'Chat'}</span>
+            <span className={`flex min-w-0 items-center ${session ? 'golem-browser-status-connected text-green-700' : 'golem-browser-status-disconnected text-neutral-500'}`} title={session}>
+              <span className="golem-browser-status-dot" aria-hidden="true" />
+              <span className="truncate">{session ? <>{sessionStatus} <span className="opacity-60">{session.slice(0, 8)}</span></> : error ? 'Not connected' : 'Connecting…'}</span>
+            </span>
+            {session && !chatting && <button type="button" className="golem-browser-terminal ml-auto shrink-0 rounded-full border border-neutral-300 px-2 py-1" title="Agent terminal" aria-label="Agent terminal" onClick={() => setTerminal(true)}>🖥️</button>}
           </div>
-          {!mode ? <div className="p-4 text-sm"><p className="text-neutral-600">Codex: {runtime.codex ? 'available' : 'unavailable'} · Claude: not yet connected</p><button className="mt-4 rounded bg-neutral-900 px-3 py-2 text-white disabled:opacity-40" disabled={!runtime.codex || enteringBuildMode} onClick={enterBuildMode}>Enter build mode</button>{error && <p className="mt-3 text-red-700">{error}</p>}</div> : <Chat key={session} config={{ agentName: 'Golem Codex', emptyState: 'Ask Codex to inspect or explain this workspace.' }} adapters={chatAdapters} />}
+          {terminal && session && !chatting && <Terminal session={session} onClose={() => setTerminal(false)} />}
+          {error && <p className="golem-browser-error px-4 pt-3 text-sm text-red-700">{error}</p>}
+          {session && (chatting
+            ? <><div className="min-h-0 flex-1"><Chat key={session} config={{ agentName: 'Assistant', emptyState: 'Ask about or update what you can see in this app.' }} adapters={chatAdapters} /></div>{offers}{source && !sourceShown && <SourceReturn source={source} onShow={() => setSourceShown(true)} />}</>
+            : <Chat key={kind} config={{ agentName: `Golem ${agentNames[sessionBackend ?? 'codex'] ?? sessionBackend}`, emptyState: kind === 'builder' ? `Ask ${agentNames[sessionBackend ?? 'codex'] ?? sessionBackend} to build or change this app.` : 'Ask about this app.' }} adapters={chatAdapters} />)}
         </div>
-      }
+      )}
       canvas={
-        <UserApp />
+        !me ? null : <>
+          {/* Mounted from the first accepted source on, so closing or switching never drops an edit. */}
+          {source && <SourcePanel source={source} shown={sourceShown} onClose={() => setSourceShown(false)} />}
+          {showBrain && (
+            <div className="golem-browser-brain h-full overflow-hidden">
+              {Brain ? <Brain config={{ title: projectConfig.title, openLocation: brainAt === 'index.md' ? undefined : brainAt }} adapters={brainAdapters} /> : <p className="p-4 text-sm text-neutral-600">The Brain reader needs golem-ui after 0.1.1 (see docs/source-development.md).</p>}
+            </div>
+          )}
+          <div className="h-full" style={(source && sourceShown) || showBrain ? { display: 'none' } : undefined}>{
+          !authConfig ? <UserApp screen={screen} />
+          : view === 'account' || (invited && !me.user)
+            ? <div className="golem-browser-admin flex h-full flex-col overflow-auto">
+                <Auth config={authConfig} adapters={authAdapters} />
+                {manages && <Groups />}
+              </div>
+          : accounts.guests ? <UserApp screen={screen} />
+          : <Auth.Guard config={authConfig} adapters={authAdapters}><UserApp screen={screen} /></Auth.Guard>
+          }</div>
+        </>
+      }
+      account={
+        !authConfig ? <span className="golem-browser-guest text-sm text-neutral-500">Guest</span>
+          : me?.user ? <Auth.AccountMenu config={authConfig} adapters={authAdapters} />
+          : <button type="button" className={`golem-browser-sign-in ${barButton}`} title="Sign in" aria-label="Sign in" onClick={() => setView('account')}>{ShellIcon ? <ShellIcon name="user" /> : '👤'}</button>
       }
-      account={<span className="shrink-0 text-sm text-neutral-500">Guest</span>}
     />
   )
 }

package/src/browser/groups.tsx

@@ -0,0 +1,29 @@
+import { useEffect, useState } from 'react'
+import { identity, setGroups, type Member } from '../client'
+
+/** Group membership beside golem-ui's member list, which edits roles but not groups. */
+export function Groups() {
+  const [members, setMembers] = useState<Member[]>([])
+  const [error, setError] = useState<string>()
+  const load = () => identity.listMembers().then((list) => setMembers(list as Member[]), (cause) => setError(String(cause?.message ?? cause)))
+  useEffect(() => { void load() }, [])
+  const save = async (member: Member, text: string) => {
+    setError(undefined)
+    try { await setGroups(member.id, text.split(',').map((group) => group.trim()).filter(Boolean)); await load() }
+    catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)) }
+  }
+  return (
+    <section className="golem-browser-groups mx-auto w-full max-w-sm p-4 text-sm">
+      <h2 className="font-semibold">Groups</h2>
+      <p className="mt-1 text-neutral-500">Comma-separated. App rules can check these.</p>
+      {members.map((member) => (
+        <form key={`${member.id}:${member.groups.join(',')}`} className="mt-3 flex items-center gap-2" onSubmit={(event) => { event.preventDefault(); void save(member, String(new FormData(event.currentTarget).get('groups') ?? '')) }}>
+          <label className="w-28 truncate" htmlFor={`groups-${member.id}`}>{member.name}</label>
+          <input id={`groups-${member.id}`} name="groups" defaultValue={member.groups.join(', ')} className="min-w-0 flex-1 rounded border border-neutral-300 px-2 py-1" />
+          <button type="submit" className="rounded border border-neutral-300 px-2 py-1">Save</button>
+        </form>
+      ))}
+      {error && <p className="golem-browser-error mt-3 text-red-700">{error}</p>}
+    </section>
+  )
+}

package/src/browser/main.tsx

@@ -1,5 +1,6 @@
 import { createRoot } from 'react-dom/client'
 import 'golem-ui/styles.css'
+import './styles.css'
 import { App } from './app'
 
 document.documentElement.style.height = '100%'

package/src/browser/panekeys.ts

@@ -0,0 +1,34 @@
+// Browser keydown → the pane input route's payload. Pure (no DOM at import) so a unit test can import it.
+// Port of Bridge Commander's ui/js/panekeys.js.
+//   { key: '<tmux key name>' } — Enter, BSpace, Up, BTab, C-c, …
+//   { text: '<literal>' }      — one printable character, typed as-is
+//   null                       — not ours: the browser keeps the event (Ctrl-V, ⌘W, F5, …)
+export type PaneInput = { key: string } | { text: string }
+
+// tmux spells several DOM keys differently (BSpace, DC), which is the whole point of the table.
+export const NAMED: Record<string, string> = {
+  Enter: 'Enter', Backspace: 'BSpace', Tab: 'Tab', Escape: 'Escape',
+  ArrowUp: 'Up', ArrowDown: 'Down', ArrowLeft: 'Left', ArrowRight: 'Right',
+  Home: 'Home', End: 'End', PageUp: 'PageUp', PageDown: 'PageDown', Delete: 'DC', Insert: 'IC',
+}
+// Ctrl-<x> combos tmux understands: letters plus the punctuation controls (C-[ Escape, C-\ quit, C-_ undo).
+export const CTRL_KEYS = 'abcdefghijklmnopqrstuvwxyz[\\]^_'
+
+export function keyForEvent(e: { key: string; altKey?: boolean; metaKey?: boolean; ctrlKey?: boolean; shiftKey?: boolean }): PaneInput | null {
+  // Alt/Meta chords belong to the browser and the OS (⌘W, Alt-Tab): a swallowed ⌘W is worse than a missing M-b.
+  if (e.altKey || e.metaKey) return null
+  if (e.key === 'Tab') return { key: e.shiftKey ? 'BTab' : 'Tab' }
+  const named = NAMED[e.key]
+  if (named) return { key: named }
+  if (e.ctrlKey) {
+    if (e.key.length !== 1) return null
+    const c = e.key.toLowerCase()
+    // Ctrl-V stays with the browser: preventDefaulting it would kill the `paste` event, and paste (bracketed,
+    // multi-line) beats a bare C-v. Ctrl-C is NOT excluded: interrupting the agent is the point of typing here.
+    if (c === 'v') return null
+    return CTRL_KEYS.includes(c) ? { key: `C-${c}` } : null
+  }
+  // Any single printable character rides as literal text; no per-character table keeps up with real keyboards.
+  if (e.key.length === 1) return { text: e.key }
+  return null // F-keys, bare modifiers, dead keys, media keys
+}

package/src/browser/sources.tsx

@@ -0,0 +1,113 @@
+import { useEffect, useMemo, useRef, useState, type ComponentProps } from 'react'
+import { Editor } from 'golem-ui'
+import { knowledge, type ViewOffer } from '../client'
+import { answerOffer, subscribeChatView } from './adapters'
+
+/** An accepted passage: `line`–`endLine` hold `text` in file `version`. */
+export type OpenSource = ViewOffer['input'] & { key: string; version: number; text: string }
+
+/**
+ * This tab's view of the open chat: the assistant's offers to open a source, answered here. Only an
+ * offer the person accepts in this tab opens, and only here.
+ */
+export function useSourceView(conversation: string | undefined, onOpen: (source: OpenSource) => void) {
+  const [offers, setOffers] = useState<ViewOffer[]>([])
+  const [error, setError] = useState<string>()
+  const open = useRef(onOpen)
+  open.current = onOpen
+  useEffect(() => {
+    setOffers([])
+    if (!conversation) return
+    return subscribeChatView((event) => {
+      if (event.type === 'offer' && event.offer.conversation === conversation) setOffers((list) => [...list.filter((one) => one.id !== event.offer.id), event.offer])
+      if (event.type === 'withdrawn') setOffers((list) => list.filter((one) => one.id !== event.id))
+      if (event.type === 'apply') open.current({ ...event.offer.input, key: event.offer.id, version: event.version, text: event.text })
+    })
+  }, [conversation])
+  const answer = async (offer: ViewOffer, accept: boolean) => {
+    setError(undefined)
+    setOffers((list) => list.filter((one) => one.id !== offer.id))
+    try { await answerOffer(offer.id, accept) } catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)) }
+  }
+  const panel = (offers.length > 0 || error) && (
+    <div className="golem-browser-offers golem-browser-header border-t border-neutral-200 px-4 py-2 text-sm">
+      {offers.map((offer) => (
+        <div key={offer.id} className="golem-browser-offer flex flex-wrap items-center gap-2 py-1">
+          <span className="golem-browser-runtime min-w-0 flex-1 break-words">Open {offer.input.path}, lines {offer.input.line}–{offer.input.endLine}?</span>
+          <button className="golem-browser-enter rounded bg-neutral-900 px-2 py-1 text-white" onClick={() => void answer(offer, true)}>Open</button>
+          <button className="golem-browser-new rounded border border-neutral-300 px-2 py-1" onClick={() => void answer(offer, false)}>Dismiss</button>
+        </div>
+      ))}
+      {error && <p className="golem-browser-error text-red-700">{error}</p>}
+    </div>
+  )
+  return panel || null
+}
+
+const clock = { now: () => new Date(), timeZone: () => Intl.DateTimeFormat().resolvedOptions().timeZone }
+// `focus` is in golem-ui's Editor after 0.1.1; `version` and `text` let it find the passage in what it
+// shows, waiting for that file version and marking nothing it cannot match exactly once. With 0.1.1
+// installed the prop is ignored: the file opens at the top and the header's line numbers are the pointer.
+type Focus = { line: number; endLine?: number; key?: string; version?: number; text?: string }
+type FocusedEditor = (props: ComponentProps<typeof Editor> & { focus?: Focus }) => ReturnType<typeof Editor>
+const SourceEditor = Editor as unknown as FocusedEditor
+const adapters = { records: knowledge, clock }
+// Editor statuses whose text is not yet in the file: an edit waiting to save, a save in flight, a
+// refused save or a conflict waiting for the person.
+const unsavedStatus = new Set(['dirty', 'saving', 'error', 'conflict'])
+
+/**
+ * The accepted sources in one golem-ui Editor, which marks the offered passage where it finds it. It
+ * stays mounted for the page's life: moving to another source parks this one's draft or conflict in the
+ * Editor, and closing only hides it, so neither loses an edit. Leaving with an edit unsaved asks first.
+ */
+export function SourcePanel({ source, shown, onClose }: { source: OpenSource; shown: boolean; onClose(): void }) {
+  const root = useRef<HTMLDivElement>(null)
+  const record = `${source.root}/${source.path}`
+  const current = useRef(record)
+  current.current = record
+  const [statuses, setStatuses] = useState<Record<string, string>>({})
+  useEffect(() => {
+    const element = root.current
+    if (!element) return
+    // The last status each source showed; a source moved away from keeps it, since the Editor parks it as it was.
+    const read = () => {
+      const status = element.querySelector('[data-golem-status]')?.getAttribute('data-golem-status')
+      if (status) setStatuses((all) => all[current.current] === status ? all : { ...all, [current.current]: status })
+    }
+    const observer = new MutationObserver(read)
+    observer.observe(element, { subtree: true, childList: true, attributes: true, attributeFilter: ['data-golem-status'] })
+    read()
+    return () => observer.disconnect()
+  }, [])
+  const unsaved = Object.keys(statuses).filter((key) => unsavedStatus.has(statuses[key]!))
+  useEffect(() => {
+    if (!unsaved.length) return
+    const ask = (event: BeforeUnloadEvent) => { event.preventDefault(); event.returnValue = '' }
+    window.addEventListener('beforeunload', ask)
+    return () => window.removeEventListener('beforeunload', ask)
+  }, [unsaved.length])
+  const focus = useMemo<Focus>(() => ({ line: source.line, endLine: source.endLine, key: source.key, version: source.version, text: source.text }), [source.key])
+  const config = useMemo(() => ({ collection: source.root, id: source.path, preview: 'toggle' as const }), [source.root, source.path])
+  return (
+    <div ref={root} className="golem-browser-source flex h-full flex-col overflow-hidden" style={shown ? undefined : { display: 'none' }}>
+      <div className="golem-browser-header flex items-center justify-between gap-2 border-b border-neutral-200 px-4 py-2 text-sm">
+        <span className="golem-browser-runtime min-w-0 truncate"><span className="font-medium">{source.path}</span>, saved lines {source.line}–{source.endLine}</span>
+        {unsaved.some((key) => key !== record) && <span className="golem-browser-error shrink-0 text-red-700">Unsaved: {unsaved.filter((key) => key !== record).map((key) => key.slice(key.indexOf('/') + 1)).join(', ')}</span>}
+        <button type="button" className="golem-browser-new shrink-0 rounded border border-neutral-300 px-2 py-1" onClick={onClose}>Back to app</button>
+      </div>
+      <div className="min-h-0 flex-1">
+        <SourceEditor config={config} adapters={adapters} focus={focus} />
+      </div>
+    </div>
+  )
+}
+
+/** Returns to the open source after Back to app, as the Editor left it. */
+export function SourceReturn({ source, onShow }: { source: OpenSource; onShow(): void }) {
+  return (
+    <div className="golem-browser-header border-t border-neutral-200 px-4 py-2 text-sm">
+      <button type="button" className="golem-browser-new rounded border border-neutral-300 px-2 py-1" onClick={onShow}>Show {source.path}</button>
+    </div>
+  )
+}

package/src/browser/styles.css

@@ -0,0 +1,36 @@
+[data-golem-theme] .golem-browser-status-connected { color: oklch(52.7% .154 150.069); }
+[data-golem-theme='dark'] .golem-browser-header { border-color: oklch(26.9% 0 0); background-color: oklch(14.5% 0 0); color: oklch(87% 0 0); }
+[data-golem-theme='dark'] .golem-browser-status-connected { color: oklch(79.2% .209 151.711); }
+[data-golem-theme='dark'] .golem-browser-status-disconnected, [data-golem-theme='dark'] .golem-browser-guest { color: oklch(70.8% 0 0); }
+[data-golem-theme='dark'] .golem-browser-runtime { color: oklch(87% 0 0); }
+[data-golem-theme='dark'] .golem-browser-enter { background-color: oklch(87% 0 0); color: oklch(14.5% 0 0); }
+[data-golem-theme='dark'] .golem-browser-error { color: oklch(70.4% .191 22.216); }
+[data-golem-theme='dark'] .golem-browser-backend { border-color: oklch(37.1% 0 0); background-color: oklch(20.5% 0 0); color: oklch(98.5% 0 0); }
+[data-golem-theme='dark'] .golem-browser-new { border-color: oklch(37.1% 0 0); color: oklch(87% 0 0); }
+/* The sign-in button matches the Shell's own bar buttons (Chat's tokens). */
+.golem-browser-bar-button { border-color: var(--chat-line, #dce3eb); color: var(--chat-dim, #5f7186); }
+.golem-browser-bar-button:hover { border-color: var(--chat-accent, #2f83c2); color: var(--chat-accent, #2f83c2); }
+.golem-browser-header { line-height: 1.25; }
+.golem-browser-header button { line-height: 1.25; }
+.golem-browser-status-dot { display: inline-block; width: .45em; height: .45em; margin-right: .35em; border-radius: 9999px; background-color: currentColor; flex-shrink: 0; }
+[data-golem-theme='dark'] .golem-browser-status-disconnected .golem-browser-status-dot { opacity: .6; }
+/* Terminal popup: Bridge Commander's pane overlay one for one. A dark surface in both themes (the ANSI palette is tuned for one). */
+.golem-terminal-overlay { background-color: rgb(4 7 11 / .6); backdrop-filter: blur(2px); }
+.golem-terminal { max-height: min(660px, 86vh); border-color: oklch(37.1% 0 0); background-color: #0a0c11; color: #c9d4e0; }
+.golem-terminal-head { border-color: oklch(26.9% 0 0); background-color: oklch(14.5% 0 0); }
+.golem-terminal-title { font-size: 12.5px; }
+.golem-terminal-live { width: 8px; height: 8px; border-radius: 50%; background: oklch(45% 0 0); flex: none; transition: background .2s; }
+.golem-terminal-live.on { background: oklch(79.2% .209 151.711); box-shadow: 0 0 7px oklch(79.2% .209 151.711); }
+/* the hint doubles as the focus indicator and as the only place the way out is written down */
+.golem-terminal-hint { flex: none; color: oklch(55.6% 0 0); font-size: 10.5px; }
+.golem-terminal-hint.on { color: oklch(70.7% .165 254.624); }
+.golem-terminal-hint.flash { color: oklch(70.4% .191 22.216); }
+.golem-terminal-close { color: oklch(70.8% 0 0); font-size: 15px; line-height: 1; }
+.golem-terminal-close:hover { color: #fff; }
+.golem-terminal-screen {
+  color: #c9d4e0; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 11.5px; line-height: 1.4;
+  white-space: pre; user-select: text; cursor: text; overscroll-behavior: contain; border-top: 2px solid transparent;
+}
+/* focused == typing: unmistakable, because a pane that silently swallows keystrokes is worse than a read-only one */
+.golem-terminal-screen.typing { border-top-color: oklch(70.7% .165 254.624); background-color: #0c1016; }
+.golem-terminal-msg { color: oklch(70.8% 0 0); }

package/src/browser/terminal.tsx

@@ -0,0 +1,89 @@
+import { useEffect, useRef, useState } from 'react'
+import { ansiToHtml } from './ansi'
+import { keyForEvent } from './panekeys'
+
+// Interrupts skip the send queue: Ctrl-C exists to arrive when the pane is not keeping up.
+const JUMPS_QUEUE = new Set(['C-c', 'C-d', 'C-z', 'C-\\'])
+
+// The Terminal popup, a port of Bridge Commander's ui/js/pane.js: the agent's live tmux screen (whole-screen
+// frames over SSE, replaced not appended) that is itself focusable. Keys go straight to the pane, paste is a
+// literal paste, text stays selectable. No terminal emulator: keys go out, frames come back.
+export function Terminal({ session, onClose }: { session: string; onClose: () => void }) {
+  const preRef = useRef<HTMLPreElement>(null)
+  const [message, setMessage] = useState<string>()
+  const [live, setLive] = useState(false)
+  const [typing, setTyping] = useState(false)
+  const [flash, setFlash] = useState<string>()
+  const base = `/api/sessions/${encodeURIComponent(session)}/pane/`
+  useEffect(() => {
+    const es = new EventSource(`${base}stream`)
+    const fail = (text: string) => { es.close(); setLive(false); setMessage(text) }
+    es.addEventListener('frame', (event) => {
+      const pre = preRef.current
+      if (!pre) return
+      // Stick to the bottom only when the user was already there: a scroll-up must survive the next frame.
+      const stick = pre.scrollTop + pre.clientHeight >= pre.scrollHeight - 12
+      pre.innerHTML = ansiToHtml(String(JSON.parse((event as MessageEvent).data)))
+      if (stick) pre.scrollTop = pre.scrollHeight
+      setLive(true)
+    })
+    es.addEventListener('unsupported', () => fail('this agent has no live terminal'))
+    es.addEventListener('busy', () => fail('too many terminals open; close one and try again'))
+    es.addEventListener('no-pane', (event) => {
+      let reason = ''
+      try { reason = JSON.parse((event as MessageEvent).data).reason ?? '' } catch { /* plain message */ }
+      fail(`no live terminal${reason ? `: ${reason}` : ''}`)
+    })
+    es.onerror = () => setLive(false)
+    return () => es.close()
+  }, [base])
+  // Escape closes the overlay only while the screen is NOT focused; focused, it belongs to the agent
+  // (the pane's own keydown stops propagation before it gets here).
+  useEffect(() => {
+    const onKey = (event: KeyboardEvent) => { if (event.key === 'Escape') onClose() }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [onClose])
+  // One POST per keystroke, chained: same-origin fetches can complete out of order, and out-of-order
+  // keystrokes scramble typed text ("abc" → "acb"). Each hop is bounded by a timeout so one stall cannot wedge the rest.
+  const chain = useRef(Promise.resolve())
+  const flashTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  const post = (payload: { text?: string; key?: string }) => fetch(`${base}input`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(payload), signal: AbortSignal.timeout(5000) })
+    .then(async (response) => { if (!response.ok) throw new Error((await response.json().catch(() => ({}))).error ?? `HTTP ${response.status}`) })
+    // A rejected keystroke was preventDefaulted away from the browser: it must not vanish in silence.
+    .catch((error: unknown) => { setFlash(error instanceof Error ? error.message : String(error)); clearTimeout(flashTimer.current); flashTimer.current = setTimeout(() => setFlash(undefined), 4000) })
+  const send = (payload: { text?: string; key?: string }) => {
+    if (payload.key && JUMPS_QUEUE.has(payload.key)) { void post(payload); return }
+    chain.current = chain.current.then(() => post(payload))
+  }
+  const onKeyDown = (event: React.KeyboardEvent) => {
+    const payload = keyForEvent(event)
+    if (!payload) return // browser/OS chord: leave it alone (Ctrl-V, ⌘W, F5…)
+    event.preventDefault()
+    event.stopPropagation()
+    send(payload)
+  }
+  // Paste rides the literal path: the harness switches to a bracketed paste for multi-line text.
+  const onPaste = (event: React.ClipboardEvent) => {
+    event.preventDefault()
+    const text = event.clipboardData.getData('text')
+    if (text) send({ text })
+  }
+  const hint = flash ? `⚠ ${flash}` : typing ? 'typing — keys go to the pane · Esc too · ✕ or click outside to close' : 'click the screen to type'
+  return (
+    <div className="golem-terminal-overlay fixed inset-0 z-50 flex items-center justify-center p-4" onClick={(event) => { if (event.target === event.currentTarget) onClose() }}>
+      <div className="golem-terminal flex h-full w-full max-w-5xl flex-col overflow-hidden rounded-xl border shadow-xl" role="dialog" aria-label="Agent terminal">
+        <div className="golem-terminal-head flex items-center gap-2 border-b px-3.5 py-2.5 text-xs">
+          <span className={`golem-terminal-live ${live ? 'on' : ''}`} title={live ? 'live' : 'not streaming'} aria-hidden="true" />
+          <span className="golem-terminal-title min-w-0 flex-1 truncate font-mono font-semibold">{session}</span>
+          {!message && <span className={`golem-terminal-hint whitespace-nowrap ${flash ? 'flash' : typing ? 'on' : ''}`}>{hint}</span>}
+          <button type="button" className="golem-terminal-close px-1.5" title="Close" onClick={onClose}>✕</button>
+        </div>
+        {message
+          ? <div className="golem-terminal-msg flex flex-1 items-center justify-center p-6 text-sm">{message}</div>
+          : <pre ref={preRef} tabIndex={0} className={`golem-terminal-screen m-0 min-h-0 flex-1 overflow-auto px-3.5 py-3 outline-none ${typing ? 'typing' : ''}`}
+              onFocus={() => setTyping(true)} onBlur={() => setTyping(false)} onKeyDown={onKeyDown} onPaste={onPaste}>connecting…</pre>}
+      </div>
+    </div>
+  )
+}

package/src/browser-build.ts

@@ -1,9 +1,11 @@
 import { execFileSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
 import { build } from 'vite';
 import { resolveUiSource } from '../vite.config.ts';
+import { sourcePaths } from './source-mode.ts';
 
 const frameworkRoot = resolve(fileURLToPath(new URL('..', import.meta.url)));
 
@@ -28,12 +30,23 @@ export async function buildBrowser(): Promise<void> {
     cwd: process.cwd(),
     stdio: 'inherit',
   });
-  execFileSync(tsc, [
-    '--ignoreConfig', '--noEmit', '--jsx', 'react-jsx', '--module', 'ESNext',
-    '--moduleResolution', 'Bundler', '--skipLibCheck', '--types', 'node,react,react-dom',
-    '--typeRoots', typeRoots,
-    resolve(process.cwd(), 'src/app.tsx'), resolve(process.cwd(), 'golem.config.ts'),
-  ], { cwd: process.cwd(), stdio: 'inherit' });
+  // A generated config rather than bare flags: `paths` is the only way to tell tsc that the app's
+  // own `golem-kit`/`golem-ui` imports come from the source checkouts, and it has no CLI flag. It
+  // lives in a temp dir so source mode never writes into the app folder.
+  const appTsconfig = resolve(mkdtempSync(resolve(tmpdir(), 'golem-typecheck-')), 'tsconfig.json');
+  writeFileSync(appTsconfig, JSON.stringify({
+    compilerOptions: {
+      noEmit: true, jsx: 'react-jsx', module: 'ESNext', moduleResolution: 'Bundler',
+      skipLibCheck: true, allowImportingTsExtensions: true,
+      types: ['node', 'react', 'react-dom'], typeRoots: [typeRoots],
+      paths: sourcePaths(),
+    },
+    files: [
+      resolve(process.cwd(), 'src/app.tsx'), resolve(process.cwd(), 'golem.config.ts'),
+      ...[resolve(process.cwd(), 'src/server/index.ts')].filter(existsSync),
+    ],
+  }));
+  execFileSync(tsc, ['-p', appTsconfig], { cwd: process.cwd(), stdio: 'inherit' });
   await build({ configFile: resolve(frameworkRoot, 'vite.config.ts') });
 }