@cmodjs/core 0.2.3 → 1.0.0

package/src/runtime/metadata.ts

@@ -1,8 +1,10 @@
 import type { FileMatch, Metadata } from '../mod.js'
 import { formatOf, MetadataError, readMetadata, sidecarSuffix, writeMetadata, type MetadataFormat } from '../utils/metadata.js'
+import { ifMissing, isMissing } from '../utils/paths.js'
 import { messageOf } from '../utils/text.js'
 import { picomatch, resolve } from '../vendor.js'
 import type { Claude } from './claude.js'
+import type { Failure } from './toaster.js'
 
 export type Places = {
   readonly home: string | undefined
@@ -34,7 +36,19 @@ export function resolvedPath(path: string, places: Places): string {
   return path.startsWith('/') ? resolve(path) : resolve(places.projectRoot(), path)
 }
 
-export function createModFiles({ name, claude, places, checkWrite }: { readonly name: string; readonly claude: Claude; readonly places: Places; readonly checkWrite: (path: string) => Promise<void> }): ModFiles {
+export function createModFiles({
+  name,
+  claude,
+  places,
+  checkWrite,
+  report,
+}: {
+  readonly name: string
+  readonly claude: Claude
+  readonly places: Places
+  readonly checkWrite: (path: string) => Promise<void>
+  readonly report: (failure: Failure) => void
+}): ModFiles {
   const prefix = `${name}.`
   const cache = new Map<string, { readonly signature: string; readonly read: Read }>()
   const logged = new Set<string>()
@@ -48,12 +62,20 @@ export function createModFiles({ name, claude, places, checkWrite }: { readonly
     const extensionless = !realPath.slice(realPath.lastIndexOf('/') + 1).includes('.')
     const firstLine = extensionless ? (await claude.fs.read(realPath)).split('\n', 1)[0] : undefined
     const format = formatOf(realPath, firstLine)
-    const holder = format.kind === 'sidecar' ? `${realPath}${sidecarSuffix}` : realPath
-    const sidecar = format.kind === 'sidecar' ? await claude.fs.stat(holder).catch(() => undefined) : undefined
+    const holder = format.type === 'sidecar' ? `${realPath}${sidecarSuffix}` : realPath
+    const sidecar = format.type === 'sidecar' ? await claude.fs.stat(holder).catch(ifMissing(undefined)) : undefined
     return { realPath, format, holder, signature: `${stat.mtimeMs}:${stat.size}:${sidecar?.kind === 'file' ? `${sidecar.mtimeMs}:${sidecar.size}` : ''}` }
   }
 
-  const textOf = async (holder: string): Promise<string> => ((await claude.fs.stat(holder).catch(() => undefined))?.kind === 'file' ? claude.fs.read(holder) : '')
+  const textOf = async (holder: string): Promise<string> => ((await claude.fs.stat(holder).catch(ifMissing(undefined)))?.kind === 'file' ? claude.fs.read(holder) : '')
+
+  const skipped = <Value>(path: string, value: Value) => (error: unknown): Value => {
+    if (isMissing(error)) return value
+    const reason = `${name}: fs.find skipped ${path}: ${messageOf(error)}`
+    if (!logged.has(reason)) claude.ui.log(reason, { to: 'debug' })
+    logged.add(reason)
+    return value
+  }
 
   const readEntry = async (path: string): Promise<Read> => {
     const located = await locate(path)
@@ -67,7 +89,7 @@ export function createModFiles({ name, claude, places, checkWrite }: { readonly
       if (!(error instanceof MetadataError)) throw error
       const failure = `${located.holder} ${error.message}`
       read = { metadata: {}, error: failure }
-      if (!logged.has(failure)) claude.ui.log(`${name}: ${failure}`)
+      if (!logged.has(failure)) report({ id: `metadata:${located.holder}`, message: `Skips the metadata of ${located.holder}`, description: failure })
       logged.add(failure)
     }
     cache.set(path, { signature: located.signature, read })
@@ -77,21 +99,21 @@ export function createModFiles({ name, claude, places, checkWrite }: { readonly
   const matchesOf = async (pattern: string): Promise<string[]> => {
     const absolute = resolvedPath(pattern, places)
     const scanned = picomatch.scan(absolute)
-    if (!scanned.isGlob) return (await claude.fs.stat(absolute).catch(() => undefined))?.kind === 'file' ? [absolute] : []
+    if (!scanned.isGlob) return (await claude.fs.stat(absolute).catch(skipped(absolute, undefined)))?.kind === 'file' ? [absolute] : []
     const isMatch = picomatch(absolute, { dot: true })
     const entersSkipped = skippedFolders.filter((folder) => scanned.glob.split('/').includes(folder))
     const maxDepth = scanned.glob.includes('**') ? Number.POSITIVE_INFINITY : scanned.glob.split('/').length
     const found: string[] = []
     const visited = new Set<string>()
     const walk = async (folder: string, depth: number): Promise<void> => {
-      const real = (await claude.fs.stat(folder, { resolve: true }).catch(() => undefined))?.realPath ?? folder
+      const real = (await claude.fs.stat(folder, { resolve: true }).catch(skipped(folder, undefined)))?.realPath ?? folder
       if (visited.has(real)) return
       visited.add(real)
-      const entries = await claude.fs.list(folder).catch(() => [])
+      const entries = await claude.fs.list(folder).catch(skipped(folder, []))
       await Promise.all(
         entries.map(async (entry) => {
           const path = `${folder}/${entry.name}`
-          const kind = entry.isLink === true ? (await claude.fs.stat(path).catch(() => undefined))?.kind : entry.kind
+          const kind = entry.isLink === true ? (await claude.fs.stat(path).catch(skipped(path, undefined)))?.kind : entry.kind
           if (kind === 'file' && isMatch(path)) found.push(path)
           if (kind !== 'dir' || depth + 1 >= maxDepth) return
           if (skippedFolders.includes(entry.name) && !entersSkipped.includes(entry.name)) return
@@ -100,7 +122,7 @@ export function createModFiles({ name, claude, places, checkWrite }: { readonly
       )
     }
     const base = scanned.base === '' ? '/' : scanned.base
-    if ((await claude.fs.stat(base).catch(() => undefined))?.kind === 'dir') await walk(base, 0)
+    if ((await claude.fs.stat(base).catch(skipped(base, undefined)))?.kind === 'dir') await walk(base, 0)
     return found
   }
 
@@ -111,7 +133,7 @@ export function createModFiles({ name, claude, places, checkWrite }: { readonly
       const kept = paths.filter((path) => !(path.endsWith(sidecarSuffix) && paths.includes(path.slice(0, -sidecarSuffix.length))))
       return Promise.all(
         kept.map(async (path): Promise<FileMatch> => {
-          const read = await readEntry(path)
+          const read = await readEntry(path).catch((error: unknown): Read => ({ metadata: {}, error: `${path} ${messageOf(error)}` }))
           return { path, ...(read.name === undefined ? {} : { name: read.name }), metadata: own(read.metadata), ...(read.error === undefined ? {} : { error: read.error }) }
         }),
       )

package/src/runtime/options.ts

@@ -3,6 +3,7 @@ import { fitsOption, isUnset, type Option, type Options } from '../options.js'
 import { configFolders } from '../records.js'
 import { listed, messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
+import type { Failure } from './toaster.js'
 
 export class MissingOptions extends Error {
   readonly keys: readonly string[]
@@ -21,7 +22,21 @@ export type ModOptions = {
   load(root: string): Promise<void>
 }
 
-export function createOptions({ name, declared, fromClaude, claude, changed }: { readonly name: string; readonly declared: Options; readonly fromClaude: PluginOptions; readonly claude: Claude; readonly changed: () => void }): ModOptions {
+export function createOptions({
+  name,
+  declared,
+  fromClaude,
+  claude,
+  report,
+  changed,
+}: {
+  readonly name: string
+  readonly declared: Options
+  readonly fromClaude: PluginOptions
+  readonly claude: Claude
+  readonly report: (failure: Failure) => void
+  readonly changed: () => void
+}): ModOptions {
   let values: Readonly<Record<string, unknown>> = merged(declared, fromClaude, {}, new Set())
   let locked: Set<string> | undefined
   let loadedRoot: string | undefined
@@ -41,7 +56,7 @@ export function createOptions({ name, declared, fromClaude, claude, changed }: {
     if (project === undefined) return {}
     const path = `${project.folder}/options.json`
     if (!(await claude.fs.exists(path))) return {}
-    const ignore = (reason: string) => claude.ui.log(`${path} ${reason}`)
+    const ignore = (reason: string) => report({ id: `options:${path} ${reason}`, message: `Ignores part of ${path}`, description: `${path} ${reason}` })
     let file: unknown
     try {
       file = JSON.parse(await claude.fs.read(path))
@@ -57,7 +72,7 @@ export function createOptions({ name, declared, fromClaude, claude, changed }: {
     for (const [key, value] of Object.entries(file)) {
       const option = declared[key]
       if (option === undefined) ignore(`sets ${key}, which ${name} does not declare. ${Object.keys(declared).length === 0 ? 'Remove it.' : `Remove it, or use one of: ${Object.keys(declared).join(', ')}.`}`)
-      else if (option.kind === 'secret') ignore(`sets ${key}, a secret, and a project file is committed for everyone to read. Remove it, and set it in /config.`)
+      else if (option.type === 'secret') ignore(`sets ${key}, a secret, and a project file is committed for everyone to read. Remove it, and set it in /config.`)
       else {
         const misfit = fitsOption(option, value)
         if (misfit === undefined) kept[key] = value
@@ -98,5 +113,5 @@ function valueOf(key: string, option: Option, own: unknown, project: Readonly<Re
   if (locked.has(key)) return own
   if (Object.hasOwn(project, key)) return project[key]
   if (!isUnset(own) && fitsOption(option, own) === undefined) return Array.isArray(own) ? Object.freeze([...own]) : own
-  return option.default ?? (option.kind === 'list' ? Object.freeze([]) : option.kind === 'number' ? undefined : '')
+  return option.default ?? (option.type === 'list' ? Object.freeze([]) : option.type === 'number' ? undefined : '')
 }

package/src/runtime/programs.ts

@@ -1,8 +1,47 @@
+import type { HookStream, ProcessSpawnChunk, ProcessSpawnResult } from 'claude-code'
 import { storeFolder } from '../records.js'
+import { ifMissing } from '../utils/paths.js'
+import { formatExit } from '../utils/text.js'
 import type { Claude } from './claude.js'
 
 export type Programs = { readonly claude: Claude; refresh(): Promise<void> }
 
+export function lastLineOf(text: string): string | undefined {
+  const trimmed = text.trim()
+  return trimmed === '' ? undefined : trimmed.slice(trimmed.lastIndexOf('\n') + 1).trim()
+}
+
+export function cmodError(stderr: string, command: string | undefined): string {
+  const line = lastLineOf(stderr) ?? ''
+  const prefix = `cmod ${command}: `
+  return line.startsWith(prefix) ? line.slice(prefix.length) : line
+}
+
+export async function readLines(stream: HookStream<ProcessSpawnChunk, ProcessSpawnResult>, onLine: (text: string) => void): Promise<{ code: number | null; lastError: string }> {
+  let pending = ''
+  let lastError = ''
+  let piece = await stream.next()
+  while (piece.done !== true) {
+    if (piece.value.stream === 'stderr') {
+      lastError = lastLineOf(piece.value.text) ?? lastError
+    } else {
+      const lines = `${pending}${piece.value.text}`.split('\n')
+      pending = lines.pop() ?? ''
+      for (const text of lines) onLine(text)
+    }
+    piece = await stream.next()
+  }
+  if (pending !== '') onLine(pending)
+  return { code: piece.value.code, lastError }
+}
+
+export async function runCmod(claude: Claude, args: readonly string[], session: string): Promise<string> {
+  const lines: string[] = []
+  const { code, lastError } = await readLines(claude.process.spawn({ argv: ['cmod', ...args], env: { CLAUDE_CODE_SESSION_ID: session } }), (line) => void lines.push(line))
+  if (code !== 0) throw new Error(cmodError(lastError, args[0]) || `cmod ${args.slice(0, 2).join(' ')} ${formatExit(code, '')}.`)
+  return lines.join('\n')
+}
+
 export function locatingPrograms(claude: Claude): Programs {
   let folder: string | undefined
   let names: ReadonlySet<string> = new Set()
@@ -21,7 +60,7 @@ export function locatingPrograms(claude: Claude): Programs {
     async refresh() {
       const [home, dataHome] = await Promise.all([claude.env.home(), claude.env.dataHome()])
       const programs = `${storeFolder({ HOME: home, XDG_DATA_HOME: dataHome })}/programs`
-      names = new Set((await claude.fs.list(programs).catch(() => [])).map((entry) => entry.name))
+      names = new Set((await claude.fs.list(programs).catch(ifMissing([]))).map((entry) => entry.name))
       folder = programs
     },
   }

package/src/runtime/router.ts

@@ -1,4 +1,5 @@
 import type { Args, EventResult, Frozen } from 'claude-code'
+import type { Disposable } from '../mod.js'
 import type { RoutedEvent } from './hooks.js'
 
 export type RouterNext<N extends RoutedEvent> = (e: Frozen<Args<N>>) => Promise<EventResult<N>>
@@ -6,7 +7,7 @@ export type RouterNext<N extends RoutedEvent> = (e: Frozen<Args<N>>) => Promise<
 export type RoutedHook<N extends RoutedEvent> = (e: Frozen<Args<N>>, next: RouterNext<N>) => EventResult<N> | Promise<EventResult<N>>
 
 export type Router = {
-  add<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): void
+  add<N extends RoutedEvent>(event: N, hook: RoutedHook<N>): Disposable
   has(event: RoutedEvent): boolean
   dispatch<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>>
 }
@@ -18,9 +19,15 @@ export function createRouter(): Router {
 
   return {
     add(event, hook) {
-      const chain = hooks.get(event) ?? []
-      chain.push(hook as unknown as ErasedHook)
-      hooks.set(event, chain)
+      const erased = hook as unknown as ErasedHook
+      hooks.set(event, [...(hooks.get(event) ?? []), erased])
+      return {
+        dispose() {
+          const chain = (hooks.get(event) ?? []).filter((each) => each !== erased)
+          if (chain.length === 0) hooks.delete(event)
+          else hooks.set(event, chain)
+        },
+      }
     },
     has: (event) => hooks.has(event),
     dispatch<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>> {

package/src/runtime/sessions.ts

@@ -0,0 +1,242 @@
+import type { Disposable } from '../mod.js'
+import type { Context } from '../session/context/context.js'
+import { Message } from '../session/context/turn/message/message.js'
+import { Note } from '../session/context/turn/message/note.js'
+import { Person } from '../session/context/turn/message/sender.js'
+import type { Turn } from '../session/context/turn/turn.js'
+import type { ContextData, GoalData, SessionChange, SessionData, TaskData, TurnData } from '../session/conversation.js'
+import type { Goal } from '../session/goal/goal.js'
+import type { Task } from '../session/goal/task.js'
+import { Session, type SessionEvent, type SessionScope, type SessionSend, type Sessions, type TaskStartArgs, type Usage } from '../session/session.js'
+import { matches, sentMatcher, type SentMatcher } from '../utils/matcher.js'
+import type { Claude } from './claude.js'
+import { cmodPluginName } from './dependencies.js'
+
+export type Subscription = { readonly event: SessionEvent; readonly matcher: SentMatcher | undefined }
+
+export const conversationMethods = {
+  sessions: 'cmod:sessions',
+  search: 'cmod:search',
+  messages: 'cmod:messages',
+  turns: 'cmod:turns',
+  contexts: 'cmod:contexts',
+  tasks: 'cmod:tasks',
+  goal: 'cmod:goal',
+  updateGoal: 'cmod:updateGoal',
+  subscribe: 'cmod:subscribe',
+  send: 'cmod:send',
+  changed: 'cmod:changed',
+} as const
+
+export type SessionsClient = {
+  readonly sessions: Sessions
+  changed(session: string, change: SessionChange): void
+  /** An empty title keeps the title the session already has. */
+  follow(current: Omit<SessionData, 'isRunning' | 'lastAt'>): void
+}
+
+type Listening = { readonly event: SessionEvent; readonly matcher: unknown; readonly listener: (payload: never) => unknown }
+
+export async function usageOf(claude: Pick<Claude, 'session'>): Promise<Usage> {
+  const [model, usage] = await Promise.all([claude.session.model(), claude.session.usage()])
+  const { tokens, window, percent } = usage.context
+  return { model, context: { ...(tokens === undefined ? {} : { tokens }), window, ...(percent === undefined ? {} : { percent }) }, ...(usage.cost === undefined ? {} : { cost: { usd: usage.cost.usd } }) }
+}
+
+export function payloadOf(change: SessionChange): unknown {
+  if (change.type === Message) return change.message
+  if ('turn' in change) return change.turn
+  if ('context' in change) return change.context
+  if ('task' in change) return change.task
+  return change.goal
+}
+
+export function isHeardBy(event: SessionEvent, matcher: unknown, change: SessionChange): boolean {
+  const named = change.type === Message ? (event === Message || event === change.message.type) : event === change.type
+  return named && (matcher === undefined || matches(payloadOf(change), matcher))
+}
+
+export function createSessionsClient({ name, claude, report }: { readonly name: string; readonly claude: Claude; readonly report: (id: string, message: string, error: unknown) => void }): SessionsClient {
+  const call = <Answer>(method: string, input: unknown) => claude.cmod.call({ to: cmodPluginName, method, input }) as Promise<Answer>
+  const listening = new Map<string, Set<Listening>>()
+  const queued = new Set<string>()
+  let current: SessionData = { id: '', title: '', project: '', cwd: '', model: '', startedAt: '', lastAt: '', isRunning: true }
+
+  const subscribe = (session: string) => {
+    if (queued.has(session)) return
+    queued.add(session)
+    void Promise.resolve().then(async () => {
+      queued.delete(session)
+      const subscriptions: Subscription[] = [...(listening.get(session) ?? [])].map(({ event, matcher }) => ({ event, matcher: matcher === undefined ? undefined : sentMatcher(matcher) }))
+      await call(conversationMethods.subscribe, { session, subscriptions }).catch((error: unknown) => report(`sessions:${session}`, `Hears nothing from session ${session}`, error))
+    })
+  }
+
+  const isCurrent = (id: string) => id === current.id
+
+  const refuseElsewhere = (id: string, what: string): never => {
+    throw new Error(`${name}: ${what} works on the session this mod runs in, and ${id} runs elsewhere or has ended.`)
+  }
+
+  const turnOf = (session: string, data: TurnData): Turn => ({ ...data, messages: () => call<Message[]>(conversationMethods.messages, { session, turn: data.prompt.id }) })
+
+  const contextOf = (session: string, data: ContextData): Context => ({
+    ...data,
+    turns: async () => (await call<TurnData[]>(conversationMethods.turns, { session, context: data.number })).map((turn) => turnOf(session, turn)),
+  })
+
+  const taskOf = (session: string, data: TaskData): Task => ({
+    ...data,
+    messages: () => call<Message[]>(conversationMethods.messages, { session, task: data.id }),
+    tasks: async () => (await call<TaskData[]>(conversationMethods.tasks, { session, task: data.id })).map((task) => taskOf(session, task)),
+  })
+
+  const goalOf = (session: string, data: GoalData): Goal => ({
+    ...data,
+    update: async ({ text }) => {
+      if (text.trim() === '') throw new Error(`${name}: a goal needs text.`)
+      await call(conversationMethods.updateGoal, { session, text })
+    },
+    tasks: async () => (await call<TaskData[]>(conversationMethods.tasks, { session })).map((task) => taskOf(session, task)),
+  })
+
+  const payloadFor = (session: string, change: SessionChange): unknown => {
+    if (change.type === Message) return change.message
+    if ('turn' in change) return turnOf(session, change.turn)
+    if ('context' in change) return contextOf(session, change.context)
+    if ('task' in change) return taskOf(session, change.task)
+    return goalOf(session, change.goal)
+  }
+
+  const sessionOf = (read: () => SessionData) => {
+    const id = () => read().id
+    const session = {
+      get id() {
+        return read().id
+      },
+      get title() {
+        return read().title
+      },
+      get project() {
+        return read().project
+      },
+      get cwd() {
+        return read().cwd
+      },
+      get model() {
+        return read().model
+      },
+      get startedAt() {
+        return read().startedAt
+      },
+      get lastAt() {
+        return read().lastAt
+      },
+      get forkedFrom() {
+        return read().forkedFrom
+      },
+      get isRunning() {
+        return read().isRunning
+      },
+      async usage(): Promise<Usage> {
+        if (!isCurrent(id())) refuseElsewhere(id(), 'usage()')
+        return usageOf(claude)
+      },
+      on(event: SessionEvent, matcherOrListener: unknown, maybeListener?: (payload: never) => unknown): Disposable {
+        const listener = (maybeListener ?? matcherOrListener) as (payload: never) => unknown
+        const matcher = maybeListener === undefined ? undefined : matcherOrListener
+        const owner = id()
+        const heard: Listening = { event, matcher, listener }
+        const set = listening.get(owner) ?? new Set()
+        set.add(heard)
+        listening.set(owner, set)
+        subscribe(owner)
+        return {
+          dispose() {
+            if (!set.delete(heard)) return
+            if (set.size === 0) listening.delete(owner)
+            subscribe(owner)
+          },
+        }
+      },
+      async send({ type, text, as }: SessionSend) {
+        if (text.trim() === '') throw new Error(`${name}: send needs text.`)
+        if (isCurrent(id())) {
+          if (as === Session) throw new Error(`${name}: send with as: Session messages another session, and this one runs this mod.`)
+          if (type === Note) {
+            if (as !== undefined) throw new Error(`${name}: a Note is always from this mod, so it takes no as.`)
+            const added = await claude.session.append({ message: { type: 'user', content: [{ type: 'text', text }] } })
+            if (added.deny !== undefined) throw new Error(`${name}: Claude Code refused the note: ${added.deny}`)
+            return
+          }
+          const submitted = await claude.prompt.submit({ text, ...(as === Person ? { asUser: true } : {}) })
+          if ('drop' in submitted && typeof submitted.drop === 'string') throw new Error(`${name}: Claude Code dropped the prompt: ${submitted.drop}`)
+          return
+        }
+        if (!read().isRunning) throw new Error(`${name}: session ${id()} has ended, so it takes no messages.`)
+        if (as === Session) {
+          if (type === Note) throw new Error(`${name}: a message from this session reaches Claude as a Prompt, so send it with type: Prompt.`)
+          const sent = await claude.session.send({ to: { sessionId: id() }, text })
+          if (sent.isDelivered !== true) throw new Error(`${name}: Claude Code could not deliver the message to session ${id()}.`)
+          return
+        }
+        await call(conversationMethods.send, { session: id(), type, text, ...(as === undefined ? {} : { as }) })
+      },
+      async startTask(task: TaskStartArgs): Promise<Task> {
+        if (!isCurrent(id())) refuseElsewhere(id(), 'startTask()')
+        const started = await claude.agent.spawn({
+          prompt: task.prompt,
+          ...(task.name === undefined ? {} : { description: task.name, name: task.name }),
+          ...(task.agentType === undefined ? {} : { subagentType: task.agentType }),
+          ...(task.model === undefined ? {} : { model: task.model }),
+          ...(task.cwd === undefined ? {} : { cwd: task.cwd }),
+        })
+        if (started.deny !== undefined) throw new Error(`${name}: Claude Code refused the task: ${started.deny}`)
+        const data: TaskData = { id: started.agentId ?? '', title: task.name ?? '', agentType: task.agentType ?? 'general-purpose', model: started.model, openedBy: '', openedAt: new Date().toISOString() }
+        return taskOf(id(), data)
+      },
+      messages: (options: { readonly after?: string; readonly last?: number } = {}) => call<Message[]>(conversationMethods.messages, { session: id(), ...options }),
+      turns: async (options: { readonly last?: number } = {}) => (await call<TurnData[]>(conversationMethods.turns, { session: id(), ...options })).map((turn) => turnOf(id(), turn)),
+      contexts: async () => (await call<ContextData[]>(conversationMethods.contexts, { session: id() })).map((context) => contextOf(id(), context)),
+      goal: async () => goalOf(id(), await call<GoalData>(conversationMethods.goal, { session: id() })),
+    }
+    return session
+  }
+
+  const currentSession = sessionOf(() => current)
+
+  return {
+    sessions: {
+      get current() {
+        return currentSession as unknown as Sessions['current']
+      },
+      list: async (scope: SessionScope = {}) =>
+        (await call<SessionData[]>(conversationMethods.sessions, scope)).map((data) => {
+          if (data.id !== current.id) return sessionOf(() => data) as unknown as Sessions['current']
+          if (current.title === '') current = { ...current, title: data.title }
+          return currentSession as unknown as Sessions['current']
+        }),
+      search: (text, options = {}) => call<Message[]>(conversationMethods.search, { text, ...options, ...(options.before === undefined ? {} : { before: { session: options.before.session, id: options.before.id } }) }),
+    },
+    changed(session, change) {
+      for (const { event, matcher, listener } of listening.get(session) ?? []) {
+        if (!isHeardBy(event, matcher, change)) continue
+        void Promise.resolve()
+          .then(() => listener(payloadFor(session, change) as never))
+          .catch((error: unknown) => report(`session:${event}`, `The ${event} listener failed`, error))
+      }
+    },
+    follow(next) {
+      const moved = next.id !== current.id && current.id !== ''
+      const previous = current.id
+      current = { ...next, title: next.title || (next.id === current.id ? current.title : ''), isRunning: true, lastAt: new Date().toISOString() }
+      if (!moved) return
+      const kept = listening.get(previous)
+      if (kept === undefined) return
+      listening.delete(previous)
+      listening.set(current.id, kept)
+      subscribe(previous)
+      subscribe(current.id)
+    },
+  }
+}

package/src/runtime/state.ts

@@ -1,6 +1,6 @@
 import type { ClassicHookInputs } from 'claude-code'
-import { messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
+import type { Failure } from './toaster.js'
 
 type Lifetime = 'memory' | 'session' | 'project' | 'global'
 
@@ -14,7 +14,9 @@ export type StateOptions = {
   readonly session: string
   readonly root: string
   readonly claude: Claude
+  readonly report: (failure: Failure) => void
   readonly changed: () => void
+  readonly forkParent: () => Promise<string | undefined>
 }
 
 export type ModState<State extends object> = {
@@ -23,12 +25,12 @@ export type ModState<State extends object> = {
   changed(): void
   load(): Promise<void>
   moveTo(root: string): Promise<void>
-  switchSession(session: string, source: ClassicHookInputs['SessionStart']['source']): Promise<void>
+  switchSession(session: string, source: ClassicHookInputs['SessionStart']['source'], transcript: string): Promise<void>
 }
 
 const lifetimes: readonly Lifetime[] = ['memory', 'session', 'project', 'global']
 
-const keptPerValue = 20
+const keptProjects = 20
 
 const listeners = new WeakMap<object, Set<() => void>>()
 
@@ -38,7 +40,16 @@ export function onStateChange(state: object, listener: () => void): void {
   listeners.set(state, own)
 }
 
-export function createState<State extends object>({ name, initial, session, root, claude, changed: redraw }: StateOptions): ModState<State> {
+export async function sessionsWith(claude: Pick<Claude, 'store'>, name: string, key: string, value: unknown): Promise<string[]> {
+  const prefix = `${name}.${key}.sessions.`
+  const found: string[] = []
+  for (const stored of (await claude.store.keys()).filter((each) => each.startsWith(prefix))) {
+    if ((await claude.store.get(stored)) === value) found.push(stored.slice(prefix.length))
+  }
+  return found
+}
+
+export function createState<State extends object>({ name, initial, session, root, claude, report, changed: redraw, forkParent }: StateOptions): ModState<State> {
   const changed = () => {
     redraw()
     for (const listener of listeners.get(state) ?? []) listener()
@@ -51,7 +62,7 @@ export function createState<State extends object>({ name, initial, session, root
 
   const inTurn = <Result>(task: () => Promise<Result>): Promise<Result> => {
     const run = turn.then(task)
-    turn = run.catch(() => undefined)
+    turn = Promise.allSettled([run])
     return run
   }
 
@@ -62,11 +73,25 @@ export function createState<State extends object>({ name, initial, session, root
   const read = (lifetime: SavedLifetime, key: string, owner: string) => claude.store.get(storeKey(lifetime, key, owner))
 
   const write = async (lifetime: SavedLifetime, key: string, value: unknown, owner: string) => {
-    if (lifetime === 'global') return claude.store.set(storeKey(lifetime, key, owner), value)
+    if (lifetime !== 'project') return claude.store.set(storeKey(lifetime, key, owner), value)
     await claude.store.delete(storeKey(lifetime, key, owner))
     await claude.store.set(storeKey(lifetime, key, owner), value)
     const owners = (await claude.store.keys()).filter((stored) => stored.startsWith(ownersKey(lifetime, key)))
-    for (const oldest of owners.slice(0, -keptPerValue)) await claude.store.delete(oldest)
+    for (const oldest of owners.slice(0, -keptProjects)) await claude.store.delete(oldest)
+  }
+
+  const transcriptsKey = `${name}.$transcripts.`
+
+  const forgetEndedSessions = async (current: string) => {
+    const stored = await claude.store.keys()
+    for (const recorded of stored.filter((key) => key.startsWith(transcriptsKey))) {
+      const owner = recorded.slice(transcriptsKey.length)
+      if (owner === current) continue
+      const transcript = await claude.store.get(recorded)
+      if (typeof transcript === 'string' && (await claude.fs.exists(transcript))) continue
+      for (const value of stored.filter((key) => key.startsWith(`${name}.`) && key.endsWith(`.sessions.${owner}`))) await claude.store.delete(value)
+      await claude.store.delete(recorded)
+    }
   }
 
   const loadGroups = async (only: readonly Lifetime[], next: { readonly root: string; readonly session: string }) => {
@@ -80,13 +105,15 @@ export function createState<State extends object>({ name, initial, session, root
     changed()
   }
 
-  const copySession = async (nextSession: string) => {
+  const copySession = async (from: string, to: string) => {
     for (const key of Object.keys(declared.session)) {
-      const saved = await read('session', key, sessionId)
-      if (saved !== undefined) await write('session', key, saved, nextSession)
+      const saved = await read('session', key, from)
+      if (saved !== undefined) await write('session', key, saved, to)
     }
   }
 
+  const hasSaved = async (owner: string) => (await claude.store.keys()).some((key) => key.startsWith(`${name}.`) && key.endsWith(`.sessions.${owner}`))
+
   const group = (lifetime: Lifetime) =>
     new Proxy(current[lifetime], {
       set(target, key, value) {
@@ -97,7 +124,7 @@ export function createState<State extends object>({ name, initial, session, root
         if (lifetime !== 'memory') {
           const owner = lifetime === 'project' ? projectRoot : sessionId
           inTurn(() => write(lifetime, key, value, owner)).catch((error: unknown) => {
-            claude.ui.log(`${name} could not keep state.${lifetime}.${key}: ${messageOf(error)}. Keep only JSON data in mod.state.`)
+            report({ id: `state:${lifetime}.${key}`, message: `Could not keep state.${lifetime}.${key}. Keep only JSON data in mod.state`, error })
           })
         }
         changed()
@@ -113,12 +140,21 @@ export function createState<State extends object>({ name, initial, session, root
       return projectRoot
     },
     changed,
-    load: () => inTurn(() => loadGroups(lifetimes, { root: projectRoot, session: sessionId })),
+    load: () =>
+      inTurn(async () => {
+        if (Object.keys(declared.session).length > 0 && !(await hasSaved(sessionId))) {
+          const parent = await forkParent()
+          if (parent !== undefined) await copySession(parent, sessionId)
+        }
+        return loadGroups(lifetimes, { root: projectRoot, session: sessionId })
+      }),
     moveTo: (nextRoot) => inTurn(async () => (nextRoot === projectRoot ? undefined : loadGroups(['project'], { root: nextRoot, session: sessionId }))),
-    switchSession: (nextSession, source) =>
+    switchSession: (nextSession, source, transcript) =>
       inTurn(async () => {
+        await claude.store.set(`${transcriptsKey}${nextSession}`, transcript)
+        await forgetEndedSessions(nextSession)
         if (nextSession === sessionId) return
-        if (source === 'fork') await copySession(nextSession)
+        if (source === 'fork') await copySession(sessionId, nextSession)
         return loadGroups(['memory', 'session'], { root: projectRoot, session: nextSession })
       }),
   }