@cmodjs/core 0.1.11 → 0.1.13

package/src/mod.ts

@@ -10,6 +10,9 @@ import type {
   HookStream,
   HttpInit,
   HttpResponse,
+  ModelCompleteOptions,
+  ModelCompleteRequest,
+  ModelCompleteResult,
   PaneOpenArgs,
   PermissionRequestDecision,
   ProcessRunInit,
@@ -20,6 +23,7 @@ import type {
   RenderElement,
   Settings,
   SettingsReadArgs,
+  Timer,
   ToastOptions,
   UiScrollArgs,
   UiScrollResult,
@@ -117,12 +121,17 @@ export type HookInput<E extends ModEvent> = HookInputs[E]
 
 export type ModHook<E extends ModEvent> = (input: HookInput<E>) => HookAnswer | void | Promise<HookAnswer | void>
 
+export type HookOptions = {
+  readonly timeoutMs?: number
+}
+
 export type Mod<State extends object = Record<never, never>> = {
   readonly name: string
   readonly state: Readonly<State>
   readonly dataFolder: string
-  on<E extends ModEvent>(event: E, hook: ModHook<E>): void
+  on<E extends ModEvent>(event: E, hook: ModHook<E>, options?: HookOptions): void
   use<Handle>(job: Job<Handle, State>): Handle
+  every(ms: number, hook: () => unknown): Timer
   readonly ui: {
     pane(pane: Pane<State>): PaneHandle
     render<S extends Slot>(slot: S, Component: (props: SlotProps<S>) => RenderElement): void
@@ -150,10 +159,15 @@ export type Mod<State extends object = Record<never, never>> = {
   }
   readonly session: {
     messages: Claude['session']['messages']
+    append(text: string): Promise<void>
+    submit(text: string): Promise<void>
   }
   readonly agent: {
     spawn(args: AgentSpawnArgs): Promise<AgentSpawnResult>
   }
+  readonly model: {
+    complete(request: ModelCompleteRequest, options?: ModelCompleteOptions): Promise<ModelCompleteResult>
+  }
   readonly projectRoot: string
   readonly cwd: string
   readonly dependencies: CmodDependencies

package/src/records.ts

@@ -1,4 +1,4 @@
-import { messageOf } from './utils/text.js'
+import { listed, messageOf } from './utils/text.js'
 
 export type InstallRecord = {
   name: string
@@ -8,16 +8,17 @@ export type InstallRecord = {
   scriptsSha256: string
   uninstall: string | null
   program: string | null
+  keys: Readonly<Record<string, string>>
 }
 
-export type Steps = { install?: string; uninstall?: string; program?: string }
+export type Steps = { install?: string; uninstall?: string; program?: string; keys?: Readonly<Record<string, string>> }
 
 export type ReadFile = (path: string) => Promise<string | undefined>
 
 export type RunnerEvent =
   | { kind: 'progress'; done: number; total: number; label: string }
   | { kind: 'log'; text: string }
-  | { kind: 'needs-consent'; sha256: string; install: string; uninstall: string }
+  | { kind: 'needs-consent'; sha256: string; install: string; uninstall: string; keys: string }
   | { kind: 'done'; name: string; version?: string }
   | { kind: 'missing'; name: string }
   | { kind: 'failed'; code: number; message: string }
@@ -89,6 +90,8 @@ function parseRecord(text: string, path: string): InstallRecord {
   if (uninstall !== null && typeof uninstall !== 'string') throw new Error(`${path} has an "uninstall" that is neither a path nor null. ${fix}`)
   const program = value['program']
   if (program !== null && typeof program !== 'string') throw new Error(`${path} has a "program" that is neither a command name nor null. ${fix}`)
+  const keys = value['keys'] ?? {}
+  if (!isObject(keys) || Object.values(keys).some((command) => typeof command !== 'string')) throw new Error(`${path} has "keys" that are not key bindings. ${fix}`)
   return {
     name: value['name'] as string,
     version: value['version'] as string,
@@ -97,6 +100,7 @@ function parseRecord(text: string, path: string): InstallRecord {
     scriptsSha256: value['scriptsSha256'] as string,
     uninstall,
     program,
+    keys: keys as Record<string, string>,
   }
 }
 
@@ -108,7 +112,27 @@ export function readSteps(pkg: unknown): Steps | undefined {
   if (!isObject(steps)) throw new Error('package.json has a "cmod" key that is not an object. Write "cmod": { "install": "./setup/install.sh", "uninstall": "./setup/uninstall.sh" }.')
   const program = steps['program']
   if (program !== undefined && (typeof program !== 'string' || !pluginName.test(program))) throw new Error('package.json "cmod.program" must be the program\'s command, such as "hello".')
-  return { ...readCommand(steps, 'install'), ...readCommand(steps, 'uninstall'), ...(program === undefined ? {} : { program }) }
+  return { ...readCommand(steps, 'install'), ...readCommand(steps, 'uninstall'), ...(program === undefined ? {} : { program }), ...readKeys(steps['keys']) }
+}
+
+function readKeys(keys: unknown): Steps {
+  if (keys === undefined) return {}
+  if (!isObject(keys) || Object.keys(keys).length === 0) throw new Error('package.json "cmod.keys" must bind each key to a command, such as "keys": { "shift+tab": "/mode" }.')
+  const commands: Record<string, string> = {}
+  for (const [key, value] of Object.entries(keys)) {
+    const command = typeof value === 'string' ? /^\/([A-Za-z0-9][A-Za-z0-9._:-]*)$/.exec(value)?.[1] : undefined
+    if (key.trim() === '' || command === undefined) throw new Error(`package.json "cmod.keys" binds "${key}" to ${JSON.stringify(value)}. Bind each key to one of the mod's commands, such as "shift+tab": "/mode".`)
+    commands[key] = command
+  }
+  return { keys: commands }
+}
+
+export function oldestCmodFor(keys: Readonly<Record<string, string>>): string {
+  return Object.keys(keys).length > 0 ? '0.1.12' : '0.0.0'
+}
+
+export function keyWords(keys: Readonly<Record<string, string>> | undefined): string {
+  return listed(Object.entries(keys ?? {}).map(([key, command]) => `${key} to /${command}`))
 }
 
 function readCommand(steps: Record<string, unknown>, key: 'install' | 'uninstall'): Steps {
@@ -145,7 +169,7 @@ export async function scriptsSha256(steps: Steps, files: { read: ReadFile; list:
     if (scriptFolders.length === 0) throw new Error(`package.json "cmod.${key}" runs "${command}", which names no script file in the mod, so consent cannot cover what it runs. Put the commands in a script, such as ./setup/${key}.sh.`)
     for (const folder of scriptFolders) folders.add(folder)
   }
-  let text = [steps.install ?? '', steps.uninstall ?? '', steps.program ?? ''].join('\0')
+  let text = [steps.install ?? '', steps.uninstall ?? '', steps.program ?? '', ...(steps.keys === undefined ? [] : [JSON.stringify(Object.entries(steps.keys).sort())])].join('\0')
   for (const folder of [...folders].sort()) {
     for (const name of (await files.list(folder)).sort()) {
       const path = `${folder}/${name}`
@@ -165,7 +189,7 @@ export function formatEvent(event: RunnerEvent): string {
     case 'log':
       return `log ${event.text}`
     case 'needs-consent':
-      return `needs-consent ${event.sha256}\t${event.install}\t${event.uninstall}`
+      return `needs-consent ${event.sha256}\t${event.install}\t${event.uninstall}\t${event.keys}`
     case 'done':
       return event.version === undefined ? `done ${event.name}` : `done ${event.name} ${event.version}`
     case 'missing':
@@ -178,8 +202,8 @@ export function formatEvent(event: RunnerEvent): string {
 export function parseEvent(line: string): RunnerEvent {
   const progress = /^progress (\d+) (\d+)(?: (.*))?$/.exec(line)
   if (progress !== null) return { kind: 'progress', done: Number(progress[1]), total: Number(progress[2]), label: progress[3] ?? '' }
-  const consent = /^needs-consent (\S+)\t([^\t]*)\t(.*)$/.exec(line)
-  if (consent !== null) return { kind: 'needs-consent', sha256: consent[1] as string, install: consent[2] as string, uninstall: consent[3] as string }
+  const consent = /^needs-consent (\S+)\t([^\t]*)\t([^\t]*)(?:\t(.*))?$/.exec(line)
+  if (consent !== null) return { kind: 'needs-consent', sha256: consent[1] as string, install: consent[2] as string, uninstall: consent[3] as string, keys: consent[4] ?? '' }
   const done = /^done (\S+)(?: (\S+))?$/.exec(line)
   if (done !== null) return { kind: 'done', name: done[1] as string, ...(done[2] === undefined ? {} : { version: done[2] }) }
   const missing = /^missing (\S+)$/.exec(line)

package/src/register.ts

@@ -1,4 +1,4 @@
-import type { Args, EngineInterface, EventResult, Frozen, Next, On } from 'claude-code'
+import type { Args, EngineInterface, EventResult, Frozen, Next, On, ToolCallArgs } from 'claude-code'
 import type { ModDefinition } from './mod.js'
 import type { Claude } from './runtime/claude.js'
 import type { RoutedEvent } from './runtime/hooks.js'
@@ -56,9 +56,12 @@ async function startMod($: EngineInterface, eventInput: Frozen<Args<'session.sta
       usage: () => $.session.usage(),
       surfaces: () => $.session.surfaces(),
       messages: ((args?: Parameters<Claude['session']['messages']>[0]) => (args === undefined ? $.session.messages() : $.session.messages(args))) as Claude['session']['messages'],
+      append: (args) => $.session.append(args),
     },
+    prompt: { submit: (args) => $.prompt.submit(args) },
+    model: { complete: (request, options) => $.model.complete(request, options) },
     command: { register: (command) => $.command.register(command) },
-    tool: { register: (tool) => $.tool.register(tool) },
+    tool: { register: (tool) => $.tool.register(tool), call: ((input: ToolCallArgs) => $.tool.call(input)) as Claude['tool']['call'] },
     agent: {
       list: () => $.agent.list(),
       spawn: (args) => $.agent.spawn(args),

package/src/runtime/claude.ts

@@ -83,9 +83,12 @@ export type Claude = {
     usage(): Promise<SessionUsage>
     surfaces(): Promise<readonly RenderSurface[]>
     messages: EngineInterface['session']['messages']
+    append: EngineInterface['session']['append']
   }
+  readonly prompt: { submit: EngineInterface['prompt']['submit'] }
+  readonly model: { complete: EngineInterface['model']['complete'] }
   readonly command: { register(command: CommandSpec): Promise<{ command: string }> }
-  readonly tool: { register(tool: ToolSpec): Promise<{ tool: string }> }
+  readonly tool: { register(tool: ToolSpec): Promise<{ tool: string }>; call: EngineInterface['tool']['call'] }
   readonly agent: {
     list(): Promise<AgentInfo[]>
     spawn(args: AgentSpawnArgs): Promise<AgentSpawnResult>

package/src/runtime/hooks.ts

@@ -4,7 +4,7 @@ import { configFolders } from '../records.js'
 import type { Claude } from './claude.js'
 import type { RoutedHook } from './router.js'
 import { reservedKeys, toolInputOf, type ToolCalls } from './tool-calls.js'
-import { callEffects, type FileAccess, type ToolUse } from '../utils/call-effects.js'
+import { callEffects, inputOf, type CallBase, type FileAccess } from '../utils/call-effects.js'
 import { dynamicPattern } from '../utils/parse-shell.js'
 import { messageOf } from '../utils/text.js'
 
@@ -53,14 +53,14 @@ const readFields: Record<ModEvent, readonly string[]> = {
 }
 
 export function classicHook<E extends Exclude<ModEvent, 'PreToolUse'>>(name: string, event: E, hook: ModHook<E>, claude: Claude, calls: ToolCalls): RoutedHook<RoutedEvent> {
-  const inputOf = async (e: unknown): Promise<unknown> => {
+  const hookInputOf = async (e: unknown): Promise<unknown> => {
     if (event !== 'PostToolUse' && event !== 'PostToolUseFailure') return e
     const input = e as ClassicHookInputs['PostToolUse' | 'PostToolUseFailure']
     const cwd = calls.cwdOf(input.tool_use_id) ?? input.cwd
-    return { ...input, files: await callFiles(name, claude, { tool: input.tool_name, input: input.tool_input }, cwd) }
+    return { ...input, files: await callFiles(name, claude, { tool: input.tool_name, input: inputOf(input.tool_input) }, cwd) }
   }
   const resultOf = async (e: unknown): Promise<ClassicFields | undefined> => {
-    const answer = await hook((await inputOf(e)) as HookInput<E>)
+    const answer = await hook((await hookInputOf(e)) as HookInput<E>)
     if (answer === undefined) return undefined
     if (answer.systemMessage !== undefined) claude.ui.log(answer.systemMessage)
     return classicResult(event, answer)
@@ -165,7 +165,7 @@ async function preToolUseInput(name: string, envelope: Frozen<Args<'tool.call'>>
   }
 }
 
-async function callFiles(name: string, claude: Claude, use: ToolUse, cwd: string): Promise<CallFiles> {
+async function callFiles(name: string, claude: Claude, use: CallBase, cwd: string): Promise<CallFiles> {
   try {
     const home = await claude.env.home()
     if (home === undefined) throw new Error('HOME is not set, so ~ in a path has no meaning.')

package/src/runtime/lifecycle.ts

@@ -1,6 +1,6 @@
 import type { Args, EventResult, Frozen, HookBudget, HookStream, ProcessSpawnChunk, ProcessSpawnResult } from 'claude-code'
 import type { HookInput, Mod, ModDefinition, ModEvent, ModHook } from '../mod.js'
-import { dataFolder, isAtLeast, parseEvent, readRecord, readSteps, scriptsSha256, storeFolder, type ReadFile, type RunnerEvent } from '../records.js'
+import { dataFolder, isAtLeast, oldestCmodFor, parseEvent, readRecord, readSteps, scriptsSha256, storeFolder, type ReadFile, type RunnerEvent } from '../records.js'
 import { relativePath } from '../utils/paths.js'
 import { formatExit, listed, messageOf } from '../utils/text.js'
 import type { Claude } from './claude.js'
@@ -19,6 +19,7 @@ export type Plugin = {
   readonly store: string
   readonly isInstalled: boolean
   readonly shouldRecord: boolean
+  readonly keys: Readonly<Record<string, string>>
 }
 
 export type Phase = 'starting' | 'installing' | 'waiting' | 'declined' | 'failed' | 'ready' | 'active'
@@ -36,6 +37,7 @@ type ModRuntime = {
   readonly router: Router
   readonly progress: Progress
   readonly dataFolder: string
+  readonly keys: Readonly<Record<string, string>>
   readonly checksPermissions: () => boolean
 }
 
@@ -74,12 +76,12 @@ export async function readPlugin(claude: Claude): Promise<Plugin> {
   const manifest = (await readJson(read, `${root}/.claude-plugin/plugin.json`)) as { version?: unknown } | undefined
   const version = typeof manifest?.version === 'string' ? manifest.version : undefined
   const store = storeFolder({ HOME: await claude.env.home(), XDG_DATA_HOME: await claude.env.dataHome() })
-  const plugin = { name, root, version, store }
   if (name === cmodPluginName) {
     const installed = await cmodVersion(claude)
-    return { ...plugin, isInstalled: version !== undefined && installed !== undefined && isAtLeast(installed, version), shouldRecord: false }
+    return { name, root, version, store, keys: {}, isInstalled: version !== undefined && installed !== undefined && isAtLeast(installed, version), shouldRecord: false }
   }
   const steps = readSteps(await readJson(read, `${root}/package.json`)) ?? {}
+  const plugin = { name, root, version, store, keys: steps.keys ?? {} }
   const record = await readRecord(read, store, name)
   if (Object.keys(steps).length === 0) return { ...plugin, isInstalled: true, shouldRecord: record?.version !== version }
   const scripts = await scriptsSha256(steps, {
@@ -181,7 +183,7 @@ export function createLifecycle<State extends object>(definition: ModDefinition<
   const activate = async () => {
     if (runtime === undefined || plugin === undefined) return
     const activeRouter = createRouter()
-    const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), checksPermissions }).catch((error: unknown) => {
+    const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), keys: plugin.keys, checksPermissions }).catch((error: unknown) => {
       fail(messageOf(error), 'Fix it, then run /reload-plugins.')
       throw error
     })
@@ -215,8 +217,12 @@ export function createLifecycle<State extends object>(definition: ModDefinition<
       return
     }
     showLine().wait('Waiting for your answer')
-    const removal = event.uninstall === '' ? '' : `, and ${event.uninstall} when you remove it`
-    const answer = await claude().ui.ask(`${name} runs ${event.install} to install${removal}. Run it now?`, { options: ['Install', 'Not now'], header: 'Install' })
+    const actions = [
+      ...(event.install === '' ? [] : [`runs ${event.install} to install`]),
+      ...(event.uninstall === '' ? [] : [`runs ${event.uninstall} when you remove it`]),
+      ...(event.keys === '' ? [] : [`binds ${event.keys}`]),
+    ]
+    const answer = await claude().ui.ask(`${name} ${listed(actions)}. Install it now?`, { options: ['Install', 'Not now'], header: 'Install' })
     if (answer === 'Install') return install(event.sha256)
     phase = 'declined'
     endLine()
@@ -227,7 +233,8 @@ export function createLifecycle<State extends object>(definition: ModDefinition<
     if (plugin === undefined) return
     if (plugin.name === cmodPluginName) return bootstrap(plugin.root)
     phase = 'installing'
-    if ((await cmodVersion(claude())) === undefined) return waitForcmod()
+    const found = await cmodVersion(claude())
+    if (!fits(found)) return waitForcmod(found)
     endLine()
     const progress = showLine()
     let outcome: RunnerEvent | undefined
@@ -243,9 +250,12 @@ export function createLifecycle<State extends object>(definition: ModDefinition<
     fail(reason, `Fix the cause, then run: cmod install ${definition.name}`)
   }
 
-  const waitForcmod = () => {
+  const fits = (found: string | undefined): found is string => found !== undefined && isAtLeast(found, oldestCmodFor(plugin?.keys ?? {}))
+
+  const waitForcmod = (found: string | undefined) => {
     phase = 'waiting'
     showLine().wait('Waiting for cmod')
+    let latest = found
     let check: Promise<void> | undefined
     const stop = () => {
       timer.cancel()
@@ -255,7 +265,8 @@ export function createLifecycle<State extends object>(definition: ModDefinition<
       check ??= cmodVersion(claude())
         .then((version) => {
           check = undefined
-          if (version === undefined) return
+          latest = version
+          if (!fits(version)) return
           stop()
           return install()
         })
@@ -264,7 +275,13 @@ export function createLifecycle<State extends object>(definition: ModDefinition<
           report(error)
         })
     })
-    const longWait = claude().clock.after(cmodWaitMs, () => showLine().wait("Still waiting for cmod to download cmod. See cmod's own line."))
+    const longWait = claude().clock.after(cmodWaitMs, () =>
+      showLine().wait(
+        latest === undefined
+          ? "Still waiting for cmod to download cmod. See cmod's own line."
+          : `PATH finds cmod ${latest}, and ${definition.name} needs cmod ${oldestCmodFor(plugin?.keys ?? {})} or later. Run npm i -g @cmodjs/cli, or put ~/.local/bin ahead of the old cmod on PATH.`,
+      ),
+    )
   }
 
   const bootstrap = async (root: string) => {
@@ -350,7 +367,8 @@ export function createLifecycle<State extends object>(definition: ModDefinition<
 }
 
 async function createMod<State extends object>(definition: ModDefinition<State>, runtime: ModRuntime): Promise<ActiveMod<State>> {
-  const { claude, router, progress } = runtime
+  const { router, progress } = runtime
+  const claude = checkingKeys(runtime.claude, definition.name, runtime.keys)
   const added: string[] = []
   const hookEvents: ModEvent[] = []
   const announce = (feature: string) => {
@@ -367,12 +385,26 @@ async function createMod<State extends object>(definition: ModDefinition<State>,
     name: definition.name,
     state: modState.state,
     dataFolder: runtime.dataFolder,
-    on(event, hook) {
+    on(event, hook, options) {
+      const bounded = options?.timeoutMs === undefined ? hook : timedHook(definition.name, event, hook, checkedMs(definition.name, `the ${event} hook's timeoutMs`, options.timeoutMs), claude)
       if (!hookEvents.includes(event)) hookEvents.push(event)
-      if (event === 'PreToolUse') router.add('tool.call', preToolUseHook(definition.name, hook as ModHook<'PreToolUse'>, claude, agents, held))
-      else router.add(`classic.${event as Exclude<ModEvent, 'PreToolUse'>}`, classicHook(definition.name, event as Exclude<ModEvent, 'PreToolUse'>, hook as ModHook<Exclude<ModEvent, 'PreToolUse'>>, claude, agents))
+      if (event === 'PreToolUse') router.add('tool.call', preToolUseHook(definition.name, bounded as ModHook<'PreToolUse'>, claude, agents, held))
+      else router.add(`classic.${event as Exclude<ModEvent, 'PreToolUse'>}`, classicHook(definition.name, event as Exclude<ModEvent, 'PreToolUse'>, bounded as ModHook<Exclude<ModEvent, 'PreToolUse'>>, claude, agents))
     },
     use: (job) => job({ mod, claude, on: (event, hook) => router.add(event, hook), announce, reserveName, toolCalls: agents }),
+    every(ms, hook) {
+      let isRunning = false
+      return claude.clock.every(checkedMs(definition.name, 'mod.every', ms), () => {
+        if (isRunning) return
+        isRunning = true
+        void Promise.resolve()
+          .then(hook)
+          .catch((error: unknown) => claude.ui.log(`${definition.name}: the every ${ms} ms hook failed: ${messageOf(error)}`))
+          .finally(() => {
+            isRunning = false
+          })
+      })
+    },
     ui: area.ui,
     process: {
       run: (argv, init) => claude.process.run(argv, init),
@@ -387,8 +419,19 @@ async function createMod<State extends object>(definition: ModDefinition<State>,
     },
     http: { fetch: (url, init) => claude.http.fetch(url, init) },
     settings: { read: (args) => claude.settings.read(args) },
-    session: { messages: claude.session.messages },
+    session: {
+      messages: claude.session.messages,
+      async append(text) {
+        const added = await claude.session.append({ message: { type: 'user', content: [{ type: 'text', text }] } })
+        if (added.deny !== undefined) throw new Error(`${definition.name}: Claude Code refused the note: ${added.deny}`)
+      },
+      async submit(text) {
+        const submitted = await claude.prompt.submit({ text })
+        if ('drop' in submitted && typeof submitted.drop === 'string') throw new Error(`${definition.name}: Claude Code dropped the prompt: ${submitted.drop}`)
+      },
+    },
     agent: { spawn: (args) => claude.agent.spawn(args) },
+    model: { complete: (request, options) => claude.model.complete(request, options) },
     get projectRoot() {
       return modState.root
     },
@@ -464,6 +507,49 @@ async function createMod<State extends object>(definition: ModDefinition<State>,
   return { mod, added }
 }
 
+function checkingKeys(claude: Claude, name: string, keys: Readonly<Record<string, string>>): Claude {
+  const bound = Object.entries(keys)
+  if (bound.length === 0) return claude
+  const register: Claude['command']['register'] = (command) => {
+    for (const [key, commandName] of bound) {
+      if (commandName === command.name && command.immediate !== true) {
+        claude.ui.log(`${name}: ${key} runs /${command.name}, which waits for Claude's turn to end and adds a row to the conversation. Give /${command.name} immediate: true.`)
+      }
+    }
+    return claude.command.register(command)
+  }
+  return { ...claude, command: { ...claude.command, register } }
+}
+
+const longestTimerMs = 2_147_483_647
+
+function checkedMs(name: string, subject: string, ms: number): number {
+  if (!Number.isInteger(ms) || ms <= 0 || ms > longestTimerMs) throw new Error(`${name}: ${subject} is ${ms}. Give a whole number of milliseconds above 0 and at most ${longestTimerMs}.`)
+  return ms
+}
+
+function timedHook<E extends ModEvent>(name: string, event: E, hook: ModHook<E>, ms: number, claude: Claude): ModHook<E> {
+  return (input) =>
+    new Promise((resolve, reject) => {
+      const timer = claude.clock.after(ms, () => {
+        claude.ui.log(`${name}: the ${event} hook passed its ${ms / 1000} s timeout`)
+        resolve(undefined)
+      })
+      Promise.resolve()
+        .then(() => hook(input))
+        .then(
+          (answer) => {
+            timer.cancel()
+            resolve(answer)
+          },
+          (error: unknown) => {
+            timer.cancel()
+            reject(error)
+          },
+        )
+    })
+}
+
 async function failsAs(subject: string, step: () => unknown): Promise<void> {
   try {
     await step()

package/src/runtime/state.ts

@@ -32,7 +32,19 @@ const savedLifetimes: readonly SavedLifetime[] = ['session', 'project', 'global'
 
 const keptPerValue = 20
 
-export function createState<State extends object>({ name, initial, session, root, claude, changed }: StateOptions): ModState<State> {
+const listeners = new WeakMap<object, Set<() => void>>()
+
+export function onStateChange(state: object, listener: () => void): void {
+  const own = listeners.get(state) ?? new Set()
+  own.add(listener)
+  listeners.set(state, own)
+}
+
+export function createState<State extends object>({ name, initial, session, root, claude, changed: redraw }: StateOptions): ModState<State> {
+  const changed = () => {
+    redraw()
+    for (const listener of listeners.get(state) ?? []) listener()
+  }
   const declared = declaredGroups(name, initial)
   const current = copied(declared)
   let defaults = declared

package/src/testing/fake-claude.ts

@@ -13,20 +13,28 @@ export type Fakes = {
   http: { fetch?: Claude['http']['fetch'] }
   settings: { read?: Claude['settings']['read'] }
   ui: { ask?: Claude['ui']['ask']; open?: Claude['ui']['open']; scroll?: Claude['ui']['scroll'] }
-  session: { messages?: Claude['session']['messages'] }
+  session: { messages?: Claude['session']['messages']; append?: Claude['session']['append'] }
+  prompt: { submit?: Claude['prompt']['submit'] }
+  model: { complete?: Claude['model']['complete'] }
   agent: { list?: Claude['agent']['list']; spawn?: Claude['agent']['spawn'] }
   clock: { after?: Claude['clock']['after']; every?: Claude['clock']['every'] }
   cmod: { call?: Claude['cmod']['call'] }
+  tool: { call?: Claude['tool']['call'] }
 }
 
+export type ShownSchedule = { readonly id: string; readonly cron: string; readonly prompt: string }
+
 export type Shown = {
   readonly toasts: string[]
+  readonly notes: string[]
+  readonly prompts: string[]
   readonly logs: string[]
   readonly debug: string[]
   readonly statuses: (string | undefined)[]
   readonly openPanes: Set<string>
   readonly commands: string[]
   readonly tools: string[]
+  readonly schedules: ShownSchedule[]
 }
 
 export type FakeClaude = {
@@ -40,8 +48,8 @@ export type FakeClaude = {
 
 export function fakeClaude(plugin: { readonly name: string; readonly root: string }): FakeClaude {
   const calls: TestCall[] = []
-  const fakes: Fakes = { process: {}, fs: {}, http: {}, settings: {}, ui: {}, session: {}, agent: {}, clock: {}, cmod: {} }
-  const shown: Shown = { toasts: [], logs: [], debug: [], statuses: [], openPanes: new Set(), commands: [], tools: [] }
+  const fakes: Fakes = { process: {}, fs: {}, http: {}, settings: {}, ui: {}, session: {}, prompt: {}, model: {}, agent: {}, clock: {}, cmod: {}, tool: {} }
+  const shown: Shown = { toasts: [], notes: [], prompts: [], logs: [], debug: [], statuses: [], openPanes: new Set(), commands: [], tools: [], schedules: [] }
   const unplacedPanes = new Set<string>()
   let focusedPane: string | undefined
   const store = new Map<string, unknown>()
@@ -61,6 +69,31 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
     return async (...args: Args): Promise<Result> => run(...args)
   }
 
+  const appendNote: Claude['session']['append'] = async ({ message }) => {
+    shown.notes.push(message.content.map((block) => (typeof block['text'] === 'string' ? block['text'] : '')).join(''))
+    return { message, uuid: `note-${shown.notes.length}` } as unknown as Awaited<ReturnType<Claude['session']['append']>>
+  }
+  const submitPrompt: Claude['prompt']['submit'] = async ({ text }) => {
+    shown.prompts.push(text)
+    return { text, origin: { kind: 'plugin', name: plugin.name } } as unknown as Awaited<ReturnType<Claude['prompt']['submit']>>
+  }
+  let scheduled = 0
+  const scheduleTools = async (input: Record<string, unknown>): Promise<unknown> => {
+    if (input['tool'] === 'CronCreate') {
+      const created = { id: `cron-${(scheduled += 1)}`, cron: String(input['cron']), prompt: String(input['prompt']) }
+      shown.schedules.push(created)
+      return { result: { id: created.id, humanSchedule: created.cron, recurring: input['recurring'] !== false } }
+    }
+    if (input['tool'] === 'CronDelete') {
+      const at = shown.schedules.findIndex((created) => created.id === input['id'])
+      if (at === -1) return { result: { id: input['id'] }, text: `No job ${String(input['id'])}`, isError: true }
+      shown.schedules.splice(at, 1)
+      return { result: { id: input['id'] }, text: `Cancelled job ${String(input['id'])}.` }
+    }
+    if (input['tool'] === 'CronList') return { result: { jobs: shown.schedules.map(({ id, cron, prompt }) => ({ id, cron, humanSchedule: cron, prompt })) } }
+    throw new Error(`tool.call(${JSON.stringify(input)}) has no fake answer. Set fakes.tool.call on the tested mod.`)
+  }
+
   const claude: Claude = {
     plugin,
     ui: {
@@ -142,7 +175,10 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
       usage: async () => ({ context: { window: 200000 }, rateLimits: {}, cost: { usd: 0 } }) as unknown as Awaited<ReturnType<Claude['session']['usage']>>,
       surfaces: async () => ['terminal'],
       messages: rejected('session.messages', () => fakes.session.messages as ((args?: unknown) => Promise<unknown>) | undefined) as Claude['session']['messages'],
+      append: rejected('session.append', () => fakes.session.append ?? appendNote),
     },
+    prompt: { submit: rejected('prompt.submit', () => fakes.prompt.submit ?? submitPrompt) },
+    model: { complete: rejected('model.complete', () => fakes.model.complete) },
     command: {
       register: async (command) => {
         shown.commands.push(command.name)
@@ -154,6 +190,7 @@ export function fakeClaude(plugin: { readonly name: string; readonly root: strin
         shown.tools.push(tool.name)
         return { tool: `mcp__${plugin.name}__${tool.name}` }
       },
+      call: rejected('tool.call', () => fakes.tool.call ?? scheduleTools) as Claude['tool']['call'],
     },
     env: {
       home: async () => '/test/home',

package/src/testing.ts

@@ -108,6 +108,7 @@ export function testMod<State extends object>(definition: ModDefinition<State>,
       store: storeFolder({ HOME: await claude.env.home(), XDG_DATA_HOME: await claude.env.dataHome() }),
       isInstalled: true,
       shouldRecord: false,
+      keys: {},
     }))
     await started
     if (lifecycle.phase !== 'active') throw lifecycle.failure ?? new Error(`${name} did not start: the lifecycle is ${lifecycle.phase}.`)

package/src/utils/call-effects.ts

@@ -2,9 +2,7 @@ import { parseShell, type ShellCommand } from './parse-shell.js'
 import { expandHome, type FileSystem } from './paths.js'
 import { resolve } from '../vendor.js'
 
-export type ToolUse = { tool: string; input: unknown; agentId?: string; agentType?: string }
-
-export type CallBase = { tool: string; agentId?: string; agentType?: string }
+export type CallBase = { tool: string; input: Readonly<Record<string, unknown>>; agentId?: string; agentType?: string }
 export type CommandCall = CallBase & { commands: [string, ...string[]][]; isFullyParsed: boolean }
 export type FileCall = CallBase & { path: string; content?: string; previousContent?: string }
 export type FetchCall = CallBase & { url: string }
@@ -20,7 +18,7 @@ export type CallEffects = {
   subagent: string | undefined
 }
 
-export function callEffects(use: ToolUse, workspace: { cwd: string; home: string; fs: FileSystem }): CallEffects {
+export function callEffects(use: CallBase, workspace: { cwd: string; home: string; fs: FileSystem }): CallEffects {
   const { fs } = workspace
   const absolute = (path: string, folder = workspace.cwd) => resolve(folder, expandHome(path, workspace.home))
   const access = (path: string): FileAccess => ({ path: absolute(path), contents: undefined })
@@ -60,11 +58,15 @@ export function callEffects(use: ToolUse, workspace: { cwd: string; home: string
   return effects
 }
 
-export function callBaseOf({ tool, agentId, agentType }: ToolUse): CallBase {
-  return { tool, ...(agentId === undefined ? {} : { agentId }), ...(agentType === undefined ? {} : { agentType }) }
+export function inputOf(value: unknown): Readonly<Record<string, unknown>> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : {}
+}
+
+export function callBaseOf({ tool, input, agentId, agentType }: CallBase): CallBase {
+  return { tool, input, ...(agentId === undefined ? {} : { agentId }), ...(agentType === undefined ? {} : { agentType }) }
 }
 
-async function editedContents(use: ToolUse, path: string, fs: FileSystem): Promise<Contents> {
+async function editedContents(use: CallBase, path: string, fs: FileSystem): Promise<Contents> {
   const previousContent = await previousContentOf(path, fs)
   const oldString = textField(use, 'old_string')
   const newString = textField(use, 'new_string')
@@ -90,16 +92,16 @@ function once<Value>(load: () => Promise<Value>): () => Promise<Value> {
   return () => (loaded ??= load())
 }
 
-function fieldOf(use: ToolUse, name: string): unknown {
-  return typeof use.input === 'object' && use.input !== null ? (use.input as Record<string, unknown>)[name] : undefined
+function fieldOf(use: CallBase, name: string): unknown {
+  return use.input[name]
 }
 
-function textField(use: ToolUse, name: string): string {
+function textField(use: CallBase, name: string): string {
   const value = fieldOf(use, name)
   if (typeof value !== 'string') throw new Error(`The ${use.tool} call has no text field ${name}.`)
   return value
 }
 
-function optionalTextField(use: ToolUse, name: string): string | undefined {
+function optionalTextField(use: CallBase, name: string): string | undefined {
   return fieldOf(use, name) === undefined ? undefined : textField(use, name)
 }