@mmmbuto/nexuscrew 0.8.58 → 0.9.0

package/lib/server.js

@@ -23,7 +23,11 @@ const VERSION = require('../package.json').version;
 const { transcribe } = require('./voice/transcribe.js');
 const { selectProvider } = require('./fleet/provider.js');
 const { fleetRoutes } = require('./fleet/routes.js');
+const { leaseRoutes } = require('./fleet/lease-routes.js');
 const { cellsRoutes } = require('./cells/routes.js');
+const { liveHostRoutes } = require('./live-host/routes.js');
+const { createLiveHostStore, liveHostPath } = require('./live-host/store.js');
+const { createLiveBridge } = require('./live-host/bridge.js');
 const { fsRoutes } = require('./fs/routes.js');
 const nodesStore = require('./nodes/store.js');
 const nodesTunnel = require('./nodes/tunnel.js');
@@ -33,6 +37,8 @@ const { createReverseSlotListeners } = require('./nodes/reverse-slot-listeners.j
 const reverseRotation = require('./nodes/reverse-rotation.js');
 const topologyCache = require('./nodes/topology-cache.js');
 const { createNodeProxy, handleNodeUpgrade } = require('./proxy/node-proxy.js');
+const { createPanelProxy, handlePanelUpgrade } = require('./proxy/panel-proxy.js');
+const { createPanelAuth } = require('./proxy/panel-auth.js');
 const federation = require('./proxy/federation.js');
 const { audioRoutes } = require('./audio/routes.js');
 const { isConsent: isAudioConsent } = require('./audio/consent.js');
@@ -549,9 +555,81 @@ function createServer(opts = {}) {
     if (!reverseSlotListeners.respond(req, res)) res.status(404).json({ error: 'reverse slot non disponibile' });
   });
 
-  // Tutte le /api dietro Bearer: sul loopback il gate vero è il tunnel,
+  // Pannello per-cella (D8): inoltra il traffico verso il `panelUrl` di UNA cella
+  // LOCALE. La destinazione non arriva mai dal chiamante — si risolve dallo stato
+  // della cella — e il token di NexusCrew non prosegue verso il pannello, che e'
+  // un servizio terzo e non un nodo. Local-only come /api/live-host: il pass-through
+  // /node/<name>/ NON deve portarci un peer qualsiasi (vedi LOCAL_ONLY_PREFIXES in
+  // proxy/node-proxy.js). L'attraversamento verso i nodi del proprietario passera'
+  // dalla via allowlistata della federazione, dietro il gate di proprieta'.
+  async function resolveCellPanel(cellId) {
+    const fleet = await fleetP;
+    if (!fleet || fleet.available !== true) return null;          // fleet non interrogabile
+    const statusFn = typeof fleet.status === 'function' ? fleet.status : fleet.cellStatus;
+    if (typeof statusFn !== 'function') return null;
+    const st = await statusFn.call(fleet);
+    const cells = Array.isArray(st && st.cells) ? st.cells : [];
+    // La chiave e' `cell`, non `id`: e' cio' che cellStatus PRODUCE
+    // (fleet/runtime.js scrive `cell: c.id`, dove `id` e' il nome interno della
+    // definizione). Cercare `c.id` qui non trovava MAI nulla, quindi ogni cella
+    // con un pannello configurato rispondeva «pannello non disponibile» — e la
+    // UI mostrava una causa col nome sbagliato. Tutti gli altri consumatori di
+    // cellStatus usano gia' `c.cell` (cells/routes.js, live-host/bridge.js,
+    // live-host/routes.js): questo era l'unico fuori posto.
+    const cell = cells.find((c) => c && c.cell === cellId);
+    if (!cell) return undefined;                                   // cella sconosciuta
+    return typeof cell.panelUrl === 'string' ? cell.panelUrl.trim() : '';
+  }
+  // Tutte le altre /api dietro Bearer: sul loopback il gate vero è il tunnel,
   // ma il token chiude anche altri processi locali della stessa macchina.
   const api = express.Router();
+  // L'INGRESSO al pannello sta PRIMA del requireToken generale: un <iframe> e'
+  // una navigazione del browser e non porta header, quindi l'autenticazione
+  // qui e' dedicata — Bearer per la PWA, ticket monouso + cookie di visione
+  // per l'iframe (proxy/panel-auth.js, misura 2026-08-15). Il cookie vale
+  // SOLO sul path della cella che lo ha emesso: non e' e non diventa
+  // un'autenticazione dell'origine.
+  const panelAuth = createPanelAuth({
+    verifyToken: (t) => verify(tokenHolder.value, t),
+    resolveCellPanel,
+    // Senza questo segreto il pannello non saprebbe distinguere la PWA
+    // dall'ultimo hop di una route federata — che entra qui col Bearer che il
+    // proxy si e' iniettato da se'. E' lo stesso segreto per-processo che
+    // firma gli hop di sotto: due valori diversi renderebbero ogni federata
+    // 'sospetta', cioe' chiuderebbero il pannello remoto invece di proteggerlo.
+    hopSecret: () => hopSecret,
+    log: (entry) => diagnostics.record('panel-auth', 'info', entry.outcome, {
+      cell: entry.cell, reason: entry.reason, state: entry.outcome,
+    }),
+  });
+  api.use('/panel', panelAuth.panelAuthMiddleware, createPanelProxy({
+    resolveCellPanel,
+    log: (entry) => diagnostics.record('panel-proxy', 'info', entry.outcome, {
+      cell: entry.cell, reason: entry.reason, state: entry.outcome,
+    }),
+  }));
+  // L'ingresso ai pannelli REMOTI ha la stessa malattia dell'iframe locale: la
+  // via federata /api/route/<nodi>/_/panel/... sta per finire sotto requireToken
+  // e una navigazione del browser non porta header. QUI il ticket non si può
+  // validare — è del nodo che lo ha emesso — quindi per le panel-resource
+  // federate il requireToken NON si applica: decide il nodo proprietario (gate
+  // panelAccess + panelAuth col ticket/cookie, e l'ultimo hop lo riconosce
+  // dalla prova di hop: di là il Bearer non apre più il pannello, altrimenti
+  // il contenuto uscirebbe per ogni peer con panelAccess senza che nessuno
+  // abbia mai preso un ticket). Resta della PWA autenticata l'EMISSIONE: il POST
+  // .../panel/<cella>/ticket transita di sotto, col Bearer, come ogni altra /api.
+  const panelFederatoRouter = federation.localRouter({
+    nodesPath, localPort: () => (server && server.address() ? server.address().port : cfg.port), localCredential: () => tokenHolder.value, readonly: proxyReadonly,
+    hopSecret: () => hopSecret,
+  });
+  api.use('/route', (req, res, next) => {
+    const i = req.url.indexOf('/_/');
+    if (i === -1) return next();
+    const resource = req.url.slice(i + 2);
+    if (!/^\/panel\/[A-Za-z0-9._-]{1,32}(?:\/.*)?$/.test(resource)) return next();
+    if (req.method === 'POST' && /^\/panel\/[A-Za-z0-9._-]{1,32}\/ticket\/?$/.test(resource)) return next();
+    panelFederatoRouter(req, res, next);
+  });
   api.use(requireToken(tokenStore));
   // Origine per lo scope celle: stessa prova di hop usata da audio e notify.
   // requireCell:false perche' qui interessa QUALE NODO parla, non quale cella
@@ -710,6 +788,10 @@ function createServer(opts = {}) {
     federatedRate: createSpeakRateLimiter(),
   }));
   api.use('/fleet', fleetRoutes(fleetP, { ...cfg, diagnostics }));
+  // Fetta 2b (D3): superficie child del lease Live via canale nativo del
+  // bridge (HTTP loopback + Bearer). La cella e' derivata dalla sessione; il
+  // proof firmato dal verifier per-installazione autorizza refresh/recovery.
+  api.use('/lease', leaseRoutes({ fleetP, readonly: proxyReadonly }));
   // Audio Share. L'identita' del nodo NON e' un campo di cfg: si legge dal node
   // store, la stessa fonte usata da /api/cells e /api/peers. Lo stato Fleet e'
   // asincrono e va atteso: leggerlo come se fosse sincrono lascerebbe la
@@ -776,6 +858,27 @@ function createServer(opts = {}) {
     })),
     readonly: proxyReadonly,
   }));
+  // Cella ospite Live (contratto rev6 §2): hostCell unico per nodo con CAS. Lo store
+  // vive accanto al token (stessa dir isolata nei test); le route sono local-only e
+  // il proxy nega /api/live-host via /node (federazione default-deny).
+  // Fetta 3: il ponte risolve il puntamento all'avvio di una Live (POST /bridge
+  // nello stesso gruppo, stessa auth, stesso local-only). Isolabile da cfg
+  // (rev5 MC0): spento non crea connessioni e la Live resta standard.
+  api.use('/live-host', liveHostRoutes({
+    fleetP,
+    store: createLiveHostStore({ filePath: liveHostPath(cfg) }),
+    readonly: proxyReadonly,
+    bridge: createLiveBridge({
+      cfg,
+      fleetP,
+      tokenGet: () => tokenHolder.value,
+      filesRoot: cfg.filesRoot,
+      log: opts.log || console.log,
+    }),
+  }));
+  // Pannello per-cella: montato con il suo ingresso dedicato (ticket+cookie)
+  // PRIMA del requireToken generale — vedi il blocco sopra, dove nascono
+  // `panelAuth` e `resolveCellPanel`.
   api.use('/vl-nodes', vlNodeApiRoutes({
     storePath: vlNodesPath, broker: vlNodeBroker, ownerId: vlOwnerId, readonly: proxyReadonly,
   }));
@@ -954,7 +1057,14 @@ function createServer(opts = {}) {
     if (pathname.startsWith('/api/route/')) {
       let u; try { u = new URL(req.url, 'http://127.0.0.1'); } catch (_) { return socket.destroy(); }
       const given = bearerFrom(req) || u.searchParams.get('token') || '';
-      if (!verify(tokenHolder.value, given)) return socket.destroy();
+      // Le WebSocket di un pannello REMOTO partono dalla pagina nel frame e
+      // portano solo il cookie di visione: il token qui non c'è e non deve
+      // esserci. L'HUB non può validarle (il cookie è del nodo che lo ha
+      // emesso): transita e decide il proprietario, gate panelAccess compreso
+      // — stessa forma del bypass HTTP sulle panel-resource federate.
+      const panelFederato = /^\/api\/route\/[^?#]*\/_\/panel\/[A-Za-z0-9._-]{1,32}(?:\/.*)?$/.test(pathname)
+        && /(?:^|;\s*)npanel=/.test(String(req.headers.cookie || ''));
+      if (!panelFederato && !verify(tokenHolder.value, given)) return socket.destroy();
       federation.forwardUpgrade({ req, socket, head, nodesPath, localPort: runtimePort, localCredential: () => tokenHolder.value, ingress: null, readonly: proxyReadonly, activeSockets: proxySockets, hopSecret: () => hopSecret });
       return;
     }
@@ -964,6 +1074,19 @@ function createServer(opts = {}) {
       federation.forwardUpgrade({ req, socket, head, nodesPath, localPort: runtimePort, localCredential: () => tokenHolder.value, ingress, readonly: proxyReadonly, activeSockets: proxySockets, hopSecret: () => hopSecret });
       return;
     }
+    if (pathname.startsWith('/api/panel/')) {
+      handlePanelUpgrade({
+        req, socket, head, resolveCellPanel,
+        verifyToken: (t) => verify(tokenHolder.value, t),
+        // Il cookie di visione apre le WS del pannello (la pagina nel frame
+        // non puo' mettere header); Bearer e ?token= restano validi come prima.
+        authorize: panelAuth.authorizeUpgrade,
+        log: (entry) => diagnostics.record('panel-proxy', 'info', entry.outcome, {
+          cell: entry.cell, reason: entry.reason, state: entry.outcome,
+        }),
+      });
+      return;
+    }
     if (pathname === '/node' || pathname.startsWith('/node/')) {
       handleNodeUpgrade({
         req, socket, head, resolveNode,
@@ -991,7 +1114,7 @@ function createServer(opts = {}) {
     // async questo handler rischierebbe di perdere i frame che arrivano prima
     // di bindWs. `/ws` attacca per NOME DI SESSIONE e senza questo gate ogni
     // filtro sugli elenchi sarebbe decorativo — basterebbe indovinare
-    // `cloud-Dev`.
+    // `cloud-X`.
     const wsScope = wsCellScope(req);
     bindWs(ws, {
       openAttach,
@@ -1024,7 +1147,7 @@ function createServer(opts = {}) {
 }
 
 function start(opts = {}) {
-  const { server, cfg } = createServer(opts);
+  const { server, cfg } = createServer({ ...opts, cellLeaseEnabled: true });
   const log = opts.log || console.log;
   const requestedPort = cfg.port;
   const nodesPath = opts.nodesPath || nodesStore.defaultNodesPath(cfg.home || os.homedir());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.8.58",
+  "version": "0.9.0",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {

package/skills/alibaba-token-media/SKILL.md

@@ -131,3 +131,22 @@ overwrite. An explicit `--output` must remain under the current user's home.
 
 Read [references/api-contract.md](references/api-contract.md) before changing
 payloads, limits, endpoints, or model handling.
+
+## Dependencies
+
+**Bundled (installed with the package):** the CLI
+`scripts/alibaba_token_media.py` ships with this skill and is
+dependency-free — Python 3 standard library only (verified against the
+script's imports; it needs a Unix-like environment because it uses `fcntl`,
+so Windows is out of scope).
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| Python 3 | Debian/Ubuntu `apt install python3`, Fedora `dnf install python3`, macOS `brew install python`, Termux `pkg install python` | `python3 --version` fails → nothing in this skill runs |
+| An Alibaba Cloud **Token Plan Personal** subscription that includes the media models | activate on the Alibaba Cloud console — no local install | API calls fail with an authorization error from the service |
+| API key in the environment | `export ALIBABA_CODE_API_KEY=<your key>` in the shell/service that runs the script | the script refuses with `ALIBABA_CODE_API_KEY is not set in this process environment` — the failure names the exact variable; no network call is made without it |
+
+The key is read only from the environment: never paste it into a prompt, a
+script argument, or a file.

package/skills/crew/SKILL.md

@@ -87,3 +87,18 @@ report.
 
 Transport receipts do not prove task acceptance or completion. Report only
 results that have been verified.
+
+## Dependencies
+
+**Bundled:** nothing — this skill is documentation only.
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| A Crew MCP fabric (companion) | optional companion `mcp-crewd-rs`: <https://github.com/DioNanos/mcp-crewd-rs> — the repository's Install section is authoritative and may change; this skill deliberately does not duplicate its commands (**not verified here**) | if the companion is not registered, the client exposes no `cell_*` tools; ask the client for its tool list |
+| Client MCP registration | register the companion's stdio command in the AI client's MCP config | same failure mode: absent tools, not a runtime error |
+| A `crew` token issued by the fabric | `crew token issue` on the host that runs the fabric (see the companion's docs) | spawns are rejected as unauthorized — the rejection names the missing authorization |
+
+Without the companion there is no worker delegation in that session: say so
+and suggest the companion once instead of emulating cells with raw tmux.

package/skills/fill-forms/SKILL.md

@@ -152,3 +152,26 @@ user deliberately chooses `--allow-unused`.
    name.
 5. Show the final preview or document to the user before calling it ready.
 6. State clearly which fields remain empty, uncertain, unsigned or unsubmitted.
+
+## Dependencies
+
+**Bundled (installed with the package):** the five scripts
+(`inspect_pdf.py`, `fill_pdf.py`, `fill_docx.py`, `dump_docx.py`,
+`prepare_signature.py`) and `requirements.txt` ship inside this skill
+directory.
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| Python 3 | Debian/Ubuntu `apt install python3 python3-pip`, Fedora `dnf install python3 pip`, macOS `brew install python`, Termux `pkg install python` | `python3 --version` fails → nothing in this skill runs |
+| PyMuPDF, Pillow, numpy, python-docx (exact pins in the bundled `requirements.txt`) | add those four packages to the Python environment that runs the scripts, taking the versions from the bundled `requirements.txt`; this skill deliberately does not spell out the command, because it must ask before touching an environment | probe with `python3 -c "import fitz, PIL, numpy, docx"` — a missing module fails by naming itself (`ModuleNotFoundError: No module named 'fitz'`); add that package, not "dependencies" in the abstract |
+
+Termux note: Termux has no systemd and no Docker assumptions here, but the
+native wheels for PyMuPDF/numpy on Termux are **not verified**: if `pip`
+cannot build them, this skill is not usable on that device — report that
+plainly instead of switching to an unverified PDF writer.
+
+Every script keeps the blank source untouched and writes a new output file;
+if a dependency is missing mid-flow, the scripts refuse rather than emit a
+half-filled form.

package/skills/mail-assistant/SKILL.md

@@ -69,3 +69,18 @@ client-native scheduler or loop mechanism instead of manual polling, avoid
 duplicate jobs, respect quiet hours, and remain silent on unchanged ticks when
 the host workflow supports silent monitoring. A recurring authorization does
 not automatically authorize sending or permanent deletion.
+
+## Dependencies
+
+**Bundled:** nothing — this skill is documentation only.
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| A mail MCP connector already exposed by the current client (any Gmail/IMAP-capable MCP server; e.g. the optional companion `mcp-email-rs` <https://github.com/DioNanos/mcp-email-rs> — its Install section is authoritative, **not verified here**) | register the connector in the AI client's MCP config, following that connector's own instructions | if no mail tools are exposed, mailbox discovery returns nothing to call — ask the client for its tool list; do not assume provider folders or account layout |
+| Mailbox credentials | provided by the connector's own auth flow | auth failures surface from the connector, not from this skill |
+
+This skill never sends or deletes mail on its own initiative; a missing
+connector means the task cannot start, which must be reported, not worked
+around with direct IMAP scripting.

package/skills/memory/SKILL.md

@@ -79,3 +79,18 @@ document store, not in a bounded log.
 If no Memory MCP tool is available and this skill is packaged with NexusCrew,
 the optional companion is documented in `../../MCP_COMPANIONS.md`. Explain the
 missing capability and ask before installing or configuring anything.
+
+## Dependencies
+
+**Bundled:** nothing — this skill is documentation only.
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| A Memory MCP server (companion) | optional companion `mcp-memory-rs`: <https://github.com/DioNanos/mcp-memory-rs> — the repository's Install section is authoritative and may change; this skill deliberately does not duplicate its commands (**not verified here**) | if the companion is not registered, the client exposes no `memory_*` tools; ask the client for its tool list rather than guessing |
+| Client MCP registration | register the companion's stdio command in the AI client's MCP config | same failure mode as above: absent tools, not a runtime error |
+
+Without the companion this skill is not usable in that session: say so and
+suggest the companion once (see the packaged `mcp-companions.json` catalog)
+instead of approximating with file reads.

package/skills/nexuscrew-agent/SKILL.md

@@ -169,3 +169,21 @@ work. The setting is also applied to windows created later in that session.
 - **Assuming a node listens on the port you know** → NexusCrew selects a free port per installation, and a peer's remote port is not the port that node listens on locally. Read it from `nexuscrew status` on that node; a health check aimed at the wrong port reports a dead service that is perfectly alive.
 - **Writing a reply into a local inbox directory** → the inbox is per-installation and is not synchronised between nodes. Answering a remote caller by dropping a file in your own inbox reaches nobody; reply through the tool that addressed you.
 - **Treating a dead scroll gesture as a web-terminal bug** → the pane is in the alternate buffer. Check whether it predates the NexusCrew setting or opted out with `alternateScreen:true`; never send raw page keys to a TUI to work around it.
+
+## Dependencies
+
+**Bundled (installed with the package):** the `nexuscrew` CLI, `lib/`, these
+skills, and the `bin/nc-send` / `bin/nc-deliver` helpers arrive with
+`npm install -g @mmmbuto/nexuscrew` (Node.js >= 18 required by `engines`).
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| Node.js >= 18 | Debian/Ubuntu `apt install nodejs` (nodesource for 18+), Fedora `dnf install nodejs`, macOS `brew install node`, Termux `pkg install nodejs-lts` | `node -v` prints >= 18; below that `npm install` refuses per `engines` |
+| tmux | Debian/Ubuntu `apt install tmux`, Fedora `dnf install tmux`, macOS `brew install tmux`, Termux `pkg install tmux` | `nexuscrew doctor` reports tmux missing by name; `nc-send` exits 127 with `nc-send: tmux not found on PATH (set TMUX_BIN)` — the failure names itself |
+| An AI client that can register the MCP server | register the stdio command `nexuscrew mcp` in the client's MCP config | if the `nc_*` tools are not exposed, no `nc_` tool exists in the session — see "MCP bridge" above |
+| A running NexusCrew service (for most tools) | `nexuscrew serve` (foreground) or your platform service manager | tools fail to reach the bridge; Termux has no systemd — run `nexuscrew serve` inside a tmux session or your own keep-alive |
+
+If tmux is missing, MCP inspection (`nc_status`, `nc_identity`) still works;
+anything that targets a session (including the `nc-send` fallback) does not.

package/skills/vl-msa/SKILL.md

@@ -66,3 +66,18 @@ round. Avoid a single unbounded search.
 If no VL-MSA tool is available and this skill is packaged with NexusCrew, the
 optional companion is documented in `../../MCP_COMPANIONS.md`. Explain the
 missing capability and ask before installing or configuring anything.
+
+## Dependencies
+
+**Bundled:** nothing — this skill is documentation only.
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| A VL-MSA MCP server (companion) | optional companion `mcp-vl-msa-rs`: <https://github.com/DioNanos/mcp-vl-msa-rs> — the repository's Install section is authoritative and may change; this skill deliberately does not duplicate its commands (**not verified here**) | if the companion is not registered, the client exposes no `msa_*` tools; ask the client for its tool list |
+| Client MCP registration | register the companion's stdio command in the AI client's MCP config | same failure mode: absent tools, not a runtime error |
+
+Without the companion, durable retrieval is simply unavailable in that
+session: say so and suggest the companion once instead of reading the
+server's on-disk collections directly (which this skill forbids).