@cmodjs/core 3.1.0 → 4.0.0

package/runtime/lifecycle.js

@@ -1,4 +1,4 @@
-import { changelogPage, consentPath, dataFolder, finishStepsMethod, isAtLeast, marketplaceOf, oldestCmodFor, openPageMethod, parseConsent, pendingStepsMethod, parseEvent, permissionWords, readRecord, readSteps, recordPath, scriptsSha256, settingsPagesMethod, storeFolder, updatesToTurnOn } from '../records.js';
+import { consentPath, dataFolder, finishStepsMethod, grantFix, coreVersion, isAtLeast, marketplaceOf, parseConsent, pendingStepsMethod, parseEvent, permissionWords, readRecord, readSteps, recordPath, scriptsSha256, storeFolder, updatesToTurnOn } from '../records.js';
 import { homePrefix, ifMissing, relativePath } from '../utils/paths.js';
 import { firstLine, formatExit, messageOf } from '../utils/text.js';
 import { beforeDeadline } from './deadline.js';
@@ -9,7 +9,7 @@ import { answerCall, answeringOwnCalls, cmodPluginName, dependencyCalls, withBar
 import { keepEngine } from './engine.js';
 import { classicFailure, classicHook, userSkillHook } from './hooks.js';
 import { checkedAnswer, checkingGrants, checkSettings, checksAnswers, checkWrite, isCovered, itemOf, passedDown, programAddresses } from './grants.js';
-import { cmodError, lastLineOf, locatingPrograms, readLines } from './programs.js';
+import { cmodError, locatingPrograms, readLines } from './programs.js';
 import { createModFiles, resolvedPath } from './metadata.js';
 import { fitsOption } from '../options.js';
 import { createInstaller } from './installer.js';
@@ -20,11 +20,19 @@ import { matches } from '../utils/matcher.js';
 import { createState } from './state.js';
 import { createToaster } from './toaster.js';
 import { toolCalls } from './tool-calls.js';
-import { createUi } from './ui.js';
+import { createHotkeys } from './hotkeys.js';
+import { servePages } from './pages.js';
+import { drawnParts } from './parts.js';
+import { createWatches } from './watches.js';
+import { createUi, partMethods } from './ui.js';
+import { serveWidgets } from './widgets.js';
 import { Progress } from '../ui/components.js';
 import { Box, Text } from '../ui/elements.js';
 const announcedKey = 'cmod:announced';
+const cmodUpdatedKey = 'cmod:cmod-updated-for';
 const installId = 'cmod:install';
+const askingId = 'cmod:asking';
+const recordId = 'cmod:record';
 const installRetrySeconds = [2, 4, 8, 16, 32, 64, 128];
 const cmodCheckMs = 1000;
 const cmodWaitMs = 60_000;
@@ -32,7 +40,6 @@ const cmodSlowCheckMs = 10_000;
 const hookMs = 10_000;
 const startHoldMs = hookMs - 1_000;
 const dependencyCallMs = 30_000;
-const cannotStart = /failed to start: /;
 const shellTools = ['Bash', 'PowerShell'];
 export async function readPlugin(claude) {
     const { name, root } = claude.plugin;
@@ -58,7 +65,10 @@ export async function readPlugin(claude) {
         read: (path) => read(`${root}/${path}`),
         list: (folder) => filesBelow(claude, `${root}/${folder}`),
     });
-    return { ...plugin, isInstalled: version !== undefined && record?.version === version && record.scriptsSha256 === scripts, shouldRecord: false };
+    if (version === undefined || record?.scriptsSha256 !== scripts)
+        return { ...plugin, isInstalled: false, shouldRecord: false };
+    const isInstalled = record.version === version || record.root === root;
+    return { ...plugin, isInstalled, shouldRecord: isInstalled && record.version !== version };
 }
 async function filesBelow(claude, folder) {
     const entries = await claude.fs.list(folder);
@@ -83,17 +93,18 @@ async function readJson(read, path) {
     }
 }
 async function cmodVersion(claude) {
-    const result = await claude.process.run(['cmod', '--version']).catch((error) => {
-        if (cannotStart.test(messageOf(error)))
-            return undefined;
-        throw error;
-    });
-    if (result === undefined)
+    const store = storeFolder({ HOME: await claude.env.home(), XDG_DATA_HOME: await claude.env.dataHome() });
+    const exists = async (path) => (await claude.fs.stat(path).catch(ifMissing(undefined))) !== undefined;
+    if (!(await exists(`${store}/programs/cmod`)))
         return undefined;
-    if (result.exitCode !== 0)
-        throw new Error(`cmod --version ${formatExit(result.exitCode, lastLineOf(result.stderr) ?? '')}`);
-    return result.stdout.trim().split(/\s+/).at(-1);
+    const versions = (await claude.fs.list(`${store}/bin/cmod`).catch(ifMissing([]))).filter((entry) => entry.kind === 'dir' && releaseVersion.test(entry.name)).map((entry) => entry.name);
+    const newestFirst = versions.toSorted((one, other) => (isAtLeast(one, other) ? -1 : 1));
+    for (const version of newestFirst)
+        if (await exists(`${store}/bin/cmod/${version}/cmod`))
+            return version;
+    return undefined;
 }
+const releaseVersion = /^\d+\.\d+\.\d+$/;
 export function createLifecycle(definition, permissionRoutes = () => undefined, options = {}, asksPerson = true) {
     let router = createRouter();
     let phase = 'starting';
@@ -103,14 +114,25 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
     const granted = new Set();
     let activation;
     let mod;
+    const openSettings = async (tab) => {
+        await claude().cmod.call({ to: cmodPluginName, method: partMethods.changed, input: { requests: [{ settings: true, ...(tab === undefined ? {} : { tab }) }], isAsked: true } });
+    };
     let imports;
     let raise;
     let failure;
     let pluginOptions = options;
-    const installer = createInstaller(definition.name, () => claude());
+    const installer = createInstaller(definition.name, () => claude(), {
+        show: (open) => {
+            if (phase !== 'active')
+                runtime?.toaster.toast.dismiss(installId);
+            runtime?.toaster.toast.info('Installing', { id: askingId, description: 'Waiting for your answer', duration: Infinity, action: { label: 'Answer', onClick: open } });
+        },
+        hide: () => runtime?.toaster.toast.dismiss(askingId),
+    });
     let shouldRecord = false;
     let recording;
     let missedSessionStart;
+    let hasHeardSessionStart = false;
     let settleStart = () => undefined;
     const startSettled = new Promise((resolve) => (settleStart = resolve));
     const claude = () => {
@@ -120,14 +142,15 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
     };
     const installing = (description) => runtime?.toaster.toast.loading('Installing', { id: installId, ...(description === undefined ? {} : { description }) });
     const toastFailure = (shown) => runtime?.toaster.fail(shown);
-    const fail = (reason, fix, retry) => {
+    const fail = (reason, fix, retry, error) => {
         phase = 'failed';
-        failure ??= new Error(`${definition.name}: ${reason}${/[.!?]$/.test(reason) ? '' : '.'}${fix === undefined ? '' : ` ${fix}`}`);
+        failure ??= new Error(`${definition.name}: ${reason}${/[.!?]$/.test(reason) ? '' : '.'}${fix === undefined ? '' : ` ${fix}`}`, { cause: error });
         const again = retry === undefined ? {} : { retry: () => ((failure = undefined), stopRetrying(), retry().catch(report)) };
-        toastFailure({ id: installId, message: reason, ...(fix === undefined ? {} : { description: fix }), ...again });
+        toastFailure({ id: installId, message: reason, ...(fix === undefined ? {} : { description: fix }), ...(error === undefined ? {} : { error }), ...again });
     };
     let consented;
     const installAgain = () => install(consented);
+    const updateAgain = () => claude().store.delete(cmodUpdatedKey).then(installAgain);
     let retrying;
     const retryLater = (next) => {
         const seconds = installRetrySeconds[Math.min(next.tries, installRetrySeconds.length - 1)];
@@ -139,47 +162,47 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
         retrying?.timer.cancel();
         retrying = undefined;
     };
-    const checkoutState = async () => {
-        if (plugin === undefined)
-            return undefined;
-        const lines = [];
-        const { code } = await readLines(claude().process.spawn({ argv: ['sh', '-c', 'git rev-parse HEAD && git status --porcelain=v1 -uall && git diff HEAD'], cwd: plugin.root }), (text) => void lines.push(text));
-        return code === 0 ? lines.join('\n') : undefined;
-    };
-    const failInstall = async (reason, when) => {
+    const failInstall = (reason, when) => {
         if (when === undefined) {
             stopRetrying();
             return fail(reason, undefined, installAgain);
         }
-        retryLater({ when, tries: retrying?.when === when ? retrying.tries : 0, checkout: when === 'changed' ? await checkoutState() : undefined, reason });
+        retryLater({ when, tries: retrying?.when === when ? retrying.tries : 0, reason });
     };
     const retryInBackground = async () => {
-        const waiting = retrying;
-        if (phase !== 'failed' || waiting === undefined)
+        if (phase !== 'failed' || retrying === undefined)
             return;
         if (await recover()) {
             stopRetrying();
             return whenActive();
         }
-        if (waiting.when === 'changed' && waiting.checkout !== undefined && (await checkoutState()) === waiting.checkout)
-            return retryLater(waiting);
         await install(consented, true);
         await whenActive();
     };
     const finish = async () => {
         await programs?.refresh();
         phase = 'ready';
+        activation ??= new Promise((resolve) => claude().clock.after(0, () => resolve(activate().catch(report))));
         claude().ui.invalidate('ui.render');
     };
     const recordThroughCmod = async () => {
         if (plugin === undefined || (await cmodVersion(claude())) === undefined)
             return;
+        let failed;
         const { code, lastError } = await readLines(claude().process.spawn({ argv: ['cmod', 'setup', plugin.root, '--events'] }), (text) => {
-            if (parseEvent(text).type === 'done')
+            const event = parseEvent(text);
+            if (event.type === 'done')
                 shouldRecord = false;
+            if (event.type === 'failed')
+                failed = event.message;
         });
-        if (shouldRecord)
-            throw new Error(`cmod setup ${formatExit(code, lastError)}`);
+        if (!shouldRecord) {
+            runtime?.toaster.toast.dismiss(recordId);
+            return programs?.refresh();
+        }
+        if (failed !== undefined)
+            return void toastFailure({ id: recordId, message: failed, retry: record });
+        throw new Error(`cmod setup ${formatExit(code, lastError)}`);
     };
     const record = () => {
         recording ??= recordThroughCmod()
@@ -239,9 +262,9 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
             if (!isAnswered) {
                 runtime?.toaster.toast.warning(steps.length - index === 1 ? 'Needs one more step' : `Needs ${steps.length - index} more steps`, {
                     id: 'cmod:steps',
-                    description: `Starting with ${step.title}. Finish them in /mods ${definition.name}.`,
+                    description: `Starting with ${step.title}.`,
                     duration: Infinity,
-                    action: { label: 'Finish', onClick: () => active.settings.open() },
+                    action: { label: 'Finish', onClick: () => runSteps(active) },
                 });
                 break;
             }
@@ -255,7 +278,7 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
         const active = await createMod(definition, { ...runtime, router: activeRouter, dataFolder: dataFolder(plugin.store, plugin.name), store: plugin.store, steps: plugin.steps, granted, refreshGrants, permissionRoutes, options: pluginOptions }).catch(async (error) => {
             if (error instanceof MissingOptions && (await askOptions(error)))
                 return undefined;
-            fail(messageOf(error), error instanceof MissingOptions ? `Set ${error.keys.length === 1 ? 'it' : 'them'} in /config.` : undefined, begin);
+            fail(messageOf(error), error instanceof MissingOptions ? `Retry asks for ${error.keys.length === 1 ? 'it' : 'them'}.` : undefined, begin, error);
             throw error;
         });
         if (active === undefined)
@@ -270,20 +293,8 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
         void runSteps(active.mod).catch((error) => toastFailure({ id: 'cmod:steps', message: 'Its installer stopped', error }));
         const missed = missedSessionStart;
         missedSessionStart = undefined;
-        const replay = (e) => (definition.name === cmodPluginName ? activeRouter.dispatch('classic.SessionStart', e, async () => ({})) : checkedRoute('classic.SessionStart', e, async () => ({})));
-        const lateAnswer = missed === undefined ? {} : await replay(missed).catch((error) => {
-            toastFailure({ id: 'classic.SessionStart', message: 'The SessionStart hook failed', error });
-            return {};
-        });
-        const { additionalContext, ...unread } = lateAnswer;
-        for (const text of additionalContext ?? []) {
-            const added = await runtime.claude.session.append({ message: { type: 'user', content: [{ type: 'text', text }] } });
-            if (added.deny !== undefined)
-                runtime.claude.ui.log(`${definition.name}: Claude Code refused its SessionStart note: ${added.deny}`, { to: 'debug' });
-        }
-        if (Object.keys(unread).length > 0) {
-            runtime.claude.ui.log(`${definition.name} started after Claude Code's SessionStart, so Claude Code did not read ${Object.keys(unread).join(', ')} from its SessionStart hooks.`, { to: 'debug' });
-        }
+        if (missed !== undefined)
+            await replaySessionStart(missed);
         const version = plugin.version ?? '';
         const announced = announcedOf(await runtime.claude.store.get(announcedKey));
         if (announced?.version === version) {
@@ -292,10 +303,27 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
         }
         await runtime.claude.store.set(announcedKey, { version, added });
         const { toaster } = runtime;
-        void announcementOf(runtime.claude, plugin, granted, added, announced)
+        void announcementOf(runtime.claude, plugin, granted, added, announced, openSettings)
             .then(({ message, ...options }) => toaster.toast.success(message, { id: installId, duration: announcementMs, ...options }))
             .catch((error) => toastFailure({ id: installId, message: 'Could not say what it installed', error }));
     };
+    const replaySessionStart = async (e) => {
+        hasHeardSessionStart = true;
+        const ran = definition.name === cmodPluginName ? router.dispatch('classic.SessionStart', e, async () => ({})) : checkedRoute('classic.SessionStart', e, async () => ({}));
+        const answer = await ran.catch((error) => {
+            toastFailure({ id: 'classic.SessionStart', message: 'The SessionStart hook failed', error });
+            return {};
+        });
+        const { additionalContext, ...unread } = answer;
+        for (const text of additionalContext ?? []) {
+            const added = await claude().session.append({ message: { type: 'user', content: [{ type: 'text', text }] } });
+            if (added.deny !== undefined)
+                claude().ui.log(`${definition.name}: Claude Code refused its SessionStart note: ${added.deny}`, { to: 'debug' });
+        }
+        if (Object.keys(unread).length > 0) {
+            claude().ui.log(`${definition.name} started after Claude Code's SessionStart, so Claude Code did not read ${Object.keys(unread).join(', ')} from its SessionStart hooks.`, { to: 'debug' });
+        }
+    };
     const updatesToShow = async () => {
         const [home, configHome] = await Promise.all([claude().env.home(), claude().env.configHome()]);
         const configRoot = configHome ?? `${home ?? ''}/.claude`;
@@ -311,7 +339,6 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
             claude().ui.log(`${name} waits for consent to run ${event.install}. Run cmod install ${name} in a terminal.`);
             return;
         }
-        runtime?.toaster.toast.info('Installing', { id: installId, description: 'Waiting for your answer', duration: Infinity });
         const updates = await updatesToShow().catch((error) => {
             toastFailure({ id: 'cmod:updates', message: 'Could not read whether its marketplace updates automatically', error });
             return undefined;
@@ -358,7 +385,7 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
             return askConsent(outcome);
         return failInstall(outcome?.type === 'failed' ? outcome.message : `cmod setup ${formatExit(code, lastError)}`, retries);
     };
-    const fits = (found) => found !== undefined && isAtLeast(found, oldestCmodFor(plugin?.steps ?? {}));
+    const fits = (found) => found !== undefined && isAtLeast(found, coreVersion);
     const waitForcmod = (found) => {
         phase = 'waiting';
         installing('Waiting for cmod');
@@ -387,9 +414,26 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
         const longWait = claude().clock.after(cmodWaitMs, () => {
             timer.cancel();
             timer = poll(cmodSlowCheckMs);
-            installing(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?.steps ?? {})} or later. Run npm i -g @cmodjs/cli, or put ~/.local/bin ahead of the old cmod on PATH.`);
+            if (latest === undefined)
+                return installing("Still waiting for cmod to download cmod. See cmod's own line.");
+            const found = latest;
+            const tried = `${found} to ${coreVersion}`;
+            return claude()
+                .store.get(cmodUpdatedKey)
+                .then(async (updated) => {
+                if (updated === tried) {
+                    stop();
+                    return fail(`${definition.name} needs cmod ${coreVersion} or later, and the newest cmod is ${found}.`, undefined, updateAgain);
+                }
+                await claude().store.set(cmodUpdatedKey, tried);
+                installing(`${definition.name} needs cmod ${coreVersion} or later, and this computer has cmod ${found}, so cmod is updating itself.`);
+                const { code, lastError } = await readLines(claude().process.spawn({ argv: ['cmod', 'update', 'cmod'] }), () => undefined);
+                if (code === 0)
+                    return;
+                stop();
+                fail(`${definition.name} needs cmod ${coreVersion} or later, and updating cmod ${found} ${formatExit(code, lastError)}`, undefined, updateAgain);
+            })
+                .catch(report);
         });
     };
     const bootstrap = async (root) => {
@@ -427,7 +471,7 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
     const report = (error) => {
         failure = error;
         if (phase !== 'failed')
-            fail(messageOf(error), undefined, begin);
+            fail(messageOf(error), undefined, begin, error);
     };
     let consentMs = 0;
     const stampOf = async (path) => {
@@ -479,8 +523,13 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
                 return;
             droppedParts.add(item);
             const declared = plugin?.steps.permissions ?? [];
-            const fix = declared.includes(item) ? `Turn it on in /mods ${definition.name}.` : `It needs "permissions": { "${item}": true } in package.json "cmod".`;
-            runtime?.toaster.toast.warning(`Answered ${part} without your grant to "${permissionWords(item)}", so cmod dropped it`, { id: `dropped:${item}`, description: fix, duration: Infinity });
+            const isDeclared = declared.includes(item);
+            runtime?.toaster.toast.warning(`Answered ${part} without your grant to "${permissionWords(item)}", so cmod dropped it`, {
+                id: `dropped:${item}`,
+                description: isDeclared ? grantFix : `It needs "permissions": { "${item}": true } in package.json "cmod".`,
+                duration: Infinity,
+                ...(isDeclared ? { action: { label: 'Settings', onClick: () => openSettings('permissions') } } : {}),
+            });
         },
     };
     const checkedRoute = async (event, e, next) => {
@@ -527,7 +576,7 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
             if (runtime !== undefined)
                 return;
             programs = locatingPrograms(claudeCalls);
-            runtime = { claude: programs.claude, toaster: createToaster(claudeCalls, definition.name, () => plugin?.version) };
+            runtime = { claude: programs.claude, toaster: createToaster(claudeCalls, definition.name, () => plugin?.version, () => openSettings('permissions')) };
             readStarted = read;
             try {
                 await programs.refresh();
@@ -544,8 +593,10 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
                 return installer.draw(e);
             if (event === 'ui.close')
                 installer.closed(e.id);
-            if (event === 'classic.SessionStart')
+            if (event === 'classic.SessionStart') {
                 missedSessionStart = undefined;
+                hasHeardSessionStart = true;
+            }
             if (event === 'classic.SessionStart' && runtime === undefined) {
                 missedSessionStart = e;
                 return next(e);
@@ -575,6 +626,10 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
             }
             if (event === 'classic.UserPromptSubmit' || event === 'classic.SessionStart')
                 await refreshGrants().catch((error) => claude().ui.log(`${definition.name} keeps its grants from before: ${messageOf(error)}`, { to: 'debug' }));
+            if (event === 'classic.UserPromptSubmit' && phase === 'active' && !hasHeardSessionStart) {
+                const { session_id, transcript_path, cwd } = e;
+                await replaySessionStart({ session_id, transcript_path, cwd, hook_event_name: 'SessionStart', source: 'resume' });
+            }
             if (checksAnswers(event) && phase === 'active' && definition.name !== cmodPluginName)
                 return checkedRoute(event, e, next);
             const answer = router.dispatch(event, e, next);
@@ -599,7 +654,7 @@ export function createLifecycle(definition, permissionRoutes = () => undefined,
 async function createMod(definition, runtime) {
     const { router, toaster } = runtime;
     const report = (failure) => void toaster.fail(failure);
-    const claude = answeringOwnCalls(withBareRefusals(checkingKeys(runtime.claude, toaster.toast, runtime.steps.keys ?? {})), router);
+    const claude = answeringOwnCalls(withBareRefusals(runtime.claude), router);
     const added = [];
     const announce = (feature) => {
         added.push(feature);
@@ -627,26 +682,6 @@ async function createMod(definition, runtime) {
         checkWrite: (path) => checkWrite(grants, `metadata.update(${path})`, path),
         report,
     });
-    const pages = new Map();
-    const settingsPages = {
-        page(page) {
-            if (pages.has(page.id))
-                throw new Error(`${definition.name}: the settings page "${page.id}" is already added. Give each page its own id.`);
-            if (page.id === changelogPage)
-                throw new Error(`${definition.name}: the settings page id "${changelogPage}" opens the mod's CHANGELOG.md in /mods. Give the page another id.`);
-            pages.set(page.id, { title: page.title, handle: area.ui.pane(page) });
-        },
-        async open(pageId) {
-            if (pageId === undefined) {
-                await claude.cmod.call({ to: cmodPluginName, method: 'openSettings', input: { mod: definition.name } });
-                return;
-            }
-            const page = pages.get(pageId);
-            if (page === undefined)
-                throw new Error(`${definition.name} has no settings page "${pageId}". It has: ${[...pages.keys()].join(', ') || 'none'}.`);
-            await page.handle.open({ focus: true });
-        },
-    };
     let cwd = startCwd;
     let loadedCwd = startCwd;
     let staleCwd;
@@ -654,7 +689,7 @@ async function createMod(definition, runtime) {
     let parentAsked;
     let hasEarlierPrompts = true;
     let agentType;
-    const area = createUi({ name: definition.name, claude, router, toaster, report, announce, mod: () => mod });
+    const area = createUi({ name: definition.name, claude, router, report, announce, mod: () => mod });
     const askParent = async () => {
         if (definition.name === cmodPluginName)
             return undefined;
@@ -692,8 +727,7 @@ async function createMod(definition, runtime) {
         permissionRoutes: runtime.permissionRoutes,
     });
     let followed;
-    let isSetUp = false;
-    const watches = new Set();
+    const watches = createWatches(claude, report);
     const followFolders = (project, folder) => {
         if (followed === undefined)
             return;
@@ -750,23 +784,10 @@ async function createMod(definition, runtime) {
                 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', () => ({ 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) => report({ id: 'fs:onChange', message: 'The fs.onChange listener failed', error }));
-                        return undefined;
-                    });
-                }
-                return { dispose: () => void watches.delete(watch) };
-            },
+            onChange: ({ path }, listener) => watches.add([path].flat().map((each) => resolvedPath(each, places)), (change) => {
+                bind(imports);
+                return listener(change);
+            }),
         },
         metadata: {
             read: (path) => files.read(path),
@@ -777,15 +798,23 @@ async function createMod(definition, runtime) {
             spawn: (argv, init) => checked.process.spawn({ ...init, argv }),
         },
         http: { fetch: (url, init) => checked.http.fetch(url, init) },
+        clipboard: {
+            async write(text) {
+                await toaster.copy(text);
+            },
+        },
     };
     const allowed = (permission) => ({ allows: (value) => isCovered(granted, itemOf(permission, value), home) });
     const flag = (permission) => isCovered(granted, permission, home);
-    const timer = (ms, subject, start, listener) => {
-        let isRunning = false;
-        const started = start(checkedMs(definition.name, `mod.${subject}`, ms), () => {
-            if (isRunning)
+    const timer = (ms, subject, repeats, listener) => {
+        let isFiring = false;
+        let isRunning = true;
+        const fire = () => {
+            if (!repeats)
+                isRunning = false;
+            if (isFiring)
                 return;
-            isRunning = true;
+            isFiring = true;
             void Promise.resolve()
                 .then(() => {
                 bind(imports);
@@ -793,11 +822,22 @@ async function createMod(definition, runtime) {
             })
                 .catch((error) => report({ id: `${subject}:${ms}`, message: `The ${subject} ${ms} ms timer failed`, error }))
                 .finally(() => {
-                isRunning = false;
+                isFiring = false;
             });
-        });
-        return { dispose: () => started.cancel() };
+        };
+        const checked = checkedMs(definition.name, `mod.${subject}`, ms);
+        const started = repeats ? claude.clock.every(checked, fire) : claude.clock.after(checked, fire);
+        return {
+            get isRunning() {
+                return isRunning;
+            },
+            stop() {
+                isRunning = false;
+                started.cancel();
+            },
+        };
     };
+    const hotkeys = await createHotkeys({ name: definition.name, declared: definition.hotkeys ?? {}, configRoot, claude, router, answerInput: area.answerInput, report });
     const mod = {
         name: definition.name,
         folder: claude.plugin.root,
@@ -830,12 +870,18 @@ async function createMod(definition, runtime) {
             files: allowed('files'),
             config: allowed('config'),
         },
-        every: (ms, listener) => timer(ms, 'every', claude.clock.every, listener),
-        after: (ms, listener) => timer(ms, 'after', claude.clock.after, listener),
+        hotkeys,
+        every: (ms, listener) => timer(ms, 'every', true, listener),
+        after: (ms, listener) => timer(ms, 'after', false, listener),
         use: (job) => job({ mod, announce, reserveName }),
         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,
+        panes: area.panes,
+        sidebar: area.sidebar,
+        settings: area.settings,
+        widgets: area.widgets,
+        styles: area.styles,
+        toast: toaster.toast,
+        ask: (question, options) => claude.ui.ask(question, options),
         dependencies: dependencyCalls(claude, (call, task) => beforeDeadline(claude, { ms: dependencyCallMs }, call, task)),
     };
     bind(imports);
@@ -917,8 +963,14 @@ async function createMod(definition, runtime) {
         return answer;
     });
     router.add('skill.prompt', userSkillHook(claude));
-    const api = Object.fromEntries(Object.entries(definition.api ?? {}).map(([method, run]) => [method, (input) => run(input, mod)]));
-    const conversations = definition.name === cmodPluginName ? serveConversations({ claude, router, store: runtime.store, project: () => modState.root, report: (id, message, error) => report({ id, message, error }) }) : undefined;
+    router.add('ui.press', (e, next) => area.asked(() => next(e)));
+    let api = {};
+    const conversations = definition.name === cmodPluginName ? serveConversations({ claude, router, store: runtime.store, project: () => modState.root, report: (id, message, error) => report({ id, message, error }), clear: (id) => toaster.toast.dismiss(id) }) : undefined;
+    let pages;
+    const reportPart = (id, message, error) => report({ id, message, error });
+    const parts = drawnParts({ claude, report: reportPart, press: (to, input) => pages?.press(to, input) });
+    const widgets = conversations === undefined ? undefined : serveWidgets({ claude, router, store: runtime.store, report: reportPart, turnClosedBy: (rowId) => conversations.turnClosedBy(rowId), parts });
+    pages = widgets === undefined ? undefined : servePages({ claude, router, report: reportPart, widgets, parts });
     router.add('cmod.call', async (e, next) => {
         if (e.to !== definition.name)
             return next(e);
@@ -933,11 +985,14 @@ async function createMod(definition, runtime) {
         const ask = beforeAskOf(call);
         if (ask !== undefined)
             return { value: (await client.answerBefore(ask.session, ask.event, ask.change, ask.isInProject)) ?? null };
-        if (e.method === settingsPagesMethod)
-            return { value: [...pages].map(([id, { title }]) => ({ id, title })) };
-        if (e.method === openPageMethod) {
-            await settingsPages.open(String(e.input));
-            return { value: null };
+        if (e.method === partMethods.changed && call.caller !== undefined && pages !== undefined) {
+            return { value: { isHeld: pages.update(call.caller, e.input) } };
+        }
+        if (call.caller === cmodPluginName) {
+            const turn = e.method === partMethods.draw ? e.input.turn : undefined;
+            const answered = area.answer(e.method, turn === undefined ? e.input : { ...e.input, turn: client.turn(turn) });
+            if (answered !== undefined)
+                return answered;
         }
         const served = await conversations?.answer(call);
         return served ?? answerCall(definition.name, api, e);
@@ -948,14 +1003,14 @@ async function createMod(definition, runtime) {
         return ask === undefined ? { deny: `${definition.name}: ${error.message}` } : { value: client.failedBefore(ask.session, ask.event, ask.change, ask.isInProject, error) ?? null };
     });
     const agents = toolCalls(claude, router);
-    keepEngine(mod, { claude: checked, router, toolCalls: agents, report, hasPermissionCheck: () => runtime.permissionRoutes() !== undefined });
+    keepEngine(mod, { claude: checked, router, toolCalls: agents, report, hasPermissionCheck: () => runtime.permissionRoutes() !== undefined, answerInput: area.answerInput, ...(widgets === undefined ? {} : { widgets }), ...(pages === undefined ? {} : { pages }) });
     const names = new Set();
     const reserveName = (type, name, taken) => {
         const key = `${type}:${name}`;
         if (names.has(key))
             throw new Error(taken);
         names.add(key);
-        return { dispose: () => void names.delete(key) };
+        return { remove: () => void names.delete(key) };
     };
     await failsAs('its state did not load', () => modState.load());
     await failsAs('its options did not load', () => modOptions.load(root));
@@ -963,24 +1018,18 @@ async function createMod(definition, runtime) {
     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 returned = await failsAs('its setup function threw', () => definition.setup(mod));
+    api = apiOf(definition.name, returned);
     await failsAs('its open panes did not load', () => area.restorePanes());
-    return { mod, added, imports, raise: client.raise };
+    area.started();
+    return { mod, added, imports, raise: client.raise, area };
 }
-function checkingKeys(claude, toast, keys) {
-    const bound = Object.entries(keys);
-    if (bound.length === 0)
-        return claude;
-    const addCommand = (command) => {
-        for (const [key, commandName] of bound) {
-            if (commandName === command.name && command.immediate !== true) {
-                toast.warning(`${key} runs /${command.name}, which waits for Claude's turn to end`, { id: `key:${key}`, description: `It adds a row to the conversation. Give /${command.name} immediate: true.`, duration: Infinity });
-            }
-        }
-        return claude.command.register(command);
-    };
-    return { ...claude, command: { ...claude.command, register: addCommand } };
+function apiOf(name, returned) {
+    if (returned === undefined || returned === null)
+        return {};
+    if (typeof returned !== 'object' || !Object.values(returned).every((method) => typeof method === 'function'))
+        throw new Error(`${name}: setup returns its API, an object of methods other mods call, or nothing. It returned ${typeof returned === 'object' ? 'an object with values that are not methods' : typeof returned}.`);
+    return returned;
 }
 const longestTimerMs = 2_147_483_647;
 function checkedMs(name, subject, ms) {
@@ -996,7 +1045,7 @@ function beforeAskOf(call) {
 }
 async function failsAs(subject, step) {
     try {
-        await step();
+        return await step();
     }
     catch (error) {
         throw new Error(`${subject}: ${messageOf(error)}`, { cause: error });

package/runtime/options.js

@@ -1,5 +1,5 @@
 import { fitsOption, isUnset } from '../options.js';
-import { configFolders } from '../records.js';
+import { configFolders, secretFix } from '../records.js';
 import { listed, messageOf } from '../utils/text.js';
 export class MissingOptions extends Error {
     keys;
@@ -50,7 +50,7 @@ export function createOptions({ name, declared, fromClaude, claude, report, chan
             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.type === 'secret')
-                ignore(`sets ${key}, a secret, and a project file is committed for everyone to read. Remove it, and set it in /config.`);
+                ignore(`sets ${key}, a secret, and a project file is committed for everyone to read. Remove it. ${secretFix}`);
             else {
                 const misfit = fitsOption(option, value);
                 if (misfit === undefined)