@cmodjs/core 3.1.0 → 4.0.1

package/src/runtime/announce.ts

@@ -1,9 +1,8 @@
-import { changelogPage, isObject, marketplaceOf, permissionWords } from '../records.js'
+import { isObject, marketplaceOf, permissionWords } from '../records.js'
 import { changeLines, changelogSections, unreleased } from '../utils/changelog.js'
 import { ifMissing } from '../utils/paths.js'
 import { listed } from '../utils/text.js'
 import type { Claude } from './claude.js'
-import { cmodPluginName } from './dependencies.js'
 import type { Plugin } from './lifecycle.js'
 
 export type Announced = { readonly version: string; readonly added: readonly string[] }
@@ -20,20 +19,20 @@ export function announcedOf(saved: unknown): Announced | undefined {
   return { version: saved['version'], added: Array.isArray(saved['added']) ? saved['added'].map(String) : [] }
 }
 
-export async function announcementOf(claude: Claude, plugin: Plugin, granted: ReadonlySet<string>, added: readonly string[], previous: Announced | undefined): Promise<Announcement> {
+export async function announcementOf(claude: Claude, plugin: Plugin, granted: ReadonlySet<string>, added: readonly string[], previous: Announced | undefined, openSettings: (tab?: 'changelog') => Promise<void>): Promise<Announcement> {
   const read = (path: string) => claude.fs.read(`${plugin.root}/${path}`).catch(ifMissing(undefined))
   const manifest = jsonOf(await read('.claude-plugin/plugin.json'))
   const field = (key: string) => (isObject(manifest) && typeof manifest[key] === 'string' ? manifest[key] : undefined)
-  const open = (page?: string) => () => claude.cmod.call({ to: cmodPluginName, method: 'openSettings', input: { mod: plugin.name, ...(page === undefined ? {} : { page }) } })
+  const open = (tab?: 'changelog') => () => openSettings(tab)
   if (previous === undefined) {
-    const { program, keys } = plugin.steps
+    const { program, hotkeys } = plugin.steps
     const rules = (await claude.fs.list(`${plugin.root}/rules`).catch(ifMissing([]))).filter((entry) => entry.kind === 'file' && entry.name.endsWith('.md')).map((entry) => entry.name.slice(0, -'.md'.length)).toSorted()
     const lines = [
       field('description'),
       added.length > 0 ? `Adds ${listed(added)}.` : undefined,
       rules.length > 0 ? `Adds ${rules.length} ${rules.length === 1 ? 'rule' : 'rules'}: ${listed(rules)}.` : undefined,
       program === undefined ? undefined : `Installed the ${program} program.`,
-      ...Object.entries(keys ?? {}).map(([key, command]) => `Binds ${key} to /${command}.`),
+      ...Object.values(hotkeys ?? {}).map(({ title, default: combo }) => `Binds ${combo} to ${title}.`),
       ...[...granted].map((item) => `${permissionWords(item)}.`),
     ]
     return { message: 'Installed', ...described(lines), action: { label: 'Settings', onClick: open() } }
@@ -57,7 +56,7 @@ export async function announcementOf(claude: Claude, plugin: Plugin, granted: Re
   return {
     message: `Updated to ${version}`,
     ...described(lines),
-    ...(sections.length > 0 ? { action: { label: 'Changelog', onClick: open(changelogPage) } } : {}),
+    ...(sections.length > 0 ? { action: { label: 'Changelog', onClick: open('changelog') } } : {}),
   }
 }
 

package/src/runtime/before.ts

@@ -1,5 +1,5 @@
 import type { Args, Frozen } from 'claude-code'
-import type { Disposable } from '../mod.js'
+import type { Subscription } from '../utils/subscription.js'
 import { ContextEnd } from '../session/context/context.js'
 import { InstructionFile, isRulePath } from '../session/context/turn/message/instruction-file.js'
 import { instructionPathOf, Message, messagesOf, noFiles, rowOfAppend, withTexts, type Unplaced } from '../session/context/turn/message/message.js'
@@ -55,7 +55,7 @@ export function relayOf(e: Frozen<Args<'session.receive'>>): string | undefined
   return isFromCmod ? relayTag.exec(e.text)?.[1] : undefined
 }
 
-export function installBefore({ claude, router, hooks }: { readonly claude: Claude; readonly router: Router; readonly hooks: BeforeHooks }): Disposable {
+export function installBefore({ claude, router, hooks }: { readonly claude: Claude; readonly router: Router; readonly hooks: BeforeHooks }): Subscription {
   const { place, wants, fold } = hooks
   const now = () => new Date().toISOString()
   const asked = async (event: BeforeEvent, change: SessionChange, decide: Decide = fold()) => (await decide(event, change)) ?? {}
@@ -82,7 +82,7 @@ export function installBefore({ claude, router, hooks }: { readonly claude: Clau
     const failed = answer.isError === true && !isFailure ? { block: answer.note === undefined ? `${name} failed.` : untagged(answer.note) } : {}
     return { ...withNote(below, answer.isError === true ? undefined : answer.note), ...rewritten, ...failed }
   }
-  const added: Disposable[] = [
+  const added: Subscription[] = [
     router.add('prompt.submit', async (e, next) => {
       if (!(await wants(Prompt))) return next(e)
       const where = await place()
@@ -215,7 +215,7 @@ export function installBefore({ claude, router, hooks }: { readonly claude: Clau
       return answer.refuse === undefined ? next(e) : { skip: answer.refuse }
     }),
   ]
-  return { dispose: () => added.forEach((each) => each.dispose()) }
+  return { remove: () => added.forEach((each) => each.remove()) }
 }
 
 export function closingContext(where: Place, task: RunningTask | undefined, closedAt: string): ContextData {

package/src/runtime/claude.ts

@@ -46,7 +46,6 @@ import type {
 export type Claude = {
   readonly plugin: { readonly name: string; readonly root: string }
   readonly ui: {
-    status(text: string | undefined): void
     log(text: string, options?: UiLogOptions): void
     notice(toolUseId: string, text: string | undefined): void
     invalidate(event: InvalidatableEventName): void

package/src/runtime/conversations.ts

@@ -1,11 +1,12 @@
 import type { Args, EventResult, Frozen } from 'claude-code'
-import { consentPath, dataFolder, isObject, parseConsent } from '../records.js'
+import { consentPath, coreVersion, dataFolder, grantFix, isObject, parseConsent } from '../records.js'
 import { Message, rowOfAppend, type Row } from '../session/context/turn/message/message.js'
 import { modNote, Note } from '../session/context/turn/message/note.js'
 import { Person } from '../session/context/turn/message/sender.js'
 import { createConversation, emptyConversation, type Conversation, type ConversationState, type ContextData, type SessionChange, type SessionData, type TaskData, type TurnData, type TurnEnding } from '../session/conversation.js'
 import { Session, UsageChange, type BeforeEvent, type Surface, type SessionSend, type TaskStartArgs, type ToolCallArgs } from '../session/session.js'
 import { GoalChange } from '../session/goal/goal.js'
+import { TurnEnd, TurnStart } from '../session/context/turn/turn.js'
 import { receivedMatcher } from '../utils/matcher.js'
 import { ifMissing } from '../utils/paths.js'
 import { formatExit, messageOf } from '../utils/text.js'
@@ -15,13 +16,13 @@ import { cmodPluginName } from './dependencies.js'
 import { readLines, runCmod } from './programs.js'
 import type { RoutedHook, Router } from './router.js'
 import { PassedTimeout } from './deadline.js'
-import { actPermission, conversationMethods, everySession, isAct, isHeardBy, isInScope, resultOf, spawnTask, usageOf, type Act, type Subscription } from './sessions.js'
+import { actPermission, conversationMethods, everySession, isAct, isHeardBy, isInScope, resultOf, spawnTask, usageOf, type Act, type Listened } from './sessions.js'
 
 type Request = Readonly<Record<string, unknown>>
 
-type Heard = { readonly event: Subscription['event']; readonly matcher: unknown }
+type Heard = { readonly event: Listened['event']; readonly matcher: unknown }
 
-type Watch = { readonly mod: string; readonly target: string; readonly project: string; readonly events: readonly string[]; readonly refusing?: readonly Subscription[] }
+type Watch = { readonly mod: string; readonly target: string; readonly project: string; readonly events: readonly string[]; readonly refusing?: readonly Listened[] }
 
 type Watcher = Watch & { readonly from: string }
 
@@ -31,6 +32,10 @@ type Question =
 
 type Relay = (Question & { readonly id: string; readonly from: string }) | { readonly kind: 'answer'; readonly id: string; readonly value?: unknown; readonly deny?: string } | { readonly kind: 'watch' } | { readonly kind: 'goal'; readonly task?: string; readonly text: string }
 
+const relayKinds: ReadonlySet<unknown> = new Set(['act', 'before', 'answer', 'watch', 'goal'] satisfies Relay['kind'][])
+
+const isRelay = (value: unknown): value is Relay => isObject(value) && relayKinds.has(value['kind'])
+
 type Asked = { resolve(value: unknown): void; reject(error: Error): void }
 
 
@@ -46,9 +51,28 @@ const livenessMs = 5000
 export type Conversations = {
   answer(e: Frozen<Args<'cmod.call'>> & { readonly caller?: string }): Promise<EventResult<'cmod.call'> | undefined>
   moved(): void
+  turnClosedBy(rowId: string): TurnData | undefined
 }
 
-export function serveConversations({ claude, router, store, project, report }: { readonly claude: Claude; readonly router: Router; readonly store: string; readonly project: () => string; readonly report: (id: string, message: string, error: unknown) => void }): Conversations {
+const keptClosings = 200
+
+const keptMessages = 200
+
+export function serveConversations({
+  claude,
+  router,
+  store,
+  project,
+  report,
+  clear,
+}: {
+  readonly claude: Claude
+  readonly router: Router
+  readonly store: string
+  readonly project: () => string
+  readonly report: (id: string, message: string, error: unknown) => void
+  readonly clear: (id: string) => void
+}): Conversations {
   const folder = dataFolder(store, cmodPluginName)
   const goals = `${folder}/goals`
   const watches = `${folder}/before`
@@ -98,16 +122,23 @@ export function serveConversations({ claude, router, store, project, report }: {
 
   const isRunning = async (id: string) => (await json<SessionData[]>(['history', 'sessions', '--running', '--all'])).some((each) => each.id === id)
 
+  let lastTurn: TurnData | undefined
+  const closings = new Map<string, TurnData>()
   const dispatch = (to: string, changes: readonly SessionChange[], isInProject = true) => {
     for (const change of changes) {
+      if (to === session && (change.type === TurnStart || change.type === TurnEnd) && change.turn.prompt.task === undefined) lastTurn = change.turn
       if (change.type === Message && !liveIds.has(change.message.id) && to === session) {
         live.push(change.message)
         liveIds.add(change.message.id)
+        if (live.length > keptMessages) liveIds.delete(live.shift()?.id ?? '')
       }
       for (const [mod, sessions] of heard) {
         const subscriptions = [...(sessions.get(to) ?? []), ...(isInProject ? (sessions.get(everySession) ?? []) : [])]
         if (!subscriptions.some(({ event, matcher }) => isHeardBy(event, matcher, change))) continue
-        void claude.cmod.call({ to: mod, method: conversationMethods.changed, input: { session: to, change, isInProject } }).catch((error: unknown) => report(`changed:${mod}`, `Could not tell ${mod} about session ${to}`, error))
+        void claude.cmod.call({ to: mod, method: conversationMethods.changed, input: { session: to, change, isInProject } }).then(
+          () => clear(`changed:${mod}`),
+          (error: unknown) => report(`changed:${mod}`, `Could not tell ${mod} about session ${to}`, error),
+        )
       }
     }
   }
@@ -239,7 +270,7 @@ export function serveConversations({ claude, router, store, project, report }: {
   }
 
   const askHere = async (mod: string, event: BeforeEvent, change: SessionChange, from = session, isInProject = true) => {
-    if (from !== session && !(await isGranted(mod, 'conversation'))) throw new Error(`${mod} needs the conversation permission to change what happens in another session. Turn it on in /mods ${mod}.`)
+    if (from !== session && !(await isGranted(mod, 'conversation'))) throw new Error(`${mod} needs the conversation permission to change what happens in another session. ${grantFix}`)
     return claude.cmod.call({ to: mod, method: conversationMethods.before, input: { session: from, event, change, isInProject } })
   }
 
@@ -333,6 +364,9 @@ export function serveConversations({ claude, router, store, project, report }: {
       return
     }
     dispatch(session, conversation.add(row, task))
+    if (task !== undefined || row.type !== 'system' || row.name !== 'turn_duration' || lastTurn === undefined) return
+    closings.set(row.id, lastTurn)
+    if (closings.size > keptClosings) closings.delete(closings.keys().next().value as string)
   }
 
   router.add('classic.SessionStart', async (e, next) => {
@@ -386,11 +420,18 @@ export function serveConversations({ claude, router, store, project, report }: {
   router.add('session.receive', async (e, next) => {
     const sent = relayOf(e)
     if (sent === undefined) return next(e)
-    const relay = JSON.parse(sent) as Relay
-    claude.clock.after(0, () => void received(relay).catch((error: unknown) => report('relay', 'Could not answer another session', error)))
+    const relay = JSON.parse(sent) as unknown
+    claude.clock.after(0, () => void (isRelay(relay) ? received(relay) : refuse(relay)).catch((error: unknown) => report('relay', 'Could not answer another session', error)))
     return { consumed: 'cmod relay' }
   })
 
+  const unknownTo = async (what: string) => new Error(`Session ${await claude.session.id()} runs cmod ${coreVersion}, which has no ${what}.`)
+
+  const refuse = async (relay: unknown) => {
+    if (!isObject(relay) || typeof relay['id'] !== 'string' || typeof relay['from'] !== 'string') return
+    await post(relay['from'], { kind: 'answer', id: relay['id'], deny: (await unknownTo(`"${String(relay['kind'])}" relay`)).message })
+  }
+
   const received = async (relay: Relay) => {
     if (relay.kind === 'answer') {
       const waiting = asked.get(relay.id)
@@ -411,13 +452,13 @@ export function serveConversations({ claude, router, store, project, report }: {
         await post(relay.from, { kind: 'answer', id: relay.id, deny: messageOf(error) })
       }
     }
-    if (relay.kind === 'act') return answered(() => perform(relay.caller, relay.action, relay.input, relay.task))
+    if (relay.kind === 'act') return answered(async () => (isAct(relay.action) ? perform(relay.caller, relay.action, relay.input, relay.task) : Promise.reject(await unknownTo(`"${String(relay.action)}" action`))))
     return answered(() => askHere(relay.mod, relay.event, relay.change, relay.from, relay.project === project()))
   }
 
   const checkAct = async (caller: string, action: Act, input: unknown) => {
     const needed = actPermission(action, input)
-    if (needed !== undefined && !(await isGranted(caller, needed))) throw new Error(`${caller} needs the ${needed} permission for ${action}. Turn it on in /mods ${caller}.`)
+    if (needed !== undefined && !(await isGranted(caller, needed))) throw new Error(`${caller} needs the ${needed} permission for ${action}. ${grantFix}`)
   }
 
   const perform = async (caller: string, action: Act, input: unknown, task: string | undefined): Promise<unknown> => {
@@ -509,6 +550,8 @@ export function serveConversations({ claude, router, store, project, report }: {
 
   const lastOf = <Item>(items: readonly Item[], last: unknown): Item[] => (typeof last === 'number' ? items.slice(-last) : [...items])
 
+  const isHeld = (kept: readonly unknown[], last: unknown) => typeof last === 'number' && kept.length >= last
+
   const methods: Readonly<Record<string, (request: Request, caller: string | undefined) => Promise<unknown>>> = {
     async [conversationMethods.sessions](request) {
       const found = await json<SessionData[]>(['history', 'sessions', ...scopeArgs(request), ...(request['running'] === true ? ['--running'] : [])])
@@ -522,21 +565,23 @@ export function serveConversations({ claude, router, store, project, report }: {
     async [conversationMethods.messages](request) {
       const id = String(request['session'])
       const filters = [...textArg('--turn', request['turn']), ...textArg('--task', request['task']), ...textArg('--after', request['after'])]
-      const saved = await json<Message[]>(['history', 'messages', id, ...filters, ...countArg('--last', request['last'])])
-      if (id !== session) return saved
+      const saved = () => json<Message[]>(['history', 'messages', id, ...filters, ...countArg('--last', request['last'])])
+      if (id !== session) return saved()
       await starting
       const fits = (message: Message) => (request['turn'] === undefined || message.turn === request['turn']) && message.task === request['task']
       const after = typeof request['after'] === 'string' ? live.findIndex((message) => message.id === request['after']) : -1
       const kept = live.slice(after + 1).filter(fits)
-      return lastOf(merged(saved, kept, (message) => message.id), request['last'])
+      if (after >= 0 || isHeld(kept, request['last'])) return lastOf(kept, request['last'])
+      return lastOf(merged(await saved(), kept, (message) => message.id), request['last'])
     },
     async [conversationMethods.turns](request) {
       const id = String(request['session'])
-      const saved = await json<TurnData[]>(['history', 'turns', id, ...textArg('--task', request['task']), ...countArg('--context', request['context']), ...countArg('--last', request['last'])])
-      if (id !== session) return saved
+      const saved = () => json<TurnData[]>(['history', 'turns', id, ...textArg('--task', request['task']), ...countArg('--context', request['context']), ...countArg('--last', request['last'])])
+      if (id !== session) return saved()
       await starting
       const kept = liveTurns(request['task']).filter((turn) => request['context'] === undefined || turn.context === request['context'])
-      return lastOf(merged(saved, kept, (turn) => turn.prompt.id), request['last'])
+      if (isHeld(kept, request['last'])) return lastOf(kept, request['last'])
+      return lastOf(merged(await saved(), kept, (turn) => turn.prompt.id), request['last'])
     },
     async [conversationMethods.contexts](request) {
       const id = String(request['session'])
@@ -583,7 +628,7 @@ export function serveConversations({ claude, router, store, project, report }: {
     async [conversationMethods.subscribe](request, caller) {
       if (caller === undefined) throw new Error('cmod hears no caller for this subscription.')
       const id = String(request['session'])
-      const list = Array.isArray(request['subscriptions']) ? (request['subscriptions'] as readonly Subscription[]) : []
+      const list = Array.isArray(request['subscriptions']) ? (request['subscriptions'] as readonly Listened[]) : []
       const sessions = heard.get(caller) ?? new Map<string, readonly Heard[]>()
       sessions.set(id, list.map(({ event, matcher }) => ({ event, matcher: matcher === undefined ? undefined : receivedMatcher(matcher) })))
       heard.set(caller, sessions)
@@ -593,7 +638,7 @@ export function serveConversations({ claude, router, store, project, report }: {
     async [conversationMethods.watchBefore](request, caller) {
       if (caller === undefined) throw new Error('cmod hears no caller for this before listener.')
       const target = String(request['session'])
-      const list = Array.isArray(request['subscriptions']) ? (request['subscriptions'] as readonly Subscription[]) : []
+      const list = Array.isArray(request['subscriptions']) ? (request['subscriptions'] as readonly Listened[]) : []
       ownWatches.set(`${caller}\n${target}`, { mod: caller, target, project: project(), events: [...new Set(list.map(({ event }) => event))], refusing: list.filter((each) => each.onFailure === 'refuse') })
       await publishWatches()
       return null
@@ -610,6 +655,7 @@ export function serveConversations({ claude, router, store, project, report }: {
   }
 
   return {
+    turnClosedBy: (rowId) => closings.get(rowId),
     moved() {
       for (const [key, watch] of ownWatches) ownWatches.set(key, { ...watch, project: project() })
       void publishWatches().catch((error: unknown) => report('before', 'Kept its before listeners on the project from before', error))
@@ -621,7 +667,7 @@ export function serveConversations({ claude, router, store, project, report }: {
       if (method === undefined) return undefined
       const input = isObject(e.input) ? e.input : {}
       const isDropping = (e.method === conversationMethods.subscribe || e.method === conversationMethods.watchBefore) && Array.isArray(input['subscriptions']) && input['subscriptions'].length === 0
-      if (e.method !== conversationMethods.act && !isDropping && input['session'] !== (await claude.session.id()) && !(await isGranted(e.caller, 'conversation'))) return { deny: `${e.caller ?? 'A mod'} reads your conversations without your grant. Turn it on in /mods ${e.caller ?? ''}.`.trim() }
+      if (e.method !== conversationMethods.act && !isDropping && input['session'] !== (await claude.session.id()) && !(await isGranted(e.caller, 'conversation'))) return { deny: `${e.caller ?? 'A mod'} reads your conversations without your grant. ${grantFix}` }
       try {
         return { value: await method(input, e.caller) }
       } catch (error) {

package/src/runtime/dependencies.ts

@@ -1,4 +1,5 @@
 import type { Args, CmodDependencies, EventResult, Frozen } from 'claude-code'
+import { installFix } from '../records.js'
 import { messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
 import type { Router } from './router.js'
@@ -46,5 +47,5 @@ export function answeringOwnCalls(claude: Claude, router: Router): Claude {
 }
 
 export function notInstalled(name: string): string {
-  return `${name} is not installed. Add it with /plugin.`
+  return `${name} is not installed. ${installFix}`
 }

package/src/runtime/engine.ts

@@ -1,7 +1,9 @@
 import type { Claude } from './claude.js'
+import type { Pages } from './pages.js'
 import type { Router } from './router.js'
 import type { Failure } from './toaster.js'
 import type { ToolCalls } from './tool-calls.js'
+import type { Widgets } from './widgets.js'
 
 export type Engine = {
   readonly claude: Claude
@@ -9,6 +11,9 @@ export type Engine = {
   readonly toolCalls: ToolCalls
   readonly report: (failure: Failure) => void
   readonly hasPermissionCheck: () => boolean
+  readonly answerInput: <Answer>(run: () => Promise<Answer>, passOn: () => Promise<unknown>) => Promise<Answer>
+  readonly widgets?: Widgets
+  readonly pages?: Pages
 }
 
 const engines = new WeakMap<object, Engine>()

package/src/runtime/grants.ts

@@ -1,4 +1,4 @@
-import { isObject, isSettingCovered, permissionWords, settingPaths } from '../records.js'
+import { grantFix, isObject, isSettingCovered, permissionWords, settingPaths } from '../records.js'
 import { relativePath } from '../utils/paths.js'
 import type { Claude } from './claude.js'
 import { cmodPluginName } from './dependencies.js'
@@ -198,7 +198,7 @@ function writeItem(grants: Grants, path: string): string | undefined {
 
 export function refusal(grants: Pick<Grants, 'name' | 'declared' | 'home'>, call: string, item: string): string {
   const { name } = grants
-  if (isCovered(new Set(grants.declared), item, grants.home)) return `${name} calls ${call} without your grant to "${permissionWords(item)}". Turn it on in /mods ${name}.`
+  if (isCovered(new Set(grants.declared), item, grants.home)) return `${name} calls ${call} without your grant to "${permissionWords(item)}". ${grantFix}`
   return `${name} calls ${call}, which needs ${declaration(item, grants.home)} in package.json "cmod".`
 }
 

package/src/runtime/hooks.ts

@@ -22,6 +22,7 @@ export type RoutedEvent =
   | 'prompt.context'
   | 'prompt.attachment'
   | 'command.run'
+  | 'command.describe'
   | 'session.measure'
   | 'skill.prompt'
   | 'ui.render'

package/src/runtime/hotkeys.ts

@@ -0,0 +1,80 @@
+import type { Hotkey, Hotkeys } from '../hotkeys.js'
+import { boundCombos, hotkeyCommand } from '../records.js'
+import { ifMissing } from '../utils/paths.js'
+import { messageOf } from '../utils/text.js'
+import type { Claude } from './claude.js'
+import type { Router } from './router.js'
+import type { Failure } from './toaster.js'
+
+export async function readCombos(claude: Claude, configRoot: string | undefined): Promise<Map<string, string>> {
+  if (configRoot === undefined) return new Map()
+  const text = await claude.fs.read(`${configRoot}/keybindings.json`).catch(ifMissing('{}'))
+  try {
+    return boundCombos(JSON.parse(text))
+  } catch (error) {
+    claude.ui.log(`${configRoot}/keybindings.json is not JSON, so cmod reads no combos from it: ${messageOf(error)}`, { to: 'debug' })
+    return new Map()
+  }
+}
+
+export async function createHotkeys({
+  name,
+  declared,
+  configRoot,
+  claude,
+  router,
+  answerInput,
+  report,
+}: {
+  readonly name: string
+  readonly declared: Hotkeys
+  readonly configRoot: string | undefined
+  readonly claude: Claude
+  readonly router: Router
+  readonly answerInput: <Answer>(run: () => Promise<Answer>, passOn: () => Promise<unknown>) => Promise<Answer>
+  readonly report: (failure: Failure) => void
+}): Promise<Readonly<Record<string, Hotkey>>> {
+  const entries = Object.entries(declared)
+  if (entries.length === 0) return {}
+  const combos = await readCombos(claude, configRoot)
+  const listeners = new Map<string, Set<() => unknown>>()
+  const commands = new Map<string, string>()
+  for (const [hotkey, { title }] of entries) {
+    listeners.set(hotkey, new Set())
+    claude.command.register({ name: hotkeyCommand(name, hotkey), description: title, immediate: true }).then(
+      ({ command }) => void commands.set(command, hotkey),
+      (error: unknown) => report({ id: `hotkey:${hotkey}`, message: `The ${title} hotkey is not added`, error }),
+    )
+  }
+  router.add('command.describe', async (e, next) => {
+    const described = await next(e)
+    return commands.has(e.command) ? { ...described, isHidden: true } : described
+  })
+  router.add('command.run', async (e, next) => {
+    const hotkey = commands.get(e.command)
+    if (hotkey === undefined) return next(e)
+    return answerInput(async () => {
+      for (const listener of listeners.get(hotkey) ?? []) {
+        try {
+          await listener()
+        } catch (error) {
+          report({ id: `hotkey:${hotkey}`, message: `The ${declared[hotkey]?.title ?? hotkey} hotkey failed`, error })
+        }
+      }
+      return {}
+    }, () => next(e))
+  })
+  return Object.fromEntries(
+    entries.map(([hotkey, { title }]): [string, Hotkey] => [
+      hotkey,
+      {
+        title,
+        combo: combos.get(hotkeyCommand(name, hotkey)) as Hotkey['combo'],
+        onPress(listener) {
+          listeners.get(hotkey)?.add(listener)
+          return { remove: () => void listeners.get(hotkey)?.delete(listener) }
+        },
+      },
+    ]),
+  )
+}

package/src/runtime/installer.ts

@@ -2,7 +2,7 @@ import type { Args, Frozen, RenderElement, RenderPropsOf } from 'claude-code'
 import type { Step } from '../installer.js'
 import type { Mod } from '../mod.js'
 import type { Option } from '../options.js'
-import { permissionWords } from '../records.js'
+import { permissionWords, secretFix } from '../records.js'
 import { Box, Button, drawWith, Input, Text } from '../ui/elements.js'
 import { messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
@@ -12,7 +12,7 @@ export const installerPaneOf = (name: string): string => `installer-${name.repla
 export type Consent = {
   readonly install: string
   readonly uninstall: string
-  readonly keys: string
+  readonly hotkeys: string
   readonly permissions: readonly string[]
   readonly updates?: string | undefined
 }
@@ -32,25 +32,32 @@ export type Installer = {
   close(): Promise<void>
 }
 
-export function createInstaller(name: string, claude: () => Claude): Installer {
+export function createInstaller(name: string, claude: () => Claude, waiting: { show(open: () => Promise<void>): void; hide(): void }): Installer {
   const paneId = installerPaneOf(name)
   let page: Page | undefined
   let isOpen = false
 
+  const open = async () => {
+    isOpen = true
+    await claude().ui.open({ id: paneId, title: `Install ${name}`, focus: true, holdToasts: true, closeOnEscape: true })
+  }
+
   const show = async <Answer>(build: (answer: (value: Answer) => void) => Omit<Page, 'cancel'>, cancelled: Answer): Promise<Answer> => {
     page?.cancel()
     const answer = new Promise<Answer>((resolve) => {
       const done = (value: Answer) => {
         if (page === shown) page = undefined
+        waiting.hide()
         resolve(value)
       }
       const shown: Page = { ...build(done), cancel: () => done(cancelled) }
       page = shown
     })
-    if (!isOpen) {
-      isOpen = true
-      await claude().ui.open({ id: paneId, title: `Install ${name}`, focus: true, holdToasts: true, closeOnEscape: true })
-    }
+    waiting.show(open)
+    if (!isOpen) await open().catch((error: unknown) => {
+      waiting.hide()
+      throw error
+    })
     claude().ui.invalidate('ui.render')
     return answer
   }
@@ -70,11 +77,11 @@ export function createInstaller(name: string, claude: () => Claude): Installer {
       isOpen = false
       page?.cancel()
     },
-    consent({ install, uninstall, keys, permissions, updates }) {
+    consent({ install, uninstall, hotkeys, permissions, updates }) {
       const changes = [
         ...(install === '' ? [] : [`Run ${install} now${uninstall === '' ? '' : `, and ${uninstall} when you remove it`}`]),
         ...(install === '' && uninstall !== '' ? [`Run ${uninstall} when you remove it`] : []),
-        ...(keys === '' ? [] : [`Bind ${keys}`]),
+        ...(hotkeys === '' ? [] : [`Bind ${hotkeys}`]),
         ...(updates === undefined ? [] : [`Update ${name} automatically from the ${updates} marketplace`]),
       ]
       return show<boolean>(
@@ -85,7 +92,7 @@ export function createInstaller(name: string, claude: () => Claude): Installer {
               [
                 ...(permissions.length === 0 ? [] : [Box({ flexDirection: 'column', children: permissions.map((item) => bullet(permissionWords(item))) })]),
                 ...(changes.length === 0 ? [] : [Text({ children: permissions.length === 0 ? 'Change your computer:' : 'and change your computer:' }), Box({ flexDirection: 'column', children: changes.map(bullet) })]),
-                Text({ dimColor: true, children: 'You can turn each permission off later in /mods.' }),
+                Text({ dimColor: true, children: 'You can turn each permission off later in Settings.' }),
               ],
               [Button({ key: 'not-now', hotkey: 'n', label: 'Not now', onPress: () => answer(false) }), Button({ key: 'accept', hotkey: 'a', label: 'Accept', onPress: () => answer(true) })],
             ),
@@ -103,11 +110,16 @@ export function createInstaller(name: string, claude: () => Claude): Installer {
               `${name} needs ${missing.length === 1 ? 'one setting' : `${missing.length} settings`}:`,
               missing.map(([key, option]) => {
                 const label = Text({ children: [Text({ bold: true, children: option.title }), option.description === '' ? '' : Text({ dimColor: true, children: `  ${option.description}` })] })
-                if (option.type === 'secret') return Box({ flexDirection: 'column', children: [label, Text({ dimColor: true, children: `Set it in /config, where Claude Code keeps it in your keychain, then press Next.` })] })
+                if (option.type === 'secret') {
+                  return Box({
+                    flexDirection: 'column',
+                    children: [label, Text({ dimColor: true, children: `${secretFix} Then press Next.` }), Button({ key: `secret:${key}`, label: 'Open /config', onPress: () => void claude().command.run({ command: 'config' }) })],
+                  })
+                }
                 const failure = failures.get(key)
                 const field = Input({
                   key: `option:${key}`,
-                  label: '› ',
+                  label: 'Value',
                   placeholder: option.type === 'choice' ? (option.choices ?? []).join(', ') : option.type === 'toggle' ? 'true or false' : option.type === 'list' ? 'comma-separated' : '',
                   value: saved.get(key) ?? '',
                   submitLabel: 'save',