notebook-intelligence 5.3.1__tar.gz → 5.4.0__tar.gz

{notebook_intelligence-5.3.1 → notebook_intelligence-5.4.0}/CHANGELOG.md

@@ -8,7 +8,80 @@ For each release we list user-facing changes grouped as **Added**, **Changed**,
 
 <!-- <START NEW CHANGELOG ENTRY> -->
 
-## [Unreleased]
+## [5.4.0] - unreleased
+
+5.4.0 adds a second agent mode (ACP, with Codex as the first agent type) alongside Claude mode, a way to serve NBI's Jupyter-UI tools to an agent running outside the Lab page, and two diagnostic surfaces for deployments where something is misconfigured or slow: a configuration readiness preflight that names the missing piece, and opt-in performance diagnostics with per-turn timelines. Every one of them is opt-in and defaults to off. No traitlet, env-var, REST route, or on-disk-format renames or removals.
+
+### Added
+
+- **Experimental ACP agent mode** (#378). A second agent mode that drives an external coding agent over the [Agent Client Protocol](https://agentclientprotocol.com/), with OpenAI Codex (via the `codex-acp` adapter) as the first selectable agent type. Adds an ACP tab in Settings with an agent-type dropdown, chat model, API key, and base URL; session listing and resume through the agent's own `session/list` and `session/load`; and streaming, tool-call, and permission-request handling that reuses NBI's existing confirmation flow. ACP mode and Claude mode are mutually exclusive: enabling one disables the other on save, and a hand-edited config that enables both resolves to Claude. Two new admin policies both default to `force-off` rather than `user-choice`: `acp_mode_policy` (`NBI_ACP_MODE_POLICY`), the off switch for the whole mode, and `acp_full_access_policy` (`NBI_ACP_FULL_ACCESS_POLICY`), which governs whether the agent may run tools without asking. While full access is `force-off`, NBI pins Codex to `approval_policy = untrusted` through the adapter's `-c` command-line override, so it asks before anything beyond trusted read-only commands. Credentials and model follow the same env-override locks as Claude (`OPENAI_API_KEY`, `OPENAI_BASE_URL`, `NBI_ACP_CHAT_MODEL`), and `NBI_ACP_AGENT_COMMAND` overrides the adapter command NBI launches. When an API key is configured, codex runs with an isolated `CODEX_HOME` under the NBI user directory so neither the workspace's nor the user's `~/.codex` config is read. See [Gating the experimental ACP agent](docs/admin-guide.md#gating-the-experimental-acp-agent-378).
+- **Proxied Jupyter UI tools for external agents** (#398). NBI's Jupyter-UI tools (create and edit notebooks, run cells, open files, drive the terminal) were only reachable from the in-process MCP server NBI registers with the Claude SDK. Managed and enterprise Claude Code configurations can forbid dynamically configured MCP servers, which made those tools unavailable in exactly the deployments that most need them. A standalone stdio MCP server, `python -m notebook_intelligence.mcp_ui_proxy`, now serves the same tool manifest and relays each call over HTTP to the running Jupyter Server, so it can be declared in a static `mcp.json` like any other server. Setting `jupyter_ui_tools_external` in the Claude settings switches Claude mode from the in-process tools to the relay. The relay endpoint is `/notebook-intelligence/ui-tools` (GET for the manifest, POST to invoke); it requires Jupyter authentication like every other NBI route, and the proxy additionally sends a per-process bridge secret in an `X-NBI-UI-Tools-Token` header, which the relay uses only to exempt the call from the XSRF check (not as an identity). `NBI_UI_TOOLS_URL`, `NBI_UI_TOOLS_TOKEN`, `NBI_UI_TOOLS_SECRET`, `NBI_UI_TOOLS_HTTP_TIMEOUT`, and `NBI_UI_TOOLS_SERVER_NAME` configure the proxy when discovery cannot find the server on its own. See [Serving the Jupyter UI tools to an external agent](docs/admin-guide.md#serving-the-jupyter-ui-tools-to-an-external-agent-398).
+
+- **Configuration readiness preflight** (#410). NBI Settings now opens on a Status card answering whether the deployment is configured to work and, if not, which specific piece is missing. Checks resolve the provider and model, confirm the model list is reachable and that the selected model is one the endpoint actually serves, and for the agent modes confirm the CLI answers `--version` and that credentials are present; a missing key is a warning rather than an error, because the Claude CLI and ACP agents can hold subscription logins NBI cannot see. Every row that is not `ok` carries a remedy naming the next action. `GET /notebook-intelligence/readiness` runs the checks that bill nothing. An opt-in `POST` with `{"live": true}` sends one short real request, which is the only way to catch a gateway that returns 200s but buffers instead of streaming, or a proxy that strips the `tools` field so agent mode silently never calls a tool; it is refused when `NBI_READINESS_LIVE_CHECK=off` (traitlet `readiness_live_check_allowed`) and returns 429 if one is already running. No model output is retained. See [Configuration readiness](docs/admin-guide.md#configuration-readiness).
+- **Opt-in performance diagnostics** (#408). A Performance tab that answers "where did this turn's time go," aimed at internal LLM gateways, network home directories, and TLS-intercepting proxies. Each chat turn records a phase timeline (rule and context preparation, agent connect and spawn, time to first token, streaming with stall events, tool calls, time spent waiting on the user) plus token counts and the SDK-reported API duration, with a verdict naming the dominant phase; comparing active time against API time separates a slow gateway from a slow machine. An environment probe measures filesystem, subprocess, and optional network latency from the server's own vantage point. Off by default, and when off the cost is a single boolean check per instrumentation site. Attributes are redacted by default (paths hashed to basenames), turns are held in a capped ring buffer, and each turn is also summarized as one `perf turn ...` INFO line so headless installs get the same signal. `NBI_PERF_DIAGNOSTICS` locks the enabled state, `NBI_PERF_DIAGNOSTICS_POLICY` governs it fleet-wide, `NBI_PERF_PROBE_NETWORK=off` disables just the network check, and `NBI_PERF_LOG_DIR` redirects the optional JSONL log. See [`docs/performance-diagnostics.md`](docs/performance-diagnostics.md).
+- **Separate model for inline chat** (#413). New optional `claude_settings.inline_chat_model` picks the model used by the inline chat popover, falling back to `chat_model` when unset so existing configs behave exactly as before. Inline chat calls the Anthropic API directly while the other Claude modes go through the Claude Code CLI, and the two transports do not accept the same model-id grammar: a CLI-only id spelling reaches the raw API verbatim and is rejected. Exposed as a collapsible "Inline chat model" control nested under Claude → Chat model, and pinnable via `NBI_CLAUDE_INLINE_CHAT_MODEL`. `NBI_CLAUDE_CHAT_MODEL` keeps governing both surfaces as it does today (while it is set the inline key is ignored and its control is disabled), so an existing pin loses no coverage on upgrade; pin the inline var as well to give the two transports different models.
+
+### Changed
+
+- **Dependency floors raised past known-vulnerable releases** (#399). `cryptography>=48.0.1`, `jupyter_server>=2.20.0`, `litellm>=1.83.7`, `mcp>=1.28.1`, `urllib3>=2.7.0`, `tornado>=6.5.7`, `starlette>=1.3.1`, `pydantic-settings>=2.14.2`, `aiohttp>=3.14.1`, `mistune>=3.3.0`, and `python-multipart>=0.0.27`, plus npm-side overrides for the transitive packages whose parents did not pin tightly enough. `mcp` is additionally capped below `2.0`: 2.x moved the FastMCP server out of the SDK, so `mcp.server.fastmcp.tools` no longer exists there and the server extension fails to load.
+- **Chat response streams now finalize when participant handlers return** (#403). Participant implementations must complete streaming and UI-command work before their awaited `handle_chat_request` coroutine returns; detached post-return writes (including provider events arriving after a timeout) are logged and ignored so every request delivers exactly one terminal response. Cancelling a GitHub Copilot chat stream now also stops consuming later provider events.
+- **Large cell-output and Claude terminal-tool results are bounded before returning to the agent** (#404). Oversized responses now retain their beginning and end with an explicit truncation marker instead of consuming the agent's context without limit, and cell-output tools accept optional `offset` and `limit` arguments so agents can retrieve omitted ranges. Source-returning and structured tools remain lossless, while unexpected structured values from the text-oriented cell-output and terminal bridges are stringified and bounded. Claude's approximate output budget defaults to 10,000 tokens and can be adjusted with `NBI_CLAUDE_TOOL_RESULT_MAX_OUTPUT_TOKENS`; set it to numeric zero to restore unbounded output.
+- **Ask-mode chat requests are budgeted against the active model's context window** (#412). Prior conversation and current-turn context are now fitted to 80% of the model's input budget instead of being sent whole. System instructions, injected rules, required inline-edit source, an MCP prompt sequence, and the newest request are preserved, with the newest request truncated only when mandatory context cannot otherwise fit; older history is retained only as complete turns, so a tool-call exchange is never split. Fenced and multimodal context is dropped whole rather than cut mid-delimiter, and an omission notice is added when anything was left out. Agent tool loops are unchanged. OpenAI-compatible and LiteLLM-compatible providers require an explicit **Context window** setting; left blank, history is passed through unchanged rather than pruned against a guessed limit.
+
+### Fixed
+
+- **Claude inline edits now receive their intended system instructions and applicable workspace rules** (#405). The inline-edit prompt is forwarded through the Claude handler to Anthropic's `system` field instead of being silently dropped before generation. Injected repository guidance is capped against the model context window, and disabling rules now suppresses `AGENTS.md` instructions as well as configured rule files.
+- **Empty code blocks no longer render as inline code with actions attached** (#407). A fenced block that streamed in empty was misclassified as an inline span, so the chat renderer offered copy and insert actions on nothing.
+- **GitHub Copilot chat no longer sends an unsupported `stop` parameter** (#397). Chat requests carried `stop: ['<END>']` to `/chat/completions`, with `gpt-5` and `gpt-5-mini` excluded by literal id comparison after they began rejecting it. Every GPT-5 family model released since inherited that blind spot: selecting GPT-5.4 made chat unusable, with each message failing as `Unsupported parameter: 'stop' is not supported with this model`. The parameter is now omitted for every model on that endpoint. The `<END>` sentinel was never load-bearing there, and the model id does not predict which models reject it, so no id-keyed exclusion list can stay correct. Inline completions, which use a different endpoint where the sentinel does bound a completion, are unchanged.
+- **AI-streamed code blocks no longer pick up trailing whitespace** (#384). The chat renderer ran a blanket `\n` to `  \n` string replace before markdown parsing, intended for user input but applied to every message, which injected two trailing spaces into every line of a streamed fenced code block and carried them into anything copy-pasted out. The pre-parse transform is gone; NBI now uses the `remark-breaks` plugin, which converts soft breaks to hard breaks at the AST level and is fence-aware, so prose still breaks on single newlines while code blocks are left alone in both directions.
+- **Inline-code styling no longer leaks into fenced code blocks** (#401). `react-markdown` 9 stopped setting the `inline` prop, so the chat renderer's `inline || !match` branch also caught fenced blocks with an unrecognized or missing language and gave them the inline-code pill background; the visible symptom reported was a first-line indent on highlighted blocks, which is that rule's `padding: 1px 4px` landing on a `<code>` it was never meant to reach. Inline and fenced content are now told apart by content shape (`remark-rehype` appends a trailing newline to fenced code and never to an inline span), and the CSS targets an explicit `.inline-code` class instead of `:not(pre) > code`, which had itself been broken by the `PreTag="div"` wrapper the syntax highlighter inserts.
+- **Korean and other IME composition needs only one Enter to submit** (#400). The chat input listened for `keydown` without checking composition state, so the Enter that commits an IME candidate also submitted the message, and users typing Hangul had to retype the last syllable. The handler now ignores Enter while a composition is in progress.
+
+## [5.3.1] - 2026-07-29
+
+A patch release: one skills-import fix. No traitlet, env-var, REST route, or on-disk-format changes.
+
+### Fixed
+
+- **The GitHub skill-import size cap applies to the skill subpath, not the whole repository** (#394). Importing a single skill from a large monorepo could be rejected because the cap was measured against every file in the archive rather than the subdirectory actually being imported, so legitimate imports failed on repository size alone.
+
+## [5.3.0] - 2026-07-22
+
+5.3.0 makes notebook work kernel-aware rather than Python-assuming, modernizes the Claude model defaults, and adds an opt-in per-turn usage footer. It also carries two workspace-containment fixes for the built-in file tools. One ruleset frontmatter key was removed; see the migration note.
+
+### Migration note
+
+- **`scope.kernels` is no longer accepted in ruleset frontmatter** (#379). The old key conflated a kernel name with a language. Rules now scope on `scope.languages` (the notebook's language, e.g. `python`) or `scope.kernel_names` (the kernelspec name, e.g. `python3`), and a rule file that still uses `scope.kernels` is rejected with a `ValueError` naming the file rather than being silently ignored. Update any rule that used it; see [Ruleset system](docs/rulesets.md).
+
+### Added
+
+- **Multi-language and kernel-aware notebook support** (#379). Notebook creation, cell insertion, and inline code generation previously assumed Python. NBI now resolves the active notebook's kernel and language and carries them through the chat context, the built-in toolsets, and the ruleset scope, so generated code matches the notebook it is going into. A `list-available-notebook-kernels` tool lets the agent enumerate installed kernelspecs instead of guessing a name, and the Claude system prompt instructs it to call that tool before creating a notebook in a language the current context has not established. Requesting a notebook in a kernel that is not installed now raises instead of silently falling back to Python.
+- **Opt-in per-turn usage footer in Claude mode** (#391). The Claude SDK ends every turn with a `ResultMessage` carrying duration, token counts, and a cost estimate, which NBI previously discarded. Setting `show_turn_usage` in the Claude settings (default off) appends a one-line italic footer to each completed turn. The `$` cost segment is shown only when NBI is running against a direct Anthropic API key on Anthropic's own endpoint: the SDK prices from the CLI's built-in public list rates, so on a subscription login the marginal cost is really zero and on a custom `base_url` the endpoint's pricing is unknown. Duration and token counts, which are always accurate, are shown either way.
+- **Inline-completion and inline-chat acceptance are tracked as distinct telemetry events** (#383). Acceptance of a ghost-text completion and acceptance of an inline-chat edit were previously indistinguishable. JupyterLab's inline-completer provider interface has no accept callback, so NBI wraps JupyterLab's own `IInlineCompleterFactory` and patches `accept()` on the widget instance rather than subclassing the completer. The factory is taken as an optional dependency, so NBI still loads if JupyterLab stops providing it. See [Telemetry events](docs/admin-guide.md#telemetry-events).
+
+### Changed
+
+- **Claude model defaults modernized, and inline-completion output bounded** (#389). The chat default resolves to `claude-sonnet-5` and the inline-completion default to `claude-haiku-4-5`, both resolved against the live model list rather than a hardcoded id, with a version-aware fallback within the tier (a bogus `claude-sonnet-99` resolves to the newest Sonnet, not a lexicographic pick). Because the Models API lists Haiku only under its dated id, the inline default resolves to that snapshot and logs an INFO line at startup; that line is expected, not an error. Inline-completion output is capped at 1024 tokens instead of 10,000, since a suggestion is at most a few dozen lines and the old ceiling let a rambling response generate for seconds before the extraction regex discarded most of it. `NBI_CLAUDE_INLINE_COMPLETION_MAX_TOKENS` overrides the cap and is clamped to `[1, 4096]`. The fetched model list is cached per endpoint, so switching `base_url` no longer reuses the previous endpoint's models.
+- **Context token budget derives from the Claude model in Claude mode** (#390). The budget was computed from the general chat model's context window even when Claude mode was active, so history was trimmed against the wrong number.
+
+### Fixed
+
+- **`search_files` reads are confined to the workspace** (#386). The tool sandboxed only the search root, then opened each glob hit directly, so a symlink inside the workspace pointing outside it (`leak.txt -> /etc/passwd`) let an agent-mode model read arbitrary host files through `content_pattern` matches. `read_file` already routed every path through the workspace gate and rejected outbound symlinks after resolution; `search_files` now does the same for each match. Confidentiality only, no write path.
+- **Outbound symlinks are no longer stat-followed during enumeration** (#387). The directory-descent check called `is_dir(follow_symlinks=True)` on a symlink's target before testing that target for workspace containment. The containment check still rejected it afterwards, so nothing was read, but the probe itself reached past the workspace boundary. The path is now resolved and range-checked first, and only an in-workspace target is stat'd. No behavior change beyond that.
+- **Attachment context survives a slash-command prompt** (#388). When the last user line started with `/`, the CLI query assembly kept only that line and silently discarded the context lines NBI had just appended for the same turn: attachment `@`-mentions, cell pointers, and output context. Control-only commands (`/clear`, `/cost`, and friends) still drop the context, since it means nothing to them, but any other command is now moved to the front of the query, where the CLI expects it, with the context lines preserved after it. Custom skill and plugin commands therefore receive the user's attachments.
+- **Kernel-scoped rules apply to inline code generation** (#379). Inline generation did not pass the notebook's kernel into rule selection, so rules scoped to a kernel or language never matched there.
+
+## [5.2.1] - 2026-06-26
+
+A patch release: one Claude-mode timeout fix. No traitlet, env-var, REST route, or on-disk-format changes.
+
+### Fixed
+
+- **A turn waiting on a user prompt no longer times out** (#381). Time spent blocked on the user counted toward the agent response timeout, so an approval left on screen for about 30 minutes failed the turn with "Claude agent response timeout" while the worker was still mid-request, and the orphaned request then wedged the next prompt. NBI now tracks the wall-clock time a turn spends waiting on input (every tool approval, plan confirmation, and question) and subtracts it from the timeout window, so a slow human reply no longer looks like an unresponsive agent while a genuine post-approval hang still trips the timeout. The user-input listener is also disconnected in a `finally`, so a cancelled turn cannot leak the subscription. Because a parked approval no longer self-resolves via the timeout, in-flight requests are cancelled when the WebSocket closes: an abandoned turn (the user closes the tab) tears down its worker thread and the Claude subprocess instead of spinning until the process exits.
+
+## [5.2.0] - 2026-06-18
+
+5.2.0 adds the Claude permission-mode selector to the chat input, halves the server-extension import cost by deferring provider SDK imports, and makes three Claude-CLI integration points honor `CLAUDE_CONFIG_DIR`. One new admin policy (`claude_bypass_permissions_policy`), which defaults to `force-off`; no traitlet, env-var, REST route, or on-disk-format renames or removals.
 
 ### Added
 

{notebook_intelligence-5.3.1 → notebook_intelligence-5.4.0}/CONTRIBUTING.md

@@ -165,7 +165,14 @@ TypeScript unit tests:
 jlpm test
 ```
 
-There is no Python test suite at the moment. Manual end-to-end verification is documented per change in pull request descriptions.
+Python tests (the `test` extra pulls in pytest, `pytest-timeout`, `psutil`, and `pyyaml`):
+
+```bash
+pip install -e ".[test]"
+pytest tests/ -q
+```
+
+CI runs both suites on every push, in that order. Every test is capped at 30 seconds by `pytest-timeout`, so a hung subprocess or pipe fails the run instead of stalling the job.
 
 ## Linting
 

{notebook_intelligence-5.3.1 → notebook_intelligence-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: notebook_intelligence
-Version: 5.3.1
+Version: 5.4.0
 Summary: AI coding assistant for JupyterLab
 Project-URL: Homepage, https://github.com/plmbr/notebook-intelligence
 Project-URL: Bug Tracker, https://github.com/plmbr/notebook-intelligence/issues
@@ -694,14 +694,15 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.10
+Requires-Dist: agent-client-protocol==0.10.1
 Requires-Dist: aiohttp>=3.14.1
 Requires-Dist: anthropic>=0.22.1
 Requires-Dist: claude-agent-sdk
-Requires-Dist: cryptography
+Requires-Dist: cryptography>=48.0.1
 Requires-Dist: fuzy-jon==0.1.0
 Requires-Dist: jupyter-server<3,>=2.20.0
 Requires-Dist: litellm>=1.83.7
-Requires-Dist: mcp>=1.28.1
+Requires-Dist: mcp<2,>=1.28.1
 Requires-Dist: mistune>=3.3.0
 Requires-Dist: ollama
 Requires-Dist: openai
@@ -739,6 +740,7 @@ NBI is free and open-source. Connect it to a free or paid LLM provider of your c
   - [Chat interface](#chat-interface)
   - [Cell output actions](#cell-output-actions)
   - [Notebook toolbar generation](#notebook-toolbar-generation)
+  - [Multi-language and kernel-aware notebooks](#multi-language-and-kernel-aware-notebooks)
   - [Reload open files when changed on disk](#reload-open-files-when-changed-on-disk)
 - [Configuration](#configuration)
   - [Configuration files](#configuration-files)
@@ -751,6 +753,8 @@ NBI is free and open-source. Connect it to a free or paid LLM provider of your c
 - [Claude MCP Servers](#claude-mcp-servers)
 - [Claude Plugins](#claude-plugins)
 - [Chat feedback](#chat-feedback)
+- [Configuration readiness](#configuration-readiness)
+- [Performance diagnostics](#performance-diagnostics)
 - [Documentation](#documentation)
 - [Further reading](#further-reading)
 - [Roadmap](#roadmap)
@@ -807,6 +811,9 @@ Configure via the NBI Settings dialog (gear icon in the chat panel, or _Settings
 - **Chat Agent setting sources** — user, project, or both, mirroring [Claude Code's settings](https://code.claude.com/docs/en/settings).
 - **Chat Agent tools** — which tool sets to activate. _Claude Code tools_ are always on. _Jupyter UI tools_ are NBI's own (authoring notebooks, running cells, etc.).
 - **API key** and **Base URL** — point at Anthropic or a self-hosted endpoint.
+- **Show turn usage**: off by default. When on, each completed turn ends with a one-line italic footer giving the turn's duration and token counts. A `$` cost figure appears only when NBI is running against a direct Anthropic API key on Anthropic's own endpoint: the SDK prices from the CLI's built-in public list rates, which are not the marginal cost on a subscription login and not the rate on a custom `base_url`, so NBI omits a number it cannot stand behind rather than showing a misleading one.
+
+**Model defaults.** With no model selected, the chat model resolves to the newest Sonnet (`claude-sonnet-5` today) and auto-complete to the newest Haiku, both matched against the model list fetched from the configured endpoint rather than a hardcoded ID. If a configured ID no longer exists, NBI falls back within the same tier by version rather than alphabetically, so `claude-sonnet-99` resolves to the newest Sonnet. The fetched list is cached per endpoint, so changing **Base URL** does not reuse the previous endpoint's models. Auto-complete responses are capped at 1024 tokens, since a suggestion is at most a few dozen lines; `NBI_CLAUDE_INLINE_COMPLETION_MAX_TOKENS` overrides the cap and is clamped to `[1, 4096]`.
 
 If the Claude Code CLI is on `PATH`, NBI launches it automatically. To override the location, set the `NBI_CLAUDE_CLI_PATH` environment variable before starting JupyterLab.
 
@@ -827,7 +834,7 @@ Bypass Permissions never persists: starting a **New chat session** (or `/clear`)
 
 Choosing **Bypass Permissions** does not arm it immediately. It opens a confirmation step; only after you confirm does bypass take effect, and while it is active the shield turns into a red warning icon as a persistent indicator. Bypass must be re-armed each session: starting a new chat or restarting the Claude client drops back to Default. And because the server re-checks the requested mode on every message, an armed bypass can never outlive a policy that an administrator has since turned off.
 
-**Admin gating.** Bypass Permissions is **off by default** and hidden from the selector unless an administrator enables it: it is governed by the `claude_bypass_permissions` policy (`NBI_CLAUDE_BYPASS_PERMISSIONS_POLICY`), the only admin policy whose default is `force-off` rather than `user-choice`. The requested mode is also clamped on the server for every message, so the gate can't be bypassed by a hand-crafted request. Independently, NBI honors Claude Code's enterprise [managed settings](https://code.claude.com/docs/en/settings): `permissions.disableBypassPermissionsMode` removes the option regardless of the NBI policy, and `permissions.defaultMode` sets the selector's starting mode (Bypass excepted, since it never auto-arms). See [Allowing Bypass Permissions](docs/admin-guide.md#allowing-bypass-permissions-in-the-claude-permission-mode-selector) in the admin guide.
+**Admin gating.** Bypass Permissions is **off by default** and hidden from the selector unless an administrator enables it: it is governed by the `claude_bypass_permissions` policy (`NBI_CLAUDE_BYPASS_PERMISSIONS_POLICY`), one of three admin policies that default to `force-off` rather than `user-choice` (the others gate the experimental ACP agent mode and ACP full access). The requested mode is also clamped on the server for every message, so the gate can't be bypassed by a hand-crafted request. Independently, NBI honors Claude Code's enterprise [managed settings](https://code.claude.com/docs/en/settings): `permissions.disableBypassPermissionsMode` removes the option regardless of the NBI policy, and `permissions.defaultMode` sets the selector's starting mode (Bypass excepted, since it never auto-arms). See [Allowing Bypass Permissions](docs/admin-guide.md#allowing-bypass-permissions-in-the-claude-permission-mode-selector) in the admin guide.
 
 The `/enter-plan-mode` and `/exit-plan-mode` slash commands still work if typed but are no longer offered in autocomplete; the selector replaces them and will retire the commands in a future release.
 
@@ -900,6 +907,12 @@ Each is per-user toggleable from Settings (saved as `enable_explain_error`, `ena
 
 Active notebooks show a sparkle icon on the toolbar. Click it to open a popover that scopes the generation request to that specific notebook — handy for multi-notebook sessions where you don't want the chat sidebar to compete for context.
 
+### Multi-language and kernel-aware notebooks
+
+Notebook creation, cell insertion, and inline generation follow the notebook you are actually in rather than assuming Python. NBI resolves the active notebook's kernel and language and carries both through the chat context, the built-in tools, and ruleset scoping, so generated code matches the target notebook, and a rule scoped to `languages: ['r']` or `kernel_names: ['ir']` applies where you would expect (including in inline generation, which previously did not receive the kernel).
+
+When the agent needs a notebook in a language the current context has not established, it calls a `list-available-notebook-kernels` tool and picks from the kernelspecs that are actually installed instead of guessing a name. Asking for a kernel that is not installed now fails with a clear error rather than silently producing a Python notebook.
+
 ### Reload open files when changed on disk
 
 NBI reloads open document tabs when their files change on disk, so edits an AI agent makes via its Read/Write tools appear in the editor without a manual refresh. Tabs with unsaved local edits are skipped so user work is never clobbered. Toggle via the **NBI Settings dialog → External changes → "Refresh open files when changed on disk"** (default on).
@@ -924,24 +937,26 @@ Most settings panel toggles can be locked by org administrators. Two shapes:
 
 **Boolean policies** use the `*_POLICY` suffix and accept three values: `user-choice` (default — user toggles freely), `force-on` (locked enabled), `force-off` (locked disabled). When forced, the panel control is disabled with a "Locked by your administrator" tooltip and any client-side write is ignored.
 
-| Env var                                        | Locks the Settings panel control for                                                                                                                                                      |
-| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `NBI_EXPLAIN_ERROR_POLICY`                     | "Explain cell errors"                                                                                                                                                                     |
-| `NBI_OUTPUT_FOLLOWUP_POLICY`                   | "Ask about cell outputs"                                                                                                                                                                  |
-| `NBI_OUTPUT_TOOLBAR_POLICY`                    | "Show output toolbar"                                                                                                                                                                     |
-| `NBI_CLAUDE_MODE_POLICY`                       | "Enable Claude mode"                                                                                                                                                                      |
-| `NBI_CLAUDE_CONTINUE_CONVERSATION_POLICY`      | "Remember conversation history"                                                                                                                                                           |
-| `NBI_CLAUDE_CODE_TOOLS_POLICY`                 | "Claude Code tools"                                                                                                                                                                       |
-| `NBI_CLAUDE_JUPYTER_UI_TOOLS_POLICY`           | "Jupyter UI tools"                                                                                                                                                                        |
-| `NBI_CLAUDE_SETTING_SOURCE_USER_POLICY`        | Setting source: User                                                                                                                                                                      |
-| `NBI_CLAUDE_SETTING_SOURCE_PROJECT_POLICY`     | Setting source: Project                                                                                                                                                                   |
-| `NBI_STORE_GITHUB_ACCESS_TOKEN_POLICY`         | "Remember my GitHub Copilot access token"                                                                                                                                                 |
-| `NBI_SKILLS_MANAGEMENT_POLICY`                 | The Skills tab (force-off hides it and 403s the API; also disables the managed-skills reconciler)                                                                                         |
-| `NBI_CLAUDE_MCP_MANAGEMENT_POLICY`             | The Claude-mode MCP Servers tab (force-off hides it and 403s `/claude-mcp/*`; independent of the non-Claude MCP Servers tab)                                                              |
-| `NBI_CLAUDE_PLUGINS_MANAGEMENT_POLICY`         | The Claude-mode Plugins tab (force-off hides it and 403s `/plugins/*`)                                                                                                                    |
-| `NBI_CLAUDE_BYPASS_PERMISSIONS_POLICY`         | "Bypass Permissions" in the Claude permission-mode selector (defaults to `force-off`, the only policy that does; `user-choice` exposes the option, which the user still arms per session) |
-| `NBI_TERMINAL_DRAG_DROP_POLICY`                | Terminal drag-drop file attach feature                                                                                                                                                    |
-| `NBI_REFRESH_OPEN_FILES_ON_DISK_CHANGE_POLICY` | "Refresh open files when changed on disk"                                                                                                                                                 |
+| Env var                                        | Locks the Settings panel control for                                                                                                                                                                                         |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NBI_EXPLAIN_ERROR_POLICY`                     | "Explain cell errors"                                                                                                                                                                                                        |
+| `NBI_OUTPUT_FOLLOWUP_POLICY`                   | "Ask about cell outputs"                                                                                                                                                                                                     |
+| `NBI_OUTPUT_TOOLBAR_POLICY`                    | "Show output toolbar"                                                                                                                                                                                                        |
+| `NBI_CLAUDE_MODE_POLICY`                       | "Enable Claude mode"                                                                                                                                                                                                         |
+| `NBI_ACP_MODE_POLICY`                          | "Enable ACP mode" (experimental agent mode over the Agent Client Protocol, with Codex as the first agent type; defaults to `force-off`, set `user-choice` to allow it)                                                       |
+| `NBI_ACP_FULL_ACCESS_POLICY`                   | "Full access" for the ACP agent: run tools without asking (defaults to `force-off`, so the agent asks before anything beyond trusted read-only commands; `user-choice` lets users opt into unattended runs)                  |
+| `NBI_CLAUDE_CONTINUE_CONVERSATION_POLICY`      | "Remember conversation history"                                                                                                                                                                                              |
+| `NBI_CLAUDE_CODE_TOOLS_POLICY`                 | "Claude Code tools"                                                                                                                                                                                                          |
+| `NBI_CLAUDE_JUPYTER_UI_TOOLS_POLICY`           | "Jupyter UI tools"                                                                                                                                                                                                           |
+| `NBI_CLAUDE_SETTING_SOURCE_USER_POLICY`        | Setting source: User                                                                                                                                                                                                         |
+| `NBI_CLAUDE_SETTING_SOURCE_PROJECT_POLICY`     | Setting source: Project                                                                                                                                                                                                      |
+| `NBI_STORE_GITHUB_ACCESS_TOKEN_POLICY`         | "Remember my GitHub Copilot access token"                                                                                                                                                                                    |
+| `NBI_SKILLS_MANAGEMENT_POLICY`                 | The Skills tab (force-off hides it and 403s the API; also disables the managed-skills reconciler)                                                                                                                            |
+| `NBI_CLAUDE_MCP_MANAGEMENT_POLICY`             | The Claude-mode MCP Servers tab (force-off hides it and 403s `/claude-mcp/*`; independent of the non-Claude MCP Servers tab)                                                                                                 |
+| `NBI_CLAUDE_PLUGINS_MANAGEMENT_POLICY`         | The Claude-mode Plugins tab (force-off hides it and 403s `/plugins/*`)                                                                                                                                                       |
+| `NBI_CLAUDE_BYPASS_PERMISSIONS_POLICY`         | "Bypass Permissions" in the Claude permission-mode selector (defaults to `force-off`, as do `NBI_ACP_MODE_POLICY` and `NBI_ACP_FULL_ACCESS_POLICY`; `user-choice` exposes the option, which the user still arms per session) |
+| `NBI_TERMINAL_DRAG_DROP_POLICY`                | Terminal drag-drop file attach feature                                                                                                                                                                                       |
+| `NBI_REFRESH_OPEN_FILES_ON_DISK_CHANGE_POLICY` | "Refresh open files when changed on disk"                                                                                                                                                                                    |
 
 The first three also have matching traitlets on `NotebookIntelligence` (`explain_error_policy`, `output_followup_policy`, `output_toolbar_policy`); add the others as needed in the same shape:
 
@@ -962,10 +977,18 @@ Per-user preferences (default on for the cell-output features) live in `config.j
 | `NBI_CHAT_MODEL_ID`                    | General → Chat model → Model                                                 |
 | `NBI_INLINE_COMPLETION_MODEL_PROVIDER` | General → Auto-complete model → Provider                                     |
 | `NBI_INLINE_COMPLETION_MODEL_ID`       | General → Auto-complete model → Model                                        |
-| `NBI_CLAUDE_CHAT_MODEL`                | Claude → Chat model                                                          |
+| `NBI_CLAUDE_CHAT_MODEL`                | Claude → Chat model (and Inline chat model, unless pinned separately)        |
+| `NBI_CLAUDE_INLINE_CHAT_MODEL`         | Claude → Chat model → Inline chat model                                      |
 | `NBI_CLAUDE_INLINE_COMPLETION_MODEL`   | Claude → Auto-complete model                                                 |
 | `ANTHROPIC_API_KEY`                    | Claude → API Key (input is locked + blanked; the SDK reads the env directly) |
 | `ANTHROPIC_BASE_URL`                   | Claude → Base URL                                                            |
+| `NBI_ACP_CHAT_MODEL`                   | ACP → Chat model                                                             |
+| `OPENAI_API_KEY`                       | ACP → API Key (input is locked + blanked; the agent reads the env directly)  |
+| `OPENAI_BASE_URL`                      | ACP → Base URL                                                               |
+
+Inline chat calls the Anthropic API directly while the other Claude modes go through the Claude Code CLI, so a deployment can need a different model id for each. It uses `inline_chat_model`, falling back to `chat_model` when that is unset. `NBI_CLAUDE_CHAT_MODEL` therefore governs both surfaces: while it is set, a stored `inline_chat_model` is ignored and its control is disabled. Set `NBI_CLAUDE_INLINE_CHAT_MODEL` as well to pin inline chat to a different model — it takes precedence and re-enables nothing, so both surfaces stay administrator-controlled.
+
+`NBI_ACP_AGENT_COMMAND` (not a settings lock) overrides the adapter command NBI launches for the selected ACP agent type; the value is shell-split. Leave it unset to use the agent's registered default command.
 
 Provider IDs: `github-copilot`, `openai-compatible`, `litellm-compatible`, `ollama`, `none`. The `*_MODEL_ID` value is whatever the chosen provider exposes (e.g. `gpt-4o`, `llama3:latest`). Claude model IDs are the literal IDs from the Anthropic API (e.g. `claude-opus-4-7`, `claude-sonnet-4-6`); empty string = "Default (recommended)"; `NBI_CLAUDE_INLINE_COMPLETION_MODEL` also accepts `none` (no inline completion in Claude mode) or `inherit` (use the General-tab Auto-complete model).
 
@@ -1012,7 +1035,7 @@ In multi-tenant deployments, `nbi-command-execute` and `nbi-file-edit` are effec
 
 ## Model Context Protocol (MCP) support
 
-NBI integrates with [MCP](https://modelcontextprotocol.io) servers. It supports both stdio and Streamable HTTP transports. **MCP server tools are supported; resources and prompts are not yet supported.**
+NBI integrates with [MCP](https://modelcontextprotocol.io) servers. It supports both stdio and Streamable HTTP transports. **Tools and prompts are supported; resources are not.** A server's prompts appear in the chat input's slash-command autocomplete as `/mcp:<server>:<prompt>`.
 
 Add MCP servers by editing `~/.jupyter/nbi/mcp.json`. An environment-wide base file at `<env-prefix>/share/jupyter/nbi/mcp.json` is also supported.
 
@@ -1139,12 +1162,46 @@ c.NotebookIntelligence.enable_chat_feedback_always_visible = True
 
 <img src="media/chat-feedback.png" alt="Chat feedback" width=500 />
 
+## Configuration readiness
+
+NBI Settings opens on a **Status** card that answers one question: is this deployment configured to work, and if not, which specific piece is missing? Each check reports `ok`, `warn`, or `blocked`, and anything that is not `ok` carries the next action rather than just the failure ("the claude CLI was not found" plus "install it, or set `NBI_CLAUDE_CLI_PATH` and restart").
+
+It runs on open and costs nothing: it resolves your provider and model, checks the model list is reachable and that your selected model is one the endpoint actually serves, and for the agent modes checks that the CLI answers `--version` and that credentials are present. A missing key is a warning rather than an error, because the Claude CLI and ACP agents can hold their own subscription logins that NBI cannot see.
+
+**Test the endpoint** sends one short request to your configured model, after asking first. It is the only way to catch two failures nothing cheaper can see: a gateway that returns 200s but buffers instead of streaming, and a proxy that strips the `tools` field so agent mode silently never calls a tool. No model output is kept, so the result is safe to paste into a support ticket.
+
+That button is the only readiness check that bills anything, so it has an off switch: `NBI_READINESS_LIVE_CHECK=off` (traitlet `readiness_live_check_allowed`, default on) refuses it while leaving every other check available. One live test runs at a time per server; a second concurrent request gets a 429 rather than spending tokens.
+
+## Performance diagnostics
+
+An opt-in mode for answering "where did this turn's time go," aimed at deployments where NBI feels slower than it should: internal LLM gateways, network home directories, TLS-intercepting proxies. Off by default, and when off the cost is a single boolean check per instrumentation site.
+
+**Turning it on.** NBI Settings, **Performance** tab, **Enabled**. It takes effect immediately with no restart.
+
+**Reading a turn.** Every chat turn records a phase timeline (rule and context preparation, agent connect and spawn, time to first token, streaming with stall events, tool calls, time spent waiting on you) plus token counts and the SDK-reported API duration. The table shows the recent turns, one row each, with a **Verdict** column naming the phase that dominated. The comparison that matters most is **Active** against **API ms**: close together means the time is in the gateway or the model, far apart means it is local. Expanding a row shows that turn's spans as proportional bars with their attributes. Each turn is also summarized as one `perf turn ...` INFO line in the Jupyter server log, so headless installs get the same signal with no UI.
+
+**Reading the environment.** **Run probe** measures the machine instead of a turn: filesystem latency and throughput for the config and `~/.claude` directories with filesystem type and mount options, interpreter and CLI cold-start cost, and process and host contention. Results are grouped and banded, so a slow network filesystem or a throttled container is called out in a sentence rather than left in a JSON blob. An opt-in network check adds connections to your configured endpoint to time DNS, TCP, and TLS and to capture the presented certificate chain, which is what makes TLS interception visible. It asks for confirmation first and names the host it will contact.
+
+**Privacy.** Recorded: durations, counts, byte sizes, status enums, token counts, and tool, server, model, and provider names. Never recorded: prompt or response text, file contents, absolute paths, environment variable values, API keys, exception messages, or hostnames. This is enforced by a fixed per-attribute allowlist rather than by convention, and the default `redacted` detail level additionally hashes file basenames and model, tool, and server names.
+
+**Collecting across sessions.** Turns can optionally be appended as JSON Lines to `<nbi-dir>/perf/`, with size- and age-capped retention. On network home directories, point the log at local scratch with `NBI_PERF_LOG_DIR`.
+
+Full guide, including the span and event reference, the probe thresholds, worked diagnoses for a slow gateway, a slow home directory, and an intercepting proxy, and the JSONL schema: [`docs/performance-diagnostics.md`](docs/performance-diagnostics.md).
+
+| Environment variable          | Effect                                                                                                         |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `NBI_PERF_DIAGNOSTICS`        | Locks the enabled state on or off (value lock; the UI shows the toggle as locked).                             |
+| `NBI_PERF_DIAGNOSTICS_POLICY` | `user-choice` (default), `force-off`, or `force-on` (fleet-wide collection with redacted attributes enforced). |
+| `NBI_PERF_PROBE_NETWORK`      | `off` disables just the probe's network check while leaving the rest available.                                |
+| `NBI_PERF_LOG_DIR`            | Redirects the JSONL perf log directory.                                                                        |
+
 ## Documentation
 
 - [`docs/admin-guide.md`](docs/admin-guide.md) — deployment, env vars, security model, air-gap, multi-tenancy.
 - [`docs/skills.md`](docs/skills.md) — Claude Skills management and the org-manifest reconciler.
 - [`docs/rulesets.md`](docs/rulesets.md) — ruleset frontmatter and discovery.
 - [`docs/troubleshooting.md`](docs/troubleshooting.md) — common problems with copy-pasteable fixes.
+- [`docs/performance-diagnostics.md`](docs/performance-diagnostics.md): turn timelines, the environment probe, and how to read both.
 - [`PRIVACY.md`](PRIVACY.md) — what NBI sends to which provider, and the egress allowlist.
 - [`SECURITY.md`](SECURITY.md) — how to report a vulnerability.
 - [`CHANGELOG.md`](CHANGELOG.md) — release history.

{notebook_intelligence-5.3.1 → notebook_intelligence-5.4.0}/README.md

@@ -17,6 +17,7 @@ NBI is free and open-source. Connect it to a free or paid LLM provider of your c
   - [Chat interface](#chat-interface)
   - [Cell output actions](#cell-output-actions)
   - [Notebook toolbar generation](#notebook-toolbar-generation)
+  - [Multi-language and kernel-aware notebooks](#multi-language-and-kernel-aware-notebooks)
   - [Reload open files when changed on disk](#reload-open-files-when-changed-on-disk)
 - [Configuration](#configuration)
   - [Configuration files](#configuration-files)
@@ -29,6 +30,8 @@ NBI is free and open-source. Connect it to a free or paid LLM provider of your c
 - [Claude MCP Servers](#claude-mcp-servers)
 - [Claude Plugins](#claude-plugins)
 - [Chat feedback](#chat-feedback)
+- [Configuration readiness](#configuration-readiness)
+- [Performance diagnostics](#performance-diagnostics)
 - [Documentation](#documentation)
 - [Further reading](#further-reading)
 - [Roadmap](#roadmap)
@@ -85,6 +88,9 @@ Configure via the NBI Settings dialog (gear icon in the chat panel, or _Settings
 - **Chat Agent setting sources** — user, project, or both, mirroring [Claude Code's settings](https://code.claude.com/docs/en/settings).
 - **Chat Agent tools** — which tool sets to activate. _Claude Code tools_ are always on. _Jupyter UI tools_ are NBI's own (authoring notebooks, running cells, etc.).
 - **API key** and **Base URL** — point at Anthropic or a self-hosted endpoint.
+- **Show turn usage**: off by default. When on, each completed turn ends with a one-line italic footer giving the turn's duration and token counts. A `$` cost figure appears only when NBI is running against a direct Anthropic API key on Anthropic's own endpoint: the SDK prices from the CLI's built-in public list rates, which are not the marginal cost on a subscription login and not the rate on a custom `base_url`, so NBI omits a number it cannot stand behind rather than showing a misleading one.
+
+**Model defaults.** With no model selected, the chat model resolves to the newest Sonnet (`claude-sonnet-5` today) and auto-complete to the newest Haiku, both matched against the model list fetched from the configured endpoint rather than a hardcoded ID. If a configured ID no longer exists, NBI falls back within the same tier by version rather than alphabetically, so `claude-sonnet-99` resolves to the newest Sonnet. The fetched list is cached per endpoint, so changing **Base URL** does not reuse the previous endpoint's models. Auto-complete responses are capped at 1024 tokens, since a suggestion is at most a few dozen lines; `NBI_CLAUDE_INLINE_COMPLETION_MAX_TOKENS` overrides the cap and is clamped to `[1, 4096]`.
 
 If the Claude Code CLI is on `PATH`, NBI launches it automatically. To override the location, set the `NBI_CLAUDE_CLI_PATH` environment variable before starting JupyterLab.
 
@@ -105,7 +111,7 @@ Bypass Permissions never persists: starting a **New chat session** (or `/clear`)
 
 Choosing **Bypass Permissions** does not arm it immediately. It opens a confirmation step; only after you confirm does bypass take effect, and while it is active the shield turns into a red warning icon as a persistent indicator. Bypass must be re-armed each session: starting a new chat or restarting the Claude client drops back to Default. And because the server re-checks the requested mode on every message, an armed bypass can never outlive a policy that an administrator has since turned off.
 
-**Admin gating.** Bypass Permissions is **off by default** and hidden from the selector unless an administrator enables it: it is governed by the `claude_bypass_permissions` policy (`NBI_CLAUDE_BYPASS_PERMISSIONS_POLICY`), the only admin policy whose default is `force-off` rather than `user-choice`. The requested mode is also clamped on the server for every message, so the gate can't be bypassed by a hand-crafted request. Independently, NBI honors Claude Code's enterprise [managed settings](https://code.claude.com/docs/en/settings): `permissions.disableBypassPermissionsMode` removes the option regardless of the NBI policy, and `permissions.defaultMode` sets the selector's starting mode (Bypass excepted, since it never auto-arms). See [Allowing Bypass Permissions](docs/admin-guide.md#allowing-bypass-permissions-in-the-claude-permission-mode-selector) in the admin guide.
+**Admin gating.** Bypass Permissions is **off by default** and hidden from the selector unless an administrator enables it: it is governed by the `claude_bypass_permissions` policy (`NBI_CLAUDE_BYPASS_PERMISSIONS_POLICY`), one of three admin policies that default to `force-off` rather than `user-choice` (the others gate the experimental ACP agent mode and ACP full access). The requested mode is also clamped on the server for every message, so the gate can't be bypassed by a hand-crafted request. Independently, NBI honors Claude Code's enterprise [managed settings](https://code.claude.com/docs/en/settings): `permissions.disableBypassPermissionsMode` removes the option regardless of the NBI policy, and `permissions.defaultMode` sets the selector's starting mode (Bypass excepted, since it never auto-arms). See [Allowing Bypass Permissions](docs/admin-guide.md#allowing-bypass-permissions-in-the-claude-permission-mode-selector) in the admin guide.
 
 The `/enter-plan-mode` and `/exit-plan-mode` slash commands still work if typed but are no longer offered in autocomplete; the selector replaces them and will retire the commands in a future release.
 
@@ -178,6 +184,12 @@ Each is per-user toggleable from Settings (saved as `enable_explain_error`, `ena
 
 Active notebooks show a sparkle icon on the toolbar. Click it to open a popover that scopes the generation request to that specific notebook — handy for multi-notebook sessions where you don't want the chat sidebar to compete for context.
 
+### Multi-language and kernel-aware notebooks
+
+Notebook creation, cell insertion, and inline generation follow the notebook you are actually in rather than assuming Python. NBI resolves the active notebook's kernel and language and carries both through the chat context, the built-in tools, and ruleset scoping, so generated code matches the target notebook, and a rule scoped to `languages: ['r']` or `kernel_names: ['ir']` applies where you would expect (including in inline generation, which previously did not receive the kernel).
+
+When the agent needs a notebook in a language the current context has not established, it calls a `list-available-notebook-kernels` tool and picks from the kernelspecs that are actually installed instead of guessing a name. Asking for a kernel that is not installed now fails with a clear error rather than silently producing a Python notebook.
+
 ### Reload open files when changed on disk
 
 NBI reloads open document tabs when their files change on disk, so edits an AI agent makes via its Read/Write tools appear in the editor without a manual refresh. Tabs with unsaved local edits are skipped so user work is never clobbered. Toggle via the **NBI Settings dialog → External changes → "Refresh open files when changed on disk"** (default on).
@@ -202,24 +214,26 @@ Most settings panel toggles can be locked by org administrators. Two shapes:
 
 **Boolean policies** use the `*_POLICY` suffix and accept three values: `user-choice` (default — user toggles freely), `force-on` (locked enabled), `force-off` (locked disabled). When forced, the panel control is disabled with a "Locked by your administrator" tooltip and any client-side write is ignored.
 
-| Env var                                        | Locks the Settings panel control for                                                                                                                                                      |
-| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `NBI_EXPLAIN_ERROR_POLICY`                     | "Explain cell errors"                                                                                                                                                                     |
-| `NBI_OUTPUT_FOLLOWUP_POLICY`                   | "Ask about cell outputs"                                                                                                                                                                  |
-| `NBI_OUTPUT_TOOLBAR_POLICY`                    | "Show output toolbar"                                                                                                                                                                     |
-| `NBI_CLAUDE_MODE_POLICY`                       | "Enable Claude mode"                                                                                                                                                                      |
-| `NBI_CLAUDE_CONTINUE_CONVERSATION_POLICY`      | "Remember conversation history"                                                                                                                                                           |
-| `NBI_CLAUDE_CODE_TOOLS_POLICY`                 | "Claude Code tools"                                                                                                                                                                       |
-| `NBI_CLAUDE_JUPYTER_UI_TOOLS_POLICY`           | "Jupyter UI tools"                                                                                                                                                                        |
-| `NBI_CLAUDE_SETTING_SOURCE_USER_POLICY`        | Setting source: User                                                                                                                                                                      |
-| `NBI_CLAUDE_SETTING_SOURCE_PROJECT_POLICY`     | Setting source: Project                                                                                                                                                                   |
-| `NBI_STORE_GITHUB_ACCESS_TOKEN_POLICY`         | "Remember my GitHub Copilot access token"                                                                                                                                                 |
-| `NBI_SKILLS_MANAGEMENT_POLICY`                 | The Skills tab (force-off hides it and 403s the API; also disables the managed-skills reconciler)                                                                                         |
-| `NBI_CLAUDE_MCP_MANAGEMENT_POLICY`             | The Claude-mode MCP Servers tab (force-off hides it and 403s `/claude-mcp/*`; independent of the non-Claude MCP Servers tab)                                                              |
-| `NBI_CLAUDE_PLUGINS_MANAGEMENT_POLICY`         | The Claude-mode Plugins tab (force-off hides it and 403s `/plugins/*`)                                                                                                                    |
-| `NBI_CLAUDE_BYPASS_PERMISSIONS_POLICY`         | "Bypass Permissions" in the Claude permission-mode selector (defaults to `force-off`, the only policy that does; `user-choice` exposes the option, which the user still arms per session) |
-| `NBI_TERMINAL_DRAG_DROP_POLICY`                | Terminal drag-drop file attach feature                                                                                                                                                    |
-| `NBI_REFRESH_OPEN_FILES_ON_DISK_CHANGE_POLICY` | "Refresh open files when changed on disk"                                                                                                                                                 |
+| Env var                                        | Locks the Settings panel control for                                                                                                                                                                                         |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NBI_EXPLAIN_ERROR_POLICY`                     | "Explain cell errors"                                                                                                                                                                                                        |
+| `NBI_OUTPUT_FOLLOWUP_POLICY`                   | "Ask about cell outputs"                                                                                                                                                                                                     |
+| `NBI_OUTPUT_TOOLBAR_POLICY`                    | "Show output toolbar"                                                                                                                                                                                                        |
+| `NBI_CLAUDE_MODE_POLICY`                       | "Enable Claude mode"                                                                                                                                                                                                         |
+| `NBI_ACP_MODE_POLICY`                          | "Enable ACP mode" (experimental agent mode over the Agent Client Protocol, with Codex as the first agent type; defaults to `force-off`, set `user-choice` to allow it)                                                       |
+| `NBI_ACP_FULL_ACCESS_POLICY`                   | "Full access" for the ACP agent: run tools without asking (defaults to `force-off`, so the agent asks before anything beyond trusted read-only commands; `user-choice` lets users opt into unattended runs)                  |
+| `NBI_CLAUDE_CONTINUE_CONVERSATION_POLICY`      | "Remember conversation history"                                                                                                                                                                                              |
+| `NBI_CLAUDE_CODE_TOOLS_POLICY`                 | "Claude Code tools"                                                                                                                                                                                                          |
+| `NBI_CLAUDE_JUPYTER_UI_TOOLS_POLICY`           | "Jupyter UI tools"                                                                                                                                                                                                           |
+| `NBI_CLAUDE_SETTING_SOURCE_USER_POLICY`        | Setting source: User                                                                                                                                                                                                         |
+| `NBI_CLAUDE_SETTING_SOURCE_PROJECT_POLICY`     | Setting source: Project                                                                                                                                                                                                      |
+| `NBI_STORE_GITHUB_ACCESS_TOKEN_POLICY`         | "Remember my GitHub Copilot access token"                                                                                                                                                                                    |
+| `NBI_SKILLS_MANAGEMENT_POLICY`                 | The Skills tab (force-off hides it and 403s the API; also disables the managed-skills reconciler)                                                                                                                            |
+| `NBI_CLAUDE_MCP_MANAGEMENT_POLICY`             | The Claude-mode MCP Servers tab (force-off hides it and 403s `/claude-mcp/*`; independent of the non-Claude MCP Servers tab)                                                                                                 |
+| `NBI_CLAUDE_PLUGINS_MANAGEMENT_POLICY`         | The Claude-mode Plugins tab (force-off hides it and 403s `/plugins/*`)                                                                                                                                                       |
+| `NBI_CLAUDE_BYPASS_PERMISSIONS_POLICY`         | "Bypass Permissions" in the Claude permission-mode selector (defaults to `force-off`, as do `NBI_ACP_MODE_POLICY` and `NBI_ACP_FULL_ACCESS_POLICY`; `user-choice` exposes the option, which the user still arms per session) |
+| `NBI_TERMINAL_DRAG_DROP_POLICY`                | Terminal drag-drop file attach feature                                                                                                                                                                                       |
+| `NBI_REFRESH_OPEN_FILES_ON_DISK_CHANGE_POLICY` | "Refresh open files when changed on disk"                                                                                                                                                                                    |
 
 The first three also have matching traitlets on `NotebookIntelligence` (`explain_error_policy`, `output_followup_policy`, `output_toolbar_policy`); add the others as needed in the same shape:
 
@@ -240,10 +254,18 @@ Per-user preferences (default on for the cell-output features) live in `config.j
 | `NBI_CHAT_MODEL_ID`                    | General → Chat model → Model                                                 |
 | `NBI_INLINE_COMPLETION_MODEL_PROVIDER` | General → Auto-complete model → Provider                                     |
 | `NBI_INLINE_COMPLETION_MODEL_ID`       | General → Auto-complete model → Model                                        |
-| `NBI_CLAUDE_CHAT_MODEL`                | Claude → Chat model                                                          |
+| `NBI_CLAUDE_CHAT_MODEL`                | Claude → Chat model (and Inline chat model, unless pinned separately)        |
+| `NBI_CLAUDE_INLINE_CHAT_MODEL`         | Claude → Chat model → Inline chat model                                      |
 | `NBI_CLAUDE_INLINE_COMPLETION_MODEL`   | Claude → Auto-complete model                                                 |
 | `ANTHROPIC_API_KEY`                    | Claude → API Key (input is locked + blanked; the SDK reads the env directly) |
 | `ANTHROPIC_BASE_URL`                   | Claude → Base URL                                                            |
+| `NBI_ACP_CHAT_MODEL`                   | ACP → Chat model                                                             |
+| `OPENAI_API_KEY`                       | ACP → API Key (input is locked + blanked; the agent reads the env directly)  |
+| `OPENAI_BASE_URL`                      | ACP → Base URL                                                               |
+
+Inline chat calls the Anthropic API directly while the other Claude modes go through the Claude Code CLI, so a deployment can need a different model id for each. It uses `inline_chat_model`, falling back to `chat_model` when that is unset. `NBI_CLAUDE_CHAT_MODEL` therefore governs both surfaces: while it is set, a stored `inline_chat_model` is ignored and its control is disabled. Set `NBI_CLAUDE_INLINE_CHAT_MODEL` as well to pin inline chat to a different model — it takes precedence and re-enables nothing, so both surfaces stay administrator-controlled.
+
+`NBI_ACP_AGENT_COMMAND` (not a settings lock) overrides the adapter command NBI launches for the selected ACP agent type; the value is shell-split. Leave it unset to use the agent's registered default command.
 
 Provider IDs: `github-copilot`, `openai-compatible`, `litellm-compatible`, `ollama`, `none`. The `*_MODEL_ID` value is whatever the chosen provider exposes (e.g. `gpt-4o`, `llama3:latest`). Claude model IDs are the literal IDs from the Anthropic API (e.g. `claude-opus-4-7`, `claude-sonnet-4-6`); empty string = "Default (recommended)"; `NBI_CLAUDE_INLINE_COMPLETION_MODEL` also accepts `none` (no inline completion in Claude mode) or `inherit` (use the General-tab Auto-complete model).
 
@@ -290,7 +312,7 @@ In multi-tenant deployments, `nbi-command-execute` and `nbi-file-edit` are effec
 
 ## Model Context Protocol (MCP) support
 
-NBI integrates with [MCP](https://modelcontextprotocol.io) servers. It supports both stdio and Streamable HTTP transports. **MCP server tools are supported; resources and prompts are not yet supported.**
+NBI integrates with [MCP](https://modelcontextprotocol.io) servers. It supports both stdio and Streamable HTTP transports. **Tools and prompts are supported; resources are not.** A server's prompts appear in the chat input's slash-command autocomplete as `/mcp:<server>:<prompt>`.
 
 Add MCP servers by editing `~/.jupyter/nbi/mcp.json`. An environment-wide base file at `<env-prefix>/share/jupyter/nbi/mcp.json` is also supported.
 
@@ -417,12 +439,46 @@ c.NotebookIntelligence.enable_chat_feedback_always_visible = True
 
 <img src="media/chat-feedback.png" alt="Chat feedback" width=500 />
 
+## Configuration readiness
+
+NBI Settings opens on a **Status** card that answers one question: is this deployment configured to work, and if not, which specific piece is missing? Each check reports `ok`, `warn`, or `blocked`, and anything that is not `ok` carries the next action rather than just the failure ("the claude CLI was not found" plus "install it, or set `NBI_CLAUDE_CLI_PATH` and restart").
+
+It runs on open and costs nothing: it resolves your provider and model, checks the model list is reachable and that your selected model is one the endpoint actually serves, and for the agent modes checks that the CLI answers `--version` and that credentials are present. A missing key is a warning rather than an error, because the Claude CLI and ACP agents can hold their own subscription logins that NBI cannot see.
+
+**Test the endpoint** sends one short request to your configured model, after asking first. It is the only way to catch two failures nothing cheaper can see: a gateway that returns 200s but buffers instead of streaming, and a proxy that strips the `tools` field so agent mode silently never calls a tool. No model output is kept, so the result is safe to paste into a support ticket.
+
+That button is the only readiness check that bills anything, so it has an off switch: `NBI_READINESS_LIVE_CHECK=off` (traitlet `readiness_live_check_allowed`, default on) refuses it while leaving every other check available. One live test runs at a time per server; a second concurrent request gets a 429 rather than spending tokens.
+
+## Performance diagnostics
+
+An opt-in mode for answering "where did this turn's time go," aimed at deployments where NBI feels slower than it should: internal LLM gateways, network home directories, TLS-intercepting proxies. Off by default, and when off the cost is a single boolean check per instrumentation site.
+
+**Turning it on.** NBI Settings, **Performance** tab, **Enabled**. It takes effect immediately with no restart.
+
+**Reading a turn.** Every chat turn records a phase timeline (rule and context preparation, agent connect and spawn, time to first token, streaming with stall events, tool calls, time spent waiting on you) plus token counts and the SDK-reported API duration. The table shows the recent turns, one row each, with a **Verdict** column naming the phase that dominated. The comparison that matters most is **Active** against **API ms**: close together means the time is in the gateway or the model, far apart means it is local. Expanding a row shows that turn's spans as proportional bars with their attributes. Each turn is also summarized as one `perf turn ...` INFO line in the Jupyter server log, so headless installs get the same signal with no UI.
+
+**Reading the environment.** **Run probe** measures the machine instead of a turn: filesystem latency and throughput for the config and `~/.claude` directories with filesystem type and mount options, interpreter and CLI cold-start cost, and process and host contention. Results are grouped and banded, so a slow network filesystem or a throttled container is called out in a sentence rather than left in a JSON blob. An opt-in network check adds connections to your configured endpoint to time DNS, TCP, and TLS and to capture the presented certificate chain, which is what makes TLS interception visible. It asks for confirmation first and names the host it will contact.
+
+**Privacy.** Recorded: durations, counts, byte sizes, status enums, token counts, and tool, server, model, and provider names. Never recorded: prompt or response text, file contents, absolute paths, environment variable values, API keys, exception messages, or hostnames. This is enforced by a fixed per-attribute allowlist rather than by convention, and the default `redacted` detail level additionally hashes file basenames and model, tool, and server names.
+
+**Collecting across sessions.** Turns can optionally be appended as JSON Lines to `<nbi-dir>/perf/`, with size- and age-capped retention. On network home directories, point the log at local scratch with `NBI_PERF_LOG_DIR`.
+
+Full guide, including the span and event reference, the probe thresholds, worked diagnoses for a slow gateway, a slow home directory, and an intercepting proxy, and the JSONL schema: [`docs/performance-diagnostics.md`](docs/performance-diagnostics.md).
+
+| Environment variable          | Effect                                                                                                         |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `NBI_PERF_DIAGNOSTICS`        | Locks the enabled state on or off (value lock; the UI shows the toggle as locked).                             |
+| `NBI_PERF_DIAGNOSTICS_POLICY` | `user-choice` (default), `force-off`, or `force-on` (fleet-wide collection with redacted attributes enforced). |
+| `NBI_PERF_PROBE_NETWORK`      | `off` disables just the probe's network check while leaving the rest available.                                |
+| `NBI_PERF_LOG_DIR`            | Redirects the JSONL perf log directory.                                                                        |
+
 ## Documentation
 
 - [`docs/admin-guide.md`](docs/admin-guide.md) — deployment, env vars, security model, air-gap, multi-tenancy.
 - [`docs/skills.md`](docs/skills.md) — Claude Skills management and the org-manifest reconciler.
 - [`docs/rulesets.md`](docs/rulesets.md) — ruleset frontmatter and discovery.
 - [`docs/troubleshooting.md`](docs/troubleshooting.md) — common problems with copy-pasteable fixes.
+- [`docs/performance-diagnostics.md`](docs/performance-diagnostics.md): turn timelines, the environment probe, and how to read both.
 - [`PRIVACY.md`](PRIVACY.md) — what NBI sends to which provider, and the egress allowlist.
 - [`SECURITY.md`](SECURITY.md) — how to report a vulnerability.
 - [`CHANGELOG.md`](CHANGELOG.md) — release history.