@rubytech/create-maxy-code 0.1.49 → 0.1.57

package/payload/platform/plugins/admin/hooks/turn-completed-graph-write.sh

@@ -1,48 +1,88 @@
 #!/usr/bin/env bash
 # Stop hook — fires on every completed admin-agent turn and dispatches one
-# headless database-operator session against the conversation transcript.
-# The hidden recorder is the only writer to the Neo4j graph; the admin agent
+# headless database-operator session against the operator's most recent turn
+# text. The recorder is the only writer to the Neo4j graph; the admin agent
 # stays focused on the operator's request.
 #
-# Pipeline (Task 114 redesign — replaces Task 106's `--print` + stdin-EOT
-# shape, which is incompatible with the OAuth subscription the manager runs
-# on):
-#   1. /spawn with `hidden=true, specialist=database-operator` — the manager
-#      produces a structurally normal admin specialist session (same argv,
-#      same OAuth path) and returns its sessionId.
-#   2. POST /<sessionId>/input with `<instruction>\n\nConversation transcript:\n<filtered JSON>`.
-#   3. The manager's recorder-auto-archive subscriber stops the PTY as soon
-#      as the recorder's JSONL contains an assistant message with
-#      `stop_reason === "end_turn"`. The hook does not need to follow up.
+# Task 134 — the four-step per-turn process is:
+#   1. New admin session is spawned the SAME way a Sidebar "New session"
+#      click spawns one — same route (`POST /api/admin/claude-sessions`,
+#      the one Sidebar hits), same payload schema. The wrapper bypasses
+#      cookie auth on this exact path when the request originates from
+#      127.0.0.1; the body carries `originatingSessionId` and
+#      `specialist: 'database-operator'`, and the wrapper looks up the
+#      operator's senderId from `/<originatingSessionId>/meta`. The
+#      Task-122-era `/recorder-spawn` sibling route is gone.
+#   2. The spawned session's specialist is `database-operator`.
+#   3. The initial message is the OPERATOR'S LAST TURN, prefixed with the
+#      literal instruction
+#        "update the graph with any new or missing information or intent"
+#      followed by a blank line. No transcript tail, no `Conversation id:`
+#      prose — both removed in Task 131. The recorder reads only this one
+#      most-recent turn.
+#   4. When the recorder's turn ends (`stop_reason:"end_turn"` lands in
+#      the recorder JSONL), the manager posts `/<sid>/stop`, claude exits,
+#      the fs-watcher observes the PID-file removal, and the row leaves
+#      the index. No reaper involvement on the success path.
 #
-# Gating:
-#   - MAXY_SESSION_ROLE must equal "admin"
-#   - MAXY_HIDDEN_SPAWN must equal "0" (the recorder PTY itself runs with
-#     MAXY_HIDDEN_SPAWN=1; the guard prevents accidental recursion).
+# Task 129 — every emit goes through the platform's `/api/admin/log-ingest`
+# endpoint (loopback-only). Hook stderr is silent on the success path.
+# Every line carries the operator's `sessionId=<op>` so one grep against
+# `server.log` returns the whole chain. The `originatingSessionId` is
+# posted as a top-level field of the spawn body; the wrapper reads it,
+# resolves the operator's account from it, and forwards a Sidebar-shape
+# spawn body to the manager.
+#
+# Gating (emits a `trigger-skipped` line, no longer a silent exit 0):
+#   - MAXY_SESSION_ROLE must equal "admin"  → reason=role-not-admin
+#   - MAXY_IS_RECORDER must NOT equal "1"   → reason=is-recorder
+#   - Stop-hook stdin must be non-empty     → reason=empty-stdin
+#   - transcript_path must exist on disk    → reason=missing-transcript
+#   - a most-recent assistant or user turn  → reason=last-turn-empty
+#     must be extractable from the JSONL
 #
 # Input: Claude Code's Stop hook stdin shape
 #   { "session_id": "<intrinsic>", "transcript_path": "<jsonl path>", ... }
-#
-# Failure modes are silent (exit 0) — a failure here must never break the
-# operator's session.
 
 set -uo pipefail
 
-START_MS=$(python3 -c 'import time; print(int(time.time()*1000))')
-
-if [ "${MAXY_SESSION_ROLE:-}" != "admin" ]; then
-  exit 0
-fi
-if [ "${MAXY_HIDDEN_SPAWN:-0}" = "1" ]; then
+# UI listener port is stamped on the claude-session-manager systemd unit
+# as `Environment=MAXY_UI_INTERNAL_PORT=<port>` (Task 134). Absence is a
+# structural defect — historically the hook fell back to 19199 with no
+# listener on most devices and silently swallowed connection-refused. Now
+# it short-circuits with a named diagnostic to stderr (the only sink the
+# log-ingest endpoint itself depends on this var to reach).
+UI_PORT="${MAXY_UI_INTERNAL_PORT:-}"
+if [ -z "$UI_PORT" ]; then
+  echo "[turn-recorder] spawn-failed 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 one log line via the platform's log-ingest endpoint. Best-effort:
+# a failed POST does not break the hook — but the absence of the line is
+# itself a system-level defect per Task 129 §157. We do NOT fall back to
+# stderr, because stderr never reaches server.log.
+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": "turn-recorder", "level": "info", "line": sys.argv[1]}))
+' "$line")" \
+    "$LOG_INGEST_URL" 2>/dev/null || true
+}
 
+# Parse stdin first so trigger-skipped lines can carry the operator
+# session id (when present). Stop-hook stdin is required.
+INPUT=""
 if [ -t 0 ]; then
-  exit 0
-fi
-INPUT=$(cat)
-if [ -z "$INPUT" ]; then
-  exit 0
+  INPUT=""
+else
+  INPUT=$(cat)
 fi
 
 PARSED=$(printf '%s' "$INPUT" | python3 -c '
@@ -58,111 +98,145 @@ except Exception:
 ADMIN_SESSION_ID="${PARSED%%	*}"
 TRANSCRIPT_PATH="${PARSED#*	}"
 
+# Gate ordering — each gate gets a distinct trigger-skipped reason so the
+# operator-ID-keyed grep can tell why a given turn did not record. Role
+# gate fires first because non-admin invocations may have no operator id
+# at all (the field is empty for public/recorder).
+if [ "${MAXY_SESSION_ROLE:-}" != "admin" ]; then
+  emit_log "trigger-skipped sessionId=${ADMIN_SESSION_ID:-unknown} reason=role-not-admin"
+  exit 0
+fi
+# Task 131 — the recorder gate is now MAXY_IS_RECORDER (set to '1' by the
+# pty-spawner whenever a spawn carries `originatingSessionId`). The prior
+# MAXY_HIDDEN_SPAWN gate conflated UI visibility with recorder identity;
+# with hidden=false on recorder spawns now, the dedicated env var is the
+# only correct discriminator against hook-recursion.
+if [ "${MAXY_IS_RECORDER:-0}" = "1" ]; then
+  emit_log "trigger-skipped sessionId=${ADMIN_SESSION_ID:-unknown} reason=is-recorder"
+  exit 0
+fi
+if [ -z "$INPUT" ]; then
+  emit_log "trigger-skipped sessionId=${ADMIN_SESSION_ID:-unknown} reason=empty-stdin"
+  exit 0
+fi
 if [ -z "$ADMIN_SESSION_ID" ] || [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  emit_log "trigger-skipped sessionId=${ADMIN_SESSION_ID:-unknown} reason=missing-transcript"
   exit 0
 fi
 
-# Filter the JSONL tail down to records the database-operator cares about:
-# user prompts, assistant messages, and tool calls. Drop ephemeral
-# admin-state records that bloat the prompt without graph value.
-FILTERED_TAIL=$(python3 - "$TRANSCRIPT_PATH" <<'PY'
+# Extract the operator's most-recent turn text from the JSONL. The single
+# rule (no fallbacks beyond the assistant→user pair) is:
+#   - the most-recent `assistant` record whose message.content yields any
+#     extractable text, OR
+#   - if no assistant record produces text, the most-recent `user` record
+#     that produces text.
+# Tool-call blocks, system records, and ephemeral admin-state records are
+# never the candidate. Empty output → reason=last-turn-empty.
+LAST_TURN_TEXT=$(python3 - "$TRANSCRIPT_PATH" <<'PY'
 import sys, json
-DROP = {
-  'queue-operation', 'auto_mode', 'deferred_tools_delta',
-  'last-prompt', 'skill_listing', 'mcp_instructions_delta',
-  'permission-mode',
-}
-def keep(rec):
-  t = rec.get('type') if isinstance(rec, dict) else None
-  if not isinstance(t, str): return False
-  if t in DROP: return False
-  if t.startswith('hook_'): return False
-  if t in ('user', 'assistant', 'message'): return True
-  if 'tool' in t.lower(): return True
-  return False
+
+def block_text(block):
+    if not isinstance(block, dict): return ""
+    if block.get("type") != "text": return ""
+    t = block.get("text")
+    return t if isinstance(t, str) else ""
+
+def record_text(rec):
+    if not isinstance(rec, dict): return ""
+    msg = rec.get("message")
+    if not isinstance(msg, dict): return ""
+    content = msg.get("content")
+    if isinstance(content, str): return content
+    if isinstance(content, list):
+        parts = [block_text(b) for b in content]
+        return "\n".join(p for p in parts if p)
+    return ""
 
 path = sys.argv[1]
-out = []
+last_assistant = ""
+last_user = ""
 try:
-  with open(path, 'r', encoding='utf-8') as f:
-    for line in f:
-      line = line.strip()
-      if not line: continue
-      try: rec = json.loads(line)
-      except Exception: continue
-      if keep(rec): out.append(rec)
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line: continue
+            try: rec = json.loads(line)
+            except Exception: continue
+            t = rec.get("type") if isinstance(rec, dict) else None
+            if t == "assistant":
+                tx = record_text(rec).strip()
+                if tx: last_assistant = tx
+            elif t == "user":
+                tx = record_text(rec).strip()
+                if tx: last_user = tx
 except Exception:
-  pass
-out = out[-200:]
-print(json.dumps(out, separators=(',', ':')))
+    pass
+
+print(last_assistant if last_assistant else last_user, end="")
 PY
 )
 
-FILTERED_COUNT=$(printf '%s' "$FILTERED_TAIL" | python3 -c 'import sys,json; d=json.load(sys.stdin); print(len(d) if isinstance(d,list) else 0)' 2>/dev/null || echo 0)
+LAST_TURN_BYTES=$(printf '%s' "$LAST_TURN_TEXT" | wc -c | tr -d ' ')
+TRANSCRIPT_BYTES=$(wc -c <"$TRANSCRIPT_PATH" 2>/dev/null | tr -d ' ' || echo 0)
 
-MANAGER_PORT="${CLAUDE_SESSION_MANAGER_PORT:-19400}"
-MANAGER_BASE="http://127.0.0.1:${MANAGER_PORT}"
+# Step 0 — trigger line. First link in the chain the operator-ID-keyed
+# grep returns. Task 131: replaced `filteredRecords=<n>` with
+# `lastTurnBytes=<n>` because the hook no longer ships a filtered
+# transcript tail.
+emit_log "trigger sessionId=${ADMIN_SESSION_ID} turnIndex=0 transcriptBytes=${TRANSCRIPT_BYTES} lastTurnBytes=${LAST_TURN_BYTES}"
 
+if [ -z "$LAST_TURN_TEXT" ]; then
+  emit_log "trigger-skipped sessionId=${ADMIN_SESSION_ID} reason=last-turn-empty"
+  exit 0
+fi
+
+# Compose the recorder spawn body. Task 134:
+#   - `initialMessage` = literal instruction + "\n\n" + last-turn text.
+#     Verbatim instruction wording (no trailing qualifier, includes "new").
+#   - `originatingSessionId` carries the operator's session id; the
+#     wrapper looks up the operator's real senderId from
+#     `/<originatingSessionId>/meta` and forwards a Sidebar-shape spawn
+#     body to the manager. No synthetic `senderId: 'turn-recorder'`
+#     marker — the loopback bypass is method+path-scoped.
+#   - `specialist: 'database-operator'` discriminates the recorder spawn
+#     from a vanilla Sidebar click.
+#   - No `Conversation id:` prose; no transcript-tail JSON.
 SPAWN_BODY=$(python3 -c '
-import json
+import sys, json
+sid = sys.argv[1]
+last_turn = sys.argv[2]
+instruction = "update the graph with any new or missing information or intent"
+text = instruction + "\n\n" + last_turn
 body = {
-  "senderId": "turn-recorder",
-  "role": "admin",
-  "channel": "browser",
-  "hidden": True,
   "specialist": "database-operator",
+  "initialMessage": text,
+  "originatingSessionId": sid,
 }
 print(json.dumps(body))
-' 2>/dev/null)
+' "$ADMIN_SESSION_ID" "$LAST_TURN_TEXT" 2>/dev/null)
 
-SPAWN_RES=$(curl -sS -X POST \
+SPAWN_RES_FILE=$(mktemp)
+SPAWN_HTTP=$(curl -sS -o "$SPAWN_RES_FILE" -w '%{http_code}' -X POST \
   -H 'Content-Type: application/json' \
   --max-time 10 \
   --data "$SPAWN_BODY" \
-  "${MANAGER_BASE}/spawn" 2>/dev/null)
-
-RECORDER_SESSION_ID=$(printf '%s' "$SPAWN_RES" | python3 -c '
-import sys, json
-try:
-  d = json.load(sys.stdin)
-  print(d.get("sessionId", "") or "")
-except Exception:
-  print("")
-' 2>/dev/null)
-
-if [ -z "$RECORDER_SESSION_ID" ]; then
-  echo "turn-completed-graph-write spawn-failed conversationId=${ADMIN_SESSION_ID:0:8}" >&2
-  exit 0
+  "${UI_BASE}/api/admin/claude-sessions" 2>/dev/null || echo 000)
+
+# The wrapper emits the named `spawn-request` / `spawn-success` /
+# `input-delivered` lines itself. The hook only emits the hook-side
+# failure variant — `loopback-http` — and even then only when the wrapper
+# returned a non-2xx that is NOT one of the preflight reasons (those are
+# logged by the manager before the wrapper sees them).
+RES_BODY=$(cat "$SPAWN_RES_FILE" 2>/dev/null || true)
+rm -f "$SPAWN_RES_FILE"
+
+if [ "$SPAWN_HTTP" -lt 200 ] || [ "$SPAWN_HTTP" -ge 300 ]; then
+  ERR_SHORT=$(printf '%s' "$RES_BODY" | tr -d '\r\n' | cut -c1-200)
+  if printf '%s' "$RES_BODY" | grep -q '"error":"tool-surface-missing"\|"error":"missing-originating-session-id"\|"error":"originating-session-id-required"\|"error":"originating-session-not-found"'; then
+    : # preflight or lookup already named the failure
+  else
+    emit_log "spawn-failed sessionId=${ADMIN_SESSION_ID} reason=loopback-http http=${SPAWN_HTTP} err=$(python3 -c 'import sys,json; print(json.dumps(sys.argv[1]))' "${ERR_SHORT}")"
+  fi
 fi
 
-# Compose the input prompt and POST it to /<sessionId>/input. The instruction
-# string is fixed (Task 114). The transcript is appended as a JSON array so
-# the recorder reads it as a single user turn.
-INPUT_BODY=$(python3 -c '
-import sys, json
-sid = sys.argv[1]
-tail_json = sys.argv[2]
-instruction = "update the graph with any missing information or intent that can be derived from this conversation"
-text = (
-  f"{instruction}\n\n"
-  f"Conversation id: {sid}\n"
-  f"Conversation transcript:\n{tail_json}\n"
-)
-print(json.dumps({"text": text}))
-' "$ADMIN_SESSION_ID" "$FILTERED_TAIL" 2>/dev/null)
-
-INPUT_BYTES=$(printf '%s' "$INPUT_BODY" | python3 -c 'import sys,json; b=json.load(sys.stdin); print(len(b.get("text","").encode("utf-8")))' 2>/dev/null || echo 0)
-
-INPUT_HTTP=$(curl -sS -o /tmp/turn-recorder-input.out -w '%{http_code}' -X POST \
-  -H 'Content-Type: application/json' \
-  --max-time 10 \
-  --data "$INPUT_BODY" \
-  "${MANAGER_BASE}/${RECORDER_SESSION_ID}/input" 2>/dev/null || echo 000)
-
-echo "[turn-recorder] spawn-with-input sessionId=${RECORDER_SESSION_ID:0:8} bytes=${INPUT_BYTES} filtered-from-records=${FILTERED_COUNT} input-http=${INPUT_HTTP}" >&2
-
-END_MS=$(python3 -c 'import time; print(int(time.time()*1000))')
-ELAPSED=$((END_MS - START_MS))
-echo "turn-completed-graph-write fired conversationId=${ADMIN_SESSION_ID:0:8} recorderSessionId=${RECORDER_SESSION_ID:0:8} filtered=${FILTERED_COUNT} ms=${ELAPSED}" >&2
-
 exit 0

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

@@ -9,6 +9,7 @@ import { resolve, join } from "node:path";
 import { execFileSync } from "node:child_process";
 import { appendFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { writeAdminEntry, removeAdminFromAccount } from "../../../../lib/admins-write/dist/index.js";
+import { requirePortEnv } from "../../../../lib/require-port-env/dist/index.js";
 import { deviceUrlBlock } from "../../../../lib/device-url/dist/index.js";
 import { substituteBrandPlaceholders } from "../../../../lib/brand-templating/dist/index.js";
 import { resolveEntitlement } from "../../../../lib/entitlement/dist/index.js";
@@ -28,10 +29,13 @@ const ACCOUNT_ID = process.env.ACCOUNT_ID;
 if (!ACCOUNT_ID) {
     throw new Error("ACCOUNT_ID environment variable is required");
 }
-const PLATFORM_PORT = process.env.PLATFORM_PORT;
-if (!PLATFORM_PORT) {
-    throw new Error("PLATFORM_PORT environment variable is required — set by getMcpServers() in claude-agent.ts");
-}
+// Task 142 — `PLATFORM_PORT` is the internal loopback port, stamped on
+// the claude-session-manager systemd unit and forwarded to this MCP
+// process via the per-spawn `maxy-mcp-*.json` env block written by
+// `pty-spawner.writePerSpawnMcpConfig`. `MAXY_BRAND_PORT` is the brand's
+// public UI port, used only for display-surface `.local` URLs.
+const PLATFORM_PORT = String(requirePortEnv("PLATFORM_PORT", { tag: "admin:module-init" }));
+const MAXY_BRAND_PORT = String(requirePortEnv("MAXY_BRAND_PORT", { tag: "admin:module-init" }));
 // Brand-aware config — reads configDir, productName, and commercialMode from
 // brand.json stamped at install time. commercialMode gates the
 // entitlement verifier: false (default) preserves personal-mode installs;
@@ -372,9 +376,10 @@ eagerTool(server, "system-status", "Check health of all Maxy platform services:
         console.error("[system-status] os.hostname() failed, falling back to brand.hostname", err);
         checks.hostname = "unknown (os.hostname failed)";
     }
-    // Running port — PLATFORM_PORT is what the parent process passes to MCP subprocesses;
-    // PORT is the main-process variable (available in dev); 19200 is the install default.
-    checks.port = process.env.PLATFORM_PORT ?? process.env.PORT ?? "19200";
+    // Task 142: `port` shown to the operator is the brand's public port
+    // (the one external clients reach via `.local`), not the internal
+    // loopback. Loud-fail if absent (Task 139 doctrine).
+    checks.port = String(requirePortEnv("MAXY_BRAND_PORT", { tag: "system-status" }));
     console.error(`[system-status] port=${checks.port} hostname=${checks.hostname}`);
     // Local URL — pre-computed for agent URL construction (avoids hostname/port assembly errors)
     checks.localUrl = `http://${checks.hostname}.local:${checks.port}`;
@@ -433,15 +438,18 @@ eagerTool(server, "public-hostname", "Resolve this account's canonical public ho
 });
 eagerTool(server, "remote-auth-status", "Check whether the remote access password is configured. When not configured, emits a device-bound URL affordance (maxy-device-url fenced block) pointing at the password setup page — this URL opens on the device's own screen when the operator clicks it. The agent never constructs the password file path or runs shell commands — this tool is the single authority.", {}, async () => {
     const TAG = "[remote-auth-status]";
-    const platformPort = parseInt(PLATFORM_PORT, 10);
-    const setupUrl = `http://${osHostname()}.local:${platformPort}/__remote-auth/setup`;
+    // Task 142: `.local` URL is a display surface — read the brand's
+    // public port. The loopback fetch reads PLATFORM_PORT (internal).
+    const brandPort = parseInt(MAXY_BRAND_PORT, 10);
+    const internalPort = parseInt(PLATFORM_PORT, 10);
+    const setupUrl = `http://${osHostname()}.local:${brandPort}/__remote-auth/setup`;
     try {
-        const res = await fetch(`http://127.0.0.1:${platformPort}/api/remote-auth/status`, {
+        const res = await fetch(`http://127.0.0.1:${internalPort}/api/remote-auth/status`, {
             signal: AbortSignal.timeout(5000),
         });
         const body = await res.json();
         const configured = body.configured === true;
-        console.error(`${TAG} configured=${configured} port=${platformPort}`);
+        console.error(`${TAG} configured=${configured} brandPort=${brandPort} internalPort=${internalPort}`);
         // Shape the response for both the agent (deciding what to say) and
         // the user (seeing the device-URL button when they need to act).
         // Configured → plain status, no URL. Unconfigured → include the
@@ -461,7 +469,7 @@ eagerTool(server, "remote-auth-status", "Check whether the remote access passwor
         return {
             content: [{
                     type: "text",
-                    text: `Cannot verify remote authentication — the web server at http://127.0.0.1:${platformPort} is not reachable: ${errMsg}. Ensure the ${BRAND_NAME} platform is running.`,
+                    text: `Cannot verify remote authentication — the web server at http://127.0.0.1:${internalPort} is not reachable: ${errMsg}. Ensure the ${BRAND_NAME} platform is running.`,
                 }],
             isError: true,
         };