marvisx-cli 0.2.3__tar.gz → 0.3.6__tar.gz

{marvisx_cli-0.2.3 → marvisx_cli-0.3.6}/MANIFEST.in

@@ -9,4 +9,5 @@
 recursive-include migrations *.sql
 recursive-include core/scripts/install_hooks *.sh *.json *.py
 recursive-include core/api/templates *.md *.j2
+recursive-include core/api/mcp/tools/workflow_playbooks *.md
 recursive-include projects/_template *

{marvisx_cli-0.2.3 → marvisx_cli-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: marvisx-cli
-Version: 0.2.3
+Version: 0.3.6
 Summary: MarvisX OSS — agent-native company-brain CLI runtime (init, status, brief, triage)
 Author: MarvisX maintainers
 License: BSL-1.1
@@ -31,12 +31,12 @@ Requires-Dist: click>=8
 Requires-Dist: pydantic>=2.5
 Requires-Dist: pydantic-settings>=2.7.0
 Requires-Dist: PyYAML>=6
+Requires-Dist: platformdirs>=4.0
 Requires-Dist: cryptography>=42
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: slowapi>=0.1.9
 Requires-Dist: cachetools>=5.3.0
 Requires-Dist: uvicorn[standard]>=0.34.0
-Requires-Dist: uvloop>=0.21.0
 Requires-Dist: aiosqlite>=0.20.0
 Requires-Dist: PyJWT>=2.10.0
 Requires-Dist: bcrypt>=4.2.0

marvisx_cli-0.3.6/README.md

@@ -0,0 +1,122 @@
+# Marvis
+
+**The Company Brain your agents install.** Use Claude Code, or whatever coding agent you run, to manage projects and coordinate your agents, not just write code. Marvis captures what your agents do as they work, structures it into a cross-project Knowledge Graph, and hands it back to them, so your work stays on track and the system learns from it. Self-hosted, EU-resident, governed by an immutable audit chain.
+
+**Open-core and free to run.** Marvis is the free core: you self-host it, read the source, fork it, audit it, at no cost. MarvisX is the commercial tier on top of the same brain: multi-department teams, data sovereignty and managed hosting, and autonomous, hands-off-the-keyboard operation. Marvis is what you install today; MarvisX is what you reach for when a single self-hosted instance is no longer enough.
+
+## Install
+
+Marvis runs as a CLI your agent drives. Install it, then let the agent you already use take it from there:
+
+```bash
+uv tool install marvisx-cli
+marvis init
+```
+
+`marvis init` scaffolds the project and installs the governance hooks, then exposes the MCP surface to your agent. Python 3.10–3.13; on 3.14, pin the interpreter: `uv tool install --python 3.13 marvisx-cli`. No `uv` yet? `curl -LsSf https://astral.sh/uv/install.sh | sh`.
+
+To run the full Console + API stack yourself, see [Self-hosting the full stack](#self-hosting-the-full-stack).
+
+## What it does, in plain terms
+
+- **Your agents stop forgetting.** Decisions, specs, playbooks, learnings and mistakes are captured as a side effect of the work your agents already do, not retyped by hand.
+- **Your work stays on track.** A reflective Brain layer compares what agents produce against your intent and surfaces drift early, before it compounds across sessions.
+- **One brain, many projects and teams.** A cross-project Knowledge Graph links decisions, code and documents, so an agent working in one project can see what was decided in another.
+- **Governed by default.** Constitution rules enforced at the hook level, plus a foreign-key-immutable audit log: every action traces back to the human who approved it.
+- **It lives in your terminal, not a dashboard.** An agent-native MCP surface keeps your existing Claude Code / Codex / Cursor as the place you work.
+
+## Under the hood
+
+- **Cross-project Knowledge Graph** with 17 deterministic edge types covering code, work-chain artifacts, knowledge-chain documents, cross-project references, and bridge edges. Canonical IDs follow `{prefix}:{kind}:{slug}`.
+- **Foreign-key-immutable audit log** with provenance pinned at the SQLite level. Designed to satisfy the logging surface required by EU Regulation 2024/1689 (AI Act) Article 12.
+- **Brain reflection pipeline** in five layers — substrate, digest and journal, drift checker, memory operations, findings — closed by a Direction-Aware loop.
+- **Constitution-enforced safety rules** enforced by deterministic hook gates and an MCP mirror for providers without native hooks.
+- **Agent-native MCP surface** exposing 91 tools, callable identically from Claude Code, Codex, Gemini, OpenCode, and a web console.
+
+## Search and embedding quality
+
+Marvis defaults to **IBM Granite-Embedding-97m-Multilingual-R2** self-hosted via ONNX, blended with SQLite BM25 keyword search through Reciprocal Rank Fusion. Backend is selectable through `EMBEDDING_MODE`.
+
+This is a deliberate tradeoff: EU compliance, self-hosting, and zero external embedding cost come at the cost of retrieval quality that is below commercial managed embedding providers. See [`docs/SEARCH-QUALITY.md`](docs/SEARCH-QUALITY.md) for the benchmark numbers, affected workflows, mitigations available today, and the Phase 2 fine-tune roadmap.
+
+## License posture
+
+- **Free to self-host.** Code is **source-available** under the **Business Source License 1.1**, with an automatic change date converting to **Apache License 2.0** four years after release.
+- Documentation and architectural patterns: **CC-BY 4.0**.
+
+This is open-core, not OSI open source: the core is free to run and read, and the BSL holds back only competing commercial-as-a-service use until the change date. The combination keeps the architecture freely citable while preserving the ability to ship a self-hosted reference deployment.
+
+## Architecture map
+
+The system groups capabilities into eight functional domains (`M1 Capture`, `M2 Index`, `M3 Retrieve`, `M4 Reflect`, `M5 Act`, `M6 Agent-native I/O`, `M7 Compliance`, `M8 Productization`). The Knowledge Graph stitches them together with canonical IDs and an audit chain.
+
+The full architectural description is the MarvisX preprint on Zenodo: [`10.5281/zenodo.20341860`](https://doi.org/10.5281/zenodo.20341860).
+
+## Repository layout
+
+```
+core/
+├── api/        # FastAPI service: KG, ingest, brain, MCP transport
+├── console/    # Next.js web console
+├── kb/         # Project-local knowledge base templates
+├── mcp-pir/    # MCP server (stdio) exposing the 91-tool surface
+└── scripts/    # Deployment, migration, and operational scripts
+
+deploy/
+└── _template/  # Reference deployment template
+                # (Docker Compose + environment scaffolding)
+```
+
+## Self-hosting the full stack
+
+The CLI above runs Marvis against a local SQLite database. To run the full Console + API stack yourself, use the reference Docker Compose deployment. Clone the repository, copy `deploy/_template/.env.example` to `.env`, populate the required secrets, and bring the stack up:
+
+```bash
+cp deploy/_template/.env.example deploy/_template/.env
+cd deploy/_template/
+docker compose up -d
+```
+
+The Console becomes available on the configured `CONSOLE_PORT` and the API on the configured `API_PORT`. Detailed first-run instructions are inside the deployment template.
+
+## MCP surface
+
+Marvis ships an MCP server exposing 91 tools across 11 categories: project and session context, tasks, handoffs, semantic search, learnings, costs, pull requests, knowledge graph queries, ingest triage, brain reflection layer, and audit-and-monitoring controls.
+
+The same surface is used by autonomous agents and by humans through the web console. The intent is parity: any action a user can take through the console, an agent can also take through MCP, and the reverse.
+
+## Single-user local runtime (`MARVIS_OSS_LOCAL`)
+
+The MCP server runs in-process: it calls the same use_cases the HTTP API calls, against the local SQLite database, with no uvicorn and no Node bridge. In this single-user mode there is no HTTP API in front of the database, so the HTTP audit chokepoint (which in the managed deployment forces every mutation through the API) does not exist.
+
+Audit is still recorded: the extracted use_cases write the audit log themselves (`core/api/use_cases/{tasks,pull_requests,audit}.py`), so a mutation issued through MCP still produces an audit row at the use_case level. What is lost is only the additional HTTP-surface chokepoint.
+
+Setting `MARVIS_OSS_LOCAL=1` (truthy: `1`/`true`/`yes`/`on`) makes the `block-db-direct-write` safety rule **advisory** — direct writes to a Marvis SQLite database are allowed with a warning instead of being blocked. When the variable is unset or falsey the rule is unchanged: direct DB writes are blocked fail-closed, exactly as in the managed deployment. This trade-off is intentional for single-user self-hosting and never weakens the default.
+
+**No-fork guarantee.** The HTTP API and the MCP server are not two implementations: both are thin adapters over the same `core/api/use_cases`, differing only in how they fill the per-call `CallerContext`. The proof is the API test suite staying green after the extraction — the same behaviour, exercised through the HTTP surface, over the identical use_cases the MCP server calls.
+
+## Telemetry
+
+Marvis sends anonymous, opt-out usage telemetry to help improve it: coarse event counts plus version and OS buckets, tied to a random install id (a plain UUID, never derived from your machine, user, or email). It never sends file content, project data, or personal information.
+
+Turn it off at any time:
+
+```bash
+marvis telemetry off
+```
+
+Or per environment: `MARVIS_TELEMETRY=0`, the universal `DO_NOT_TRACK=1`, or `telemetry: false` in `~/.marvis/settings.yaml`. With `MARVIS_TELEMETRY=log`, Marvis prints exactly what it would send to stderr and transmits nothing.
+
+## Documentation
+
+- [`docs/SEARCH-QUALITY.md`](docs/SEARCH-QUALITY.md) — search quality expectations, affected workflows, and mitigations
+
+## Contributing
+
+Issues and bug reports are welcome through the repository tracker.
+
+## References
+
+- Preprint (Zenodo): [`10.5281/zenodo.20341860`](https://doi.org/10.5281/zenodo.20341860)
+- License (code): Business Source License 1.1, change date converts to Apache License 2.0 four years after release
+- License (documentation): CC-BY 4.0

{marvisx_cli-0.2.3 → marvisx_cli-0.3.6}/core/api/agents/session_manager.py

@@ -38,7 +38,9 @@ async def list_agent_managed_sessions() -> list[SessionInfo]:
     import urllib.request
     from core.api.config import settings as cfg
     token = cfg.tasks_api_token if hasattr(cfg, "tasks_api_token") else os.environ.get("TASKS_API_TOKEN", "")
-    api_base = os.environ.get("PIR_INTERNAL_BASE", "http://localhost:8100")
+    api_base = os.environ.get("MARVIS_INTERNAL_BASE") or os.environ.get(
+        "PIR_INTERNAL_BASE", "http://localhost:8100"
+    )
     try:
         req = urllib.request.Request(
             f"{api_base}/api/v1/sessions?agent_managed=true",

{marvisx_cli-0.2.3 → marvisx_cli-0.3.6}/core/api/config.py

@@ -8,6 +8,8 @@ from typing import Literal
 from pydantic import AliasChoices, Field, SecretStr
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+from core.platform import current_user, db_default_path
+
 # Prod (Hetzner/Docker) ships the vec0 loadable at this path; it stays the
 # final fallback so prod keeps working unchanged.
 _VEC0_PATH_PROD_DEFAULT = "/data/pir/lib/vec0"
@@ -40,22 +42,43 @@ class Settings(BaseSettings):
         populate_by_name=True,
     )
 
-    pir_env: str = "development"
+    pir_env: str = Field(
+        default="development",
+        validation_alias=AliasChoices("MARVIS_ENV", "PIR_ENV"),
+    )
     # Free-form tenant identifier. Default "core" (OSS). Deploy bundles set
     # DEPLOY_MODE to their own tenant slug via .env; no tenant names are
     # hard-coded in core.
     deploy_mode: str = Field(default="core", alias="DEPLOY_MODE")
-    pir_instance: str = Field(default="prod", alias="PIR_INSTANCE")
+    pir_instance: str = Field(
+        default="prod",
+        validation_alias=AliasChoices("MARVIS_INSTANCE", "PIR_INSTANCE"),
+    )
     marvisx_phase: Literal["A", "B", "C", "D"] = Field(
         default="A", alias="MARVISX_PHASE"
     )
-    pir_canary_banner: bool = Field(default=False, alias="PIR_CANARY_BANNER")
-    pir_voyage_disabled: bool = Field(default=False, alias="PIR_VOYAGE_DISABLED")
-    pir_jwt_secret: str = "dev-secret-change-in-production"
-    pir_admin_password_hash: str = ""
+    pir_canary_banner: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("MARVIS_CANARY_BANNER", "PIR_CANARY_BANNER"),
+    )
+    pir_jwt_secret: str = Field(
+        default="dev-secret-change-in-production",
+        validation_alias=AliasChoices("MARVIS_JWT_SECRET", "PIR_JWT_SECRET"),
+    )
+    pir_admin_password_hash: str = Field(
+        default="",
+        validation_alias=AliasChoices(
+            "MARVIS_ADMIN_PASSWORD_HASH", "PIR_ADMIN_PASSWORD_HASH"
+        ),
+    )
     db_path: str = Field(
-        default="console.db",
-        validation_alias=AliasChoices("PIR_DB_PATH", "DB_PATH"),
+        # Fallback when no MARVIS_DB_PATH/PIR_DB_PATH/DB_PATH env is set: the
+        # platformdirs data root (was a CWD-relative "console.db" that opened a
+        # different DB per launch directory — split-brain, and on Windows a
+        # nonsense root). The env aliases still win via pydantic; this factory
+        # runs ONLY when none are set.
+        default_factory=lambda: str(db_default_path()),
+        validation_alias=AliasChoices("MARVIS_DB_PATH", "PIR_DB_PATH", "DB_PATH"),
     )
     cookie_domain: str | None = Field(default=None, alias="COOKIE_DOMAIN")
     cors_origins_prod: list[str] = Field(
@@ -83,6 +106,16 @@ class Settings(BaseSettings):
     brain_run_off_peak_only: bool = Field(
         default=False, alias="BRAIN_RUN_OFF_PEAK_ONLY"
     )
+    # Warehouse consolidation pass (full-store learning dedup, ships DORMANT).
+    # Unlike memory_ops M2 (same-cycle only), this scans the WHOLE learnings
+    # warehouse and PROPOSES consolidation of cross-cycle duplicates. Default
+    # FALSE — a human enables it after reviewing. Daily cadence guard.
+    brain_warehouse_consolidation_enabled: bool = Field(
+        default=False, alias="BRAIN_WAREHOUSE_CONSOLIDATION_ENABLED"
+    )
+    brain_warehouse_consolidation_interval_seconds: int = Field(
+        default=86400, alias="BRAIN_WAREHOUSE_CONSOLIDATION_INTERVAL_SECONDS"
+    )
 
     # GitHub Webhook
     github_webhook_secret: str = ""
@@ -401,9 +434,6 @@ class Settings(BaseSettings):
     # WIP limit: max tasks in_progress per project (doc/none tasks count as 0.5)
     wip_max_in_progress: int = 3
 
-    # Voyage AI embeddings
-    voyage_api_key: str = ""
-
     # sqlite-vec: env VEC0_PATH → sqlite_vec.loadable_path() → prod fallback.
     vec0_path: str = Field(
         default_factory=_default_vec0_path,
@@ -521,16 +551,14 @@ class Settings(BaseSettings):
 
         Returns '' when GIT_RUNAS_USER is unset or already matches the current
         OS user (no privilege hop needed)."""
-        import pwd
-
         user = (self.git_runas_user or "").strip()
         if not user:
             return ""
-        try:
-            if pwd.getpwuid(os.getuid()).pw_name == user:
-                return ""
-        except (KeyError, OSError):
-            pass
+        # current_user() is pwd.getpwuid(os.getuid()).pw_name on POSIX (identical
+        # to the previous inline lookup) and getpass-based on Windows; the bare
+        # `import pwd` here crashed `marvis project list` on Windows.
+        if current_user() == user:
+            return ""
         return user
 
 

{marvisx_cli-0.2.3 → marvisx_cli-0.3.6}/core/api/db.py

@@ -740,18 +740,26 @@ def _seed_users_and_migrate_owner(conn: sqlite3.Connection) -> None:
     install seeds no hardcoded name. On an existing deployment this seed is
     skipped (users already exist), so the defaults never affect a running install.
     """
-    # Prefer pre-hashed password (production .env has PIR_ADMIN_PASSWORD_HASH)
-    hashed = os.environ.get("PIR_ADMIN_PASSWORD_HASH", "").strip()
+    # Prefer pre-hashed password. Canonical var is MARVIS_ADMIN_PASSWORD_HASH;
+    # PIR_ADMIN_PASSWORD_HASH stays accepted as a deprecated alias.
+    hashed = (
+        os.environ.get("MARVIS_ADMIN_PASSWORD_HASH")
+        or os.environ.get("PIR_ADMIN_PASSWORD_HASH", "")
+    ).strip()
     if not hashed:
         import bcrypt
 
-        pir_password = os.environ.get("PIR_PASSWORD", "").strip()
-        if not pir_password:
+        seed_password = (
+            os.environ.get("MARVIS_PASSWORD")
+            or os.environ.get("PIR_PASSWORD", "")
+        ).strip()
+        if not seed_password:
             raise RuntimeError(
-                "Migration 016 requires PIR_ADMIN_PASSWORD_HASH or PIR_PASSWORD env var "
-                "to seed the admin user. Set at least one in .env."
+                "Migration 016 requires MARVIS_ADMIN_PASSWORD_HASH or MARVIS_PASSWORD "
+                "env var (PIR_* aliases still accepted) to seed the admin user. "
+                "Set at least one in .env."
             )
-        hashed = bcrypt.hashpw(pir_password.encode("utf-8"), bcrypt.gensalt()).decode()
+        hashed = bcrypt.hashpw(seed_password.encode("utf-8"), bcrypt.gensalt()).decode()
 
     admin_id = os.environ.get("MARVIS_ADMIN_USER_ID", "").strip() or "usr_admin"
     admin_slug = os.environ.get("MARVIS_ADMIN_SLUG", "").strip() or "admin"

{marvisx_cli-0.2.3 → marvisx_cli-0.3.6}/core/api/main.py

@@ -1,7 +1,7 @@
 # v1.18.0 - 2026-05-22 - P1.5.E1: remove PaddleOCR local (broken warm-up since 30-apr); OCR live via Mac Gateway tier-ocr
 # v1.17.0 - 2026-04-30 - P1.5.E0: add PaddleOCR async warm + /health/ocr backend status
 # v1.16.0 - 2026-04-17 - P2: add slowapi rate limiting middleware for /graph endpoints
-# v1.15.0 - 2026-03-15 - Add push delivery + Voyage init in lifespan + orphan proxy cleanup
+# v1.15.0 - 2026-03-15 - Add push delivery + embedding client init in lifespan + orphan proxy cleanup
 from __future__ import annotations
 
 import asyncio
@@ -986,7 +986,7 @@ async def lifespan(app: FastAPI):
         _pr_impact_gc_task
 
     # Startup
-    logger.info("Starting Console PiR API (env=%s)", settings.pir_env)
+    logger.info("Starting Console Marvis API (env=%s)", settings.pir_env)
     run_migrations()
 
     # Phase 1.5 D14: Phoenix client-side OTel SDK (feature flag — default OFF).
@@ -1109,13 +1109,17 @@ async def lifespan(app: FastAPI):
         _push_delivery_task = asyncio.create_task(_periodic_push_delivery())
         logger.info("Push delivery started (interval=5s)")
 
-    # Voyage AI client for embeddings
-    from core.api.services.embedding_service import init_voyage_client
+    # Embedding backend client (remote backend when present + configured,
+    # else the in-process local engine). The operator kill-switch lives inside
+    # the optional remote backend module, so we ask it rather than config.
+    from core.api.services.embedding_service import init_embedding_client
+    from core.api.services.embedding_backends import load_remote_backend
 
-    if settings.pir_voyage_disabled:
-        logger.info("[canary] skipping Voyage client initialization")
+    _remote = load_remote_backend()
+    if _remote is not None and _remote.is_disabled():
+        logger.info("[canary] skipping remote embedding client initialization")
     else:
-        init_voyage_client()
+        init_embedding_client()
 
     # Monitoring collectors
     await metrics_collector.start()
@@ -1266,7 +1270,7 @@ async def lifespan(app: FastAPI):
 from core.api.rate_limit import limiter  # noqa: E402
 
 app = FastAPI(
-    title="Console PiR API",
+    title="Console Marvis API",
     version="1.0.0",
     docs_url="/docs" if settings.expose_openapi else None,
     redoc_url="/redoc" if settings.expose_openapi else None,
@@ -1477,7 +1481,7 @@ async def _resolve_ws_user(ws: WebSocket):
                 )
         return None
 
-    # 2. Cookie (Console PiR web)
+    # 2. Cookie (Console Marvis web)
     cookie_token = ws.cookies.get("pir_session")
     if not cookie_token:
         return None

{marvisx_cli-0.2.3 → marvisx_cli-0.3.6}/core/api/mcp/_adapter.py

@@ -70,7 +70,7 @@ LOCAL_CTX: CallerContext = CallerContext.local_single_user()
 #                           on the running tool loop — no Node, no HTTP, no fork. The
 #                           use_case calls this sync seam un-awaited (side effect),
 #                           so it schedules a background task and returns immediately;
-#                           the embed (incl. the slow model/Voyage call) runs OUTSIDE
+#                           the embed (incl. the slow model/remote backend call) runs OUTSIDE
 #                           any write lock, then writes via the single-writer pool.
 #                           No-ops gracefully when the embedder is unavailable.
 #   * mcp_requires_pr_gate -> returns False locally. The completed-PR gate (code/
@@ -136,6 +136,75 @@ def mcp_schedule_embed(
     t.add_done_callback(_bg_embed_tasks.discard)
 
 
+# Background set for the remote-backend fire-and-forget learning embeds (the local
+# backend awaits inline instead — see below). Same GC-prevention pattern as
+# ``_bg_embed_tasks``.
+_bg_embed_learnings: set[asyncio.Task] = set()
+
+
+async def mcp_embed_learning(
+    *,
+    learning_id: str,
+    title: str,
+    description: str,
+    category: str,
+    severity: str,
+    prevention: str | None = None,
+    project: str | None = None,
+    workspace_id: str,
+) -> None:
+    """Backend-aware embed-on-write for learnings on the local MCP surface.
+
+    The learning analogue of ``mcp_schedule_embed``, but ASYNC + backend-aware: the
+    product decision is "embed synchronously on write", and a local Granite embed
+    (sub-second) can honor it — it is awaited inline so the just-created learning is
+    immediately retrievable by meaning, not just by keyword. A rate-limited remote
+    backend (remote, 3 RPM) must not block the create -> fire-and-forget instead.
+    Either way the SHARED fastapi-free body (``embedding_service.embed_learning_document``)
+    runs the embed OUTSIDE the write lock. The caller (the ``create_learning`` tool)
+    invokes this AFTER its ``acquire_write_db`` block has released the writer lock, so
+    the inline await cannot deadlock the non-reentrant single-writer lock (learning
+    f83f5209). No-ops when the embedder is unavailable.
+    """
+    from core.api.services import embedding_service
+
+    if not embedding_service.is_available():
+        return
+
+    async def _embed() -> None:
+        try:
+            await embedding_service.embed_learning_document(
+                learning_id=learning_id,
+                title=title,
+                description=description,
+                category=category,
+                severity=severity,
+                prevention=prevention,
+                project=project,
+                workspace_id=workspace_id,
+            )
+        except Exception:
+            logger.debug(
+                "MCP auto-embed learning %s failed (non-critical)",
+                learning_id,
+                exc_info=True,
+            )
+
+    if embedding_service.embedding_is_synchronous():
+        # Local Granite: await inline -> synchronous, immediately retrievable.
+        await _embed()
+        return
+
+    # Remote / rate-limited backend: fire-and-forget so the create never blocks.
+    try:
+        t = asyncio.create_task(_embed())
+    except RuntimeError:
+        logger.debug("MCP auto-embed learning skipped: no running event loop")
+        return
+    _bg_embed_learnings.add(t)
+    t.add_done_callback(_bg_embed_learnings.discard)
+
+
 def mcp_requires_pr_gate(_project: str | None) -> bool:
     """Local PR-gate seam: governance gate collapses in single-user OSS (S1 §AUTH)."""
     return False

{marvisx_cli-0.2.3 → marvisx_cli-0.3.6}/core/api/mcp/server.py

@@ -1,7 +1,7 @@
 # v1.0.0 - 2026-05-27 - S1 F3.0: Python MCP server skeleton (FastMCP, stdio, use_cases-direct)
 """Python MCP server — the payoff of the S1 "collapse runtime" refactor.
 
-A single ``FastMCP("pir")`` instance exposes the PiR tools, each calling the
+A single ``FastMCP("marvis")`` instance exposes the Marvis tools, each calling the
 ``use_cases`` layer DIRECTLY (no Node, no HTTP, no uvicorn). Claude Code launches
 this as a stdio subprocess exactly as it does the Node ``index.mjs`` today:
 
@@ -34,7 +34,7 @@ from core.api.mcp.tools import register_all
 # `app.state` equivalent for a server with no FastAPI `app`). Tools register on
 # this at import time so `from core.api.mcp.server import mcp` already carries the
 # full tool set — the smoke test introspects it without launching stdio.
-mcp = FastMCP("pir")
+mcp = FastMCP("marvis")
 
 register_all(mcp)
 

{marvisx_cli-0.2.3 → marvisx_cli-0.3.6}/core/api/mcp/tools/__init__.py

@@ -35,6 +35,7 @@ from . import (
     safety,
     search,
     tasks,
+    workflows,
 )
 
 #: Ordered registration callables. ``server.py`` iterates this so adding a new
@@ -50,6 +51,7 @@ REGISTRARS = (
     ingest.register,
     pull_requests.register,
     safety.register,
+    workflows.register,
 )
 
 

{marvisx_cli-0.2.3 → marvisx_cli-0.3.6}/core/api/mcp/tools/brain.py

@@ -391,7 +391,7 @@ def register(mcp) -> None:
     ) -> dict[str, Any]:
         """Get apply GUIDANCE for an approved memory operation (NO write — sub-03 §11.1).
 
-        QUANDO USARLO: dopo aver `approved` un'operazione (via brain_memory_operations_patch), per ottenere `next_action.tool` (es. mcp__pir__create_task) + args + `must_include_in_tags` (es. `brain_memory_op:abc123`). L'apply NON scrive l'artifact — ritorna istruzioni. L'agente esegue il `next_action.tool` con i tag richiesti per stabilire la chain di audit.
+        QUANDO USARLO: dopo aver `approved` un'operazione (via brain_memory_operations_patch), per ottenere `next_action.tool` (es. mcp__marvis__create_task) + args + `must_include_in_tags` (es. `brain_memory_op:abc123`). L'apply NON scrive l'artifact — ritorna istruzioni. L'agente esegue il `next_action.tool` con i tag richiesti per stabilire la chain di audit.
         QUANDO NON USARLO: per scrivere direttamente l'artifact — questo endpoint ritorna SOLO guidance. Pattern: PATCH → apply (guidance) → call next_action.tool con must_include_in_tags. Non usarlo prima di approval_state='approved' (409 precondition).
         RESTITUISCE: {operation_id, next_action:{tool, args, must_include_in_tags}, operation_summary}."""
         # GUIDANCE-only: the use_case calls get_apply_guidance (READ-only precondition
@@ -535,8 +535,8 @@ def register(mcp) -> None:
     ) -> dict[str, Any]:
         """Get apply GUIDANCE for an approved finding (NO write — sub-04 F1).
 
-        QUANDO USARLO: dopo aver `approved` una finding, per ottenere `next_action.tool` (es. mcp__pir__create_task con title/description/tags pre-compilato) + `must_include_in_tags=brain_finding:{id}` per audit chain. L'apply NON scrive l'artifact — ritorna istruzioni. L'agente esegue il next_action.tool con i tag richiesti.
-        QUANDO NON USARLO: per scrivere artifact direttamente — pattern e' GUIDANCE-only. Non usarlo prima di approval_state='approved' (409). Non chiamarlo in loop 'ricomputa finche' la finding X appare': se non emerge, e' un problema del producer rule — file un learning via mcp__pir__create_learning.
+        QUANDO USARLO: dopo aver `approved` una finding, per ottenere `next_action.tool` (es. mcp__marvis__create_task con title/description/tags pre-compilato) + `must_include_in_tags=brain_finding:{id}` per audit chain. L'apply NON scrive l'artifact — ritorna istruzioni. L'agente esegue il next_action.tool con i tag richiesti.
+        QUANDO NON USARLO: per scrivere artifact direttamente — pattern e' GUIDANCE-only. Non usarlo prima di approval_state='approved' (409). Non chiamarlo in loop 'ricomputa finche' la finding X appare': se non emerge, e' un problema del producer rule — file un learning via mcp__marvis__create_learning.
         RESTITUISCE: {operation_id (=finding_id), next_action:{tool, args, must_include_in_tags}, operation_summary}."""
         # GUIDANCE-only: the use_case calls get_apply_guidance (READ-only precondition
         # + next-action envelope). No write transaction, no mutation — preserved.
@@ -588,7 +588,7 @@ def register(mcp) -> None:
     async def brain_capabilities() -> dict[str, Any]:
         """Discover Brain schema metadata (enums + glyphs + node kinds) — sub-05 OD-11.
 
-        QUANDO USARLO: cold-start dell'agente — leggere i Literal enum esposti dal Brain (event_types, signal_types, knowledge_forms, operation_types, finding_types, severities, confidence_tiers, drift_axes, approval_states, signal_states, run_statuses, closure_condition_kinds, knowledge_glyphs). Pattern equivalente di mcp__pir__graph_capabilities. Evita hardcoding constants. Schema_version aumenta quando i Literal cambiano.
+        QUANDO USARLO: cold-start dell'agente — leggere i Literal enum esposti dal Brain (event_types, signal_types, knowledge_forms, operation_types, finding_types, severities, confidence_tiers, drift_axes, approval_states, signal_states, run_statuses, closure_condition_kinds, knowledge_glyphs). Pattern equivalente di mcp__marvis__graph_capabilities. Evita hardcoding constants. Schema_version aumenta quando i Literal cambiano.
         QUANDO NON USARLO: per dati live del ciclo — usa brain_runs/brain_events/etc. Non e' un health check.
         RESTITUISCE: {schema_version, event_types[], source_systems[], signal_types[], knowledge_forms[], operation_types[], finding_types[], severities[], confidence_tiers[], drift_axes[], approval_states[], finding_approval_states[], signal_states[], run_statuses[], run_triggers[], scope_types[], suggested_artifacts[], closure_condition_kinds[], knowledge_glyphs:{form: glyph}}."""
         # Deterministic; no DB. The use_case takes only ctx.

{marvisx_cli-0.2.3 → marvisx_cli-0.3.6}/core/api/mcp/tools/learnings.py

@@ -22,7 +22,14 @@ from typing import Annotated, Any, Literal
 
 from pydantic import Field
 
-from core.api.mcp._adapter import LOCAL_CTX, acquire_db, acquire_write_db, dump, raise_mcp_error
+from core.api.mcp._adapter import (
+    LOCAL_CTX,
+    acquire_db,
+    acquire_write_db,
+    dump,
+    mcp_embed_learning,
+    raise_mcp_error,
+)
 from core.api.use_cases import learnings as learnings_uc
 from core.api.use_cases._errors import ServiceError
 
@@ -85,7 +92,73 @@ def register(mcp) -> None:
                     tags=tags,
                     project=project,
                 )
-                return dump(result)
+            # Writer lock released: embed-on-write. On a local Granite backend this
+            # awaits inline (synchronous) so the learning is immediately retrievable by
+            # meaning — not just by keyword until a manual reindex (the bug this fixes).
+            await mcp_embed_learning(
+                learning_id=result.id,
+                title=result.title,
+                description=result.description,
+                category=result.category,
+                severity=result.severity,
+                prevention=result.prevention,
+                project=result.project,
+                workspace_id=LOCAL_CTX.workspace_id,
+            )
+            return dump(result)
+        except ServiceError as e:
+            raise_mcp_error(e)
+
+    @mcp.tool()
+    async def update_learning(
+        learning_id: Annotated[str, Field(min_length=1)],
+        title: Annotated[str, Field(min_length=1, max_length=200)] | None = None,
+        category: LearningCategory | None = None,
+        description: Annotated[str, Field(min_length=1)] | None = None,
+        prevention: Annotated[str, Field(min_length=1)] | None = None,
+        severity: LearningSeverity | None = None,
+        module: str | None = None,
+        tags: list[str] | None = None,
+        project: str | None = None,
+    ) -> dict[str, Any]:
+        """Update an existing learning (operator+), then re-embed it so search/check_learnings see the new content immediately.
+
+        QUANDO USARLO: il contenuto di un learning e' obsoleto/incompleto (prevention piu' precisa, severity ricalibrata, nuovo modulo) ma vuoi PRESERVARE la history. BOUNDARY: update_learning aggiorna in-place + re-embed; delete_learning cancella permanente; create_learning scrive nuovo.
+        QUANDO NON USARLO: NOT per un learning nuovo -> usa create_learning. NOT per azzerare un campo a null: la superficie MCP NON puo' settare null (omettere un campo lo lascia invariato) -> usa l'HTTP PATCH se devi pulire un campo.
+        RESTITUISCE: il learning aggiornato {id, title, category, severity, prevention, tags, module, project, updated_at} — gia' ri-embeddato (retrievable by meaning, non solo keyword)."""
+        fields = {
+            k: v
+            for k, v in {
+                "title": title,
+                "category": category,
+                "description": description,
+                "prevention": prevention,
+                "severity": severity,
+                "module": module,
+                "tags": tags,
+                "project": project,
+            }.items()
+            if v is not None
+        }
+        try:
+            async with acquire_write_db(label="mcp.update_learning") as db:
+                result = await learnings_uc.update_learning(
+                    LOCAL_CTX, db, learning_id=learning_id, fields=fields
+                )
+            # Writer lock released: re-embed-on-write (mirror create_learning) so the
+            # updated content is retrievable by meaning immediately, not stale until
+            # a manual reindex.
+            await mcp_embed_learning(
+                learning_id=result.id,
+                title=result.title,
+                description=result.description,
+                category=result.category,
+                severity=result.severity,
+                prevention=result.prevention,
+                project=result.project,
+                workspace_id=LOCAL_CTX.workspace_id,
+            )
+            return dump(result)
         except ServiceError as e:
             raise_mcp_error(e)
 
@@ -142,3 +215,21 @@ def register(mcp) -> None:
                 return dump(result)
         except ServiceError as e:
             raise_mcp_error(e)
+
+    @mcp.tool()
+    async def delete_learning(
+        learning_id: Annotated[str, Field(min_length=1)],
+    ) -> dict[str, Any]:
+        """Permanently remove a learning from the Marvis DB (non-recoverable) + prune the search index.
+
+        QUANDO USARLO: solo per learning duplicati, spam, o entry chiaramente invalide. Hard delete: rimuove anche il mirror nell'indice di ricerca (documents + vec_documents + FTS) cosi' il learning smette di comparire in search/check_learnings.
+        QUANDO NON USARLO: NOT per archiviare un learning ancora valido — la cancellazione e' permanente e perde la history. Aggiornalo con update_learning se il contenuto e' obsoleto.
+        RESTITUISCE: {deleted: true} o 404 se non esiste."""
+        try:
+            async with acquire_write_db(label="mcp.delete_learning") as db:
+                await learnings_uc.delete_learning(
+                    LOCAL_CTX, db, learning_id=learning_id
+                )
+                return {"deleted": True}
+        except ServiceError as e:
+            raise_mcp_error(e)

{marvisx_cli-0.2.3 → marvisx_cli-0.3.6}/core/api/mcp/tools/projects.py

@@ -39,7 +39,7 @@ def register(mcp) -> None:
 
     @mcp.tool()
     async def list_projects() -> list[dict[str, Any]]:
-        """List all PiR-tracked projects grouped by program.
+        """List all Marvis-tracked projects grouped by program.
 
         QUANDO USARLO: serve un inventario (quali progetti ci sono, dammi tutti gli slug) o non conosci lo slug target.
         QUANDO NON USARLO: NOT quando hai gia' uno slug specifico e vuoi i dettagli -> usa get_project. NOT per cold-start di un progetto -> usa session_brief.