golem-kit 0.1.1 → 0.2.0

package/src/runtime/session.ts

@@ -1,18 +1,44 @@
 import { randomUUID } from 'node:crypto'
 import type { AgentName } from './discovery.ts'
+import type { TurnContext } from './assistant.ts'
+import { citations } from '../brain.ts'
+
+/** A terminal agent, or `anthropic`: the ordinary-use API agent. */
+export type BackendName = AgentName | 'anthropic'
 
 export type BackendEvent =
   | { type: 'message'; text: string }
   | { type: 'interrupted'; reason?: string }
   | { type: 'error'; message: string }
+  | { type: 'tool'; name: string; ok: boolean; text?: string }
 
-/** The runtime contract only; Claude/Codex process bridging is intentionally not implemented yet. */
 export type SessionBackend = {
-  start(emit: (event: BackendEvent) => void): Promise<void>
-  send(text: string): Promise<void>
+  /** `sessionId` names the conversation this backend serves (the tmux backend's session name and `GOLEM_SESSION`). */
+  start(emit: (event: BackendEvent) => void, sessionId: string): Promise<void>
+  /** `context` is the sender of this message, when the server accepted it from a person. */
+  send(text: string, context?: TurnContext): Promise<void>
   shutdown(): Promise<void>
   interrupt?(): Promise<void>
-  threadId?(): string | undefined
+  /** Called instead of `shutdown` when the server stops: a backend that outlives the server keeps running. */
+  detach?(): Promise<void>
+  /** Where to find or resume the agent after a server restart; saved with the conversation. */
+  harnessRef?(): unknown
+  /** Conversation state a backend keeps itself, saved with the conversation and handed back on restore. */
+  transcript?(): unknown
+  /** The agent's live terminal screen, when the backend has one to show (the tmux backend). */
+  pane?(): PaneAccess | undefined
+  /** Slash commands the harness honours, and their runner; the reply is the strip's system text. */
+  commands?(): SlashCommand[]
+  runCommand?(line: string): Promise<string>
+}
+
+export type SlashCommand = { name: string; description: string; args?: Array<{ value: string; description: string }> }
+
+/** One agent screen: `open` streams whole-screen frames on change until closed, `input` types one key or a literal string. */
+export type PaneAccess = {
+  open(onFrame: (frame: string) => void): Promise<{ close(): void }> | { close(): void }
+  snapshot(): Promise<string>
+  input(input: { key?: string; text?: string }): Promise<void>
 }
 
 export type SessionStatus = 'starting' | 'ready' | 'interrupted' | 'stopped' | 'failed'
@@ -20,10 +46,17 @@ export type SessionStatus = 'starting' | 'ready' | 'interrupted' | 'stopped' | '
 export type SessionEvent = {
   sequence: number
   sessionId: string
-  type: 'status' | 'user' | 'message' | 'interrupted' | 'error' | 'rebuilt'
+  type: 'status' | 'user' | 'message' | 'interrupted' | 'error' | 'rebuilt' | 'tool'
   status?: SessionStatus
   text?: string
   reason?: string
+  /** A tool event's operation name and whether the call succeeded. */
+  name?: string
+  ok?: boolean
+  clientMessageId?: string
+  attachments?: Array<{ id: string; name: string; size?: number }>
+  /** Brain locations (`path#Lstart-Lend`) the agent cited in this message. */
+  sources?: string[]
 }
 
 export class Session {
@@ -31,31 +64,40 @@ export class Session {
   status: SessionStatus = 'starting'
   private readonly listeners = new Set<(event: SessionEvent) => void>()
   private sequence = 0
-  private readonly pending: Array<{ text: string; resolve: () => void; reject: (error: Error) => void }> = []
+  private readonly pending: Array<{ text: string; context?: TurnContext; generation: number; resolve: () => void; reject: (error: Error) => void }> = []
   private active = false
   private dispatchScheduled = false
   private closed = false
   private shutdownPromise: Promise<void> | undefined
   private workerShutdownPromise: Promise<void> | undefined
   private activeReject: ((error: Error) => void) | undefined
+  /** The sender of the turn now running; revocation checks it. */
+  activeContext: TurnContext | undefined
   private workerStarted = false
   private persistence = Promise.resolve()
   private persistenceError: Error | undefined
+  private readonly pendingReceipts = new Map<string, { event: SessionEvent; receipt: Promise<void> }>()
+  private requestGeneration = 0
+  private updatedAt: string | undefined = new Date().toISOString()
   readonly id: string
-  readonly backend: AgentName
+  readonly backend: BackendName
   /** Server-owned: set once at creation from the request's explicit build intent, never inferred. */
   readonly buildMode: boolean
-  private readonly worker: SessionBackend
+  /** The account that started this conversation when the app has accounts; only it may use it. */
+  readonly owner: string | undefined
+  readonly worker: SessionBackend
   private readonly save?: (snapshot: SessionSnapshot) => Promise<void>
 
   constructor(
-    backend: AgentName,
+    backend: BackendName,
     worker: SessionBackend,
     id: string,
     buildMode = false,
     save?: (snapshot: SessionSnapshot) => Promise<void>,
+    owner?: string,
   ) {
     this.id = id
+    this.owner = owner
     this.backend = backend
     this.worker = worker
     this.buildMode = buildMode
@@ -81,17 +123,19 @@ export class Session {
   }
 
   static restore(snapshot: SessionSnapshot, worker: SessionBackend, save?: (snapshot: SessionSnapshot) => Promise<void>): Session {
-    const session = new Session(snapshot.backend, worker, snapshot.id, snapshot.buildMode, save)
+    const session = new Session(snapshot.backend, worker, snapshot.id, snapshot.buildMode, save, snapshot.owner)
     session.history.push(...snapshot.history)
     session.status = snapshot.status
     session.sequence = Math.max(-1, ...snapshot.history.map((event) => event.sequence)) + 1
-    session.closed = snapshot.status === 'stopped'
+    session.updatedAt = snapshot.updatedAt
+    // A stopped session with a harness ref was parked, not closed: its next message resumes the agent.
+    session.closed = snapshot.status === 'stopped' && !snapshot.harness
     if (snapshot.active) session.recoverInterrupted()
     return session
   }
 
   snapshot(): SessionSnapshot {
-    return { id: this.id, backend: this.backend, buildMode: this.buildMode, status: this.status, active: this.active, history: this.history, threadId: this.worker.threadId?.() }
+    return { id: this.id, backend: this.backend, buildMode: this.buildMode, ...(this.owner ? { owner: this.owner } : {}), status: this.status, active: this.active, history: [...this.history, ...[...this.pendingReceipts.values()].map(({ event }) => event)], harness: this.worker.harnessRef?.(), ...(this.worker.transcript ? { transcript: this.worker.transcript() } : {}), updatedAt: this.updatedAt }
   }
 
   async flush(): Promise<void> {
@@ -99,15 +143,28 @@ export class Session {
     if (this.persistenceError) throw this.persistenceError
   }
 
-  send(text: string): Promise<void> {
-    if (this.closed || (this.status !== 'ready' && this.status !== 'interrupted' && this.status !== 'failed')) {
-      return Promise.reject(new Error(`Session ${this.status}`))
-    }
-    if (this.status === 'interrupted' || this.status === 'failed') this.setStatus('ready')
-    return new Promise((resolve, reject) => {
-      this.pending.push({ text, resolve, reject })
-      this.pump()
-    })
+  /** `context` stays with this message through the queue; a duplicate keeps the first one's. */
+  async accept(text: string, clientMessageId: string, attachments?: SessionEvent['attachments'], context?: TurnContext): Promise<{ duplicate: boolean; completion?: Promise<void> }> {
+    if (this.closed || this.status === 'starting') throw new Error(`Session ${this.status}`)
+    if (!clientMessageId) throw new Error('clientMessageId is required')
+    if (this.history.some((event) => event.type === 'user' && event.clientMessageId === clientMessageId)) return { duplicate: true }
+    const pending = this.pendingReceipts.get(clientMessageId)
+    if (pending) { await pending.receipt; return { duplicate: true } }
+    if (this.status !== 'ready') this.setStatus('ready')
+    const generation = this.requestGeneration
+    await this.recordDurably({ type: 'user', text, clientMessageId, attachments })
+    if (generation !== this.requestGeneration || this.closed || this.status !== 'ready') throw new Error(`Session ${this.status}`)
+    let resolve!: () => void
+    let reject!: (error: Error) => void
+    const completion = new Promise<void>((ok, fail) => { resolve = ok; reject = fail })
+    this.pending.push({ text, context, generation, resolve, reject })
+    this.pump()
+    return { duplicate: false, completion }
+  }
+
+  async send(text: string): Promise<void> {
+    const accepted = await this.accept(text, randomUUID())
+    await accepted.completion
   }
 
   subscribe(listener: (event: SessionEvent) => void): () => void {
@@ -123,16 +180,35 @@ export class Session {
   async shutdown(): Promise<void> {
     if (this.shutdownPromise) return this.shutdownPromise
     this.closed = true
+    this.requestGeneration++
     this.setStatus('stopped')
     this.rejectPending(new Error('Session stopped'))
     this.shutdownPromise = this.closeWorker()
     return this.shutdownPromise
   }
 
-  async dispose(): Promise<void> { await this.closeWorker() }
+  /** The agent is running: a tmux session exists for this conversation. */
+  get live(): boolean { return this.workerStarted && !this.closed }
+
+  /**
+   * Kills the worker but keeps the conversation: history and the harness ref (with its resume id) stay
+   * in the snapshot, and the next message resumes the agent the way a server restart does.
+   */
+  async park(): Promise<void> {
+    if (!this.live) return
+    this.requestGeneration++
+    this.workerStarted = false
+    this.setStatus('stopped')
+    this.activeReject?.(new Error('Session parked'))
+    this.rejectPending(new Error('Session parked'))
+    await this.worker.shutdown()
+  }
+
+  async dispose(): Promise<void> { await (this.worker.detach ? this.worker.detach() : this.closeWorker()) }
 
   abandon(): void {
     if (!this.active || this.closed) return
+    this.requestGeneration++
     this.setStatus('interrupted')
     this.record({ type: 'interrupted', reason: 'server restarted during this turn' })
     this.activeReject?.(new Error('Session interrupted'))
@@ -141,6 +217,7 @@ export class Session {
   async interrupt(): Promise<void> {
     if (this.closed || this.status === 'stopped') return
     if (this.status !== 'ready') return
+    this.requestGeneration++
     this.setStatus('interrupted')
     this.record({ type: 'interrupted', reason: 'interrupted by user' })
     this.activeReject?.(new Error('Session interrupted'))
@@ -161,9 +238,11 @@ export class Session {
     this.record({ type: 'error', text: message })
   }
 
-  private receive(event: BackendEvent): void {
+  /** Also the entry for replies the agent posts itself (`golem say`). */
+  receive(event: BackendEvent): void {
     if (this.closed) return
-    if (event.type === 'message') this.record({ type: 'message', text: event.text })
+    if (event.type === 'message') { const sources = citations(event.text); this.record({ type: 'message', text: event.text, ...(sources.length ? { sources } : {}) }) }
+    if (event.type === 'tool') this.record({ type: 'tool', name: event.name, ok: event.ok, text: event.text })
     if (event.type === 'interrupted') {
       const alreadyInterrupted = this.status === 'interrupted'
       if (!alreadyInterrupted) this.setStatus('interrupted')
@@ -185,14 +264,20 @@ export class Session {
     Promise.resolve()
       .then(async () => {
         this.dispatchScheduled = false
-        if (this.closed || this.status !== 'ready' || this.pending[0] !== next) {
+        if (next.generation !== this.requestGeneration || this.closed || this.status !== 'ready' || this.pending[0] !== next) {
           this.pump()
           return
         }
         this.pending.shift()
         this.active = true
-        this.record({ type: 'user', text: next.text })
-        if (this.closed || this.status !== 'ready') {
+        this.persist()
+        try { await this.flush() } catch (error) {
+          this.active = false
+          next.reject(error instanceof Error ? error : new Error(String(error)))
+          this.pump()
+          return
+        }
+        if (next.generation !== this.requestGeneration || this.closed || this.status !== 'ready') {
           this.active = false
           next.reject(new Error(`Session ${this.status}`))
           this.pump()
@@ -200,15 +285,17 @@ export class Session {
         }
         try {
           await this.startWorker()
-          if (this.closed || this.status !== 'ready') {
+          if (next.generation !== this.requestGeneration || this.closed || this.status !== 'ready') {
             this.active = false
             next.reject(new Error(`Session ${this.status}`))
             this.pump()
             return
           }
           this.activeReject = next.reject
-          Promise.resolve(this.worker.send(next.text)).then(next.resolve, next.reject).finally(() => {
+          this.activeContext = next.context
+          Promise.resolve(this.worker.send(next.text, next.context)).then(next.resolve, next.reject).finally(() => {
             this.activeReject = undefined
+            this.activeContext = undefined
             this.active = false
             this.persist()
             this.pump()
@@ -232,7 +319,7 @@ export class Session {
 
   private async startWorker(): Promise<boolean> {
     if (this.workerStarted) return false
-    await this.worker.start((event) => this.receive(event))
+    await this.worker.start((event) => this.receive(event), this.id)
     this.workerStarted = true
     return true
   }
@@ -252,10 +339,34 @@ export class Session {
   private record(event: Omit<SessionEvent, 'sequence' | 'sessionId'>): void {
     const complete = { ...event, sequence: this.sequence++, sessionId: this.id }
     this.history.push(complete)
+    this.updatedAt = new Date().toISOString()
     this.listeners.forEach((listener) => listener(complete))
     this.persist()
   }
 
+  /** A user receipt is not externally visible until it is durable. */
+  private async recordDurably(event: Omit<SessionEvent, 'sequence' | 'sessionId'>): Promise<void> {
+    const complete = { ...event, sequence: this.sequence++, sessionId: this.id }
+    this.updatedAt = new Date().toISOString()
+    let resolve!: () => void
+    let reject!: (error: Error) => void
+    const receipt = new Promise<void>((ok, fail) => { resolve = ok; reject = fail })
+    void receipt.catch(() => {})
+    this.pendingReceipts.set(complete.clientMessageId!, { event: complete, receipt })
+    this.persist()
+    try {
+      await this.flush()
+      this.pendingReceipts.delete(complete.clientMessageId!)
+      this.history.push(complete)
+      this.listeners.forEach((listener) => listener(complete))
+      resolve()
+    } catch (error) {
+      this.pendingReceipts.delete(complete.clientMessageId!)
+      reject(error instanceof Error ? error : new Error(String(error)))
+      throw error
+    }
+  }
+
   private persist(): void {
     if (!this.save || this.persistenceError) return
     const snapshot = this.snapshot()
@@ -272,12 +383,15 @@ export class Session {
 
 export type SessionSnapshot = {
   id: string
-  backend: AgentName
+  backend: BackendName
   buildMode: boolean
+  owner?: string
   status: SessionStatus
   active: boolean
   history: SessionEvent[]
-  threadId?: string
+  harness?: unknown
+  transcript?: unknown
+  updatedAt?: string
 }
 
 export class SessionManager {
@@ -288,8 +402,8 @@ export class SessionManager {
 
   private persist = async (): Promise<void> => this.save?.([...this.sessions.values()].map((session) => session.snapshot()))
 
-  async start(backend: AgentName, worker: SessionBackend, buildMode = false): Promise<Session> {
-    const session = new Session(backend, worker, randomUUID(), buildMode, this.persist)
+  async start(backend: BackendName, worker: SessionBackend, buildMode = false, owner?: string): Promise<Session> {
+    const session = new Session(backend, worker, randomUUID(), buildMode, this.persist, owner)
     this.sessions.set(session.id, session)
     try {
       await session.start()
@@ -303,10 +417,33 @@ export class SessionManager {
 
   get(id: string): Session | undefined { return this.sessions.get(id) }
 
+  all(): Session[] { return [...this.sessions.values()] }
+
+  /** The most recently active conversation among those `visible` allows; build conversations by default. */
+  latest(visible: (session: Session) => boolean = (session) => session.buildMode): Session | undefined {
+    let latest: Session | undefined
+    for (const session of this.sessions.values()) {
+      if (!visible(session)) continue
+      const candidate = session.snapshot().updatedAt
+      const current = latest?.snapshot().updatedAt
+      if (!latest || (candidate && (!current || candidate >= current)) || (!candidate && !current)) latest = session
+    }
+    return latest
+  }
+
   restore(snapshots: SessionSnapshot[], createWorker: (snapshot: SessionSnapshot) => SessionBackend): void {
     for (const snapshot of snapshots) this.sessions.set(snapshot.id, Session.restore(snapshot, createWorker(snapshot), this.persist))
   }
 
+  /**
+   * One agent per window: the app's tmux session has a `builder` window and a `chat` window, and a
+   * terminal-agent conversation lives in the one its `buildMode` names. Parks every other terminal-agent
+   * conversation of that window before another starts or resumes there.
+   */
+  async parkOthers(buildMode: boolean, id?: string): Promise<void> {
+    await Promise.all(this.all().filter((session) => session.id !== id && session.backend !== 'anthropic' && session.buildMode === buildMode).map((session) => session.park()))
+  }
+
   async shutdownAll(): Promise<void> {
     await Promise.all([...this.sessions.values()].map((session) => session.shutdown()))
   }

package/src/runtime/tmux.ts

@@ -0,0 +1,173 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { basename, dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { AgentName } from './discovery.ts'
+import type { BackendEvent, PaneAccess, SessionBackend, SlashCommand } from './session.ts'
+
+const require = createRequire(import.meta.url)
+const frameworkRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..')
+
+/** The Bridge Commander harness ref: enough to find, kill or resume the tmux session after a restart. */
+export type HarnessRef = { harness: string; session: string; cwd: string; resumeId?: string; window?: string }
+
+/** The seven-verb harness port (src/runtime/harness/README in bridge-commander); `fake.js` for tests. */
+export type Harness = {
+  spawn(cwd: string, prompt: string, opts: object): Promise<HarnessRef>
+  send(ref: HarnessRef, text: string): Promise<void>
+  resume(ref: HarnessRef, opts: object): Promise<HarnessRef>
+  kill(ref: HarnessRef): Promise<void> | void
+  onTurnEnd(ref: HarnessRef, hook: (event: { session_id?: string | null }) => void, opts: object): () => void
+  paneInput?(ref: HarnessRef, input: { key?: string; text?: string }): Promise<void>
+  openPane?(ref: HarnessRef, opts: { onFrame: (frame: string) => void }): Promise<PaneHandle> | PaneHandle
+  paneSnapshot?(ref: HarnessRef): Promise<string>
+  commands?(ref: HarnessRef): SlashCommand[]
+  runCommand?(ref: HarnessRef, line: string): Promise<string>
+  /** Pins a session-granular ref (pre-window conversations) to a named window without restarting the agent. */
+  adoptWindow?(ref: HarnessRef, window: string): Promise<HarnessRef | null>
+}
+export type PaneHandle = { close(): void }
+
+export const harnesses: Record<AgentName, Harness> = {
+  claude: require('./harness/claude-tmux.js'),
+  codex: require('./harness/codex-tmux.js'),
+}
+
+export function builderInstructions(cwd: string): string {
+  const source = process.env.GOLEM_SOURCE ? resolve(process.env.GOLEM_SOURCE) : frameworkRoot
+  const ui = process.env.GOLEM_UI_SOURCE ? resolve(process.env.GOLEM_UI_SOURCE) : undefined
+  const guide = resolve(source, 'docs/builder.md')
+  return `You are Golem's in-app builder. The user sees Chat beside their application's Canvas. Explain that plainly and ask what they want to create; do not redirect them to generic coding-assistant documentation. Build-mode turns may edit the app and, after success, Golem rebuilds and refreshes the Canvas. Conversation history persists, including resumed threads. Read ${existsSync(guide) ? guide : resolve(frameworkRoot, 'docs/builder.md')} and ${resolve(cwd, 'docs/domain.md')} when present before major work, implementation, or opening/updating a pull request. This app is ${cwd}; active Golem source is ${source}${ui ? `; active golem-ui source is ${ui}` : ''}. Keep app-specific decisions in the app and shared framework/UI knowledge in its owner. The user only sees what you send with \`./golem say <text>\` (or \`./golem say --file <f>\`) from the app root; answer every message that way, nothing printed in this terminal reaches them.${existsSync(resolve(cwd, 'brain/index.md')) ? ` ${brainInstructions}` : ''}`
+}
+
+/** The `chat` window's brief: the app's `docs/chat.md` when present, else a plain assistant; never a builder. */
+export function chatInstructions(cwd: string): string {
+  const brief = resolve(cwd, 'docs/chat.md')
+  const own = existsSync(brief) ? readFileSync(brief, 'utf8').trim() : `You are the assistant of the application in ${cwd}. People chat with you beside the running app; help them use it and answer questions about it.`
+  return `${own} You are not this app's builder: do not edit its files, run builds, or change its configuration; if asked to, say the Builder switch is for that. The user only sees what you send with \`./golem say <text>\` (or \`./golem say --file <f>\`) from the app root; answer every message that way, nothing printed in this terminal reaches them.${existsSync(resolve(cwd, 'brain/index.md')) ? ` ${brainInstructions}` : ''}`
+}
+
+/** Added when the app has a `brain/` folder: read the root index first, cite what you used. */
+export const brainInstructions = 'This app has a brain: `brain/` is an Open Knowledge Format bundle. Read `brain/index.md` first, then the concepts it points to. When an answer is grounded in the brain, cite each passage you used as `path#Lstart-Lend` (the path relative to `brain/`, e.g. `concepts/opening.md#L4-L9`); Golem turns those citations into source chips under your reply that open the passage in the reader.'
+
+/**
+ * `window` names this agent's window in the app's session (`builder`, `chat`); `instructions` its launch prompt;
+ * `permissions` its launch profile: `bypass` (default) may do anything, `readonly` can read the app and run
+ * `./golem say`, nothing else, and refuses rather than prompts.
+ */
+export type TmuxOptions = { harness?: Harness; stateDir?: string; api?: string; window?: string; instructions?: string; permissions?: 'bypass' | 'readonly' }
+
+/** The one tmux session of an app's build mode: `tmux attach -t golem-<app dir>` is always the place to look. */
+export const tmuxSessionName = (cwd: string): string => `golem-${basename(cwd).replace(/[^A-Za-z0-9_-]/g, '-')}`
+
+/**
+ * One agent per app, in the fixed tmux session `golem-<app dir>` (attach to watch or take over). A
+ * conversation whose agent was killed to make room for another resumes it there on its next message
+ * (`SessionManager.parkOthers`). `send` types the message with verified submit and resolves at the agent's turn end
+ * (Stop hook / codex notify); the reply itself arrives through `golem say`, never from the pane.
+ */
+export class TmuxBackend implements SessionBackend {
+  private ref: HarnessRef | undefined
+  private emit!: (event: BackendEvent) => void
+  private turnEnded: (() => void) | undefined
+  private unsubscribe: (() => void) | undefined
+  private readonly harness: Harness
+  private readonly opts: TmuxOptions
+
+  private readonly cwd: string
+  private readonly agent: AgentName
+
+  constructor(cwd: string, agent: AgentName, ref?: HarnessRef, opts: TmuxOptions = {}) {
+    this.cwd = cwd
+    this.agent = agent
+    this.ref = ref
+    this.opts = opts
+    this.harness = opts.harness ?? harnesses[agent]
+  }
+
+  async start(emit: (event: BackendEvent) => void, sessionId: string): Promise<void> {
+    this.emit = emit
+    const opts = {
+      stateDir: this.opts.stateDir ?? resolve(this.cwd, '.golem/harness'),
+      session: tmuxSessionName(this.cwd),
+      window: this.opts.window,
+      permissions: this.opts.permissions,
+      env: { GOLEM_SESSION: sessionId, GOLEM_API: this.opts.api ?? 'http://127.0.0.1:3000' },
+      // codex 0.155: the update prompt at launch would take the typed brief as its answer, the
+      // paste-burst fold swallows the first Enter of a long line, and the rate-limit "keep current
+      // model" nudge after the first turn eats the first message. All off; replayed on resume.
+      extraArgs: this.agent === 'codex' ? ['-c', 'check_for_update_on_startup=false', '-c', 'disable_paste_burst=true', '-c', 'notice.hide_rate_limit_model_nudge=true'] : [],
+    }
+    try {
+      // A ref saved under an older naming (`golem-<uuid>`) comes back in the app's fixed session: only
+      // resumeId carries continuity, and the stray session, if still up, would break one-session-per-app.
+      if (this.ref && this.ref.session !== opts.session) {
+        await this.harness.kill(this.ref)
+        this.ref = { ...this.ref, session: opts.session, window: opts.window }
+      }
+      // A conversation saved before windows existed owned the whole session: pin it to its window first.
+      if (this.ref && !this.ref.window && opts.window) this.ref = (await this.harness.adoptWindow?.(this.ref, opts.window)) ?? this.ref
+      // Whoever starts in a window owns it. A previous occupant without a live Session (parked before the
+      // last restart, never resumed since) still holds `session:window` in tmux; it resumes through its own
+      // ref later, so clearing the window here loses nothing and spares spawn the "already exists" error.
+      if (!this.ref && opts.window) await this.harness.kill({ harness: this.agent, session: opts.session, cwd: this.cwd, window: opts.window })
+      this.ref = this.ref ? await this.harness.resume(this.ref, opts) : await this.harness.spawn(this.cwd, this.opts.instructions ?? builderInstructions(this.cwd), opts)
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      emit({ type: 'error', message: `${this.agent} session failed to start: ${message}` })
+      throw error
+    }
+    this.unsubscribe = this.harness.onTurnEnd(this.ref, (event) => {
+      if (event.session_id) this.ref!.resumeId = event.session_id // codex adopts its thread id from the first turn end
+      this.turnEnded?.()
+    }, opts)
+  }
+
+  async send(text: string): Promise<void> {
+    if (this.turnEnded) throw new Error(`${this.agent} is already handling a request`)
+    // ponytail: the next turn end is taken as this message's; a launch-prompt turn still running when
+    // the first message lands ends it early. The reply still arrives via `golem say` either way.
+    const done = new Promise<void>((resolve) => { this.turnEnded = resolve })
+    try { await this.harness.send(this.ref!, text) } catch (error) { this.turnEnded = undefined; throw error }
+    await done
+    this.turnEnded = undefined
+  }
+
+  async interrupt(): Promise<void> {
+    if (!this.ref) return
+    await this.harness.paneInput?.(this.ref, { key: 'C-c' })
+    this.turnEnded?.()
+    this.turnEnded = undefined
+  }
+
+  /** The server is stopping, the agent is not: the tmux session outlives it and is resumed on restart. */
+  async detach(): Promise<void> { this.unsubscribe?.() }
+
+  async shutdown(): Promise<void> {
+    this.unsubscribe?.()
+    this.turnEnded?.() // a send cut short by the kill still resolves; its reply will never come
+    this.turnEnded = undefined
+    if (this.ref) await this.harness.kill(this.ref)
+  }
+
+  harnessRef(): HarnessRef | undefined { return this.ref }
+
+  /** The harness's own slash commands (`/status`, `/compact`, …); `/reset` is the server's, not listed here. */
+  commands(): SlashCommand[] { return this.ref && this.harness.commands ? this.harness.commands(this.ref) : [] }
+
+  async runCommand(line: string): Promise<string> {
+    if (!this.ref || !this.harness.runCommand) throw new Error(`unknown command ${line.split(/\s+/)[0]}`)
+    return this.harness.runCommand(this.ref, line)
+  }
+
+  /** The live tmux screen, for the Terminal popup: undefined until the agent has been spawned or resumed. */
+  pane(): PaneAccess | undefined {
+    const { harness, ref } = this
+    if (!ref || !harness.openPane) return undefined
+    return {
+      open: (onFrame) => harness.openPane!(ref, { onFrame }),
+      snapshot: () => harness.paneSnapshot?.(ref) ?? Promise.resolve(''),
+      input: (input) => harness.paneInput?.(ref, input) ?? Promise.reject(new Error('harness cannot take pane input')),
+    }
+  }
+}

package/src/runtime/tool-names.ts

@@ -0,0 +1,19 @@
+/**
+ * Operation names as Anthropic tool names, which must match ^[a-zA-Z0-9_-]{1,128}$. A dot becomes
+ * `__`, which is only safe while no two listed operations encode alike (`a.b` and `a__b`, or `a._b`
+ * and `a_.b`), so a list that would is refused rather than sent.
+ */
+export function toolName(operation: string): string { return operation.replaceAll('.', '__') }
+
+/** The reason these operations cannot all be tools, or undefined when each maps to its own valid name. */
+export function toolNameProblem(operations: string[]): string | undefined {
+  const seen = new Map<string, string>()
+  for (const operation of operations) {
+    const name = toolName(operation)
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(name)) return `'${operation}' is not a valid tool name: use letters, digits, '_', '-' and '.', at most 128 characters once each '.' becomes '__'`
+    const other = seen.get(name)
+    if (other !== undefined && other !== operation) return `'${other}' and '${operation}' both become the tool name '${name}'`
+    seen.set(name, operation)
+  }
+  return undefined
+}

package/src/source-mode.ts

@@ -0,0 +1,56 @@
+import { resolve } from 'node:path'
+
+/**
+ * Source mode has to cover the app's own imports, not just the shell's: the app's node_modules
+ * still holds the published golem-kit and golem-ui. One table of module specifier to file,
+ * shared by the browser bundle, the app server bundle and the app typecheck. A trailing `/*`
+ * is a prefix mapping, spelled the way tsconfig `paths` spells it.
+ */
+export function sourceModules(): Record<string, string> {
+  const modules: Record<string, string> = {}
+  const kit = process.env.GOLEM_SOURCE && resolve(process.env.GOLEM_SOURCE)
+  // golem-kit's own exports map, answered from the checkout instead of node_modules.
+  if (kit) Object.assign(modules, {
+    'golem-kit/client': resolve(kit, 'src/client.ts'),
+    'golem-kit/server': resolve(kit, 'src/backend/index.ts'),
+    'golem-kit/operations': resolve(kit, 'src/operations.ts'),
+    'golem-kit/*': resolve(kit, '*'),
+  })
+  // golem-ui publishes only dist/, so source mode answers from src/ and no `pnpm build` is needed.
+  const ui = process.env.GOLEM_UI_SOURCE && resolve(process.env.GOLEM_UI_SOURCE)
+  if (ui) Object.assign(modules, {
+    'golem-ui': resolve(ui, 'src/index.ts'),
+    'golem-ui/styles.css': resolve(ui, 'src/styles.css'),
+  })
+  return modules
+}
+
+/** The same table as tsconfig `paths`, for a `tsc` run over the app's own files. */
+export function sourcePaths(): Record<string, string[]> {
+  return Object.fromEntries(Object.entries(sourceModules()).map(([specifier, file]) => [specifier, [file]]))
+}
+
+/** The same table as Vite `resolve.alias` entries; exact specifiers sort before `/*` prefixes. */
+export function sourceAliases(): { find: RegExp; replacement: string }[] {
+  return Object.entries(sourceModules())
+    .sort(([a], [b]) => Number(a.endsWith('/*')) - Number(b.endsWith('/*')))
+    .map(([specifier, file]) => specifier.endsWith('/*')
+      ? { find: new RegExp(`^${escape(specifier.slice(0, -1))}(.+)$`), replacement: file.replace(/\*$/, '$1') }
+      : { find: new RegExp(`^${escape(specifier)}$`), replacement: file })
+}
+
+/** The file a bare specifier resolves to in source mode, or undefined when it is not ours to answer. */
+export function resolveSourceModule(specifier: string): string | undefined {
+  const modules = sourceModules()
+  if (modules[specifier]) return modules[specifier]
+  for (const [pattern, file] of Object.entries(modules)) {
+    if (pattern.endsWith('/*') && specifier.startsWith(pattern.slice(0, -1))) {
+      return file.replace(/\*$/, specifier.slice(pattern.length - 1))
+    }
+  }
+  return undefined
+}
+
+function escape(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/vite.config.ts

@@ -4,6 +4,7 @@ import { resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { defineConfig, type UserConfig } from 'vite'
 import react from '@vitejs/plugin-react'
+import { sourceAliases } from './src/source-mode.ts'
 
 const frameworkRoot = import.meta.dirname
 
@@ -61,10 +62,7 @@ export default defineConfig(async (): Promise<UserConfig> => {
     plugins,
     resolve: {
       alias: [
-        ...(ui ? [
-          { find: /^golem-ui$/, replacement: resolve(ui.root, 'src/index.ts') },
-          { find: /^golem-ui\/styles\.css$/, replacement: resolve(ui.root, 'src/styles.css') },
-        ] : []),
+        ...sourceAliases(),
         { find: /^@golem\/app$/, replacement: resolve(appRoot, 'src/app.tsx') },
         { find: /^@golem\/config$/, replacement: resolve(appRoot, 'golem.config.ts') },
       ],