@rubytech/create-maxy-code 0.1.280 → 0.1.282

package/payload/platform/plugins/admin/hooks/prompt-optimiser-compliance.sh

@@ -0,0 +1,174 @@
+#!/usr/bin/env bash
+# Stop hook (Task 719): after the admin agent finishes a turn, flag the turn when
+# the per-turn routing directive fired, the turn was non-trivial, and NO route was
+# taken — i.e. the agent answered from memory instead of dispatching a specialist,
+# loading a skill, or calling the owning plugin's tool. This is the standing
+# compliance signal the directive hook (prompt-optimiser-directive.sh) cannot
+# self-emit, because "was a route taken" is only knowable after the turn ends.
+#
+# Classification (all derived from the just-finished turn in the transcript):
+#   directive fired = the marker "PROMPT-OPTIMISER DIRECTIVE" appears in the turn
+#                     slice (robust to CC-version differences in how the
+#                     UserPromptSubmit additionalContext is recorded: a
+#                     type:"attachment"/hook_success on 2.1.x, a
+#                     type:"hook_additional_context" on the Pi).
+#   route taken     = the turn contains a tool_use named Agent, Skill, ToolSearch,
+#                     or matching mcp__*.
+#   trivial         = the prompt is a slash-command or a one-word confirmation.
+# "Direct continuation" is NOT detectable from the transcript and is a stated
+# known limitation, not guessed.
+#
+# Emits, only on (directive fired AND not trivial AND no route):
+#   <ts> [prompt-optimiser-compliance] directive-fired no-route-taken session=<id8> prompt="<clip>"
+# to $LOG_DIR/prompt-optimiser-directive.log (same log as the fired breadcrumb,
+# so the two interleave into one greppable timeline) and to stderr.
+#
+# Input (stdin, Stop contract): { "transcript_path": "...", "session_id": "...", ... }
+# Fail-open everywhere: no python3, no transcript_path, unreadable transcript, or
+# any parse error -> exit 0 with no output. A Stop hook must never block a turn.
+
+set -uo pipefail
+
+INPUT=$(cat 2>/dev/null || true)
+command -v python3 >/dev/null 2>&1 || exit 0
+
+RESULT=$(printf '%s' "$INPUT" | python3 -c '
+import json, sys, os, datetime
+
+def fail_open():
+    sys.exit(0)
+
+try:
+    inp = json.load(sys.stdin)
+except Exception:
+    fail_open()
+
+tp = inp.get("transcript_path")
+session = inp.get("session_id") or "?"
+if not isinstance(tp, str) or not tp or not os.path.exists(tp):
+    fail_open()
+
+rows = []
+try:
+    with open(tp, "r", errors="replace") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rows.append(json.loads(line))
+            except Exception:
+                continue
+except OSError:
+    fail_open()
+
+# Flatten a message.content into plain text; mark whether it is purely tool_result
+# (a tool output row, not a user prompt).
+def flatten(content):
+    if isinstance(content, str):
+        return content, False
+    if isinstance(content, list):
+        only_tool_result = bool(content)
+        parts = []
+        for b in content:
+            if not isinstance(b, dict):
+                only_tool_result = False
+                if isinstance(b, str):
+                    parts.append(b)
+                continue
+            t = b.get("type")
+            if t != "tool_result":
+                only_tool_result = False
+            if t == "text" and isinstance(b.get("text"), str):
+                parts.append(b["text"])
+        return " ".join(parts), only_tool_result
+    return "", False
+
+# A row is synthetic (not a genuine prompt) when Claude Code stamps it isMeta /
+# isSidechain / etc. Claude Code injects such user rows AFTER the real prompt
+# within the same turn — skill bodies, system-reminders, additionalContext
+# echoes — so a naive "last text-bearing user row" would land on the injection,
+# truncate the slice, and read the injected body as the prompt.
+def is_synthetic(r):
+    return any(r.get(k) for k in ("isMeta", "isSidechain", "isCompactSummary", "isVisibleInTranscriptOnly"))
+
+# Boundary: the last user row that carries a genuine prompt. A genuine prompt is
+# either a non-synthetic user turn (typed claude.ai) OR a synthetic turn whose
+# text is channel-wrapped — WhatsApp/native channels stamp the inbound prompt
+# isMeta:true and wrap it in <channel ...>, and that inbound IS the prompt. Every
+# other synthetic row (skill body, system-reminder) is skipped. The turn slice is
+# everything from the boundary to EOF.
+boundary = None
+prompt_text = ""
+for i, r in enumerate(rows):
+    if not isinstance(r, dict) or r.get("type") != "user":
+        continue
+    msg = r.get("message") if isinstance(r.get("message"), dict) else {}
+    text, only_tool_result = flatten(msg.get("content"))
+    if only_tool_result:
+        continue
+    stripped = text.strip()
+    if not stripped:
+        continue
+    if is_synthetic(r) and not stripped.startswith("<channel"):
+        continue
+    boundary = i
+    prompt_text = stripped
+
+if boundary is None:
+    fail_open()
+
+slice_rows = rows[boundary:]
+
+# Strip a leading <channel ...>...</channel> wrapper to reach the inner prompt for
+# the trivial check (WhatsApp/native-channel prompts arrive wrapped).
+inner = prompt_text
+if inner.startswith("<channel"):
+    end = inner.find(">")
+    close = inner.rfind("</channel>")
+    if end != -1 and close != -1 and close > end:
+        inner = inner[end + 1:close].strip()
+
+# Trivial-turn filter.
+is_slash = inner.startswith("/")
+tokens = inner.split()
+is_one_word = len(tokens) <= 1
+
+# Directive fired = marker present anywhere in the slice (any record shape).
+marker = "PROMPT-OPTIMISER DIRECTIVE"
+directive_fired = any(marker in json.dumps(r, ensure_ascii=False) for r in slice_rows)
+
+# Route taken = an assistant tool_use with a routing tool name.
+ROUTE_TOOLS = ("Agent", "Skill", "ToolSearch")
+def is_route(name):
+    return name in ROUTE_TOOLS or (isinstance(name, str) and name.startswith("mcp__"))
+
+route_taken = False
+for r in slice_rows:
+    if not isinstance(r, dict) or r.get("type") != "assistant":
+        continue
+    msg = r.get("message") if isinstance(r.get("message"), dict) else {}
+    content = msg.get("content")
+    if isinstance(content, list):
+        for b in content:
+            if isinstance(b, dict) and b.get("type") == "tool_use" and is_route(b.get("name")):
+                route_taken = True
+                break
+    if route_taken:
+        break
+
+if directive_fired and not is_slash and not is_one_word and not route_taken:
+    clip = prompt_text.replace("\n", " ")[:80]
+    ts = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    sid8 = session[:8] if isinstance(session, str) else "?"
+    print("%s [prompt-optimiser-compliance] directive-fired no-route-taken session=%s prompt=\"%s\"" % (ts, sid8, clip))
+' 2>/dev/null) || exit 0
+
+[ -n "$RESULT" ] || exit 0
+
+# Durable + stderr. Fail-open on an unwritable/absent LOG_DIR.
+if [ -n "${LOG_DIR:-}" ] && [ -d "$LOG_DIR" ]; then
+  printf '%s\n' "$RESULT" >> "$LOG_DIR/prompt-optimiser-directive.log" 2>/dev/null || true
+fi
+printf '%s\n' "$RESULT" >&2
+exit 0

package/payload/platform/plugins/admin/hooks/prompt-optimiser-directive.sh

@@ -32,8 +32,9 @@
 
 set -uo pipefail
 
-# Drain stdin; the directive does not depend on the prompt text.
-cat >/dev/null 2>&1 || true
+# Capture stdin: the directive does not depend on the prompt text, but the
+# UserPromptSubmit payload carries session_id, used for the durable breadcrumb.
+HOOK_INPUT=$(cat 2>/dev/null || true)
 
 # Fail-open if the JSON encoder is unavailable.
 command -v python3 >/dev/null 2>&1 || exit 0
@@ -65,6 +66,8 @@ PROMPT-OPTIMISER DIRECTIVE (standing)
 Before acting on this turn's request, run the prompt-optimiser skill on the user's raw prompt in its in-session restatement mode, then treat the restated task as the authoritative statement of what was asked and proceed from it. Set aside your own first reading of the raw wording; the restatement governs. The raw prompt stays in context for reference only.
 Skip the restatement when the prompt is a one-word confirmation, a slash-command invocation, or a direct continuation of the immediately preceding turn; restatement adds nothing in those cases.
 
+CAPABILITY QUESTIONS ARE OWNED WORK. A question about what this platform can do or how to do it — "how do I set up X", "do you have instructions for X", any configuration or how-to about a platform feature — is answered from the owning specialist or the owning plugin's tool or reference, never from your training memory. Your prior on the platform's own features is stale relative to what shipped, so memory is the wrong source here even when it feels confident. Route the question (dispatch the owning specialist, or skill-load / call the owning plugin's tool or reference) and source the answer from what that route returns. Freestyle tier 3 is not a route for these: "there is no instruction surface for this" is itself something you establish by routing and finding nothing, not by recalling.
+
 ROUTING LADDER (apply to the restated task, in this order):
 1) Delegate to a specialist. If an installed specialist owns this deliverable's type, dispatch it with the Agent tool and the matching subagent_type. Ownership covers origination, not just the final render: you may not author the substance here and hand the specialist only the formatting, the voice pass, or the PDF step. The brief states the outcome (what is true when the specialist returns) plus the binding constraints (account, file scope, deadline, acceptance check). It never names lines, anchors, or literal text to insert; deriving those is the specialist's job. Wrong shape: naming the file, the line range, and the exact text to drop in. Right shape: "on the realagent-code site, the footer respects iOS safe-area-inset-bottom on mobile; the site's CSS is the only file in scope." Installed specialists:
 DIRECTIVE_EOF
@@ -93,5 +96,22 @@ print(json.dumps({
 
 [ -n "$OUT" ] || exit 0
 printf '%s\n' "$OUT"
+
+# Durable breadcrumb: capture the per-turn injection in $LOG_DIR so "directive
+# fired on this turn" is greppable for compliance review, not only on stderr
+# (Task 719). Fail-open: no LOG_DIR, missing dir, or unwritable -> skip the file;
+# the stderr line below still emits. session_id is parsed from the captured
+# stdin; absent -> "?".
+if [ -n "${LOG_DIR:-}" ] && [ -d "$LOG_DIR" ]; then
+  SID=$(printf '%s' "$HOOK_INPUT" | python3 -c 'import json,sys
+try:
+    print(json.load(sys.stdin).get("session_id","") or "")
+except Exception:
+    print("")' 2>/dev/null)
+  TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  printf '%s [prompt-optimiser-directive] injected len=%s session=%s\n' \
+    "$TS" "${#DIRECTIVE}" "${SID:-?}" >> "$LOG_DIR/prompt-optimiser-directive.log" 2>/dev/null || true
+fi
+
 echo "[prompt-optimiser-directive] injected len=${#DIRECTIVE}" >&2
 exit 0

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:2002a63079af7332d583e86fd68fe798a5736452310f3412e20b99320194b383
+content-hash: sha256:add28451435be577d674216c86cd03078f5b25d03ce6def9fc61962971c8e9ed
 brand: maxy-code
 product-name: Maxy
 ---
@@ -145,6 +145,8 @@ Everything Maxy can do is provided by a plugin. Each plugin is a self-contained
 
 **How tools and roles reach the session.** Each `claude` PTY spawn registers every plugin's MCP server and every bundled subagent directory before the operator's first turn — a per-spawn `mcp-config.json` written by the session manager and passed as `--mcp-config` on the PTY argv, plus one `--add-dir` per agents directory. Admin sessions see every plugin and every role; public sessions see only plugins with at least one public-allowlisted tool. The manager refuses to start when a plugin's `PLUGIN.md` declares tools without a matching `mcp:` block (forensic signal: `boot-failed reason=mcp-allowlist-without-server …`). See `internals.md` "Spawn-time MCP and subagent registration" for the full mechanism and `internals.md` "Tool Eagerness" for the separate ToolSearch-vs-eager registration concern.
 
+**MCP helper death observability (Task 706).** `claude` spawns each plugin MCP helper as its own child, so the manager cannot see a helper die. Every spawn-capable plugin therefore wraps its `mcp:` command with `lib/mcp-spawn-tee`, a parent-side node wrapper that is the helper's real parent and observes its true exit code, signal, and lifetime (including SIGKILL / transport crashes). The wrapper tees the helper's stderr to a wrapper-only per-session file `~/.{brand}/logs/mcp-<server>-<sessionId>.log` — never mixed with the admin-server enumeration copy — and emits lifecycle lines keyed `session=<id8> server=<name>`: `[mcp-helper] op=spawn … pid= entry=`, `[mcp-helper] op=boot … head=<first stderr bytes>`, and `[mcp-helper] op=exit … code= signal= lifetimeMs= stderr-tail=` on every exit (including a clean one). Lines are written synchronously to the per-session file and best-effort mirrored to `server.log` via the loopback log-ingest route. Diagnose a dead helper by `grep '\[mcp-helper\]' ~/.{brand}/logs/server.log` filtered by `session=<id8>`, then read the per-session file for its last output. Full contract and diagnostic path in [`.docs/mcp-helper-observability.md`](../../../.docs/mcp-helper-observability.md). The alive-but-wedged case (no process exit) is the deferred `[mcp-helper-census]` reconciler (Task 710).
+
 **Where premium bundle subs live.** Bundle subs (`loop`, `property-data`, `brochures`, etc. inside `real-agent`) live exclusively at `premium-plugins/<bundle>/plugins/<sub>/` and are registered via the resolver's bundle-descent walk. Standalone premiums (no `BUNDLE.md`, e.g. `writer-craft`, `teaching`, `venture-studio`) live exclusively at `premium-plugins/<name>/` and are registered via the resolver's dual-root scan (`platform/plugins/` and `premium-plugins/` are both `pluginsRoots`). Neither shape is flat-copied into `platform/plugins/<name>/`. A divergent flat copy of a bundle sub is treated as an operator override: the resolver refuses to boot with `boot-failed reason=mcp-plugin-duplicate <plugin> declared by more than one plugins root: <pathA> (sha=…) vs <pathB> (sha=…)` so the operator can `sha256sum` both paths and remove the stale one. Byte-identical bundle-sub flat copies left over from installer versions that flat-copied bundle subs are reaped on the first post-upgrade boot (`[premium-auto-deliver] reaped sub=<name> reason=duplicate-of-premium-tree`). Standalone flat copies (leaked by the pre-fix `autoDeliverPremiumPlugins` standalone branch) are reaped unconditionally — there is no documented override path for standalones at `platform/plugins/<name>/` — and the reaper logs `[premium-auto-deliver] reaped standalone=<name> matches-source=<true|false>` so divergent reaps leave a forensic trail.
 
 Plugins are installed and managed through conversation. You can add marketplace plugins (like Stripe) or use Maxy's built-in ones (contacts, memory, Telegram).
@@ -1033,7 +1035,7 @@ Each installation has its own Cloudflare account. The **tunnel** sign-in is OAut
 | **Domain scope** (which zones the operator can route) | The operator picks the zone in the dashboard during OAuth or names it in chat; the agent can also enumerate zones via the API with a minted read-scoped token. |
 | **Local tunnel state** | `~/{configDir}/cloudflared/` — `cert.pem`, `<UUID>.json`, `config.yml`, `alias-domains.json`. |
 
-Tunnel auth on the operator-owned path (Mode A) is the OAuth cert (`cert.pem`); API operations use a narrow token the agent mints from your master token. To switch Cloudflare accounts, the agent runs the reset flow from `plugins/cloudflare/references/reset-guide.md` (deletes the cert and every tunnel on the current account), then the manual-setup flow again — `cloudflared tunnel login` picks a fresh account when you sign in.
+Tunnel auth on the operator-owned path (Mode A) is the OAuth cert (`cert.pem`); API operations use a narrow token the agent mints from your master token. That master may be account-scoped (`cfat_…`) or user-scoped (`cfut_…`); the agent detects the type and routes API endpoints accordingly (the account vs user token endpoints) — see `plugins/cloudflare/references/api.md`. To switch Cloudflare accounts, the agent runs the reset flow from `plugins/cloudflare/references/reset-guide.md` (deletes the cert and every tunnel on the current account), then the manual-setup flow again — `cloudflared tunnel login` picks a fresh account when you sign in.
 
 ## Setup flow