nterminal 1.3.4 → 1.3.6

package/README.md

@@ -4,7 +4,7 @@
 
 NTerminal turns your own machines into one secure browser workspace for real shells, Codex, Claude, files, and long-running terminal sessions.
 
-<img src="https://cdn.jsdelivr.net/npm/nterminal@latest/assets/screenshot/scr.png?v=readme-latest" alt="NTerminal workspace with split terminal panes" width="100%">
+<img src="https://cdn.jsdelivr.net/npm/nterminal@latest/assets/screenshot/scr.png?v=readme-latest" alt="NTerminal workspace with two servers in the sidebar, a Codex pane, and split terminal panes" width="100%">
 
 NTerminal is a single-owner web terminal for machines you control. It is not a hosted shell product, not a SaaS app, and not a multi-user IDE.
 
@@ -50,23 +50,25 @@ Run onboarding as the account that should own NTerminal. Do not use `sudo ntermi
 
 ## Major Features
 
-- **Multi-server workspace**: manage the main server and all secondary servers from one browser UI, with separate tabs, panes, files, and layout state per server.
-- **Persistent real shells**: run real host PTYs with tabs and split panes, soft-detach terminals without killing them, and keep shells alive across NTerminal restarts when `tmux` is available.
-- **Codex / Claude friendly history**: scroll terminal output without driving TUI prompt history, load older tmux scrollback on demand, and open supported JSONL transcript history for Codex and Claude sessions.
-- **Secure personal access**: password plus TOTP, trusted devices/networks, IP-aware session checks, and origin checks around terminal/file mutation routes.
-- **Files and uploads**: browse the selected pane's cwd, view/edit text and Markdown, preview browser-supported files, drag files or folders into the active terminal directory, or attach files directly from Compose for an agent to read.
-- **Guided npm deployment**: install with npm, run `nterminal onboarding`, keep runtime state under `~/.nterminal`, and update servers from the UI.
+- **Multi-server workspace**: manage the main server and every secondary server from one browser UI. Each server keeps its own workspaces, tabs, split panes, files, and layout.
+- **Persistent real shells**: real host PTYs with workspaces, tabs, and split panes. Closed terminals detach instead of dying, and shells survive NTerminal restarts when `tmux` is available.
+- **Codex / Claude aware panes**: panes running Codex or Claude get a transcript history viewer with server-side search, a subagent viewer, working/unread activity colors, and completion notifications.
+- **Provider accounts and hooks**: save several Codex or Claude logins per server, switch between them, and check weekly usage. Optional lifecycle hooks give more reliable session and activity signals.
+- **Secure personal access**: password plus TOTP, trusted devices and networks, IP-aware session checks, and origin checks around terminal/file mutation routes.
+- **Files, uploads, and attachments**: browse and edit files in the selected pane's folder, drop files or folders into the terminal, attach files to a Compose message for an agent to read, or open the pane in a browser VS Code (code-server add-on).
+- **Works on phones and tablets**: pane switcher, terminal key bar, and installable PWA with push notifications.
+- **Guided npm deployment**: install with npm, run `nterminal onboarding`, keep runtime state under `~/.nterminal`, and update every server from the UI.
 
 ## Feature Details
 
-### Server Management
+### Servers And Workspaces
 
 - Sidebar server switching does not tear down inactive server workspaces.
-- Server cards can show CPU, memory, disk, and swap usage with percentages and absolute values.
-- Compact and detailed server-list modes are available.
-- High resource usage is highlighted directly in the server list.
-- Fleet updates check npm registry versions, update secondary servers first, and update the main server last.
-- Hourly update checks badge Settings and Updates when a newer package is available.
+- Each server has named **workspaces**, each with a default folder and its own tabs and panes. Workspaces can be renamed, reordered, and deleted.
+- Server cards can show CPU, memory, disk, and swap usage with percentages and absolute values, in compact or detailed mode. High usage is highlighted.
+- Secondary servers connect **directly** (main reaches them over the network) or **outbound** (the secondary keeps an authenticated WSS connection to main, for NAT, mobile, or changing IPs, with no inbound port).
+- The **Server information** dialog shows the server role, its external IPv4, its favorite tabs, and its processes grouped by project folder with CPU and memory totals.
+- Fleet updates check the npm registry, update secondary servers first, and update the main server last. Hourly update checks badge Settings and Updates when a newer package is available.
 
 ### Terminal Workspace
 
@@ -74,38 +76,57 @@ Run onboarding as the account that should own NTerminal. Do not use `sudo ntermi
 - Closed tabs and panes become restorable detached terminals.
 - A lightweight supervisor restarts the NTerminal Node process if it exits unexpectedly.
 - Tab titles sync with tmux window names so labels survive detach/reattach cycles.
+- Tabs show a green dot while working and a blue unread badge when output finished in the background; workspaces and favorites show the same state.
+- **Favorite tabs**: star any tab, then open the favorites dialog (`Ctrl+Alt+F`) to jump to it on any server. A favorite whose tab was closed is recreated in its saved folder.
 - Scroll progress, jump-to-bottom, mobile drag handles, and follow-tail behavior keep large outputs usable.
+- Workspace shortcuts use Control-based keys and can be rebound in Settings (see [Features](docs/features.md#keyboard-shortcuts)).
 
-### Transcript History
+### Codex / Claude History And Subagents
 
-- Supported Codex/Claude panes can continue into JSONL transcript history from `~/.codex/sessions` or `~/.claude/projects`.
-- The history viewer supports full-history search, Markdown rendering, optional tool output, and scroll-to-load older transcript entries. Search scans older records progressively and can jump to results that have not been loaded in the viewer.
-- When live session evidence is ambiguous, choose a transcript from the available candidates instead of silently attaching the wrong conversation.
-- A private, bounded disk cache reuses rendered conversation records across history views and searches. New output updates the tail without rebuilding the older cached records.
-- Transcript history is attached only when NTerminal can identify the backing session unambiguously.
+<img src="https://cdn.jsdelivr.net/npm/nterminal@latest/assets/screenshot/history.png?v=readme-latest" alt="Transcript history viewer with search results in a Claude pane" width="100%">
 
-### Files, Uploads, And Clipboard
+- Supported Codex/Claude panes open JSONL transcript history (`View history`, `Alt+H`) from `~/.codex/sessions` or `~/.claude/projects`, with Markdown rendering, optional tool output, a prompt list, and scroll-to-load older entries.
+- Search runs on the server from newest to oldest, including records not yet loaded in the viewer, and selecting a result loads the history around it.
+- History is attached only when NTerminal can identify the backing session unambiguously. When several sessions are plausible, choose one from the session menu; this never changes the running CLI.
+- A private, bounded disk cache reuses parsed conversation records across views and searches, and the history layout adapts to narrow panes.
+- The subagent viewer (`View agents`, `Alt+A`) lists the subagents a session launched, with their state, and opens each one's conversation. It covers Claude subagents, Codex child threads, and `codex exec` runs started from a Claude session; nested subagents fold under their parent.
 
-- File saves reject stale overwrites when the file changed after opening.
-- Folder drops preserve internal paths and avoid overwriting existing files.
-- Compose accepts files by picker, drag-and-drop, or clipboard paste. It stores them outside the project under the runtime state directory and appends their readable paths only when the message is sent.
-- Multiple upload batches queue safely, show progress, support cancel, and retry failed files without duplicating successful uploads.
+<img src="https://cdn.jsdelivr.net/npm/nterminal@latest/assets/screenshot/subagents.png?v=readme-latest" alt="Subagent viewer listing nested subagents of a Claude session" width="100%">
+
+### Provider Accounts And Hooks
+
+<img src="https://cdn.jsdelivr.net/npm/nterminal@latest/assets/screenshot/accounts.png?v=readme-latest" alt="Codex accounts dialog with two saved accounts, weekly usage, and provider hooks" width="480">
+
+- Open a server's Codex or Claude account dialog from the provider buttons on its server card.
+- Each server keeps its own encrypted credential vault. Save several accounts, switch with **Use**, add one through a login terminal, and refresh credentials. Switching is blocked while Codex/Claude processes are running.
+- The dialog shows access-token expiry, weekly and session usage remaining, reset times, and the last refresh result. Usage checks are read-only.
+- Optional [provider lifecycle hooks](docs/provider-hooks.md) (Linux) can be installed or removed from the same dialog or with `nterminal hooks`. For Codex, **Trust NTerminal hooks in Codex** asks Codex to trust only NTerminal's own hooks, the same as approving them in `/hooks`.
+
+### Files, Uploads, And Editor
+
+- The Files sidebar browses the selected pane's folder: view/edit text and Markdown, preview browser-supported files, and create, rename, or delete entries. Saves reject stale overwrites.
+- Drop files or folders onto the terminal to upload them into the active pane's folder. Folder drops preserve internal paths and never overwrite existing files. Batches queue safely, show progress, support cancel, and retry only failed files.
+- **Compose attachments**: attach files to a Compose message by picker, drag-and-drop, or paste. They are stored privately under `~/.nterminal/attachments` on the pane's server, and their paths are appended when the message is sent, so Codex, Claude, or another CLI can read them.
+- **Remote editor**: the pane header can open the pane's folder in code-server (browser VS Code). NTerminal downloads and verifies the code-server release on first use (Linux x64/arm64) and stops idle instances.
 - Terminal Ctrl+C copies selected text and falls through to SIGINT when nothing is selected; Ctrl+V pastes clipboard text.
 
 ### Notifications
 
-- In-app completion toasts appear when background commands finish.
-- Toasts can auto-dismiss, stay until dismissed, or use custom MP4/WebM videos.
-- Settings can preview built-in/uploaded videos, enable/disable them, and randomly choose from the enabled set.
-- Clicking a completion toast jumps back to the server and pane that finished.
-- Optional OS notifications are available when the page is hidden.
+- In-app completion toasts appear when background commands or Codex/Claude turns finish. Clicking one jumps to the server and pane that finished.
+- Toasts can auto-dismiss, stay until dismissed, or play custom MP4/WebM videos chosen at random from the enabled set.
+- OS notifications are available while the page is hidden, and the installed PWA can receive push notifications (HTTPS or localhost).
 
 ### Mobile And PWA
 
-- iPad home-screen metadata and icons are included.
-- Mobile terminal key bar exposes Ctrl, Esc, Tab, and arrows when needed.
-- Split layouts on narrow screens can focus one pane at a time, with a bottom-sheet switcher for terminals and editors.
+<p>
+  <img src="https://cdn.jsdelivr.net/npm/nterminal@latest/assets/screenshot/mobile.png?v=readme-latest" alt="NTerminal on a phone: one pane of a split tab with the terminal key bar" width="280">
+  <img src="https://cdn.jsdelivr.net/npm/nterminal@latest/assets/screenshot/mobile-panes.png?v=readme-latest" alt="NTerminal on a phone: the pane switcher bottom sheet listing the tab's panes" width="280">
+</p>
+
+- Split layouts on narrow screens show one pane at a time, with previous/next buttons and a switcher for terminals and editors.
+- The mobile key bar exposes Ctrl, Esc, Tab, and arrows when needed.
 - Touch scrolling controls are tuned for long terminal output.
+- iPad home-screen metadata and icons are included.
 
 ## Requirements
 
@@ -113,6 +134,7 @@ Run onboarding as the account that should own NTerminal. Do not use `sudo ntermi
 - Linux or macOS.
 - Native build tools required by `node-pty`.
 - Optional `tmux` for PTY persistence across Node restarts.
+- Provider hooks and the code-server add-on require Linux.
 
 If PTY creation fails after a package install, rebuild the native module inside the global package:
 
@@ -125,18 +147,27 @@ npm explore -g nterminal -- npm rebuild node-pty --build-from-source
 ```bash
 nterminal onboarding
 nterminal status
-nterminal logs
-nterminal restart
+nterminal start | stop | restart
+nterminal logs [-f] [N]
+nterminal doctor
+nterminal url
+nterminal version
+nterminal hooks status --provider codex
+nterminal hooks install --provider claude
+nterminal hooks trust --provider codex
 nterminal uninstall --force
 ```
 
+Run `nterminal help` for the full list. Updates run from Settings, not from a CLI command.
+
 ## Documentation
 
 - [Onboarding](docs/onboarding.md): main/secondary setup, nginx, TLS, firewall, and package runtime setup.
 - [Configuration](docs/configuration.md): `.env`, environment variables, and deployment examples.
 - [Operations](docs/operations.md): service control, updates, clean uninstall, verification, and troubleshooting.
-- [Terminal History](docs/terminal-history.md): tmux scrollback, alternate buffer behavior, Codex/Claude JSONL history, and large-output ergonomics.
-- [Features](docs/features.md): files, uploads, notifications, mobile controls, keyboard shortcuts, and PWA behavior.
+- [Terminal History](docs/terminal-history.md): tmux scrollback, alternate buffer behavior, Codex/Claude JSONL history, search, and large-output ergonomics.
+- [Provider Hooks](docs/provider-hooks.md): optional Codex/Claude lifecycle hooks, Codex trust, and the `nterminal hooks` command.
+- [Features](docs/features.md): workspaces, accounts, files, uploads, attachments, notifications, mobile controls, keyboard shortcuts, and PWA behavior.
 - [Security](SECURITY.md): supported security boundary and vulnerability reporting.
 
 ## Limitations
@@ -145,7 +176,7 @@ nterminal uninstall --force
 - No container isolation for spawned shells by default.
 - No recovery of live PTYs after an OS reboot.
 - No Node-restart PTY persistence on hosts without `tmux`.
-- No VS Code extension host, debugger, task runner, or Git UI.
+- The built-in file editor is not an IDE. Full editing needs the optional code-server add-on, which is Linux-only.
 
 ## Publication Notes
 

package/bin/nterminal.js

@@ -48,7 +48,7 @@ function scriptEntrypoint(name) {
 function runScript(name, runArgs) {
   const [major, minor] = process.versions.node.split('.').map(Number);
   if (major < 22 || (major === 22 && minor < 13)) {
-    console.error('error: Node.js >=22.13.0 is required; update Node.js before running onboarding.');
+    console.error('error: Node.js >=22.13.0 is required; update Node.js before running this command.');
     process.exit(1);
   }
   const entrypoint = scriptEntrypoint(name);
@@ -85,6 +85,10 @@ function printHelp() {
 Commands:
   version                 Print the installed NTerminal version.
   onboarding              Run interactive main/secondary onboarding.
+  hooks <action> --provider <codex|claude>
+                          Inspect, install, or remove lifecycle hooks (status/install/remove).
+  hooks trust --provider codex [--yes]
+                          Ask Codex to trust only NTerminal's installed hooks (like /hooks).
   generate-secrets        Print a new NTERMINAL_SESSION_SECRET.
   status                  Show process status.
   start                   Start the built server.
@@ -93,8 +97,8 @@ Commands:
   restart-after-update    Restart after replacing the npm package.
   build                   Verify the bundled runtime exists.
   deploy                  Restart the installed package.
-  clean --force           Remove local runtime state.
-  uninstall --force       Stop and remove local runtime state before npm uninstall.
+  clean --force           Remove local runtime state and NTerminal's provider hooks.
+  uninstall --force       Stop and remove local runtime state and provider hooks before npm uninstall.
   logs [N]                Show recent logs.
   logs -f [N]             Follow logs.
   doctor                  Check local runtime readiness.
@@ -108,6 +112,9 @@ switch (command) {
   case 'onboarding':
     runScript('onboarding', args);
     break;
+  case 'hooks':
+    runScript('hooks', args);
+    break;
   case 'generate-secrets':
   case 'generate:secrets':
     runScript('generate-secrets', args);

package/dist/client/assets/MarkdownPreview-B-LrTjTM.js

@@ -0,0 +1 @@
+import{j as a}from"./index-D3LN5iAH.js";import{M as e,r as o}from"./index-Dd_o8KCL.js";function s({content:r}){return a.jsx(e,{remarkPlugins:[o],children:r})}export{s as default};

package/dist/client/assets/{TranscriptMarkdownBody-H8ZsISc6.js → TranscriptMarkdownBody-3aYVmqQz.js}

@@ -1,3 +1,3 @@
-import{R as a,j as t}from"./index-DwvLN_WJ.js";import{M as u,r as m}from"./index-DxfBq-4P.js";const _=a.memo(function({text:o,searchQuery:n}){const e=a.useMemo(()=>f(n),[n]),i=a.useMemo(()=>j(o),[o]);return t.jsx(u,{components:e,remarkPlugins:[m],children:i})});function f(r){return{a({node:o,children:n,...e}){return t.jsx("a",{...e,target:"_blank",rel:"noreferrer",children:d(n,r)})},blockquote({node:o,children:n,...e}){return t.jsx("blockquote",{...e,children:d(n,r)})},code({node:o,children:n,...e}){return t.jsx("code",{...e,children:d(n,r)})},em({node:o,children:n,...e}){return t.jsx("em",{...e,children:d(n,r)})},h1({node:o,children:n,...e}){return t.jsx("h1",{...e,children:d(n,r)})},h2({node:o,children:n,...e}){return t.jsx("h2",{...e,children:d(n,r)})},h3({node:o,children:n,...e}){return t.jsx("h3",{...e,children:d(n,r)})},h4({node:o,children:n,...e}){return t.jsx("h4",{...e,children:d(n,r)})},h5({node:o,children:n,...e}){return t.jsx("h5",{...e,children:d(n,r)})},h6({node:o,children:n,...e}){return t.jsx("h6",{...e,children:d(n,r)})},li({node:o,children:n,...e}){return t.jsx("li",{...e,children:d(n,r)})},p({node:o,children:n,...e}){return t.jsx("p",{...e,children:d(n,r)})},pre({node:o,children:n,...e}){return t.jsx("pre",{...e,className:"transcript-markdown-code",children:n})},strong({node:o,children:n,...e}){return t.jsx("strong",{...e,children:d(n,r)})},td({node:o,children:n,...e}){return t.jsx("td",{...e,children:d(n,r)})},th({node:o,children:n,...e}){return t.jsx("th",{...e,children:d(n,r)})}}}function d(r,o){return a.Children.map(r,n=>typeof n=="string"?p(n,o):n)}function p(r,o){const n=o.trim();if(!n)return r||" ";const e=r.toLowerCase(),i=n.toLowerCase(),c=[];let l=0,s=e.indexOf(i);for(;s!==-1;){s>l&&c.push(r.slice(l,s));const h=s+n.length;c.push(t.jsx("mark",{className:"transcript-search-hit",children:r.slice(s,h)},`${s}-${h}`)),l=h,s=e.indexOf(i,l)}return l<r.length&&c.push(r.slice(l)),c.length>0?c:r||" "}function j(r){const o=r.split(`
+import{R as a,j as t}from"./index-D3LN5iAH.js";import{M as u,r as m}from"./index-Dd_o8KCL.js";const _=a.memo(function({text:o,searchQuery:n}){const e=a.useMemo(()=>f(n),[n]),i=a.useMemo(()=>j(o),[o]);return t.jsx(u,{components:e,remarkPlugins:[m],children:i})});function f(r){return{a({node:o,children:n,...e}){return t.jsx("a",{...e,target:"_blank",rel:"noreferrer",children:d(n,r)})},blockquote({node:o,children:n,...e}){return t.jsx("blockquote",{...e,children:d(n,r)})},code({node:o,children:n,...e}){return t.jsx("code",{...e,children:d(n,r)})},em({node:o,children:n,...e}){return t.jsx("em",{...e,children:d(n,r)})},h1({node:o,children:n,...e}){return t.jsx("h1",{...e,children:d(n,r)})},h2({node:o,children:n,...e}){return t.jsx("h2",{...e,children:d(n,r)})},h3({node:o,children:n,...e}){return t.jsx("h3",{...e,children:d(n,r)})},h4({node:o,children:n,...e}){return t.jsx("h4",{...e,children:d(n,r)})},h5({node:o,children:n,...e}){return t.jsx("h5",{...e,children:d(n,r)})},h6({node:o,children:n,...e}){return t.jsx("h6",{...e,children:d(n,r)})},li({node:o,children:n,...e}){return t.jsx("li",{...e,children:d(n,r)})},p({node:o,children:n,...e}){return t.jsx("p",{...e,children:d(n,r)})},pre({node:o,children:n,...e}){return t.jsx("pre",{...e,className:"transcript-markdown-code",children:n})},strong({node:o,children:n,...e}){return t.jsx("strong",{...e,children:d(n,r)})},td({node:o,children:n,...e}){return t.jsx("td",{...e,children:d(n,r)})},th({node:o,children:n,...e}){return t.jsx("th",{...e,children:d(n,r)})}}}function d(r,o){return a.Children.map(r,n=>typeof n=="string"?p(n,o):n)}function p(r,o){const n=o.trim();if(!n)return r||" ";const e=r.toLowerCase(),i=n.toLowerCase(),c=[];let l=0,s=e.indexOf(i);for(;s!==-1;){s>l&&c.push(r.slice(l,s));const h=s+n.length;c.push(t.jsx("mark",{className:"transcript-search-hit",children:r.slice(s,h)},`${s}-${h}`)),l=h,s=e.indexOf(i,l)}return l<r.length&&c.push(r.slice(l)),c.length>0?c:r||" "}function j(r){const o=r.split(`
 `);let n=!1,e=null;return o.map((i,c)=>{const l=n,s=/^ {0,3}(```+|~~~+)/.exec(i);if(s){const h=s[1]?.startsWith("`")?"`":"~";n?e===h&&(n=!1,e=null):(n=!0,e=h)}return c===o.length-1||l||s||i.trim()===""||i.endsWith("  ")?i:`${i.replace(/[ \t]+$/,"")}  `}).join(`
 `)}export{_ as default};