@mmmbuto/nexuscrew 0.8.24 → 0.8.26

package/lib/mcp/server.js

@@ -25,7 +25,7 @@ const { loadConfig } = require('../config.js');
 const { readTokenSafe } = require('../auth/token.js');
 const { isValidSession } = require('../files/store.js');
 const VERSION = require('../../package.json').version;
-const { TOOLS } = require('./tools.js');
+const { TOOLS, IDENTITY_CODE, IDENTITY_REMEDIATION } = require('./tools.js');
 const cells = require('./cells.js');
 
 // Versione protocollo di fallback se il client non ne dichiara una valida.
@@ -39,27 +39,83 @@ const METHOD_NOT_FOUND = -32601;
 const INVALID_PARAMS = -32602;
 
 // --- identita' cella mittente ------------------------------------------------
-// Ordine (design §1): $TMUX presente -> `tmux display-message -p '#S'` (nome
-// sessione reale); fallback env NEXUSCREW_MCP_SESSION; altrimenti null (i tool
-// che RICHIEDONO la sessione falliscono con errore chiaro, nc_notify degrada
-// a sender sconosciuto). execFile argv diretto: mai shell.
-function resolveSession({ env, tmuxBin, execFileImpl }) {
-  const fallback = () => {
-    const s = env.NEXUSCREW_MCP_SESSION;
-    return (typeof s === 'string' && isValidSession(s.trim())) ? s.trim() : null;
+// Ordine (design §1, INVARIATO): $TMUX presente -> `tmux display-message -p '#S'`
+// (nome sessione reale); se fallisce/invalida -> fallback env NEXUSCREW_MCP_SESSION;
+// altrimenti null. I tool che RICHIEDONO la sessione restano fail-closed.
+// execFile argv diretto: mai shell.
+//
+// `resolveIdentity` rende OSSERVABILE la sorgente della risoluzione (P0):
+// ritorna { session, source, code, envPresence, requiredEnvVars, remediation }
+// senza cambiare la precedenza e senza esporre valori/segreti. `resolveSession`
+// resta il wrapper pubblico Promise<string|null> invariato (compatibilita').
+const IDENTITY_REQUIRED_ENV_VARS = Object.freeze(['TMUX', 'TMUX_PANE', 'NEXUSCREW_MCP_SESSION']);
+
+function envPresenceOf(env) {
+  return {
+    TMUX: !!env.TMUX,
+    TMUX_PANE: !!env.TMUX_PANE,
+    NEXUSCREW_MCP_SESSION: !!(typeof env.NEXUSCREW_MCP_SESSION === 'string' && env.NEXUSCREW_MCP_SESSION.trim()),
+  };
+}
+
+function resolveIdentity({ env, tmuxBin, execFileImpl }) {
+  const e = env || {};
+  const envPresence = envPresenceOf(e);
+  const fallbackRaw = e.NEXUSCREW_MCP_SESSION;
+  const fallbackPresent = typeof fallbackRaw === 'string' && fallbackRaw.trim().length > 0;
+  const tmuxPresent = !!e.TMUX;
+
+  // Prova il fallback NEXUSCREW_MCP_SESSION: ritorna la sessione normalizzata se
+  // valida, `false` se presente ma invalida, `null` se assente.
+  const tryFallback = () => {
+    if (!fallbackPresent) return null;
+    const s = fallbackRaw.trim();
+    return isValidSession(s) ? s : false;
   };
-  if (!env.TMUX) return Promise.resolve(fallback());
+
+  // code quando NON identificati: INVALID se c'e' un segnale di identita'
+  // (TMUX o NEXUSCREW_MCP_SESSION presente), MISSING altrimenti.
+  const codeWhenMissing = () => ((tmuxPresent || fallbackPresent)
+    ? IDENTITY_CODE.INVALID : IDENTITY_CODE.MISSING);
+
+  const ok = (session, source) => ({
+    session, source, code: IDENTITY_CODE.OK,
+    envPresence, requiredEnvVars: IDENTITY_REQUIRED_ENV_VARS, remediation: IDENTITY_REMEDIATION,
+  });
+  const missing = () => ({
+    session: null, source: 'missing', code: codeWhenMissing(),
+    envPresence, requiredEnvVars: IDENTITY_REQUIRED_ENV_VARS, remediation: IDENTITY_REMEDIATION,
+  });
+
   return new Promise((resolve) => {
+    if (!tmuxPresent) {
+      const fb = tryFallback();
+      return resolve(typeof fb === 'string' ? ok(fb, 'NEXUSCREW_MCP_SESSION') : missing());
+    }
     try {
       execFileImpl(tmuxBin, ['display-message', '-p', '#S'], { timeout: 3000 }, (err, stdout) => {
-        if (err) return resolve(fallback());
-        const name = String(stdout || '').trim();
-        resolve(isValidSession(name) ? name : fallback());
+        if (!err) {
+          const name = String(stdout || '').trim();
+          if (isValidSession(name)) return resolve(ok(name, 'tmux'));
+        }
+        // tmux fallito/invalido -> precedenza preservata: fallback env.
+        const fb = tryFallback();
+        resolve(typeof fb === 'string' ? ok(fb, 'NEXUSCREW_MCP_SESSION') : missing());
       });
-    } catch (_) { resolve(fallback()); }
+    } catch (_) {
+      const fb = tryFallback();
+      resolve(typeof fb === 'string' ? ok(fb, 'NEXUSCREW_MCP_SESSION') : missing());
+    }
   });
 }
 
+// Wrapper pubblico STORICO: stessi parametri, stesso return Promise<string|null>.
+// Mantiene i test esistenti e ogni chiamante esterno che dipende solo dal nome
+// della sessione (o null). La diagnostica source/code vive in resolveIdentity.
+function resolveSession(opts) {
+  return resolveIdentity(opts).then((i) => i.session);
+}
+
 // --- server --------------------------------------------------------------------
 function createMcpServer(opts = {}) {
   const input = opts.input || process.stdin;
@@ -75,11 +131,15 @@ function createMcpServer(opts = {}) {
   const baseUrl = `http://127.0.0.1:${cfg.port}`;
 
   // Identita' risolta una volta e cacheata (la sessione tmux non cambia a runtime).
-  let sessionP = null;
-  const session = () => {
-    if (!sessionP) sessionP = resolveSession({ env, tmuxBin: cfg.tmuxBin || 'tmux', execFileImpl });
-    return sessionP;
+  // Una sola risoluzione condivisa: `identity()` per la diagnostica completa
+  // (source/code/presence), `session()` estrae solo il nome per gli handler
+  // storici (compatibilita'). Nessuna API/token coinvolta qui.
+  let identityP = null;
+  const identity = () => {
+    if (!identityP) identityP = resolveIdentity({ env, tmuxBin: cfg.tmuxBin || 'tmux', execFileImpl });
+    return identityP;
   };
+  const session = () => identity().then((i) => i.session);
 
   // Token letto ad OGNI chiamata (rotazione-friendly), MAI incluso negli errori.
   function readToken() {
@@ -113,6 +173,7 @@ function createMcpServer(opts = {}) {
 
   const ctx = {
     session,
+    identity,
     api,
     home: () => env.HOME || os.homedir(),
     fileExists: (p) => { try { return require('node:fs').statSync(p).isFile(); } catch (_) { return false; } },
@@ -252,7 +313,7 @@ function startMcp(opts = {}) {
 }
 
 module.exports = {
-  createMcpServer, startMcp, resolveSession, TOOLS,
+  createMcpServer, startMcp, resolveSession, resolveIdentity, TOOLS,
   parseCellTarget: cells.parseCellTarget,
   normalizeCellPayload: cells.normalizeCellPayload,
   readCellDirectory: cells.readCellDirectory,

package/lib/mcp/tools.js

@@ -27,10 +27,33 @@ function argString(args, key, { required = false, max = 4096 } = {}) {
   return v;
 }
 
-function requireSession(session, tool) {
+// Codici stabili di identita' MCP (contratto P0). Valori EXACT, non sensibili,
+// usati sia nella diagnostica read-only (`nc_identity`) sia nel messaggio umano
+// dei tool identity-gated (isError=true preservato dal server). Non espongono
+// valori/env/sessioni: solo la categoria del problema.
+const IDENTITY_CODE = Object.freeze({
+  OK: 'OK',
+  MISSING: 'NEXUSCREW_MCP_IDENTITY_MISSING',
+  INVALID: 'NEXUSCREW_MCP_IDENTITY_INVALID',
+});
+
+// Remediation senza segreti/valori: nomi soltanto, compatibile con
+// `codex-vl mcp add --env-var` (allowlist di nomi, nessun valore persistito).
+const IDENTITY_REMEDIATION =
+  'Nei client che ripuliscono l\'ambiente, allowlista i nomi delle variabili di identita nel server MCP stdio '
+  + '(codex-vl mcp add ... --env-var NEXUSCREW_MCP_SESSION --env-var TMUX --env-var TMUX_PANE) '
+  + 'oppure assicurati che il client MCP inoltri il contesto tmux al processo child: nessun valore '
+  + 'viene copiato nella CLI o nel file di configurazione.';
+
+function requireSession(session, tool, code = IDENTITY_CODE.MISSING) {
   if (session) return session;
+  const stableCode = code === IDENTITY_CODE.INVALID ? IDENTITY_CODE.INVALID : IDENTITY_CODE.MISSING;
+  // Errore umano per il modello: messaggio chiaro + codice stabile fra parentesi
+  // quadre. isError=true e' impostato dal server (toolsCall); qui si propaga
+  // solo il testo. La regex storica /NEXUSCREW_MCP_SESSION/ resta soddisfatta.
   throw new Error(
-    `${tool}: sessione tmux non identificata — serve $TMUX (dentro tmux) o NEXUSCREW_MCP_SESSION`,
+    `${tool}: sessione tmux non identificata — serve $TMUX (dentro tmux) o `
+    + `NEXUSCREW_MCP_SESSION [${stableCode}]`,
   );
 }
 
@@ -79,7 +102,8 @@ const TOOLS = [
       if (args.options !== undefined && !Array.isArray(args.options)) {
         throw new Error('options deve essere un array di stringhe');
       }
-      const session = requireSession(await ctx.session(), 'nc_ask');
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_ask', identity.code);
       const j = await ctx.api('POST', '/api/asks', {
         question, ...(args.options ? { options: args.options } : {}), session,
       });
@@ -109,7 +133,8 @@ const TOOLS = [
       if (!ctx.fileExists(p)) throw new Error(`file inesistente: ${p}`);
       const home = ctx.home();
       if (p !== home && !p.startsWith(home + path.sep)) throw new Error('path fuori da HOME');
-      const session = requireSession(await ctx.session(), 'nc_send_file');
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_send_file', identity.code);
       const j = await ctx.api('POST', '/api/files/outbox', {
         session, path: p, ...(caption ? { caption } : {}),
       });
@@ -145,7 +170,8 @@ const TOOLS = [
     inputSchema: { type: 'object', properties: {} },
     annotations: { readOnlyHint: true },
     async handler(_args, ctx) {
-      const tmuxSession = requireSession(await ctx.session(), 'nc_deck');
+      const identity = await ctx.identity();
+      const tmuxSession = requireSession(identity.session, 'nc_deck', identity.code);
       const [config, topology, localDecks] = await Promise.all([
         ctx.api('GET', '/api/config'), ctx.api('GET', '/api/topology'), ctx.api('GET', '/api/decks'),
       ]);
@@ -257,7 +283,8 @@ const TOOLS = [
         if (code === 9 || code === 10 || code === 13) continue;
         if (code < 32 || code === 127) throw new Error('message contiene caratteri di controllo non ammessi');
       }
-      const callerSession = requireSession(await ctx.session(), 'nc_send_cell');
+      const identity = await ctx.identity();
+      const callerSession = requireSession(identity.session, 'nc_send_cell', identity.code);
       const directory = await readCellDirectory(ctx, callerSession);
       const sender = directory.cells.find((cell) => cell.self && cell.active);
       if (!sender) throw new Error('nc_send_cell: la sessione chiamante non e\' una cella Fleet attiva locale');
@@ -290,11 +317,33 @@ const TOOLS = [
     inputSchema: { type: 'object', properties: {} },
     annotations: { readOnlyHint: true },
     async handler(_args, ctx) {
-      const session = requireSession(await ctx.session(), 'nc_inbox');
+      const identity = await ctx.identity();
+      const session = requireSession(identity.session, 'nc_inbox', identity.code);
       const j = await ctx.api('GET', `/api/files?session=${encodeURIComponent(session)}`);
       return { inbox: Array.isArray(j.inbox) ? j.inbox : [] };
     },
   },
+  {
+    name: 'nc_identity',
+    description: 'Diagnostica read-only dell\'identita\' del chiamante MCP. Utilizzabile anche senza sessione tmux e senza token: restituisce SOLO dati non sensibili (presence delle env var, sorgente della risoluzione, codice stabile). Non chiama API HTTP e non legge il token. Usa questo tool quando gli altri tool nc_* falliscono con NEXUSCREW_MCP_IDENTITY_* per capire cosa manca.',
+    inputSchema: { type: 'object', properties: {} },
+    annotations: { readOnlyHint: true },
+    async handler(_args, ctx) {
+      const id = await ctx.identity();
+      // Output bounded e non sensibile: nessun valore/env, solo presence e codice.
+      // `session` solo se validata; `source` sempre fra i tre valori ammessi.
+      const out = {
+        identified: !!id.session,
+        source: id.source,
+        envPresence: id.envPresence,
+        requiredEnvVars: id.requiredEnvVars,
+        code: id.code,
+        remediation: id.remediation,
+      };
+      if (id.session) out.session = id.session;
+      return out;
+    },
+  },
 ];
 
-module.exports = { TOOLS, argString, requireSession };
+module.exports = { TOOLS, argString, requireSession, IDENTITY_CODE, IDENTITY_REMEDIATION };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.8.24",
+  "version": "0.8.26",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {
@@ -12,6 +12,7 @@
     "skills/",
     "frontend/dist/",
     "frontend/index.html",
+    "CHANGELOG.md",
     "LICENSE",
     "README.md",
     "NOTICE"
@@ -19,7 +20,7 @@
   "scripts": {
     "start": "node bin/nexuscrew.js serve",
     "dev": "node bin/nexuscrew.js serve",
-    "build": "cd frontend && npm install && npm run build && cd ..",
+    "build": "npm --prefix frontend ci && npm --prefix frontend run build",
     "test": "node tests/run-isolated.js && npm --prefix frontend test"
   },
   "dependencies": {

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

@@ -0,0 +1,133 @@
+---
+name: alibaba-token-media
+description: "Generate or edit images with Wan 2.7 and create videos with HappyHorse through an Alibaba Qwen Cloud Token Plan Personal subscription. Use when the user asks Claude Code, Codex, Codex-VL, or Pi to draw, generate, or edit an image with wan2.7-image or wan2.7-image-pro; create text-to-video or image-to-video media with happyhorse-1.1-t2v or happyhorse-1.1-i2v; inspect a submitted HappyHorse task; or validate the Token Plan media setup. Do not use this skill for chat, visual understanding, batch automation, backend services, or pay-as-you-go DashScope APIs."
+---
+
+# Alibaba Token Media
+
+Use the bundled, dependency-free CLI to access only the media models included
+with the Lite guardrails of Alibaba Token Plan Personal. The same skill and Python script work
+with Claude Code, Codex, Codex-VL, and Pi. Invoke the script directly from Pi;
+do not assume that Pi provides a native MCP client.
+
+Keep this workflow interactive. Every generation consumes plan Credits, and
+the plan is not for unattended batch or backend workloads.
+
+## Safety contract
+
+- Read the credential only from `ALIBABA_CODE_API_KEY`. Never request it in
+  chat, pass it on the command line, print it, persist it, or send it through
+  an agent bus.
+- Use only the fixed Token Plan host and exact model allowlist implemented by
+  the script. Never fall back to DashScope pay-as-you-go endpoints.
+- Run `status` and then a `--dry-run` before the first real request in a
+  session. Dry runs never require or reveal the key.
+- Show the user the normalized model, operation, size or duration, resolution,
+  and confirmation flags before spending Credits. A real image request needs
+  `--confirm-credit-use`; a real video request additionally needs
+  `--confirm-expensive`.
+- Require `--confirm-high-cost` for Wan Pro, 2K or 4K images, 1080P video, or
+  video longer than five seconds. Keep Lite defaults at one 1K base image or
+  one 720P three-second video.
+- Never batch, enable sequential image sets, retry a generation POST
+  automatically, or run more than one generation submit concurrently. A task
+  status GET may be retried, but never with a tight polling loop.
+- Accept local input only as a regular, non-symlink JPEG, PNG, BMP, or WEBP
+  file below 20 MiB and under the current user's home. Image-to-video accepts
+  JPEG, PNG, or WEBP first frames, not BMP. Accept remote input only
+  over public HTTPS; reject localhost, private IP literals, credentials, and
+  non-standard ports.
+- Download signed result URLs immediately. Never paste signed URLs into chat,
+  logs, source files, or an agent bus; they expire after 24 hours.
+
+## Locate the CLI
+
+Resolve `scripts/alibaba_token_media.py` relative to this `SKILL.md`, then run
+it with Python 3:
+
+```bash
+python3 <skill-dir>/scripts/alibaba_token_media.py status
+```
+
+Keep this packaged skill as the source of truth; do not copy the script into a
+project before using it.
+
+## Generate or edit an image
+
+Start with a sanitized preview:
+
+```bash
+python3 <skill-dir>/scripts/alibaba_token_media.py image \
+  --prompt "A quiet alpine lake at sunrise" \
+  --dry-run
+```
+
+After explicit approval, repeat without `--dry-run` and add
+`--confirm-credit-use`. For an edit, add one to nine `--image` values. Each
+value may be a permitted local image under the current user's home or a public
+HTTPS URL:
+
+```bash
+python3 <skill-dir>/scripts/alibaba_token_media.py image \
+  --prompt "Preserve the subject; replace the background with a night city" \
+  --image /absolute/path/input.png \
+  --confirm-credit-use
+```
+
+Use `--model wan2.7-image-pro --size 2K --confirm-high-cost` only after the
+user selects that higher-cost variant. `4K` is allowed only for Pro
+text-to-image with no input images. The script fixes `n=1` and disables image
+sets. Image watermarking is off by default and enabled only with `--watermark`.
+
+## Submit a video
+
+Text-to-video Lite preview:
+
+```bash
+python3 <skill-dir>/scripts/alibaba_token_media.py video-submit \
+  --prompt "A paper model city slowly lights up at dusk" \
+  --dry-run
+```
+
+For a real request, add both `--confirm-credit-use` and
+`--confirm-expensive`. For image-to-video, select `happyhorse-1.1-i2v` and
+supply exactly one first-frame image with `--image`. Do not supply `--ratio`
+for image-to-video; its aspect ratio follows the input. Video watermarking is
+on by default and can be disabled explicitly with `--no-watermark`.
+
+```bash
+python3 <skill-dir>/scripts/alibaba_token_media.py video-submit \
+  --model happyhorse-1.1-i2v \
+  --image /absolute/path/first-frame.png \
+  --prompt "The camera slowly moves forward" \
+  --confirm-credit-use --confirm-expensive
+```
+
+Return the task ID after a real submit. Do not hide submission success behind
+polling.
+
+## Check and download a video
+
+Query a task once:
+
+```bash
+python3 <skill-dir>/scripts/alibaba_token_media.py video-status <task-id>
+```
+
+When it is `SUCCEEDED`, repeat with `--download`. If recurring monitoring is
+requested and the client exposes a loop facility, use an interval of at least
+five minutes. Do not implement a private tight polling loop.
+
+```bash
+python3 <skill-dir>/scripts/alibaba_token_media.py video-status <task-id> \
+  --download
+```
+
+Default downloads go to
+`~/Downloads/alibaba-token-plan/YYYY-MM-DD/` with unique names and no
+overwrite. An explicit `--output` must remain under the current user's home.
+
+## Reference
+
+Read [references/api-contract.md](references/api-contract.md) before changing
+payloads, limits, endpoints, or model handling.

package/skills/alibaba-token-media/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Alibaba Token Media"
+  short_description: "Generate Wan images and HappyHorse videos"
+  default_prompt: "Use $alibaba-token-media to generate or edit media safely with my Alibaba Token Plan."

package/skills/alibaba-token-media/references/api-contract.md

@@ -0,0 +1,97 @@
+# Alibaba Token Plan media API contract
+
+Verified against the official Qwen Cloud documentation on 2026-07-19.
+
+## Fixed subscription surface
+
+- Host: `https://token-plan.ap-southeast-1.maas.aliyuncs.com`
+- Credential environment variable: `ALIBABA_CODE_API_KEY`
+- Authorization: `Bearer <token>`
+- Supported invocation surfaces: Claude Code, Codex, Codex-VL, and Pi through
+  the packaged skill and CLI. Pi is not assumed to support MCP natively.
+- Token Plan Personal Lite guardrails: interactive use only, one submit at a
+  time, no batch generation, and no automatic retry of a generation POST.
+- Never substitute the DashScope pay-as-you-go host.
+
+The Token Plan documentation says coding tools cannot configure media models
+as chat models. They must use a skill, command, agent, or equivalent extension.
+The Personal plan is intended for interactive programming and agent-tool
+work, not unattended scripts, backend services, or batch processing.
+
+## Wan 2.7 image generation and editing
+
+Synchronous endpoint:
+
+`POST /api/v1/services/aigc/multimodal-generation/generation`
+
+Allowed plan models:
+
+- `wan2.7-image`
+- `wan2.7-image-pro`
+
+Request shape:
+
+```json
+{
+  "model": "wan2.7-image",
+  "input": {
+    "messages": [{
+      "role": "user",
+      "content": [{"text": "prompt"}, {"image": "data-or-https-url"}]
+    }]
+  },
+  "parameters": {
+    "n": 1,
+    "size": "1K",
+    "enable_sequential": false,
+    "watermark": false,
+    "thinking_mode": true
+  }
+}
+```
+
+The content array requires exactly one text object and accepts zero to nine
+image objects. Prompt maximum is 5,000 characters. Inputs may be JPEG, PNG,
+BMP, or WEBP and are limited to 20 MiB each. `wan2.7-image` supports 1K and 2K;
+Pro also supports 4K for text-to-image only. The output image URL is under
+`output.choices[*].message.content[*].image` and expires after 24 hours.
+
+## HappyHorse video generation
+
+Submit endpoint:
+
+`POST /api/v1/services/aigc/video-generation/video-synthesis`
+
+Required submission header: `X-DashScope-Async: enable`.
+
+Allowed plan models:
+
+- `happyhorse-1.1-t2v`
+- `happyhorse-1.1-i2v`
+
+Text-to-video input contains `prompt`; parameters contain `resolution`,
+`ratio`, and `duration`. Image-to-video input additionally contains exactly one
+`media` item with `type: first_frame` and an HTTPS or Base64 image in `url`;
+its parameters omit `ratio` because output follows the first frame. The CLI
+enables video watermarking by default; image watermarking is disabled by
+default. Image-to-video first frames accept JPEG, PNG, or WEBP, not BMP.
+
+Duration is an integer from 3 through 15 seconds. Resolution is 720P or 1080P.
+Text-to-video ratios are 16:9, 9:16, 1:1, 4:3, 3:4, 4:5, 5:4, 9:21, or 21:9.
+The response task ID is `output.task_id`.
+
+Status endpoint:
+
+`GET /api/v1/tasks/{task_id}`
+
+Terminal states are `SUCCEEDED`, `FAILED`, `CANCELED`, and `UNKNOWN`. On
+success, `output.video_url` is an H.264 MP4 signed URL valid for 24 hours.
+
+## Official sources
+
+- https://docs.qwencloud.com/token-plan/best-practices/integrate-multimodal-gen
+- https://docs.qwencloud.com/token-plan/personal/token-plan-personal-overview
+- https://docs.qwencloud.com/api-reference/image-generation/wan27-image-gen-edit/synchronous
+- https://docs.qwencloud.com/api-reference/video-generation/happyhorse-text-to-video/create-task
+- https://docs.qwencloud.com/api-reference/video-generation/happyhorse-image-to-video/create-task
+- https://docs.qwencloud.com/api-reference/video-generation/happyhorse-text-to-video/query-result