@rubytech/create-maxy-code 0.1.102 → 0.1.104

package/payload/platform/plugins/admin/hooks/session-end-retrospective.sh

@@ -0,0 +1,268 @@
+#!/usr/bin/env bash
+# Stop hook — gates session termination until the admin agent has performed
+# a three-pass retrospective (technical learnings, operator-relationship
+# updates, graph-completeness sweep) and called the deterministic
+# `session-retrospective-mark-complete` MCP sentinel tool. Task 282.
+#
+# Trigger detection. End-intent is the operator's most recent real-user
+# message matching one of the literal token strings:
+#     /end | /archive | end session | archive this session
+# "Real user" follows the same shape used by
+# askuserquestion-investigate-gate.sh — `type=user, message.role=user,
+# content` is a string OR a list with at least one non-`tool_result` block.
+# `tool_result`-only user records are tool replies, not turn starts, and
+# never count as the latest user message.
+#
+# The Sidebar Archive button POSTs `/:sessionId/archive` which kills the
+# PTY directly — no Stop fires after that, so clicking Archive is the
+# operator's de-facto skip path. The spec lists opt-out as a deferred
+# follow-up; archive-click is its current shape and acceptable behaviour.
+#
+# Sentinel detection. Completion is recognised by greping the operator's
+# own JSONL (transcript_path on the Stop envelope) for a `tool_use` block
+# whose `name` is exactly `session-retrospective-mark-complete`. The
+# sentinel-grep doubles as the re-entry guard: every Stop that fires after
+# the agent's sentinel call sees the sentinel and exits 0 with
+# `gate-released`, so the agent's wrap-up turn never re-blocks.
+# [[feedback_no_stdout_parsing_for_control_flow]],
+# [[feedback_doctrine_paragraph_is_not_a_gate]] — the LLM is removed from
+# the per-decision path entirely.
+#
+# Gating (emits via `/api/admin/log-ingest`; hook stderr stays silent on
+# every skip path; the gate-blocked path is the only stderr emitter, by
+# Stop-hook contract — exit 2 + stderr is how the agent receives the
+# retrospective instruction block):
+#   - MAXY_SESSION_ROLE must equal "admin"      → reason=role-not-admin
+#   - MAXY_SPECIALIST must NOT equal            → reason=is-specialist
+#     "database-operator" (and any other        (recursion guard — a
+#     specialist value)                         specialist subagent stop
+#                                               must not re-enter this gate)
+#   - Stop-hook stdin must be non-empty         → reason=empty-stdin
+#   - transcript_path must exist on disk        → reason=missing-transcript
+#   - latest real-user message must match an    → reason=no-intent-match
+#     end-intent token
+#
+# Releases:
+#   - gate-released sessionId=<id> (when sentinel present in transcript)
+#
+# Blocks:
+#   - gate-blocked sessionId=<id> reason=sentinel-absent
+#     (exit 2; stderr carries the three-pass retrospective instruction)
+#
+# Input: Claude Code's Stop hook stdin shape
+#   { "session_id": "<intrinsic>", "transcript_path": "<jsonl path>", ... }
+
+set -uo pipefail
+
+UI_PORT="${MAXY_UI_INTERNAL_PORT:-}"
+if [ -z "$UI_PORT" ]; then
+  # No log-ingest reachable; emit to stderr instead of silently swallowing.
+  # Skip the gate rather than block — fail-open on infra absence so the
+  # operator is never bricked by a missing port.
+  echo "[session-retrospective] trigger-skipped sessionId=unknown reason=missing-env env=MAXY_UI_INTERNAL_PORT" >&2
+  exit 0
+fi
+UI_BASE="http://127.0.0.1:${UI_PORT}"
+LOG_INGEST_URL="${UI_BASE}/api/admin/log-ingest"
+
+emit_log() {
+  local line="$1"
+  curl -sS -o /dev/null -X POST \
+    -H 'Content-Type: application/json' \
+    --max-time 2 \
+    --data "$(python3 -c '
+import sys, json
+print(json.dumps({"tag": "session-retrospective", "level": "info", "line": sys.argv[1]}))
+' "$line")" \
+    "$LOG_INGEST_URL" 2>/dev/null || true
+}
+
+INPUT=""
+if [ -t 0 ]; then
+  INPUT=""
+else
+  INPUT=$(cat)
+fi
+
+PARSED=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    sid = d.get("session_id", "") or ""
+    tpath = d.get("transcript_path", "") or ""
+    print(f"{sid}\t{tpath}")
+except Exception:
+    print("\t")
+' 2>/dev/null)
+SESSION_ID="${PARSED%%	*}"
+TRANSCRIPT_PATH="${PARSED#*	}"
+SESSION_ID_REPORTED="${SESSION_ID:-unknown}"
+
+if [ "${MAXY_SESSION_ROLE:-}" != "admin" ]; then
+  emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=role-not-admin"
+  exit 0
+fi
+# Recursion guard. A specialist subagent dispatched via the Task tool
+# (e.g. database-operator running the operator's graph writes) carries
+# `MAXY_SPECIALIST=<name>` on the PTY env. Skip — the gate only enforces
+# end-of-session for the operator's own admin session.
+#
+# Invariant the PTY spawner is expected to honour: `MAXY_SPECIALIST` is
+# either set to a non-empty specialist name OR absent. An explicit empty
+# string from a wrapper would slip the recursion guard here (`-n ""` is
+# false) — that would be a defect at the spawn site, not here.
+if [ -n "${MAXY_SPECIALIST:-}" ]; then
+  emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=is-specialist specialist=${MAXY_SPECIALIST}"
+  exit 0
+fi
+if [ -z "$INPUT" ]; then
+  emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=empty-stdin"
+  exit 0
+fi
+if [ -z "$SESSION_ID" ] || [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  emit_log "trigger-skipped sessionId=${SESSION_ID_REPORTED} reason=missing-transcript"
+  exit 0
+fi
+
+# Single Python pass walks the transcript and reports two facts:
+#   1. The latest end-intent token in the most recent real-user message,
+#      or empty if no real user message matches.
+#   2. Whether any `tool_use` block in the transcript names the sentinel
+#      tool `session-retrospective-mark-complete`.
+# Output one line: <intent-token-or-empty>\t<sentinel-present-yes|no>
+INSPECTION=$(TRANSCRIPT_PATH="$TRANSCRIPT_PATH" python3 - <<'PY'
+import os, json
+
+SENTINEL_TOOL = "session-retrospective-mark-complete"
+INTENT_TOKENS = ("/end", "/archive", "end session", "archive this session")
+
+def is_real_user(rec):
+    if not isinstance(rec, dict) or rec.get("type") != "user":
+        return False
+    msg = rec.get("message")
+    if not isinstance(msg, dict) or msg.get("role") != "user":
+        return False
+    content = msg.get("content")
+    if isinstance(content, str):
+        return True
+    if isinstance(content, list):
+        for b in content:
+            if isinstance(b, dict) and b.get("type") != "tool_result":
+                return True
+        return False
+    return True
+
+def extract_user_text(rec):
+    msg = rec.get("message", {}) or {}
+    content = msg.get("content")
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        out = []
+        for b in content:
+            if not isinstance(b, dict):
+                continue
+            if b.get("type") == "text":
+                t = b.get("text")
+                if isinstance(t, str):
+                    out.append(t)
+        return "".join(out)
+    return ""
+
+def assistant_tool_use_names(rec):
+    if not isinstance(rec, dict) or rec.get("type") != "assistant":
+        return []
+    msg = rec.get("message", {}) or {}
+    if msg.get("role") != "assistant":
+        return []
+    content = msg.get("content")
+    if not isinstance(content, list):
+        return []
+    names = []
+    for b in content:
+        if isinstance(b, dict) and b.get("type") == "tool_use":
+            n = b.get("name")
+            if isinstance(n, str):
+                names.append(n)
+    return names
+
+path = os.environ["TRANSCRIPT_PATH"]
+records = []
+try:
+    with open(path, "r", encoding="utf-8") as f:
+        for raw in f:
+            raw = raw.strip()
+            if not raw:
+                continue
+            try:
+                records.append(json.loads(raw))
+            except Exception:
+                continue
+except Exception:
+    print("\tno")
+    raise SystemExit(0)
+
+# Sentinel presence — any assistant tool_use of the sentinel tool anywhere
+# in this session's JSONL.
+sentinel_present = False
+for r in records:
+    if SENTINEL_TOOL in assistant_tool_use_names(r):
+        sentinel_present = True
+        break
+
+# Latest real-user message text.
+latest_user_text = ""
+for r in reversed(records):
+    if is_real_user(r):
+        latest_user_text = extract_user_text(r).strip()
+        break
+
+matched = ""
+if latest_user_text:
+    # Case-insensitive whole-message match against the token set. A token
+    # must appear as the entire user message (after .strip()), or as a
+    # standalone line within it — not embedded inside a paragraph. Keeps
+    # the gate from false-positiving on "I'll end session by 5pm" prose.
+    haystacks = {latest_user_text.lower()}
+    for line in latest_user_text.splitlines():
+        s = line.strip().lower()
+        if s:
+            haystacks.add(s)
+    for tok in INTENT_TOKENS:
+        if tok.lower() in haystacks:
+            matched = tok
+            break
+
+print(f"{matched}\t{'yes' if sentinel_present else 'no'}")
+PY
+)
+INTENT_TOKEN="${INSPECTION%%	*}"
+SENTINEL_PRESENT="${INSPECTION#*	}"
+
+if [ -z "$INTENT_TOKEN" ]; then
+  emit_log "trigger-skipped sessionId=${SESSION_ID} reason=no-intent-match"
+  exit 0
+fi
+
+emit_log "trigger sessionId=${SESSION_ID} token=${INTENT_TOKEN}"
+
+if [ "$SENTINEL_PRESENT" = "yes" ]; then
+  emit_log "gate-released sessionId=${SESSION_ID}"
+  exit 0
+fi
+
+emit_log "gate-blocked sessionId=${SESSION_ID} reason=sentinel-absent"
+
+cat >&2 <<'INSTRUCTION'
+The operator signalled session end. Before this session can close, run the three-pass retrospective inside this same admin session — do not spawn a new session, do not background anything. Use the tools you already have.
+
+Pass 1 — Technical learnings. Walk this session for operator corrections and self-detected mistakes. For each one, delegate one graph write to `database-operator` via the Task tool, persisting a Learning or Correction node per the schema. Count what you write.
+
+Pass 2 — Operator-relationship updates. Walk this session for tonal signals, rejected phrasings, and working-style preferences. For each one worth carrying forward, Write the observation into `SOUL.md` at the account-scoped path. Count what you write.
+
+Pass 3 — Graph completeness sweep. Walk this session for any node, edge, or commitment that was discussed but not written to the graph in-flight. For each missing write, delegate to `database-operator` via the Task tool. Count what you write.
+
+Then call `session-retrospective-mark-complete` with the three counts and reply with one short paragraph in your house voice summarising what you wrote.
+INSTRUCTION
+
+exit 2

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -1781,8 +1781,9 @@ eagerTool(server, "skill-load", "Load a plugin skill's SKILL.md body by skill na
 // primitives the legacy tool wrapped; calling it logged a "rendered"
 // sentinel that read like a successful render to the agent while the
 // chat surface saw nothing. Admin flows now use plain markdown for
-// reviewable artefacts (`skills/file-presentation/SKILL.md`) and
-// `file-attach` for downloadable artefacts. The :Component / :KnowledgeDocument
+// reviewable artefacts and the `file-presentation` skill for downloadable
+// artefacts (the skill picks `SendUserFile` or `file-attach` by inventory).
+// The :Component / :KnowledgeDocument
 // persistence pipeline is preserved for historical conversations that
 // already carry the rows; no new conversations write to it.
 eagerTool(server, "session-reset", "Reset the current session. Compacts conversation history to memory, clears the visible conversation, " +
@@ -2480,12 +2481,15 @@ server.tool("premium-deliver", "Deliver a purchased premium plugin. Copies plugi
 // ---------------------------------------------------------------------------
 // file-attach — copy a generated file into the attachment store for download
 // ---------------------------------------------------------------------------
-eagerTool(server, "file-attach", "Attach a file from the account directory for delivery to the user. " +
-    "Copies the file into the attachment store and returns metadata the chat " +
-    "surface uses to present the download. The file must be within the account " +
-    "directory tree. The returned metadata is the operator-visible record of the " +
-    "attachment; quote it back to the user in plain text so they have the filename " +
-    "and size on screen.", {
+eagerTool(server, "file-attach", "Attach a file from the account directory for delivery to the user on non-PTY chat " +
+    "surfaces (web chat, WhatsApp) where the platform UI mediates attachment rendering. " +
+    "On the native Claude Code PTY surface, `SendUserFile` is the delivery — `file-attach` " +
+    "returns an `attachmentId` envelope only and renders no chip there. Tool selection is " +
+    "by inventory: see the `file-presentation` skill. Copies the file into the attachment " +
+    "store and returns metadata the chat surface uses to present the download. The file " +
+    "must be within the account directory tree. The returned metadata is the operator-visible " +
+    "record of the attachment; quote it back to the user in plain text so they have the " +
+    "filename and size on screen.", {
     filePath: z.string().describe("Absolute path to the file to attach"),
 }, async ({ filePath }) => {
     if (!ACCOUNT_ID)
@@ -3001,6 +3005,63 @@ eagerTool(server, "action-edit", "Edit a pending action's input and then execute
         };
     }
 });
+// ===================================================================
+// Session-end retrospective sentinel (Task 282)
+// ===================================================================
+//
+// Deterministic completion signal for the session-end retrospective gate
+// hook (`platform/plugins/admin/hooks/session-end-retrospective.sh`). The
+// hook walks the operator's JSONL for any `tool_use` of THIS tool's exact
+// name and, when present, releases the Stop gate. Prose retrospectives
+// without this call leave the gate blocked
+// ([[feedback_doctrine_paragraph_is_not_a_gate]]).
+//
+// The tool's only side-effect is one structured log line through
+// /api/admin/log-ingest so server.log carries the full chain
+//   trigger → gate-blocked → complete → gate-released
+// against one operator sessionId. The release decision itself is the
+// JSONL grep — never the log line.
+server.tool("session-retrospective-mark-complete", "Marks the end-of-session retrospective complete. Call this AFTER walking the session for technical learnings, operator-relationship updates, and missing graph writes and persisting each one (Task-tool delegations to database-operator for graph writes, Write to SOUL.md for tonal updates). The counts you pass are the number of items you actually persisted in each pass. The session-end Stop hook gate releases on the presence of this tool_use in the transcript — calling it is the deterministic signal that the retrospective ran.", {
+    learningsCount: z.number().int().nonnegative().describe("Technical-learning / correction nodes you delegated to database-operator in this retrospective."),
+    preferencesCount: z.number().int().nonnegative().describe("SOUL.md writes you made for tonal / working-style observations in this retrospective."),
+    graphWriteCount: z.number().int().nonnegative().describe("Graph nodes/edges/commitments you delegated to database-operator for content that surfaced in the session but was not written in-flight."),
+}, async ({ learningsCount, preferencesCount, graphWriteCount }) => {
+    const sessionId = process.env.SESSION_ID || "unknown";
+    const line = `complete sessionId=${sessionId} learningsCount=${learningsCount} preferencesCount=${preferencesCount} graphWriteCount=${graphWriteCount}`;
+    if (!PLATFORM_PORT) {
+        // Module-init deliberately tolerates a missing PLATFORM_PORT
+        // (lines ~62-71) so the MCP server does not loud-fail on plugin-
+        // system spawn enumeration. The hook's release decision is the
+        // JSONL tool_use entry, not this POST — so we still return success
+        // to the caller and emit the line on stderr so it lands in the
+        // MCP server's stderr log instead of disappearing into a NaN URL.
+        console.error(`[session-retrospective] log-ingest-skipped sessionId=${sessionId} reason=missing-env env=PLATFORM_PORT line=${JSON.stringify(line)}`);
+    }
+    else {
+        try {
+            const port = parseInt(PLATFORM_PORT, 10);
+            await fetch(`http://127.0.0.1:${port}/api/admin/log-ingest`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ tag: "session-retrospective", level: "info", line }),
+                signal: AbortSignal.timeout(2000),
+            });
+        }
+        catch (err) {
+            // Falling back to stderr keeps the event in the MCP server's
+            // stderr log even when the loopback POST fails. The hook's
+            // release decision is JSONL-based and does not depend on this
+            // POST succeeding.
+            console.error(`[session-retrospective] log-ingest-failed sessionId=${sessionId} err=${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return {
+        content: [{
+                type: "text",
+                text: `Retrospective marked complete (learnings=${learningsCount} preferences=${preferencesCount} graphWrites=${graphWriteCount}). Session is now free to end.`,
+            }],
+    };
+});
 // Cleanup on exit (SIGTERM for systemd service stops on Pi)
 const cleanup = async () => {
     await closeDriver();