@plmbr/notebook-intelligence 5.0.0

package/lib/markdown-renderer.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+import { JupyterFrontEnd } from '@jupyterlab/application';
+import { IActiveDocumentInfo } from './tokens';
+type MarkdownRendererProps = {
+    children: string;
+    getApp: () => JupyterFrontEnd;
+    getActiveDocumentInfo(): IActiveDocumentInfo;
+};
+export declare function MarkdownRenderer({ children: markdown, getApp, getActiveDocumentInfo }: MarkdownRendererProps): React.JSX.Element;
+export {};

package/lib/markdown-renderer.js

@@ -0,0 +1,64 @@
+// Copyright (c) Mehmet Bektas <mbektasgh@outlook.com>
+import React from 'react';
+import Markdown from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+import { Prism as SyntaxHighlighterBase } from 'react-syntax-highlighter';
+const SyntaxHighlighter = SyntaxHighlighterBase;
+import { oneLight, oneDark } from 'react-syntax-highlighter/dist/cjs/styles/prism';
+import { VscNewFile, VscInsert, VscCopy, VscNotebook, VscAdd } from './icons';
+import { isDarkTheme, writeTextToClipboard } from './utils';
+export function MarkdownRenderer({ children: markdown, getApp, getActiveDocumentInfo }) {
+    const app = getApp();
+    const activeDocumentInfo = getActiveDocumentInfo();
+    const isNotebook = activeDocumentInfo.filename.endsWith('.ipynb');
+    return (React.createElement(Markdown, { remarkPlugins: [remarkGfm], components: {
+            code({ node, inline, className, children, getApp, ...props }) {
+                const match = /language-(\w+)/.exec(className || '');
+                const codeString = String(children).replace(/\n$/, '');
+                const language = match ? match[1] : 'text';
+                const handleCopyClick = () => {
+                    void writeTextToClipboard(codeString);
+                };
+                const handleInsertAtCursorClick = () => {
+                    app.commands.execute('notebook-intelligence:insert-at-cursor', {
+                        language,
+                        code: codeString
+                    });
+                };
+                const handleAddCodeAsNewCell = () => {
+                    app.commands.execute('notebook-intelligence:add-code-as-new-cell', {
+                        language,
+                        code: codeString
+                    });
+                };
+                const handleCreateNewFileClick = () => {
+                    app.commands.execute('notebook-intelligence:create-new-file', {
+                        language,
+                        code: codeString
+                    });
+                };
+                const handleCreateNewNotebookClick = () => {
+                    app.commands.execute('notebook-intelligence:create-new-notebook-from-py', { language, code: codeString });
+                };
+                if (inline || !match) {
+                    return (React.createElement("code", { className: className, ...props }, children));
+                }
+                return (React.createElement("div", null,
+                    React.createElement("div", { className: "code-block-header" },
+                        React.createElement("div", { className: "code-block-header-language" },
+                            React.createElement("span", null, language)),
+                        React.createElement("button", { type: "button", className: "code-block-header-button", onClick: () => handleCopyClick(), "aria-label": "Copy code to clipboard" },
+                            React.createElement(VscCopy, { size: 16, "aria-hidden": "true" }),
+                            React.createElement("span", null, "Copy")),
+                        React.createElement("button", { type: "button", className: "code-block-header-button", onClick: () => handleInsertAtCursorClick(), "aria-label": "Insert code at cursor", title: "Insert at cursor" },
+                            React.createElement(VscInsert, { size: 16, "aria-hidden": "true" })),
+                        isNotebook && (React.createElement("button", { type: "button", className: "code-block-header-button", onClick: () => handleAddCodeAsNewCell(), "aria-label": "Add code as new cell", title: "Add as new cell" },
+                            React.createElement(VscAdd, { size: 16, "aria-hidden": "true" }))),
+                        React.createElement("button", { type: "button", className: "code-block-header-button", onClick: () => handleCreateNewFileClick(), "aria-label": "Create new file from code", title: "New file" },
+                            React.createElement(VscNewFile, { size: 16, "aria-hidden": "true" })),
+                        language === 'python' && (React.createElement("button", { type: "button", className: "code-block-header-button", onClick: () => handleCreateNewNotebookClick(), "aria-label": "Create new notebook from code", title: "New notebook" },
+                            React.createElement(VscNotebook, { size: 16, "aria-hidden": "true" })))),
+                    React.createElement(SyntaxHighlighter, { style: isDarkTheme() ? oneDark : oneLight, PreTag: "div", language: language, ...props }, codeString)));
+            }
+        } }, markdown));
+}

package/lib/notebook-generation-toolbar.d.ts

@@ -0,0 +1,16 @@
+import { JupyterFrontEnd } from '@jupyterlab/application';
+import { DocumentRegistry } from '@jupyterlab/docregistry';
+import { INotebookModel, NotebookPanel } from '@jupyterlab/notebook';
+import { LabIcon } from '@jupyterlab/ui-components';
+import { IDisposable } from '@lumino/disposable';
+interface INotebookGenerationToolbarOptions {
+    app: JupyterFrontEnd;
+    icon: LabIcon;
+    chatSidebarId: string;
+}
+export declare class NotebookGenerationToolbarExtension implements DocumentRegistry.IWidgetExtension<NotebookPanel, INotebookModel> {
+    constructor(options: INotebookGenerationToolbarOptions);
+    createNew(panel: NotebookPanel, _context: DocumentRegistry.IContext<INotebookModel>): IDisposable;
+    private _options;
+}
+export {};

package/lib/notebook-generation-toolbar.js

@@ -0,0 +1,197 @@
+// Copyright (c) Mehmet Bektas <mbektasgh@outlook.com>
+import { ReactWidget } from '@jupyterlab/apputils';
+import { ToolbarButton } from '@jupyterlab/ui-components';
+import { DisposableDelegate } from '@lumino/disposable';
+import { Widget } from '@lumino/widgets';
+import { UUID } from '@lumino/coreutils';
+import React from 'react';
+import { RunChatCompletionType } from './chat-sidebar';
+import { buildNotebookGenerationPrompt, NOTEBOOK_GENERATION_PROGRESS_EVENT } from './notebook-generation';
+import { NotebookGenerationPopover } from './components/notebook-generation-popover';
+const TOOLBAR_BUTTON_NAME = 'nbi-generate-notebook';
+const TOOLBAR_STATUS_NAME = 'nbi-generate-notebook-status';
+class NotebookGenerationPopoverWidget extends ReactWidget {
+    constructor(options) {
+        super();
+        this._onDocumentMouseDown = (event) => {
+            const target = event.target;
+            if (target && this.node.contains(target)) {
+                return;
+            }
+            this._options.onClose();
+        };
+        this.addClass('nbi-notebook-generation-popover-host');
+        this._options = options;
+    }
+    onAfterAttach() {
+        document.addEventListener('mousedown', this._onDocumentMouseDown, true);
+    }
+    onBeforeDetach() {
+        document.removeEventListener('mousedown', this._onDocumentMouseDown, true);
+    }
+    positionAt(rect) {
+        const popoverWidth = 360;
+        const margin = 8;
+        let left = rect.left;
+        if (left + popoverWidth + margin > window.innerWidth) {
+            left = Math.max(margin, window.innerWidth - popoverWidth - margin);
+        }
+        const top = rect.bottom + 4;
+        this.node.style.position = 'fixed';
+        this.node.style.left = `${left}px`;
+        this.node.style.top = `${top}px`;
+        this.node.style.width = `${popoverWidth}px`;
+        this.node.style.zIndex = '10000';
+    }
+    render() {
+        return (React.createElement(NotebookGenerationPopover, { initialShowInChat: this._options.initialShowInChat, onSubmit: this._options.onSubmit, onClose: this._options.onClose }));
+    }
+}
+class NotebookGenerationToolbarController {
+    constructor(options, panel) {
+        this._onProgress = (event) => {
+            const detail = event
+                .detail;
+            if (!detail || detail.requestId !== this._activeProgressRequestId) {
+                return;
+            }
+            if (!detail.inProgress) {
+                document.removeEventListener(NOTEBOOK_GENERATION_PROGRESS_EVENT, this._onProgress);
+                this._activeProgressRequestId = null;
+                if (detail.error) {
+                    this._setStatus(`Generation failed: ${detail.error}`);
+                    this._scheduleStatusHide(4000);
+                }
+                else {
+                    this._setStatus('Notebook generation complete');
+                    this._scheduleStatusHide(2500);
+                }
+            }
+        };
+        this._popover = null;
+        this._activeProgressRequestId = null;
+        this._statusWidget = null;
+        this._statusHideTimer = null;
+        this._app = options.app;
+        this._chatSidebarId = options.chatSidebarId;
+        this._panel = panel;
+    }
+    openPopover(button) {
+        if (this._popover) {
+            this.closePopover();
+            return;
+        }
+        const buttonRect = button.node.getBoundingClientRect();
+        this._popover = new NotebookGenerationPopoverWidget({
+            initialShowInChat: NotebookGenerationToolbarController._showInChat,
+            onSubmit: (prompt, showInChat) => {
+                NotebookGenerationToolbarController._showInChat = showInChat;
+                this._submitPrompt(prompt, showInChat);
+                this.closePopover();
+            },
+            onClose: () => this.closePopover()
+        });
+        Widget.attach(this._popover, document.body);
+        // ReactWidget renders on update-request; Widget.attach doesn't queue one.
+        this._popover.update();
+        this._popover.positionAt(buttonRect);
+    }
+    closePopover() {
+        if (!this._popover) {
+            return;
+        }
+        this._popover.dispose();
+        this._popover = null;
+    }
+    dispose() {
+        this.closePopover();
+        if (this._activeProgressRequestId) {
+            document.removeEventListener(NOTEBOOK_GENERATION_PROGRESS_EVENT, this._onProgress);
+            this._activeProgressRequestId = null;
+        }
+        if (this._statusHideTimer !== null) {
+            clearTimeout(this._statusHideTimer);
+            this._statusHideTimer = null;
+        }
+        this._setStatus(null);
+    }
+    _submitPrompt(rawPrompt, showInChat) {
+        const prefixedPrompt = buildNotebookGenerationPrompt(rawPrompt);
+        const externalRequestId = UUID.uuid4();
+        // chatMode and toolSelections are forced by the chat-sidebar handler
+        // (NotebookGeneration always needs agent mode + the notebook-edit
+        // toolset). Leaving them off the request keeps the toolbar
+        // independent of the sidebar's current configuration.
+        const request = {
+            type: RunChatCompletionType.NotebookGeneration,
+            content: prefixedPrompt,
+            externalRequestId,
+            hideInChat: !showInChat
+        };
+        if (!showInChat) {
+            this._setStatus('Generating notebook…');
+            this._activeProgressRequestId = externalRequestId;
+            document.addEventListener(NOTEBOOK_GENERATION_PROGRESS_EVENT, this._onProgress);
+        }
+        document.dispatchEvent(new CustomEvent('copilotSidebar:runPrompt', { detail: request }));
+        if (showInChat) {
+            this._app.commands.execute('tabsmenu:activate-by-id', {
+                id: this._chatSidebarId
+            });
+        }
+    }
+    _scheduleStatusHide(delayMs) {
+        if (this._statusHideTimer !== null) {
+            clearTimeout(this._statusHideTimer);
+        }
+        this._statusHideTimer = setTimeout(() => {
+            this._statusHideTimer = null;
+            this._setStatus(null);
+        }, delayMs);
+    }
+    _setStatus(message) {
+        if (this._panel.isDisposed) {
+            return;
+        }
+        if (!message) {
+            if (this._statusWidget) {
+                this._statusWidget.dispose();
+                this._statusWidget = null;
+            }
+            return;
+        }
+        if (!this._statusWidget) {
+            const widget = new Widget();
+            widget.addClass('nbi-notebook-generation-status');
+            this._panel.toolbar.insertAfter(TOOLBAR_BUTTON_NAME, TOOLBAR_STATUS_NAME, widget);
+            this._statusWidget = widget;
+        }
+        this._statusWidget.node.textContent = message;
+    }
+}
+// Defaults ON; remembers the user's last choice for the rest of the tab.
+NotebookGenerationToolbarController._showInChat = true;
+export class NotebookGenerationToolbarExtension {
+    constructor(options) {
+        this._options = options;
+    }
+    createNew(panel, _context) {
+        const controller = new NotebookGenerationToolbarController(this._options, panel);
+        const button = new ToolbarButton({
+            icon: this._options.icon,
+            onClick: () => controller.openPopover(button),
+            // Notebook generation works in any chat mode — the chat-sidebar
+            // handler forces agent mode and the notebook-edit toolset when
+            // routing this request (issue #229). The button used to be gated
+            // on isInClaudeCodeMode here, but that gate undermined the
+            // sidebar-side fix.
+            tooltip: 'Update active notebook with AI'
+        });
+        button.addClass('nbi-notebook-generation-toolbar-button');
+        panel.toolbar.insertAfter('cellType', TOOLBAR_BUTTON_NAME, button);
+        return new DisposableDelegate(() => {
+            controller.dispose();
+            button.dispose();
+        });
+    }
+}

package/lib/notebook-generation.d.ts

@@ -0,0 +1,8 @@
+export declare const NOTEBOOK_GENERATION_PROMPT_PREFIX = "Update active notebook based on the user request. Don't create a new notebook, always update the active one. User request: ";
+export declare const NOTEBOOK_GENERATION_PROGRESS_EVENT = "copilotSidebar:notebookGenerationProgress";
+export interface INotebookGenerationProgressDetail {
+    requestId: string;
+    inProgress: boolean;
+    error?: string;
+}
+export declare function buildNotebookGenerationPrompt(rawPrompt: string): string;

package/lib/notebook-generation.js

@@ -0,0 +1,12 @@
+// Copyright (c) Mehmet Bektas <mbektasgh@outlook.com>
+//
+// Pure helpers and event constants used by the notebook-generation toolbar
+// button. Keeping these in their own module (free of JupyterLab/React
+// dependencies) makes them easy to unit-test under jsdom without bringing
+// in the chat sidebar's heavyweight ESM imports.
+export const NOTEBOOK_GENERATION_PROMPT_PREFIX = "Update active notebook based on the user request. Don't create a new notebook, always update the active one. User request: ";
+export const NOTEBOOK_GENERATION_PROGRESS_EVENT = 'copilotSidebar:notebookGenerationProgress';
+export function buildNotebookGenerationPrompt(rawPrompt) {
+    const trimmed = (rawPrompt || '').trim();
+    return `${NOTEBOOK_GENERATION_PROMPT_PREFIX}${trimmed}`;
+}

package/lib/open-file-refresh-watcher-env.d.ts

@@ -0,0 +1,4 @@
+import { JupyterFrontEnd } from '@jupyterlab/application';
+import { Contents } from '@jupyterlab/services';
+import { IRefreshWatcherEnv } from './open-file-refresh-watcher';
+export declare function buildRefreshWatcherEnv(app: JupyterFrontEnd, contents: Contents.IManager): IRefreshWatcherEnv;

package/lib/open-file-refresh-watcher-env.js

@@ -0,0 +1,33 @@
+// Copyright (c) Mehmet Bektas <mbektasgh@outlook.com>
+import { DocumentWidget } from '@jupyterlab/docregistry';
+import { WATCHED_SHELL_AREAS } from './open-file-refresh-watcher';
+export function buildRefreshWatcherEnv(app, contents) {
+    return {
+        iterDocumentWidgets: function* () {
+            for (const area of WATCHED_SHELL_AREAS) {
+                // Defensive try/catch: LabShell.widgets() throws for areas it
+                // doesn't implement. We've audited the current set against
+                // the runtime, but a future JL bump could rename or remove
+                // an area; surfacing it as a console warning rather than an
+                // unhandled rejection keeps the watcher running for the
+                // areas that DO work.
+                let widgets;
+                try {
+                    widgets = app.shell.widgets(area);
+                }
+                catch (err) {
+                    console.warn(`[NBI] open-file-refresh-watcher: skipping shell area "${area}":`, err);
+                    continue;
+                }
+                for (const widget of widgets) {
+                    if (widget instanceof DocumentWidget) {
+                        yield widget;
+                    }
+                }
+            }
+        },
+        fetchDiskModel: path => contents.get(path, { content: false }),
+        setInterval: (handler, ms) => window.setInterval(handler, ms),
+        clearInterval: handle => window.clearInterval(handle)
+    };
+}

package/lib/open-file-refresh-watcher.d.ts

@@ -0,0 +1,97 @@
+import type { DocumentRegistry } from '@jupyterlab/docregistry';
+import type { Contents } from '@jupyterlab/services';
+export interface IRefreshWatcherWidget {
+    readonly context: DocumentRegistry.Context | null | undefined;
+}
+export declare const DEFAULT_REFRESH_POLL_INTERVAL_MS = 3000;
+export declare const DEFAULT_TICK_CONCURRENCY = 4;
+export declare const WATCHED_SHELL_AREAS: readonly ["main", "left", "right"];
+/**
+ * Inputs the revert decision depends on. Keeping this pure (no
+ * JupyterLab types) lets the unit test pin the policy without
+ * instantiating a real Context.
+ */
+export interface IRevertDecisionInputs {
+    diskLastModified: string | null | undefined;
+    contextLastModified: string | null | undefined;
+    isDirty: boolean;
+    isReady: boolean;
+    isDisposed: boolean;
+}
+/**
+ * Whether the open document's in-memory model should be reverted to
+ * match the on-disk version. The rules, in order:
+ *
+ *   1. Skip if the context is gone (disposed) or not yet populated
+ *      (`isReady` false). Calling `revert()` against an unready
+ *      context races the initial load.
+ *   2. Skip if the user has unsaved local edits (`isDirty`). Silently
+ *      clobbering their work would be hostile; the standard
+ *      JupyterLab "newer on disk" prompt will surface on save.
+ *   3. Skip if we can't parse either timestamp (either side missing
+ *      or unparseable).
+ *   4. Revert iff disk's `last_modified` parses to a strictly greater
+ *      epoch ms than the context's last-known value. Equal means
+ *      already current (a save we initiated, or a no-op re-read).
+ *
+ * The comparison is numeric, not lexicographic, because jupyter_server
+ * serializes `last_modified` via Python's `datetime.isoformat()` which
+ * omits the fractional component when `microsecond == 0`. That means
+ * the same instant can arrive as `"...:56Z"` or `"...:56.000000Z"`,
+ * and `"...:56.000000Z" < "...:56Z"` lexicographically (the `.` at
+ * 0x2E sorts below the `Z` at 0x5A at position 19). A string compare
+ * would fire a spurious revert when the two sides happen to land on
+ * different sides of the fractional/non-fractional boundary for the
+ * same mtime. Parsing both through `new Date(s).getTime()` collapses
+ * them to the same epoch ms.
+ *
+ * JupyterLab's own newer-on-disk check (`docregistry/lib/context.js`,
+ * see `lastModifiedCheckMargin`) applies a 500ms tolerance to absorb
+ * filesystem mtime jitter, but that comparison drives a user-facing
+ * "newer on disk, save anyway?" prompt where false-positive is just a
+ * dialog. Our comparison drives a silent revert that could clobber an
+ * agent's edit that landed within the margin of the user's own save;
+ * we deliberately stay strict.
+ */
+export declare function shouldRevertContext({ diskLastModified, contextLastModified, isDirty, isReady, isDisposed }: IRevertDecisionInputs): boolean;
+/**
+ * Side-effect surface the watcher reaches into. Extracted so tests
+ * can pass a thin fake without standing up a real JupyterFrontEnd or
+ * Contents singleton.
+ */
+export interface IRefreshWatcherEnv {
+    /** Yield every currently-open document widget the watcher should consider. */
+    iterDocumentWidgets: () => Iterable<IRefreshWatcherWidget>;
+    /** Fetch on-disk metadata without the body (cheap stat-shaped call). */
+    fetchDiskModel: (path: string) => Promise<Contents.IModel>;
+    /** Set/clear the polling interval. Pulled out for fake timers in tests. */
+    setInterval: (handler: () => void, ms: number) => unknown;
+    clearInterval: (handle: unknown) => void;
+}
+export interface IRefreshWatcherOptions {
+    env: IRefreshWatcherEnv;
+    intervalMs?: number;
+    /** Cap on concurrent Contents.get calls per tick. Defaults to DEFAULT_TICK_CONCURRENCY. */
+    tickConcurrency?: number;
+    /** Re-checked on every tick so a settings toggle takes effect without restart. */
+    isEnabled: () => boolean;
+    /** Hook for tests / telemetry — fired once per revert (the heavy outcome). */
+    onRevert?: (path: string) => void;
+    /** Hook for tests / diagnostics — fired when a check throws. */
+    onError?: (path: string, error: unknown) => void;
+}
+/**
+ * Polls every open document widget on a fixed cadence, comparing the
+ * file's on-disk `last_modified` against the context's last-known
+ * value, and calls `context.revert()` when the disk is newer.
+ *
+ * Why polling at all (when the Contents API exposes a `fileChanged`
+ * signal): agents like Claude write directly to the filesystem,
+ * bypassing the API. The signal fires for Lab-routed writes only.
+ * Polling catches both paths uniformly and keeps the watcher
+ * single-purpose.
+ *
+ * Returns a teardown function the caller invokes on plugin
+ * deactivation to stop the timer.
+ */
+export declare function attachOpenFileRefreshWatcher(options: IRefreshWatcherOptions): () => void;

package/lib/open-file-refresh-watcher.js

@@ -0,0 +1,190 @@
+// Copyright (c) Mehmet Bektas <mbektasgh@outlook.com>
+export const DEFAULT_REFRESH_POLL_INTERVAL_MS = 3000;
+// Max in-flight Contents.get calls per tick. The Jupyter server runs
+// each request through its own handler thread; with 15 open tabs and
+// unthrottled fan-out we'd pin 15 sockets every poll. Cap at 4 so a
+// heavy-tab user still finishes a tick well under the 3s interval
+// without hammering the server.
+export const DEFAULT_TICK_CONCURRENCY = 4;
+// Shell areas the live binding walks looking for open DocumentWidgets.
+// 'main' is the primary editor area (including split panes managed by
+// the underlying DockPanel); 'left' and 'right' catch the rare case
+// where a user drags a notebook tab into a sidebar in JL4.
+//
+// 'down' is intentionally absent. It's listed in JupyterLab's
+// TypeScript Area union (application/lib/shell.d.ts) but NOT
+// implemented in LabShell.widgets()'s runtime switch
+// (application/lib/shell.js) — asking for it throws
+// `Invalid area: down`. Reported on PR #330 review; do not re-add
+// without confirming the runtime impl in the installed JL version.
+//
+// The constant lives here (rather than in the env binding) so the
+// test suite can pin its contents without importing
+// @jupyterlab/docregistry, which ships ESM that ts-jest's default
+// transform can't parse.
+export const WATCHED_SHELL_AREAS = ['main', 'left', 'right'];
+/**
+ * Whether the open document's in-memory model should be reverted to
+ * match the on-disk version. The rules, in order:
+ *
+ *   1. Skip if the context is gone (disposed) or not yet populated
+ *      (`isReady` false). Calling `revert()` against an unready
+ *      context races the initial load.
+ *   2. Skip if the user has unsaved local edits (`isDirty`). Silently
+ *      clobbering their work would be hostile; the standard
+ *      JupyterLab "newer on disk" prompt will surface on save.
+ *   3. Skip if we can't parse either timestamp (either side missing
+ *      or unparseable).
+ *   4. Revert iff disk's `last_modified` parses to a strictly greater
+ *      epoch ms than the context's last-known value. Equal means
+ *      already current (a save we initiated, or a no-op re-read).
+ *
+ * The comparison is numeric, not lexicographic, because jupyter_server
+ * serializes `last_modified` via Python's `datetime.isoformat()` which
+ * omits the fractional component when `microsecond == 0`. That means
+ * the same instant can arrive as `"...:56Z"` or `"...:56.000000Z"`,
+ * and `"...:56.000000Z" < "...:56Z"` lexicographically (the `.` at
+ * 0x2E sorts below the `Z` at 0x5A at position 19). A string compare
+ * would fire a spurious revert when the two sides happen to land on
+ * different sides of the fractional/non-fractional boundary for the
+ * same mtime. Parsing both through `new Date(s).getTime()` collapses
+ * them to the same epoch ms.
+ *
+ * JupyterLab's own newer-on-disk check (`docregistry/lib/context.js`,
+ * see `lastModifiedCheckMargin`) applies a 500ms tolerance to absorb
+ * filesystem mtime jitter, but that comparison drives a user-facing
+ * "newer on disk, save anyway?" prompt where false-positive is just a
+ * dialog. Our comparison drives a silent revert that could clobber an
+ * agent's edit that landed within the margin of the user's own save;
+ * we deliberately stay strict.
+ */
+export function shouldRevertContext({ diskLastModified, contextLastModified, isDirty, isReady, isDisposed }) {
+    if (isDisposed || !isReady) {
+        return false;
+    }
+    if (isDirty) {
+        return false;
+    }
+    if (!diskLastModified || !contextLastModified) {
+        return false;
+    }
+    // Match JL's own idiom (docregistry/lib/context.js:625-630) and the
+    // five other `new Date(...).getTime()` call sites in this codebase.
+    // Equivalent to `Date.parse(s)` but consistent with house style.
+    const diskMs = new Date(diskLastModified).getTime();
+    const contextMs = new Date(contextLastModified).getTime();
+    // NaN on either side (unparseable string) makes the comparison
+    // false, so a malformed timestamp degrades safely to "don't revert."
+    return diskMs > contextMs;
+}
+/**
+ * Polls every open document widget on a fixed cadence, comparing the
+ * file's on-disk `last_modified` against the context's last-known
+ * value, and calls `context.revert()` when the disk is newer.
+ *
+ * Why polling at all (when the Contents API exposes a `fileChanged`
+ * signal): agents like Claude write directly to the filesystem,
+ * bypassing the API. The signal fires for Lab-routed writes only.
+ * Polling catches both paths uniformly and keeps the watcher
+ * single-purpose.
+ *
+ * Returns a teardown function the caller invokes on plugin
+ * deactivation to stop the timer.
+ */
+export function attachOpenFileRefreshWatcher(options) {
+    var _a;
+    const intervalMs = (_a = options.intervalMs) !== null && _a !== void 0 ? _a : DEFAULT_REFRESH_POLL_INTERVAL_MS;
+    let inFlight = false;
+    let stopped = false;
+    const tick = async () => {
+        var _a;
+        // Defense against the browser firing a stale interval handler
+        // after we've called clearInterval, and against tests that invoke
+        // the captured handler directly post-teardown.
+        if (stopped) {
+            return;
+        }
+        if (!options.isEnabled()) {
+            return;
+        }
+        // Re-entrancy guard: a slow Contents.get on one widget shouldn't
+        // pile up additional ticks while it resolves. Skip rather than
+        // queue so a transient server slowdown doesn't snowball.
+        if (inFlight) {
+            return;
+        }
+        inFlight = true;
+        try {
+            const seen = new Set();
+            const targets = [];
+            for (const widget of options.env.iterDocumentWidgets()) {
+                const context = widget.context;
+                if (!context || !context.path) {
+                    continue;
+                }
+                // Dedupe across widgets sharing the same context (split-view,
+                // notebook + editor view, etc.); reverting once per path is
+                // enough since the context is the shared mutable state.
+                if (seen.has(context.path)) {
+                    continue;
+                }
+                seen.add(context.path);
+                targets.push(context);
+            }
+            // Chunked fan-out: parallelism within a batch (so 4 tabs finish
+            // in one RTT instead of four), serialized across batches (so a
+            // 20-tab user doesn't pin 20 sockets at once). Per-context
+            // errors stay inside checkOneContext via its try/catch, so a
+            // Promise.all on the batch can't reject and tear the loop.
+            const concurrency = Math.max(1, (_a = options.tickConcurrency) !== null && _a !== void 0 ? _a : DEFAULT_TICK_CONCURRENCY);
+            for (let i = 0; i < targets.length; i += concurrency) {
+                const batch = targets.slice(i, i + concurrency);
+                await Promise.all(batch.map(ctx => checkOneContext(ctx, options)));
+            }
+        }
+        finally {
+            inFlight = false;
+        }
+    };
+    const handle = options.env.setInterval(() => {
+        // Swallow tick-level errors so a single bad path can't kill the
+        // poller; per-context errors are reported via onError above.
+        void tick();
+    }, intervalMs);
+    return () => {
+        stopped = true;
+        options.env.clearInterval(handle);
+    };
+}
+async function checkOneContext(context, options) {
+    var _a, _b, _c;
+    try {
+        const diskModel = await options.env.fetchDiskModel(context.path);
+        const decision = shouldRevertContext({
+            diskLastModified: diskModel.last_modified,
+            contextLastModified: (_a = context.contentsModel) === null || _a === void 0 ? void 0 : _a.last_modified,
+            isDirty: context.model.dirty,
+            isReady: context.isReady,
+            isDisposed: context.isDisposed
+        });
+        if (!decision) {
+            return;
+        }
+        // Defense in depth: re-read dirty/disposed immediately before the
+        // revert call. Today this is strictly belt-and-suspenders — no
+        // microtask boundary exists between the dirty read inside
+        // shouldRevertContext above and the await on revert() below, so a
+        // keystroke cannot land in that window. The re-check survives a
+        // future refactor that inserts an await (telemetry, an instrument
+        // hook, etc.) between the decision and the revert call without
+        // anyone having to re-derive the safety argument.
+        if (context.model.dirty || context.isDisposed) {
+            return;
+        }
+        await context.revert();
+        (_b = options.onRevert) === null || _b === void 0 ? void 0 : _b.call(options, context.path);
+    }
+    catch (error) {
+        (_c = options.onError) === null || _c === void 0 ? void 0 : _c.call(options, context.path, error);
+    }
+}

package/lib/shell-utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * POSIX-shell single-quote escape: every embedded single quote is closed,
+ * emitted as an escaped literal, and the quote re-opened. The result is
+ * safe to splice into a shell command without further sanitization.
+ */
+export declare function shellSingleQuote(value: string): string;

package/lib/shell-utils.js

@@ -0,0 +1,9 @@
+// Copyright (c) Mehmet Bektas <mbektasgh@outlook.com>
+/**
+ * POSIX-shell single-quote escape: every embedded single quote is closed,
+ * emitted as an escaped literal, and the quote re-opened. The result is
+ * safe to splice into a shell command without further sanitization.
+ */
+export function shellSingleQuote(value) {
+    return "'" + value.replace(/'/g, "'\\''") + "'";
+}

package/lib/task-target-notebook.d.ts

@@ -0,0 +1,2 @@
+export declare const NOTEBOOK_TARGETED_COMMAND_IDS: ReadonlySet<string>;
+export declare function injectTaskTargetNotebook(commandId: string, args: Record<string, unknown> | undefined, taskTargetPath: string | null): Record<string, unknown> | undefined;