@cmodjs/core 3.1.0 → 4.0.0

package/runtime/ui.js

@@ -1,8 +1,18 @@
-import { Box, drawWith, Text } from '../ui/elements.js';
-import { componentOf, nameOf } from '../ui/places.js';
+import { isObject } from '../records.js';
+import { TurnEnd } from '../ui/areas.js';
+import { Box, drawWith, elementData, Text } from '../ui/elements.js';
+import { checkPane, checkPart, sizeKeys } from '../ui/panes.js';
+import { componentOf, nameOf } from '../ui/styles.js';
 import { messageOf } from '../utils/text.js';
+import { cmodPluginName } from './dependencies.js';
+export const partMethods = {
+    list: 'cmod:parts',
+    draw: 'cmod:draw',
+    press: 'cmod:press',
+    shown: 'cmod:shown',
+    changed: 'cmod:partsChanged',
+};
 const bullet = '⏺';
-const sizeKeys = ['columns', 'rows'];
 function paneSize(pane, state) {
     const size = {};
     for (const key of sizeKeys) {
@@ -65,7 +75,14 @@ function drawPieces(pieces, place) {
         return Box({ children: [Box({ minWidth: 2, children: Text({ color: 'text', children: bullet }) }), column(spaced)] });
     return column([opening, Box({ paddingLeft: 2, children: column(rest) })]);
 }
-export function createUi({ name, claude, router, toaster, report, announce, mod }) {
+function merged(updates) {
+    const parts = updates.findLast((update) => update.parts !== undefined)?.parts;
+    const requests = updates.flatMap((update) => update.requests ?? []);
+    const isRedrawn = updates.some((update) => update.redraw === true);
+    return { ...(parts === undefined ? {} : { parts }), ...(isRedrawn ? { redraw: true } : {}), ...(requests.length === 0 ? {} : { requests }) };
+}
+const keptDrawInputs = 200;
+export function createUi({ name, claude, router, report, announce, mod }) {
     const panes = new Map();
     const paneLogs = new Map();
     const openPanes = new Set();
@@ -81,16 +98,76 @@ export function createUi({ name, claude, router, toaster, report, announce, mod
     };
     const readPanes = () => void syncPanes().catch((error) => claude.ui.log(`${name} keeps its panes' shown and focused state from before: ${messageOf(error)}`, { to: 'debug' }));
     const requestedSizes = new Map();
-    const renders = new Set();
+    const styles = new Set();
     const markdownRenders = new Map();
     let read;
     let isRouted = false;
     let isResizeQueued = false;
+    const widgets = new Map();
+    const widgetAreas = new Map();
+    const pages = new Map();
+    let shownPages = { open: [], shown: null, isFocused: false };
+    const draws = new Map();
+    const latestDraws = new Map();
+    const failedDraws = new Set();
+    let drawCount = 0;
+    let beforeStart = [];
+    let askedDepth = 0;
+    let unheldRequests = 0;
+    let collected;
+    let queued;
+    const partList = () => ({
+        widgets: [...widgets.values()].map(({ id, title, areas: listed }) => ({ id, title, areas: listed })),
+        pages: [...pages.values()].map(({ init: { id, title }, place }) => ({ id, title, place })),
+    });
+    const send = (update) => {
+        if (collected !== undefined)
+            return void collected.push(update);
+        if (beforeStart !== undefined)
+            return void beforeStart.push(update);
+        const isAsked = askedDepth > 0;
+        if (queued !== undefined && !isAsked)
+            return void queued.push(update);
+        const batch = [update];
+        if (!isAsked)
+            queued = batch;
+        const tell = () => {
+            if (queued === batch)
+                queued = undefined;
+            const input = { ...merged(batch), ...(isAsked ? { isAsked: true } : {}) };
+            return claude.cmod.call({ to: cmodPluginName, method: partMethods.changed, input }).then((answer) => {
+                if (isAsked && input.requests !== undefined && !(isObject(answer) && answer['isHeld'] === true))
+                    unheldRequests += 1;
+            }, (error) => claude.ui.log(`${name}: the cmod plugin did not hear about its pages and widgets: ${messageOf(error)}`, { to: 'debug' }));
+        };
+        return isAsked ? tell() : Promise.resolve().then(tell);
+    };
+    const asked = async (run) => {
+        askedDepth += 1;
+        try {
+            return await run();
+        }
+        finally {
+            askedDepth -= 1;
+        }
+    };
+    const collect = async (run) => {
+        const outer = collected;
+        const mine = [];
+        collected = mine;
+        try {
+            await run();
+        }
+        finally {
+            collected = outer;
+        }
+        return merged(mine);
+    };
     const logOnce = (what) => {
         let hasLogged = false;
         return (failure) => {
             if (!hasLogged)
-                report({ id: `render:${what}`, message: `The ${what} render failed`, description: failure });
+                report({ id: `draw:${what}`, message: `The ${what} failed`, description: failure });
             hasLogged = true;
         };
     };
@@ -162,32 +239,41 @@ export function createUi({ name, claude, router, toaster, report, announce, mod
             claude.ui.log(`${name}: the ${pane.title} pane kept its size: ${messageOf(error)}`, { to: 'debug' });
         }
     };
-    const route = () => {
+    const handle = async (pane, handler, run) => {
+        try {
+            await run();
+        }
+        catch (error) {
+            report({ id: `pane:${pane.id}:${handler}`, message: `The ${pane.title} pane's ${handler} threw`, error });
+        }
+    };
+    const routePanes = () => {
         if (isRouted)
             return;
         isRouted = true;
         router.add('ui.render', (e, next) => {
-            const pane = panes.get(e.requestId);
-            if (pane === undefined || e.component !== 'Pane')
+            const added = panes.get(e.requestId);
+            if (added === undefined || e.component !== 'Pane')
                 return next(e);
-            openPanes.add(pane.id);
-            paneStates.set(pane.id, { isShown: true, isFocused: e.props.isFocused });
+            const { init } = added;
+            openPanes.add(init.id);
+            paneStates.set(init.id, { isShown: true, isFocused: e.props.isFocused });
             readPanes();
             const table = claude.ui.resolve(e);
             try {
-                return drawWith(table, () => pane.render(mod(), e.props), markdownIn(table));
+                return drawWith(table, () => init.render(mod(), { ...e.props, params: added.params }), markdownIn(table));
             }
             catch (error) {
-                paneLogs.get(pane.id)?.(`threw: ${messageOf(error)}`);
-                return drawWith(table, () => Text({ color: 'error', children: `The ${pane.title} pane could not draw: ${messageOf(error)}` }));
+                paneLogs.get(init.id)?.(`threw: ${messageOf(error)}`);
+                return drawWith(table, () => Text({ color: 'error', children: `The ${init.title} pane could not draw: ${messageOf(error)}` }));
             }
         });
         router.add('ui.scroll', async (e, next) => {
-            const pane = panes.get(e.requestId);
+            const init = panes.get(e.requestId)?.init;
             const moved = await next(e);
-            if (pane?.onScroll === undefined || e.component !== 'Pane' || moved.deny !== undefined)
+            if (init?.onScroll === undefined || e.component !== 'Pane' || moved.deny !== undefined)
                 return moved;
-            await handle(pane, 'onScroll', () => pane.onScroll?.(mod(), e));
+            await handle(init, 'onScroll', () => init.onScroll?.(mod(), e));
             return moved;
         });
         router.add('ui.close', async (e, next) => {
@@ -195,107 +281,284 @@ export function createUi({ name, claude, router, toaster, report, announce, mod
             paneStates.delete(e.id);
             readPanes();
             const closed = await next(e);
-            const pane = panes.get(e.id);
-            if (pane?.onClose !== undefined)
-                await handle(pane, 'onClose', () => pane.onClose?.(mod(), e));
+            const init = panes.get(e.id)?.init;
+            if (init?.onClose !== undefined)
+                await handle(init, 'onClose', () => init.onClose?.(mod(), e));
             return closed;
         });
     };
-    const handle = async (pane, handler, run) => {
+    const scrollIn = (id, target, options) => claude.ui.scroll({ to: target, in: id, ...(options?.block === undefined ? {} : { block: options.block }) }).then(({ deny }) => {
+        if (deny !== undefined)
+            throw new Error(`${name}: Claude Code did not scroll ${id}: ${deny}`);
+    });
+    const addPane = (init) => {
+        checkPane(name, init);
+        if (panes.has(init.id))
+            throw new Error(`${name}: the pane "${init.id}" is already added. Give each pane its own id.`);
+        const added = { init, params: undefined };
+        panes.set(init.id, added);
+        paneLogs.set(init.id, logOnce(`${init.title} pane`));
+        announce(`the ${init.title} pane`);
+        routePanes();
+        const sized = init;
+        const pane = {
+            id: init.id,
+            get isOpen() {
+                return openPanes.has(init.id);
+            },
+            get isShown() {
+                return paneStates.get(init.id)?.isShown ?? false;
+            },
+            get isFocused() {
+                return paneStates.get(init.id)?.isFocused ?? false;
+            },
+            get params() {
+                return added.params;
+            },
+            async open(...[options]) {
+                if (options !== undefined && 'params' in options)
+                    added.params = options.params;
+                const { isPlaced } = await openAt(sized, paneSize(sized, mod().state), options?.focus);
+                if (isPlaced)
+                    openPanes.add(init.id);
+                await syncPanes();
+                claude.ui.invalidate('ui.render');
+            },
+            async close() {
+                await claude.ui.close({ id: init.id });
+                openPanes.delete(init.id);
+                paneStates.delete(init.id);
+                await syncPanes();
+            },
+            toggle: (options) => (openPanes.has(init.id) ? pane.close() : pane.open(options)),
+            scrollTo: (target, options) => scrollIn(init.id, target, options),
+            remove() {
+                if (panes.get(init.id) !== added)
+                    return;
+                panes.delete(init.id);
+                paneLogs.delete(init.id);
+                if (openPanes.has(init.id))
+                    void claude.ui.close({ id: init.id }).catch((error) => claude.ui.log(`${name}: the ${init.title} pane stayed open: ${messageOf(error)}`, { to: 'debug' }));
+                openPanes.delete(init.id);
+                paneStates.delete(init.id);
+            },
+        };
+        return pane;
+    };
+    const pageEntry = (id) => shownPages.open.find((each) => each.id === id);
+    const addPage = (place, init) => {
+        checkPart(name, 'page', init.id, init.title);
+        if (pages.has(init.id))
+            throw new Error(`${name}: the page "${init.id}" is already added. Give each page its own id.`);
+        const added = { init, place, params: undefined };
+        pages.set(init.id, added);
+        announce(place === 'settings' ? `the ${init.title} page in Settings` : `the ${init.title} page in the Sidebar`);
+        void send({ parts: partList() });
+        const page = {
+            id: init.id,
+            get isOpen() {
+                return place === 'settings' ? shownPages.shown === init.id : pageEntry(init.id) !== undefined;
+            },
+            get isShown() {
+                return shownPages.shown === init.id;
+            },
+            get isFocused() {
+                return shownPages.shown === init.id && shownPages.isFocused;
+            },
+            get params() {
+                return (pageEntry(init.id)?.params ?? added.params);
+            },
+            async open(...[options]) {
+                if (options !== undefined && 'params' in options)
+                    added.params = options.params;
+                await send({ requests: [{ open: init.id, ...(added.params === undefined ? {} : { params: added.params }), ...(options?.focus === true ? { focus: true } : {}) }] });
+            },
+            toggle: (options) => (page.isOpen ? page.close() : page.open(options)),
+            close: async () => {
+                await send({ requests: [{ close: init.id }] });
+            },
+            scrollTo: async (target, options) => {
+                await send({ requests: [{ scroll: init.id, to: target, ...(options?.block === undefined ? {} : { block: options.block }) }] });
+            },
+            remove() {
+                if (pages.get(init.id) !== added)
+                    return;
+                pages.delete(init.id);
+                forgetDraws(`page:${init.id}`);
+                void send({ parts: partList(), requests: [{ close: init.id }] });
+            },
+        };
+        return page;
+    };
+    const addWidget = (init) => {
+        checkPart(name, 'widget', init.id, init.title);
+        if (widgets.has(init.id))
+            throw new Error(`${name}: the widget "${init.id}" is already added. Give each widget its own id.`);
+        widgets.set(init.id, init);
+        announce(`the ${init.title} widget`);
+        void send({ parts: partList() });
+        return {
+            id: init.id,
+            get area() {
+                return widgetAreas.get(init.id);
+            },
+            remove() {
+                if (widgets.get(init.id) !== init)
+                    return;
+                widgets.delete(init.id);
+                widgetAreas.delete(init.id);
+                forgetDraws(`widget:${init.id}`);
+                void send({ parts: partList() });
+            },
+        };
+    };
+    const addStyle = ({ kind, render }) => {
+        const markdown = typeof kind === 'string' ? undefined : kind;
+        const component = componentOf(kind);
+        if (markdown === undefined && component === undefined)
+            throw new Error(`${name}: ${String(kind)} is not a kind styles.add draws, such as ToolCall or CodeBlock.`);
+        const feature = `the style of ${nameOf(kind)}`;
+        if (styles.has(feature))
+            throw new Error(`${name}: ${feature} is already added. Add one style per kind.`);
+        styles.add(feature);
+        announce(feature);
+        const Component = (props) => render(mod(), props);
+        const stop = (subscription) => () => {
+            subscription?.remove();
+            if (markdown !== undefined)
+                markdownRenders.delete(markdown.markdown);
+            styles.delete(feature);
+            claude.ui.invalidate('ui.render');
+        };
+        if (markdown !== undefined) {
+            markdownRenders.set(markdown.markdown, { Component, log: logOnce(`${nameOf(kind)} style`) });
+            routeMarkdown(markdown.createReader);
+            return { kind, remove: stop() };
+        }
+        const log = logOnce(`${nameOf(kind)} style`);
+        const drawing = router.add('ui.render', async (e, next) => {
+            if (e.component !== component)
+                return next(e);
+            const table = claude.ui.resolve(e);
+            const drawn = await drawComponent(table, (Default) => Component({ ...e.props, Default }), (given, isClaudesRow) => next({ ...e, props: pieceProps(e.props, given, isClaudesRow) }));
+            if ('failure' in drawn) {
+                log(drawn.failure);
+                return next(e);
+            }
+            if (e.component !== 'AssistantMessage')
+                return drawn.drawing;
+            return drawWith(table, () => drawPieces([drawn], e.props.isFirstOfReply ? 'opensReply' : 'inReply'));
+        });
+        return { kind, remove: stop(drawing) };
+    };
+    const forgetDraws = (key) => {
+        for (const kept of latestDraws.get(key)?.values() ?? [])
+            for (const draw of kept)
+                draws.delete(draw);
+        latestDraws.delete(key);
+    };
+    const drawPart = (key, title, input, render) => {
         try {
-            await run();
+            const pressed = [];
+            const drawn = render();
+            const tree = drawn === undefined ? null : elementData(drawn, pressed);
+            failedDraws.delete(key);
+            drawCount += 1;
+            const inputs = latestDraws.get(key) ?? new Map();
+            latestDraws.set(key, inputs);
+            const drawnFor = JSON.stringify('turn' in input ? { ...input, turn: input.turn.prompt.id } : input);
+            const earlier = inputs.get(drawnFor) ?? [];
+            const kept = [...earlier, drawCount].slice(-2);
+            for (const draw of earlier)
+                if (!kept.includes(draw))
+                    draws.delete(draw);
+            inputs.delete(drawnFor);
+            inputs.set(drawnFor, kept);
+            const [oldest] = inputs;
+            if (inputs.size > keptDrawInputs && oldest !== undefined) {
+                for (const draw of oldest[1])
+                    draws.delete(draw);
+                inputs.delete(oldest[0]);
+            }
+            draws.set(drawCount, { id: key, handlers: pressed });
+            return { draw: drawCount, tree };
         }
         catch (error) {
-            report({ id: `pane:${pane.id}:${handler}`, message: `The ${pane.title} pane's ${handler} threw`, error });
+            if (!failedDraws.has(key))
+                report({ id: key, message: `The ${title} could not draw`, error });
+            failedDraws.add(key);
+            return null;
+        }
+    };
+    const draw = (input) => {
+        if ('page' in input) {
+            const added = pages.get(input.page);
+            if (added === undefined)
+                return null;
+            return drawPart(`page:${input.page}`, `${added.init.title} page`, input, () => added.init.render(mod(), { params: input.params, isFocused: input.isFocused, columns: input.columns }));
         }
+        const widget = widgets.get(input.widget);
+        if (widget === undefined || !widget.areas.includes(input.area))
+            return null;
+        widgetAreas.set(widget.id, input.area);
+        const context = (input.area === TurnEnd && input.turn !== undefined ? { area: input.area, columns: input.columns, turn: input.turn } : { area: input.area, columns: input.columns });
+        return drawPart(`widget:${widget.id}`, `${widget.title} widget`, input, () => widget.render(mod(), context));
+    };
+    const press = async ({ draw: drawn, handler, args }) => {
+        const known = draws.get(drawn);
+        const run = known?.handlers[handler];
+        if (known === undefined || run === undefined)
+            throw new Error(`${name}: that button drew before the last redraw. Press the one it shows now.`);
+        return collect(async () => {
+            try {
+                await run(...args);
+            }
+            catch (error) {
+                report({ id: known.id, message: 'Its button failed', error });
+            }
+        });
     };
     return {
-        ui: {
-            pane(pane) {
-                if (panes.has(pane.id))
-                    throw new Error(`${name}: the pane "${pane.id}" is already added. Give each pane its own id.`);
-                panes.set(pane.id, pane);
-                paneLogs.set(pane.id, logOnce(`${pane.title} pane`));
-                announce(`the ${pane.title} pane`);
-                route();
-                const handle = {
-                    get isOpen() {
-                        return openPanes.has(pane.id);
-                    },
-                    get isShown() {
-                        return paneStates.get(pane.id)?.isShown ?? false;
-                    },
-                    get isFocused() {
-                        return paneStates.get(pane.id)?.isFocused ?? false;
-                    },
-                    async open(options) {
-                        const { isPlaced } = await openAt(pane, paneSize(pane, mod().state), options?.focus);
-                        if (isPlaced)
-                            openPanes.add(pane.id);
-                        await syncPanes();
-                    },
-                    async close() {
-                        await claude.ui.close({ id: pane.id });
-                        openPanes.delete(pane.id);
-                        paneStates.delete(pane.id);
-                        await syncPanes();
-                    },
-                    toggle: (options) => (openPanes.has(pane.id) ? handle.close() : handle.open(options)),
-                };
-                return handle;
+        panes: { add: addPane },
+        sidebar: { add: (init) => addPage('sidebar', init) },
+        settings: {
+            add: (init) => addPage('settings', init),
+            open: async () => {
+                await send({ requests: [{ settings: true }] });
             },
-            render(place, Component) {
-                const target = place;
-                const markdown = typeof target === 'string' ? undefined : target;
-                const component = componentOf(place);
-                if (markdown === undefined && component === undefined)
-                    throw new Error(`${name}: ${String(place)} is not a place render draws, such as ToolCall or CodeBlock.`);
-                const feature = `a render of ${nameOf(place)}`;
-                if (renders.has(feature))
-                    throw new Error(`${name}: ${feature} is already added. Render each place once.`);
-                renders.add(feature);
-                announce(feature);
-                if (markdown !== undefined) {
-                    const markdownType = markdown.markdown;
-                    markdownRenders.set(markdownType, { Component: Component, log: logOnce(nameOf(place)) });
-                    routeMarkdown(markdown.createReader);
-                    return {
-                        dispose() {
-                            markdownRenders.delete(markdownType);
-                            renders.delete(feature);
-                            claude.ui.invalidate('ui.render');
-                        },
-                    };
-                }
-                const log = logOnce(nameOf(place));
-                const drawing = router.add('ui.render', async (e, next) => {
-                    if (e.component !== component)
-                        return next(e);
-                    const table = claude.ui.resolve(e);
-                    const drawn = await drawComponent(table, (Default) => Component({ ...e.props, Default }), (given, isClaudesRow) => next({ ...e, props: pieceProps(e.props, given, isClaudesRow) }));
-                    if ('failure' in drawn) {
-                        log(drawn.failure);
-                        return next(e);
-                    }
-                    if (e.component !== 'AssistantMessage')
-                        return drawn.drawing;
-                    return drawWith(table, () => drawPieces([drawn], e.props.isFirstOfReply ? 'opensReply' : 'inReply'));
-                });
-                return {
-                    dispose() {
-                        drawing.dispose();
-                        renders.delete(feature);
-                        claude.ui.invalidate('ui.render');
-                    },
-                };
-            },
-            toast: toaster.toast,
-            copy: toaster.copy,
-            ask: (question, options) => claude.ui.ask(question, options),
-            scroll: (args) => claude.ui.scroll(args),
+        },
+        widgets: { add: addWidget },
+        styles: { add: addStyle },
+        asked,
+        async answerInput(run, passOn) {
+            const before = unheldRequests;
+            const answer = await asked(run);
+            if (unheldRequests > before)
+                await passOn();
+            return answer;
+        },
+        answer(method, input) {
+            if (method === partMethods.list)
+                return Promise.resolve({ value: partList() });
+            if (method === partMethods.draw)
+                return Promise.resolve({ value: draw(input) });
+            if (method === partMethods.press)
+                return press(input).then((value) => ({ value }));
+            if (method === partMethods.shown) {
+                shownPages = input;
+                return Promise.resolve({ value: null });
+            }
+            return undefined;
+        },
+        started() {
+            const held = merged(beforeStart ?? []);
+            beforeStart = undefined;
+            void send({ ...held, parts: partList() });
         },
         changed() {
-            if (panes.size === 0 && renders.size === 0)
+            if (widgets.size > 0 || pages.size > 0)
+                void send({ redraw: true });
+            if (panes.size === 0 && styles.size === 0)
                 return;
             claude.ui.invalidate('ui.render');
             if (isResizeQueued)
@@ -303,9 +566,9 @@ export function createUi({ name, claude, router, toaster, report, announce, mod
             isResizeQueued = true;
             void Promise.resolve().then(() => {
                 isResizeQueued = false;
-                for (const pane of panes.values()) {
-                    if (openPanes.has(pane.id))
-                        void resize(pane);
+                for (const { init } of panes.values()) {
+                    if (openPanes.has(init.id))
+                        void resize(init);
                 }
             });
         },

package/runtime/watches.d.ts

@@ -0,0 +1,9 @@
+import type { FileChange } from '../mod.js';
+import type { Subscription } from '../utils/subscription.js';
+import type { Claude } from './claude.js';
+import type { Failure } from './toaster.js';
+export type Watches = {
+    add(paths: readonly string[], listener: (change: FileChange) => unknown): Subscription;
+};
+export declare function createWatches(claude: Claude, report: (failure: Failure) => void): Watches;
+//# sourceMappingURL=watches.d.ts.map

package/runtime/watches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watches.d.ts","sourceRoot":"","sources":["../src/runtime/watches.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C,MAAM,MAAM,OAAO,GAAG;IAAE,GAAG,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,GAAG,YAAY,CAAA;CAAE,CAAA;AAQhH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CA4DzF"}

package/runtime/watches.js

@@ -0,0 +1,73 @@
+import { ifMissing } from '../utils/paths.js';
+const watchMs = 500;
+const watchedFiles = 2000;
+export function createWatches(claude, report) {
+    const watches = new Set();
+    let polling;
+    let isPolling = false;
+    const stampsOf = async (paths) => {
+        const stamps = new Map();
+        const visit = async (path) => {
+            const stat = await claude.fs.stat(path).catch(ifMissing(undefined));
+            if (stat === undefined)
+                return;
+            if (stat.kind !== 'dir') {
+                if (stamps.size === watchedFiles)
+                    throw new Error(`fs.onChange watches at most ${watchedFiles} files, and ${paths.join(', ')} holds more, so it stopped. Watch a smaller folder.`);
+                return void stamps.set(path, stat.mtimeMs);
+            }
+            for (const entry of await claude.fs.list(path).catch(ifMissing([])))
+                await visit(`${path}/${entry.name}`);
+        };
+        for (const path of paths)
+            await visit(path);
+        return stamps;
+    };
+    const stop = (watch) => {
+        watches.delete(watch);
+        if (watches.size > 0)
+            return;
+        polling?.cancel();
+        polling = undefined;
+    };
+    const stampsOrStop = (watch) => stampsOf(watch.paths).catch((error) => {
+        stop(watch);
+        report({ id: 'fs:onChange', message: 'Could not read the files fs.onChange watches', error });
+        return undefined;
+    });
+    const poll = async () => {
+        if (isPolling)
+            return;
+        isPolling = true;
+        try {
+            for (const watch of watches) {
+                const now = await stampsOrStop(watch);
+                if (now === undefined)
+                    continue;
+                const before = watch.seen;
+                watch.seen = now;
+                if (before === undefined)
+                    continue;
+                const changes = [
+                    ...[...now].filter(([path, at]) => before.has(path) && before.get(path) !== at).map(([path]) => ({ path, type: 'change' })),
+                    ...[...now.keys()].filter((path) => !before.has(path)).map((path) => ({ path, type: 'add' })),
+                    ...[...before.keys()].filter((path) => !now.has(path)).map((path) => ({ path, type: 'unlink' })),
+                ];
+                for (const change of changes)
+                    await Promise.resolve().then(() => watch.listener(change)).catch((error) => report({ id: 'fs:onChange', message: 'The fs.onChange listener failed', error }));
+            }
+        }
+        finally {
+            isPolling = false;
+        }
+    };
+    return {
+        add(paths, listener) {
+            const watch = { paths, listener, seen: undefined };
+            watches.add(watch);
+            void stampsOrStop(watch).then((stamps) => void (watch.seen ??= stamps));
+            polling ??= claude.clock.every(watchMs, () => void poll());
+            return { remove: () => stop(watch) };
+        },
+    };
+}