npm - @mmmbuto/nexuscrew - Versions diffs - 0.8.31 → 0.8.33 - Mend

@mmmbuto/nexuscrew 0.8.31 → 0.8.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (19) hide show

package/CHANGELOG.md +42 -0
package/MCP_COMPANIONS.md +67 -0
package/README.md +30 -9
package/frontend/dist/assets/{index-CZxcRYUd.js → index-CP5MeWCH.js} +29 -29
package/frontend/dist/index.html +1 -1
package/frontend/dist/version.json +1 -1
package/lib/fleet/launch.js +16 -2
package/lib/mcp/server.js +13 -0
package/mcp-companions.json +103 -0
package/package.json +3 -1
package/skills/crew/SKILL.md +89 -0
package/skills/crew/agents/openai.yaml +4 -0
package/skills/mail-assistant/SKILL.md +71 -0
package/skills/mail-assistant/agents/openai.yaml +4 -0
package/skills/memory/SKILL.md +81 -0
package/skills/memory/agents/openai.yaml +4 -0
package/skills/nexuscrew-agent/SKILL.md +20 -0
package/skills/vl-msa/SKILL.md +68 -0
package/skills/vl-msa/agents/openai.yaml +4 -0

package/frontend/dist/index.html CHANGED Viewed

@@ -11,7 +11,7 @@
   <meta name="apple-mobile-web-app-title" content="NexusCrew" />
   <link rel="manifest" href="/manifest.json" />
   <title>NexusCrew</title>
-  <script type="module" crossorigin src="/assets/index-CZxcRYUd.js"></script>
+  <script type="module" crossorigin src="/assets/index-CP5MeWCH.js"></script>
   <link rel="stylesheet" crossorigin href="/assets/index-CrggFFKZ.css">
 </head>
 <body>

package/frontend/dist/version.json CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":"0.8.31"}
1	+ {"version":"0.8.33"}

package/lib/fleet/launch.js CHANGED Viewed

@@ -36,6 +36,20 @@ function minimalEnv() {
   return minimalRuntimeEnv(process.env, { home: os.homedir() });
 }
+// tmux reports client-side connection failures through localized stderr. The
+// migration classifier must see the stable POSIX wording on every platform,
+// otherwise a missing first-boot socket could disable Fleet under a non-English
+// locale. Restrict only the message locale: LC_ALL=C would also force ASCII
+// character handling and tmux would sanitize the tab in our format string.
+// Panes, the shared server and the inventory protocol keep a UTF-8 LC_CTYPE.
+function tmuxInventoryEnv() {
+  const env = minimalEnv();
+  delete env.LC_ALL; // LC_ALL would override LC_MESSAGES and LC_CTYPE.
+  env.LANGUAGE = 'C';
+  env.LC_MESSAGES = 'C';
+  return env;
+}
 // httpError(status, msg, data?, cause?) — structured HTTP error. `data` carries
 // arbitrary API detail for the response body; `cause` (T4) is the OPTIONAL
 // bounded failure triple {phase, code} of the up() boundary that failed. The
@@ -170,10 +184,10 @@ async function migrateLegacyTmuxSessions(tmuxBin, defs, { readonly = false } = {
     };
   }
   const listing = await tmuxExec(tmuxBin,
-    ['list-sessions', '-F', '#{session_id}\t#{session_name}'], { env: minimalEnv() });
+    ['list-sessions', '-F', '#{session_id}\t#{session_name}'], { env: tmuxInventoryEnv() });
   if (listing.err) {
     const detail = boundedTmuxFailure(listing);
-    if (/no server running|failed to connect|connection refused|no such file.*tmux/i.test(detail)) {
+    if (/no server running|failed to connect|connection refused|no such file.*tmux|error connecting to .*\(no such file or directory\)/i.test(detail)) {
       return { migrated: [], reason: 'no-tmux-server', needsPersistence: legacyMap.size > 0 };
     }
     throw tmuxMigrationError('TMUX_MIGRATION_LIST_FAILED',

package/lib/mcp/server.js CHANGED Viewed

@@ -25,6 +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 MCP_COMPANIONS = require('../../mcp-companions.json');
 const { TOOLS, IDENTITY_CODE, IDENTITY_REMEDIATION } = require('./tools.js');
 const cells = require('./cells.js');
@@ -38,6 +39,17 @@ const INVALID_REQUEST = -32600;
 const METHOD_NOT_FOUND = -32601;
 const INVALID_PARAMS = -32602;
+function companionInstructions() {
+  const catalog = MCP_COMPANIONS.companions
+    .map((item) => `${item.id}: ${item.name} (${item.repository})`)
+    .join('; ');
+  return 'Discover the current client tools before recommending another MCP server. '
+    + 'If a requested capability is missing, these optional NexusCrew companions may cover it: '
+    + `${catalog}. Recommend only the capability actually needed and ask before installing `
+    + 'software, changing MCP configuration, starting services or requesting credentials. '
+    + 'NexusCrew does not install or configure companions automatically.';
+}
 // --- identita' cella mittente ------------------------------------------------
 // Ordine (design §1, INVARIATO): $TMUX presente -> `tmux display-message -p '#S'`
 // (nome sessione reale); se fallisce/invalida -> fallback env NEXUSCREW_MCP_SESSION;
@@ -246,6 +258,7 @@ function createMcpServer(opts = {}) {
         protocolVersion: pv,
         capabilities: { tools: {} },
         serverInfo: { name: 'nexuscrew', version: VERSION },
+        instructions: companionInstructions(),
       });
     }
     if (method === 'ping') return reply(id, {});

package/mcp-companions.json ADDED Viewed

@@ -0,0 +1,103 @@
+{
+  "schemaVersion": 1,
+  "kind": "nexuscrew-mcp-companions",
+  "policy": {
+    "optional": true,
+    "discoverToolsFirst": true,
+    "recommendOnlyForRequestedCapability": true,
+    "automaticInstall": false,
+    "automaticConfiguration": false
+  },
+  "companions": [
+    {
+      "id": "memory",
+      "name": "mcp-memory-rs",
+      "repository": "https://github.com/DioNanos/mcp-memory-rs",
+      "installation": "https://github.com/DioNanos/mcp-memory-rs#install",
+      "license": "Apache-2.0",
+      "bundledSkill": "skills/memory/SKILL.md",
+      "capabilities": [
+        "durable structured agent state",
+        "versioned categories",
+        "bounded append-only journals",
+        "full-text memory search"
+      ],
+      "primaryTools": [
+        "memory_read",
+        "memory_write",
+        "memory_append",
+        "memory_search",
+        "memory_status"
+      ]
+    },
+    {
+      "id": "msa",
+      "name": "mcp-vl-msa-rs",
+      "repository": "https://github.com/DioNanos/mcp-vl-msa-rs",
+      "installation": "https://github.com/DioNanos/mcp-vl-msa-rs#install",
+      "license": "Apache-2.0",
+      "bundledSkill": "skills/vl-msa/SKILL.md",
+      "capabilities": [
+        "persistent document collections",
+        "BM25 and optional hybrid retrieval",
+        "full-source grounding",
+        "bounded multi-hop retrieval"
+      ],
+      "primaryTools": [
+        "msa_index",
+        "msa_index_batch",
+        "msa_search",
+        "msa_fetch_doc",
+        "msa_remember",
+        "msa_forget",
+        "msa_interleave_round"
+      ]
+    },
+    {
+      "id": "crew",
+      "name": "mcp-crewd-rs",
+      "repository": "https://github.com/DioNanos/mcp-crewd-rs",
+      "installation": "https://github.com/DioNanos/mcp-crewd-rs#install",
+      "license": "Apache-2.0",
+      "bundledSkill": "skills/crew/SKILL.md",
+      "capabilities": [
+        "bounded AI worker spawning",
+        "task status and structured results",
+        "controlled inter-cell messaging"
+      ],
+      "primaryTools": [
+        "cell_spawn",
+        "cell_send_task",
+        "cell_status",
+        "cell_result",
+        "cell_list",
+        "cell_send",
+        "cell_ask"
+      ]
+    },
+    {
+      "id": "mail",
+      "name": "mcp-email-rs",
+      "repository": "https://github.com/DioNanos/mcp-email-rs",
+      "installation": "https://github.com/DioNanos/mcp-email-rs#install",
+      "license": "Apache-2.0",
+      "bundledSkill": "skills/mail-assistant/SKILL.md",
+      "capabilities": [
+        "IMAP mailbox discovery",
+        "mail search and reading",
+        "attachments and folders",
+        "drafts and optional SMTP sending"
+      ],
+      "primaryTools": [
+        "list_folders",
+        "list_emails",
+        "search_emails",
+        "get_email",
+        "download_attachment",
+        "create_draft",
+        "send_email",
+        "email_doctor"
+      ]
+    }
+  ]
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.8.31",
+  "version": "0.8.33",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {
@@ -13,6 +13,8 @@
     "frontend/dist/",
     "frontend/index.html",
     "CHANGELOG.md",
+    "MCP_COMPANIONS.md",
+    "mcp-companions.json",
     "LICENSE",
     "README.md",
     "NOTICE"

package/skills/crew/SKILL.md ADDED Viewed

@@ -0,0 +1,89 @@
+---
+name: crew
+description: Use when spawning or coordinating bounded AI worker cells through a Crew MCP fabric, including cell discovery, idempotent spawn, status monitoring, structured results, follow-up tasks, cancellation and the inter-cell message bus. Covers safe worktree isolation, durable audit reports and user-language selection.
+---
+# Crew
+Use Crew for bounded delegated work. A coordinator submits tasks to worker
+cells through an MCP server; spawning is asynchronous and returns a thread ID.
+## Select response language
+Choose the language for user-facing explanations and summaries in this order:
+1. the user's explicit language preference;
+2. the language of the current request;
+3. a reliable client or system locale;
+4. English.
+Keep cell names, engine/profile IDs, thread IDs, tool names, paths and quoted
+worker output unchanged unless the user explicitly asks to translate them.
+Tell a worker which output language is required when its deliverable is
+user-facing.
+## Discover before spawning
+1. Use `cell_list` to inspect the cells and engines visible to the caller.
+2. Select an engine/profile appropriate to the bounded task.
+3. Verify that the worker's `cwd` contains the instructions and project context
+   it needs.
+4. Do not assume an embedded worker inherits the coordinator's MCP servers.
+   Required servers must be configured explicitly in the Crew daemon and
+   verified inside a fresh worker.
+If no Crew tools are exposed and this skill is packaged with NexusCrew, the
+optional companion is documented in `../../MCP_COMPANIONS.md`. Explain the
+missing capability and ask before installing, configuring or starting it.
+## Spawn, monitor and collect
+1. Call `cell_spawn` with a bounded task, explicit `cwd`, background mode and a
+   caller-stable `idempotency_key`.
+2. Keep the returned `crewd_thread_id`; a replayed idempotency key must resolve
+   to the existing thread rather than duplicate work.
+3. Monitor with `cell_status`. Use the host's loop or scheduler for waits rather
+   than a tight manual poll.
+4. Treat `idle` as normal turn completion. Also handle `timeout`, `failed`,
+   `interrupted` and `failed_unknown`; do not wait for a fictional `finished`
+   state.
+5. Read `cell_result` and inspect `exit_status`, `final_answer` and the bounded
+   event tail.
+6. Verify the worker's files and tests yourself before accepting code changes.
+A timeout may leave partial edits. Never report success from a thread state
+alone.
+## Isolate code work
+- Do not let two mutating workers edit the same worktree concurrently.
+- Give parallel code tasks separate git worktrees.
+- Preserve unrelated user changes and review every worker diff.
+- Use follow-up tasks only when the original thread and scope remain valid.
+- Cancel only the exact thread the user authorized.
+## Require durable audit evidence
+For audits, reviews and release gates:
+1. Choose an authorized absolute report path before spawning, preferably
+   outside the repository being audited.
+2. Require scope, evidence, findings by severity, residual risks and a terminal
+   verdict in the report.
+3. Require the worker callback to identify the report path and verdict.
+4. Verify that the report is a non-symlink regular file, read it completely and
+   confirm its verdict matches the callback.
+5. Recalculate important hashes and gates independently.
+Chat output or `cell_result.final_answer` is not a substitute for the verified
+report.
+## Use the message bus deliberately
+- `cell_send` is fire-and-forget.
+- `cell_ask` plus `cell_await` is appropriate when a reply is required.
+- `cell_send_task` starts a follow-up turn on an existing thread.
+- `cell_inbox` reads queued bus messages.
+Transport receipts do not prove task acceptance or completion. Report only
+results that have been verified.

package/skills/crew/agents/openai.yaml ADDED Viewed

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Crew"
+  short_description: "Coordinate bounded AI worker cells"
+  default_prompt: "Use crew to delegate this bounded task and collect a verified result."

package/skills/mail-assistant/SKILL.md ADDED Viewed

@@ -0,0 +1,71 @@
+---
+name: mail-assistant
+description: Use for mailbox discovery, email search and reading, priority triage, attachment review, folder organisation, reply drafting, explicit sending, or recurring mail checks through an available Gmail or IMAP/SMTP MCP connector. Select the user-facing language from the request and the draft language from the thread, while preserving read-before-write discipline and explicit confirmation for consequential mail actions.
+---
+# Mail Assistant
+Use the mail tools already exposed by the current client. Discover folders,
+sender identities and supported operations live; never assume provider-specific
+folder names or account configuration.
+## Select languages
+Choose the language for digests, questions and explanations in this order:
+1. the user's explicit language preference;
+2. the language of the current request;
+3. a reliable client or system locale;
+4. English.
+Write a reply draft in the language of the email thread unless the user asks
+for another language. Preserve names, quoted text and required legal or
+technical terms; do not translate them merely to match the interface language.
+## Choose tools
+1. Prefer an exposed Gmail connector for Gmail-hosted workflows.
+2. Otherwise use an exposed IMAP/SMTP mail MCP such as `mcp-email-rs`.
+3. Search narrowly before listing large folders, and fetch complete message
+   bodies only when needed for classification, attachments or drafting.
+4. If no mail tool is available, explain the missing capability. When this
+   skill is packaged with NexusCrew, the optional companion is documented in
+   `../../MCP_COMPANIONS.md`. Do not install or configure it without consent.
+## Apply the safety boundary
+- Reading and searching are allowed when the user asks to inspect mail.
+- Treat moves, flags, drafts, folder changes and calendar/reminder creation as
+  explicit mutations; perform only the mutation the user requested.
+- Treat deletion and sending as consequential external actions. Confirm the
+  exact targets and intended content immediately before acting unless the
+  user's current request already gives unambiguous final authorization.
+- Prefer recoverable archive or Trash moves over permanent deletion.
+- Re-fetch message identifiers after moves; IMAP UIDs are folder-scoped and
+  can change.
+- Never expose credentials, authentication links or sensitive message content
+  in logs, push notifications, TTS or unrelated summaries.
+- Never infer an authorised sender identity. Use identities returned by the
+  connector or explicitly supplied by the user.
+## Triage and draft
+1. Fetch the smallest useful set of messages.
+2. Classify each item as urgent/action required, reply soon, waiting, or
+   informational, using the user's own priorities when available.
+3. Read attachments only when necessary and identify their type before
+   downloading.
+4. Present a compact digest with evidence from the messages and a proposed
+   next action.
+5. Draft only when requested. Preserve the user's tone, distinguish facts from
+   assumptions and leave unresolved details visible.
+6. Before sending, show or re-confirm recipients, subject, body and attachments.
+7. Report only actions that the tool actually completed.
+## Recurring checks
+Create recurring monitoring only when explicitly requested. Use the
+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.

package/skills/mail-assistant/agents/openai.yaml ADDED Viewed

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Mail Assistant"
+  short_description: "Safely triage and draft email in context"
+  default_prompt: "Use mail-assistant to review my new mail and prepare a concise action digest."

package/skills/memory/SKILL.md ADDED Viewed

@@ -0,0 +1,81 @@
+---
+name: memory
+description: Use when reading or writing persistent AI-agent state through a Memory MCP server, including category discovery, versioned reads and writes, merge patches, optimistic concurrency, bounded append-only journals, search, context loading and history. Keep durable state separate from bounded logs and choose the user-facing language from the request.
+---
+# Memory
+Use the exposed Memory MCP tools rather than reading or editing the server's
+database, cache or state files directly.
+## Select response language
+Choose the language for explanations and summaries in this order:
+1. the user's explicit language preference;
+2. the language of the current request;
+3. a reliable client or system locale;
+4. English.
+Keep category names, tool names, JSON fields, paths and quoted source text
+unchanged unless the user explicitly asks to translate them.
+## Understand the model
+- A category is a named JSON document. `memory_read` takes a `category`, not a
+  nested key.
+- Reads may be broadly available while writes are scoped by the server's
+  device or actor ACL.
+- Every write is versioned; inspect `memory_history` when provenance matters.
+- Treat recalled state as a snapshot. Verify live files, flags and services
+  before acting on drift-prone facts.
+## Warm up narrowly
+1. Call `memory_list` to discover available categories.
+2. Read only relevant categories with `memory_read`, or load a bounded set with
+   `memory_context`.
+3. Use `memory_search` when the category is unknown.
+Do not load every category by default.
+## Write safely
+`memory_write {category, content}` replaces the category by default.
+- Set `merge:true` for a top-level patch: supplied keys are inserted or
+  overwritten, JSON `null` deletes a key, and untouched keys remain.
+- Pass `expected_hash` from the prior read/list result for read-modify-write
+  workflows so concurrent updates fail instead of being overwritten.
+- Never write another device's namespace unless the server ACL and the user's
+  request explicitly authorize it.
+## Separate state from journals
+Use `memory_append` for a bounded append-only log category. The server stamps
+entries and prunes them according to retention.
+- Do not simulate a journal by adding ever-growing dated keys to a normal
+  memory category.
+- Do not use `memory_write` on a log category.
+- Do not use `memory_append` on a normal memory category.
+A useful convention is:
+- `<name>_state`: lean declarative state, updated with `memory_write`;
+- `<name>_log`: bounded event journal, updated with `memory_append`.
+Facts that must never be pruned belong in normal durable state or an external
+document store, not in a bounded log.
+## Search and inspect
+- Use `memory_search` for BM25 full-text retrieval across categories.
+- Use `memory_search_semantic` only when the server exposes and supports it.
+- Use `memory_history` to inspect versions before restoring or explaining a
+  change.
+- Report writes only after the tool confirms them.
+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.

package/skills/memory/agents/openai.yaml ADDED Viewed

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Memory"
+  short_description: "Use persistent agent memory safely"
+  default_prompt: "Use memory to inspect and update the durable state relevant to this task."

package/skills/nexuscrew-agent/SKILL.md CHANGED Viewed

@@ -36,6 +36,26 @@ Apply these rules:
 The MCP server is the stdio command `nexuscrew mcp` and must be registered in the host AI client. If the `nc_*` tools are not exposed, report that the bridge is not configured in that session and use the fallback flows below where applicable.
+## Optional capability companions
+NexusCrew does not make unrelated MCP servers hidden dependencies. When the
+user requests durable structured memory, document retrieval, bounded worker
+delegation or mailbox access:
+1. Discover the tools already exposed by the current AI client.
+2. Use an available tool that covers the request.
+3. If the capability is absent, consult the packaged
+   `../../mcp-companions.json` catalog and mention the matching optional
+   companion once.
+4. Explain the capability it adds and link its public repository.
+5. Ask before installing software, changing MCP configuration, starting a
+   service or requesting credentials.
+Never recommend a companion during unrelated work, repeatedly advertise it, or
+claim it is required by NexusCrew. The catalog is discovery metadata only; it
+does not authorize installation or external actions. See
+`../../MCP_COMPANIONS.md` for the human-readable guide.
 ## File exchange (inbox / outbox)
 Per session, NexusCrew watches `<root>/<session>/{inbox,outbox}` (root = `$NEXUSCREW_FILES_ROOT`, default `~/NexusFiles`):

package/skills/vl-msa/SKILL.md ADDED Viewed

@@ -0,0 +1,68 @@
+---
+name: vl-msa
+description: Use when indexing or retrieving documents, notes, research or past conversations through a VL-MSA long-term-memory MCP server, including collections, batch indexing, BM25 or hybrid search, full-document grounding, remember/forget and bounded multi-hop interleaving. Enforce locate-then-ground retrieval and choose the user-facing language from the request.
+---
+# VL MSA
+Use VL-MSA for durable searchable source material. Collections persist across
+sessions; BM25 works without embeddings, while hybrid reranking is optional.
+## Select response language
+Choose the language for explanations and answers in this order:
+1. the user's explicit language preference;
+2. the language of the current request;
+3. a reliable client or system locale;
+4. English.
+Keep collection IDs, document IDs, tool names, metadata fields and quoted
+source text unchanged unless the user explicitly asks to translate them.
+## Locate, then ground
+Retrieval has two required steps:
+1. Call `msa_search {collection, query, k}` to locate relevant chunks.
+2. Call `msa_fetch_doc` for the selected hit before using it as evidence.
+Search chunks are locators, not complete sources. Do not answer a
+context-dependent question from truncated snippets alone.
+## Index material
+- Use `msa_index` for one document or note.
+- Use `msa_index_batch` for bulk ingest.
+- Group related material into a stable named collection.
+- Inspect `msa_list_collections`, `msa_stats` or `msa_manifest` before assuming
+  a collection exists or is populated.
+Index only material the user is authorized to store. Preserve provenance and
+do not place credentials or unrelated personal data in collection metadata.
+## Manage standalone memories
+- Use `msa_remember` for a standalone agent memory. Its deduplication and
+  low-signal gate may decline a write.
+- Use `msa_forget` for an explicitly requested removal.
+Do not claim a memory was stored or removed until the tool confirms the
+outcome.
+## Handle multi-hop questions
+Use `msa_interleave_round` for one bounded route, deduplicate and read step.
+Repeat only as needed, carrying forward the grounded facts from the prior
+round. Avoid a single unbounded search.
+## Choose ranking
+- Use BM25 by default.
+- Pass `dense_alpha` only when the server is built and configured for hybrid
+  retrieval.
+- Do not describe lexical-only results as semantic retrieval.
+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.

package/skills/vl-msa/agents/openai.yaml ADDED Viewed

@@ -0,0 +1,4 @@
+interface:
+  display_name: "VL MSA"
+  short_description: "Index and ground long-term knowledge"
+  default_prompt: "Use vl-msa to find and ground the relevant source documents for this question."