npm - @rubytech/create-realagent - Versions diffs - 1.0.709 → 1.0.712 - Mend

@rubytech/create-realagent 1.0.709 → 1.0.712

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 (41) hide show

package/payload/platform/scripts/verify-skill-tool-surface.sh ADDED Viewed

@@ -0,0 +1,255 @@
+#!/usr/bin/env bash
+# Pre-publish acceptance gate (Task 744).
+#
+# Statically intersects what each shipped skill *prescribes* (every
+# backtick-quoted `mcp__<server>__<tool>` token in SKILL.md and references/*.md)
+# against the dispatched specialist's frontmatter `tools:` list. Catches the
+# class of bug where a skill prescribes a tool the specialist does not have,
+# and where a skill prescribes a forbidden direct-execution path
+# (`cypher-shell`, `neo4j-admin` invocations, raw-Cypher DML in prose).
+#
+# Wired into the root `packages/create-maxy/package.json` `prepublishOnly`
+# script so a regression cannot reach npm publish without firing.
+#
+# One stdout line per (skill, specialist) pair:
+#   [verify] skill=<plugin>/<skill> specialist=<n> resolved=<n>/<m> forbidden=<n>
+#
+# Exit 0: every prescribed token resolves AND no forbidden tokens.
+# Exit 1: any unresolved or any forbidden — stderr names the offending token.
+#
+# Skill→specialist mapping comes from PLUGIN.md frontmatter `specialist:` field.
+# Plugins without that field are admin-owned (loaded by the admin agent
+# directly via plugin-read); for those the gate only enforces the forbidden-
+# token rule, since admin's tool surface is the union of all enabled plugins.
+set -euo pipefail
+REPO_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
+cd "$REPO_ROOT"
+python3 - <<'PYEOF'
+import os, re, sys
+REPO_ROOT = os.getcwd()
+PLUGINS_DIR = os.path.join(REPO_ROOT, "platform", "plugins")
+SPECIALISTS_DIR = os.path.join(REPO_ROOT, "platform", "templates", "specialists", "agents")
+# Per-skill specialist ownership for plugins where the plugin itself is
+# multi-purpose. The PLUGIN.md `specialist:` field handles single-owner
+# plugins (linkedin-import → database-operator). Mixed-use plugins like
+# `memory` declare per-skill ownership here.
+EXPLICIT_OWNERSHIP = {
+    # plugin/skill -> specialist
+    "memory/document-ingest": "database-operator",
+}
+# Skills that are explicitly admin-owned (loaded via plugin-read by the admin
+# agent itself, not delegated to a specialist). These get only the forbidden-
+# token check since admin's effective tool set is the union of all enabled
+# plugins.
+ADMIN_OWNED_SKILLS = {
+    "memory/conversational-memory",
+}
+TOKEN_RE = re.compile(r"`(mcp__[a-z][a-z0-9_-]*__[a-z][a-z0-9_-]*)`")
+FENCED_BLOCK_RE = re.compile(r"```(?P<lang>[a-zA-Z]*)\n(?P<body>.*?)\n```", re.S)
+PROSE_CYPHER_RE = re.compile(
+    r"`(?:MERGE|CREATE|DETACH\s+DELETE)\s+\(",
+    re.IGNORECASE,
+)
+def parse_frontmatter(path: str) -> dict | None:
+    """Parse YAML-ish frontmatter without PyYAML — handles `key: value` and
+    `key:\n  - item\n  - item` shapes used in PLUGIN.md and specialist files."""
+    try:
+        text = open(path, encoding="utf-8").read()
+    except FileNotFoundError:
+        return None
+    m = re.match(r"^---\n(.*?)\n---", text, re.S)
+    if not m:
+        return None
+    block = m.group(1)
+    out: dict = {}
+    cur_key: str | None = None
+    cur_list: list[str] | None = None
+    for line in block.split("\n"):
+        if not line.strip():
+            continue
+        # List item under cur_key
+        if line.startswith("  - ") or line.startswith("- "):
+            if cur_list is None:
+                continue
+            cur_list.append(line.split("- ", 1)[1].strip())
+            continue
+        # Top-level key
+        m2 = re.match(r"^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$", line)
+        if not m2:
+            continue
+        cur_key = m2.group(1)
+        rhs = m2.group(2).strip()
+        if rhs:
+            # inline value — strip surrounding quotes
+            if (rhs.startswith('"') and rhs.endswith('"')) or (
+                rhs.startswith("'") and rhs.endswith("'")
+            ):
+                rhs = rhs[1:-1]
+            out[cur_key] = rhs
+            cur_list = None
+        else:
+            cur_list = []
+            out[cur_key] = cur_list
+    return out
+def specialist_tools(specialist: str) -> set[str] | None:
+    fm = parse_frontmatter(os.path.join(SPECIALISTS_DIR, f"{specialist}.md"))
+    if fm is None:
+        return None
+    raw = fm.get("tools", "")
+    if isinstance(raw, list):
+        items = raw
+    else:
+        items = [t.strip() for t in str(raw).split(",")]
+    return {t for t in items if t}
+def extract_prescribed_tokens(text: str) -> set[str]:
+    return set(TOKEN_RE.findall(text))
+def extract_forbidden(text: str) -> list[tuple[str, str]]:
+    forbidden: list[tuple[str, str]] = []
+    # Forbidden invocations inside fenced shell blocks
+    for m in FENCED_BLOCK_RE.finditer(text):
+        lang = m.group("lang").lower()
+        body = m.group("body")
+        if lang in {"bash", "sh", "shell", "zsh"}:
+            if re.search(r"\bcypher-shell\b", body):
+                forbidden.append(("cypher-shell", "in fenced shell block"))
+            if re.search(r"\bneo4j-admin\s+dbms\b", body):
+                forbidden.append(("neo4j-admin", "in fenced shell block"))
+    # Strip fenced blocks for the prose-Cypher heuristic
+    prose = FENCED_BLOCK_RE.sub("", text)
+    if PROSE_CYPHER_RE.search(prose):
+        forbidden.append(("raw-cypher-dml", "in backtick-quoted prose"))
+    return forbidden
+def aggregate_skill_text(skill_dir: str) -> str:
+    out: list[str] = []
+    skill_md = os.path.join(skill_dir, "SKILL.md")
+    if not os.path.exists(skill_md):
+        return ""
+    out.append(open(skill_md, encoding="utf-8").read())
+    refs = os.path.join(skill_dir, "references")
+    if os.path.isdir(refs):
+        for name in sorted(os.listdir(refs)):
+            if name.endswith(".md"):
+                out.append(open(os.path.join(refs, name), encoding="utf-8").read())
+    return "\n".join(out)
+def main() -> int:
+    if not os.path.isdir(PLUGINS_DIR):
+        print(f"[verify] PLUGINS_DIR not found: {PLUGINS_DIR}", file=sys.stderr)
+        return 1
+    if not os.path.isdir(SPECIALISTS_DIR):
+        print(f"[verify] SPECIALISTS_DIR not found: {SPECIALISTS_DIR}", file=sys.stderr)
+        return 1
+    summary: list[str] = []
+    errors: list[str] = []
+    pairs_checked = 0
+    for plugin in sorted(os.listdir(PLUGINS_DIR)):
+        pdir = os.path.join(PLUGINS_DIR, plugin)
+        if not os.path.isdir(pdir):
+            continue
+        plugin_fm = parse_frontmatter(os.path.join(pdir, "PLUGIN.md")) or {}
+        plugin_specialist = plugin_fm.get("specialist")
+        skills_dir = os.path.join(pdir, "skills")
+        if not os.path.isdir(skills_dir):
+            continue
+        for skill_name in sorted(os.listdir(skills_dir)):
+            sdir = os.path.join(skills_dir, skill_name)
+            if not os.path.isdir(sdir):
+                continue
+            text = aggregate_skill_text(sdir)
+            if not text:
+                continue
+            prescribed = extract_prescribed_tokens(text)
+            forbidden = extract_forbidden(text)
+            ownership_key = f"{plugin}/{skill_name}"
+            if ownership_key in ADMIN_OWNED_SKILLS:
+                specialist = None
+            else:
+                specialist = (
+                    EXPLICIT_OWNERSHIP.get(ownership_key)
+                    or plugin_specialist
+                )
+            if specialist is None:
+                # Admin-owned: only enforce forbidden-token rule.
+                for tok, ctx in forbidden:
+                    errors.append(
+                        f"[verify] skill={ownership_key} specialist=admin "
+                        f"FORBIDDEN token={tok} context=\"{ctx}\""
+                    )
+                summary.append(
+                    f"[verify] skill={ownership_key} specialist=admin (admin-owned) "
+                    f"tokens={len(prescribed)} forbidden={len(forbidden)}"
+                )
+                continue
+            tools = specialist_tools(specialist)
+            if tools is None:
+                errors.append(
+                    f"[verify] skill={ownership_key} specialist={specialist} "
+                    f"ERROR specialist frontmatter not parseable"
+                )
+                continue
+            unresolved = sorted(prescribed - tools)
+            for tok in unresolved:
+                errors.append(
+                    f"[verify] skill={ownership_key} specialist={specialist} "
+                    f"unresolved={tok}"
+                )
+            for tok, ctx in forbidden:
+                errors.append(
+                    f"[verify] skill={ownership_key} specialist={specialist} "
+                    f"FORBIDDEN token={tok} context=\"{ctx}\""
+                )
+            summary.append(
+                f"[verify] skill={ownership_key} specialist={specialist} "
+                f"resolved={len(prescribed) - len(unresolved)}/{len(prescribed)} "
+                f"forbidden={len(forbidden)}"
+            )
+            pairs_checked += 1
+    for line in summary:
+        print(line)
+    if errors:
+        for line in errors:
+            print(line, file=sys.stderr)
+        print(
+            f"[verify] FAIL pairs_checked={pairs_checked} errors={len(errors)}",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"[verify] OK pairs_checked={pairs_checked}")
+    return 0
+sys.exit(main())
+PYEOF

package/payload/platform/templates/specialists/agents/database-operator.md CHANGED Viewed

@@ -3,7 +3,7 @@ name: database-operator
 description: "Document and archive ingestion and ad-hoc graph operations — running the universal `document-ingest` skill for any unstructured document (PDF, text, transcript, web page, audio, video) and per-source archive-import skills (LinkedIn Basic Data Export today; CRM-type seed archives as each plugin ships), plus operator-driven graph hygiene (prune orphans, deduplicate entities, add edges, normalise labels). Delegate when the operator uploads any document, drops an archive directory into chat, or asks for any graph operation that is not a routine per-turn write."
 summary: "Ingests every unstructured document and external archive into your graph (LinkedIn today; other CRM sources in future) and handles ad-hoc graph tidy-ups on request. For example, when you upload a CV, a pricing guide, or a contract; when you drop a LinkedIn export folder into chat; or when you ask to prune orphan nodes, merge duplicate people, or add edges between entities."
 model: claude-sonnet-4-6
-tools: Read, Bash, Glob, Grep, mcp__graph__maxy-graph-read_neo4j_cypher, mcp__graph__maxy-graph-get_neo4j_schema, mcp__memory__memory-write, mcp__memory__memory-update, mcp__memory__memory-delete, mcp__memory__memory-search, mcp__memory__memory-rank, mcp__memory__memory-reindex, mcp__memory__memory-find-candidates, mcp__memory__memory-ingest, mcp__memory__memory-ingest-extract, mcp__memory__memory-ingest-web, mcp__memory__memory-classify, mcp__memory__graph-prune-denylist-list, mcp__memory__graph-prune-denylist-add, mcp__memory__graph-prune-denylist-remove, mcp__contacts__contact-create, mcp__contacts__contact-update, mcp__contacts__contact-lookup, mcp__contacts__contact-list, mcp__admin__file-attach, mcp__admin__plugin-read
+tools: Read, Bash, Glob, Grep, mcp__graph__maxy-graph-read_neo4j_cypher, mcp__graph__maxy-graph-get_neo4j_schema, mcp__memory__memory-write, mcp__memory__memory-update, mcp__memory__memory-delete, mcp__memory__memory-search, mcp__memory__memory-rank, mcp__memory__memory-reindex, mcp__memory__memory-find-candidates, mcp__memory__memory-ingest, mcp__memory__memory-ingest-extract, mcp__memory__memory-ingest-web, mcp__memory__memory-classify, mcp__memory__memory-archive-write, mcp__memory__graph-prune-denylist-list, mcp__memory__graph-prune-denylist-add, mcp__memory__graph-prune-denylist-remove, mcp__contacts__contact-create, mcp__contacts__contact-update, mcp__contacts__contact-lookup, mcp__contacts__contact-list, mcp__admin__file-attach, mcp__admin__plugin-read
 ---
 # Database Operator
@@ -12,7 +12,7 @@ You own document and archive ingestion and ad-hoc graph operations. You receive
 ## Prerogatives
-Three rules govern every turn. They are load-bearing — when they conflict with anything else in this prompt, they win.
+Four rules govern every turn. They are load-bearing — when they conflict with anything else in this prompt, they win.
 **PRECISE.** Use exact names: exact tool names, exact field values, exact file paths, exact node properties. When relaying a tool result, relay what the tool returned — do not paraphrase, do not approximate, do not invent flags. When uncertain about an exact value, look it up; never substitute a loose-but-plausible string. *Failure symptoms:* paraphrasing tool output, approximate tool name, inventing a flag.
@@ -26,6 +26,10 @@ Three rules govern every turn. They are load-bearing — when they conflict with
 A landfill graph defeats EVIDENCE-BASED: search returns noise, the agent re-writes the noise, the noise compounds. Compress on write; filter on read.
+**LOUD-FAIL.** If a dispatched skill prescribes a tool not present in your live tool surface, or a credential not provided in your tool input, terminate with a structured blocker — never improvise via Bash, never search the filesystem for credentials, never construct a parallel write path. Return: `Skill <name> prescribes <tool/credential>; not available. Cannot proceed. Operator must <remediation>.` Identical doctrine to Task 740 classifier failure and Task 560 graph-MCP loud-fail. *Failure symptoms:* `cypher-shell` invocation, `find … neo4j` / `grep … NEO4J_PASSWORD` filesystem probes, `curl` against Neo4j HTTP endpoints, any Bash improvisation that recreates the missing tool's effect.
+The pre-publish gate (`platform/scripts/verify-skill-tool-surface.sh`) statically asserts every shipped skill's prescribed `mcp__*` tokens resolve against your frontmatter `tools:` list, so a missing tool is a build error, not a production discovery. LOUD-FAIL is the runtime backstop when that gate is bypassed (e.g. operator-edited skill).
 ---
 ## Output contract