@cmodjs/core 1.5.1 → 2.0.0

package/src/runtime/lifecycle.ts

@@ -1,6 +1,6 @@
 import type { Args, EventResult, Frozen, HookBudget, PluginOptions, RenderElement, Timer } from 'claude-code'
 import type { Step } from '../installer.js'
-import { hooks, PreToolUse, type Allowed, type Disposable, type Hook, type HookInput, type HookListener, type HookOptions, type Imports, type Mod, type ModDefinition, type PaneHandle, type SettingsFile, type Toast } from '../mod.js'
+import type { Allowed, FileChange, Disposable, Imports, Mod, ModDefinition, PaneHandle, SettingsFile, SettingsFileChange, SettingsFileChangeListener, Toast } from '../mod.js'
 import type { Options, OptionValues } from '../options.js'
 import { changelogPage, consentPath, dataFolder, finishStepsMethod, isAtLeast, marketplaceOf, oldestCmodFor, openPageMethod, parseConsent, pendingStepsMethod, parseEvent, permissionWords, readRecord, readSteps, recordPath, scriptsSha256, settingsPagesMethod, storeFolder, updatesToTurnOn, type ReadFile, type RunnerEvent, type Steps } from '../records.js'
 import { homePrefix, ifMissing, relativePath } from '../utils/paths.js'
@@ -10,9 +10,9 @@ import { beforeDeadline } from './deadline.js'
 import { announcedOf, announcementMs, announcementOf } from './announce.js'
 import { bind } from './bound.js'
 import { serveConversations } from './conversations.js'
-import { answerCall, cmodPluginName, dependencyCalls, withBareRefusals } from './dependencies.js'
+import { answerCall, answeringOwnCalls, cmodPluginName, dependencyCalls, withBareRefusals } from './dependencies.js'
 import { keepEngine } from './engine.js'
-import { classicHook, heldDecisionHook, permissionEvents, preToolUseHook, userSkillHook, type HeldDecisions, type RoutedEvent } from './hooks.js'
+import { classicHook, permissionEvents, userSkillHook, type Hook, type HookListener, type RoutedEvent } from './hooks.js'
 import { checkedAnswer, checkingGrants, checkSettings, checksAnswers, checkWrite, isCovered, itemOf, passedDown, programAddresses, type AnswerCheck, type Grants } from './grants.js'
 import { cmodError, lastLineOf, locatingPrograms, readLines, type Programs } from './programs.js'
 import { createModFiles, resolvedPath, type Places } from './metadata.js'
@@ -51,6 +51,7 @@ export type Lifecycle<State extends object> = {
   readonly toasts: readonly ShownToast[]
   start(claude: Claude, read: (claude: Claude) => Promise<Plugin>): Promise<void>
   route<N extends RoutedEvent>(event: N, e: Frozen<Args<N>>, next: RouterNext<N>): Promise<EventResult<N>>
+  raise(method: string, payload: Readonly<Record<string, unknown>>): Promise<unknown>
 }
 
 type ModRuntime = {
@@ -70,6 +71,7 @@ type ActiveMod<State extends object, Declared extends Options> = {
   readonly mod: Mod<State, Declared>
   readonly added: readonly string[]
   readonly imports: Imports
+  readonly raise: (method: string, payload: Readonly<Record<string, unknown>>) => Promise<unknown>
 }
 
 
@@ -164,6 +166,7 @@ export function createLifecycle<State extends object, Declared extends Options =
   let activation: Promise<void> | undefined
   let mod: Mod<State> | undefined
   let imports: Imports | undefined
+  let raise: ActiveMod<State, Declared>['raise'] | undefined
   let failure: unknown
   let pluginOptions = options
   const installer = createInstaller(definition.name, () => claude())
@@ -325,6 +328,7 @@ export function createLifecycle<State extends object, Declared extends Options =
     const { added } = active
     mod = active.mod
     imports = active.imports
+    raise = active.raise
     router = activeRouter
     phase = 'active'
     runtime.claude.ui.invalidate('ui.render')
@@ -560,6 +564,11 @@ export function createLifecycle<State extends object, Declared extends Options =
     get toasts() {
       return runtime?.toaster.shown ?? []
     },
+    async raise(method, payload) {
+      if (raise === undefined || imports === undefined) throw new Error(`${definition.name} has not started, so ${method} has no listener yet.`)
+      bind(imports)
+      return raise(method, payload)
+    },
     async start(claudeCalls, read) {
       if (runtime !== undefined) return
       programs = locatingPrograms(claudeCalls)
@@ -609,9 +618,8 @@ export function createLifecycle<State extends object, Declared extends Options =
 async function createMod<State extends object, Declared extends Options>(definition: ModDefinition<State, string, Declared>, runtime: ModRuntime): Promise<ActiveMod<State, Declared>> {
   const { router, toaster } = runtime
   const report = (failure: Failure) => void toaster.fail(failure)
-  const claude = withBareRefusals(checkingKeys(runtime.claude, toaster.toast, runtime.steps.keys ?? {}))
+  const claude = answeringOwnCalls(withBareRefusals(checkingKeys(runtime.claude, toaster.toast, runtime.steps.keys ?? {})), router)
   const added: string[] = []
-  const hooksAdded: Hook[] = []
   const announce = (feature: string) => {
     added.push(feature)
   }
@@ -680,17 +688,26 @@ async function createMod<State extends object, Declared extends Options>(definit
     }))
   const modState = createState<State>({ name: definition.name, initial: definition.state ?? {}, session, root, claude, report, changed: area.changed, forkParent })
   const modOptions = createOptions({ name: definition.name, declared: definition.options ?? {}, fromClaude: runtime.options, claude, report, changed: modState.changed })
-  const held: HeldDecisions | undefined = runtime.checksPermissions() ? new Map() : undefined
+  const hookOn = <H extends Hook>(hook: H, listener: HookListener<H>): Disposable => router.add(`classic.${hook}`, classicHook(definition.name, hook, listener, report))
   const expand = (path: string) => (homePrefix.test(path) ? resolvedPath(path, places) : path)
   const settingsFile = (source: 'user' | 'project' | 'local'): SettingsFile => ({
     read: () => checked.settings.read({ source }),
     async update(values) {
-      await checkSettings(grants, source, Object.keys(values))
+      await checkSettings(grants, source, values)
       await claude.cmod.call({ to: cmodPluginName, method: 'updateSettings', input: { mod: definition.name, source, project: modState.root, values } })
     },
   })
-  const client = createSessionsClient({ name: definition.name, claude: checked, report: (id, message, error) => report({ id, message, error }), isGranted: (permission) => flag(permission) })
+  const client = createSessionsClient({
+    name: definition.name,
+    claude: checked,
+    report: (id, message, error) => report({ id, message, error }),
+    isGranted: (permission) => flag(permission),
+    hookOn: (hook, listener) => hookOn(hook as Hook, listener as HookListener<Hook>),
+    routeOn: (event, hook) => router.add(event, hook as never),
+  })
   let followed: Parameters<typeof client.follow>[0] | undefined
+  let isSetUp = false
+  const watches = new Set<{ readonly paths: readonly string[]; readonly listener: (change: FileChange) => unknown }>()
   const followFolders = (project: string, folder: string) => {
     if (followed === undefined) return
     followed = { ...followed, project, cwd: folder }
@@ -698,7 +715,16 @@ async function createMod<State extends object, Declared extends Options>(definit
   }
   const imports: Imports = {
     sessions: client.sessions,
-    settings: {
+    commands: {
+      list: async () => (await checked.command.list()).map(({ name, description, source, plugin }) => ({ name, description, source, ...(plugin === undefined ? {} : { plugin }) })),
+      run: async (command, args) => {
+        const { text, context } = await checked.command.run({ command, ...(args === undefined ? {} : { args }) })
+        return { ...(text === undefined ? {} : { text }), ...(context === undefined || context.length === 0 ? {} : { note: context.join('\n') }) }
+      },
+      beforeRun: (...args: unknown[]) => client.listen('beforeRun', args),
+      onRun: (...args: unknown[]) => client.listen('onRun', args),
+    },
+    config: {
       list: async () =>
         (await checked.config.list()).map(({ key, label, description, kind, value, options, provider, isLocked }) => ({
           key,
@@ -710,9 +736,21 @@ async function createMod<State extends object, Declared extends Options>(definit
           ...(options === undefined ? {} : { options }),
           ...(provider.plugin === 'engine' ? {} : { plugin: provider.plugin }),
         })),
+    },
+    settings: {
       user: settingsFile('user'),
       project: settingsFile('project'),
       local: settingsFile('local'),
+      beforeFileChange: (matcherOrListener: unknown, maybeListener?: SettingsFileChangeListener) => {
+        const listener = (maybeListener ?? matcherOrListener) as SettingsFileChangeListener
+        const matcher = maybeListener === undefined ? undefined : matcherOrListener
+        return hookOn('ConfigChange', async ({ source, file_path }) => {
+          const change: SettingsFileChange = { source: source === 'skills' ? 'skills' : (source.replace('_settings', '') as SettingsFileChange['source']), ...(file_path === undefined ? {} : { path: file_path }) }
+          if (matcher !== undefined && !matches(change, matcher)) return undefined
+          const answer = await listener(change)
+          return answer === undefined ? undefined : { decision: 'block', reason: answer.refuse }
+        })
+      },
     },
     model: { complete: (completion, options) => checked.model.complete(completion, options) },
     fs: {
@@ -725,6 +763,19 @@ async function createMod<State extends object, Declared extends Options>(definit
         const { kind, size, mtimeMs, isLink, realPath } = await checked.fs.stat(expand(path), options)
         return { isFile: kind === 'file', isFolder: kind === 'dir', isLink, size, modifiedAt: mtimeMs, ...(realPath === undefined ? {} : { realPath }) }
       },
+      onChange({ path }, listener) {
+        if (isSetUp) throw new Error(`${definition.name}: fs.onChange works only in setup, because Claude Code reads the paths it watches when a session starts.`)
+        const paths = [path].flat().map((each) => resolvedPath(each, places))
+        const watch = { paths, listener }
+        watches.add(watch)
+        if (watches.size === 1) {
+          hookOn('SessionStart', () => ({ hookSpecificOutput: { watchPaths: [...new Set([...watches].flatMap((each) => each.paths))] } }))
+          hookOn('FileChanged', ({ file_path, event }) => {
+            for (const each of watches) if (each.paths.some((watched) => relativePath(watched, file_path) !== undefined)) void Promise.resolve(each.listener({ path: file_path, type: event })).catch((error: unknown) => report({ id: 'fs:onChange', message: 'The fs.onChange listener failed', error }))
+          })
+        }
+        return { dispose: () => void watches.delete(watch) }
+      },
     },
     metadata: {
       read: (path) => files.read(path),
@@ -787,23 +838,10 @@ async function createMod<State extends object, Declared extends Options>(definit
       files: allowed('files'),
       config: allowed('config'),
     },
-    on(hook: Hook, matcherOrListener: unknown, listenerOrOptions?: unknown, maybeOptions?: HookOptions): Disposable {
-      const hasMatcher = typeof listenerOrOptions === 'function'
-      const listener = (hasMatcher ? listenerOrOptions : matcherOrListener) as HookListener<Hook>
-      const matcher = hasMatcher ? matcherOrListener : undefined
-      const options = (hasMatcher ? maybeOptions : listenerOrOptions) as HookOptions | undefined
-      if (!hooks.includes(hook)) throw new Error(`${definition.name}: mod.on takes one of Claude Code's hooks, such as PreToolUse, not ${String(hook)}.`)
-      const matched: HookListener<Hook> = matcher === undefined ? listener : (input) => (matches(input, matcher) ? listener(input) : undefined)
-      const bounded = options?.timeoutMs === undefined ? matched : timedHook(hook, matched, checkedMs(definition.name, `the ${hook} hook's timeoutMs`, options.timeoutMs), claude, toaster.toast)
-      if (!hooksAdded.includes(hook)) hooksAdded.push(hook)
-      if (hook === PreToolUse) return router.add('tool.call', preToolUseHook(definition.name, bounded as HookListener<typeof PreToolUse>, claude, agents, held))
-      const classic: Exclude<Hook, typeof PreToolUse> = hook
-      return router.add(`classic.${classic}`, classicHook(definition.name, classic, bounded as HookListener<typeof classic>, claude, agents, report))
-    },
     every: (ms, listener) => timer(ms, 'every', claude.clock.every, listener),
     after: (ms, listener) => timer(ms, 'after', claude.clock.after, listener),
     use: (job) => job({ mod, announce, reserveName }),
-    log: (text) => claude.ui.log(`${definition.name}: ${text}`, { to: 'debug' }),
+    log: (text, options) => claude.ui.log(`${definition.name}: ${text}`, { to: options?.to ?? 'debug' }),
     ui: { ...area.ui, notice: (callId, text) => claude.ui.notice(callId, text) },
     settings: settingsPages,
     dependencies: dependencyCalls(claude, (call, task) => beforeDeadline(claude, { ms: dependencyCallMs }, call, task)),
@@ -829,8 +867,8 @@ async function createMod<State extends object, Declared extends Options>(definit
       loadedCwd = nextCwd
       if (!hasMovedRoot) area.changed()
       if (nextCwd === oldCwd) return
-      const moved: HookInput<'CwdChanged'> = { session_id: await claude.session.id(), cwd: nextCwd, hook_event_name: 'CwdChanged', old_cwd: oldCwd, new_cwd: nextCwd }
-      await router.dispatch('classic.CwdChanged', moved as Frozen<Args<'classic.CwdChanged'>>, async () => ({}))
+      const moved = { session_id: await claude.session.id(), cwd: nextCwd, hook_event_name: 'CwdChanged', old_cwd: oldCwd, new_cwd: nextCwd }
+      await router.dispatch('classic.CwdChanged', moved as unknown as Frozen<Args<'classic.CwdChanged'>>, async () => ({}))
     } catch (error) {
       report({ id: 'cmod:follow', message: `Keeps the state of ${modState.root} until the next prompt or folder move`, error })
     }
@@ -883,8 +921,8 @@ async function createMod<State extends object, Declared extends Options>(definit
     if (e.to !== definition.name) return next(e)
     const call = e as typeof e & { readonly caller?: string }
     if (e.method === conversationMethods.changed && call.caller === cmodPluginName) {
-      if (!flag('conversation')) return { value: null }
       const { session: changedSession, change, isInProject } = e.input as { readonly session: string; readonly change: SessionChange; readonly isInProject?: boolean }
+      if (changedSession !== client.sessions.current.id && !flag('conversation')) return { value: null }
       client.changed(changedSession, change, isInProject !== false)
       return { value: null }
     }
@@ -915,14 +953,13 @@ async function createMod<State extends object, Declared extends Options>(definit
   if (missing.length > 0) throw new MissingOptions(missing, missing.map((key) => definition.options?.[key]?.title ?? key))
   await failsAs('the details of its session did not load', () => followCurrent(undefined))
   await failsAs('its setup function threw', () => definition.setup(mod))
+  isSetUp = true
   const permissionHooks = permissionEvents.filter((event) => router.has(event))
   if (permissionHooks.length > 0 && !runtime.checksPermissions()) {
     throw new Error(`it decides permissions on ${listed(permissionHooks)}, so hooks/register.ts must call registerPermissionCheck(addHook) after registerMod`)
   }
-  if (held !== undefined && hooksAdded.includes(PreToolUse)) router.add('tool.check', heldDecisionHook(held))
   await failsAs('its open panes did not load', () => area.restorePanes())
-  if (hooksAdded.length > 0) added.push(`${hooksAdded.length === 1 ? 'a hook' : 'hooks'} on ${listed(hooksAdded)}`)
-  return { mod, added, imports }
+  return { mod, added, imports, raise: client.raise }
 }
 
 function checkingKeys(claude: Claude, toast: Toast, keys: Readonly<Record<string, string>>): Claude {
@@ -946,28 +983,6 @@ function checkedMs(name: string, subject: string, ms: number): number {
   return ms
 }
 
-function timedHook<H extends Hook>(event: H, hook: HookListener<H>, ms: number, claude: Claude, toast: Toast): HookListener<H> {
-  return (input) =>
-    new Promise((resolve, reject) => {
-      const timer = claude.clock.after(ms, () => {
-        toast.warning(`The ${event} hook passed its ${ms / 1000} s timeout`, { id: `timeout:${event}` })
-        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()