@rubytech/create-maxy-code 0.1.82 → 0.1.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.82",
+  "version": "0.1.84",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/plugins/admin/PLUGIN.md

@@ -129,7 +129,7 @@ Tools are available via the `admin` MCP server.
 - `hooks/pre-tool-use.sh` — enforces admin agent write boundaries
 - `hooks/playwright-file-guard.sh` — rewrites file:// URLs to a backgrounded loopback http.server before Playwright sees them
 - `hooks/webfetch-preflight.mjs` — short-circuits WebFetch on JS-SPA shells with a structured `WEBFETCH_CANNOT_READ_JS_SPA` error so the agent surfaces a loud failure to the owner instead of paying the 60s extraction timeout. Fail-open on any internal error.
-- `hooks/turn-completed-graph-write.sh` — Stop hook fired once per completed admin-agent turn. Gates on `MAXY_SESSION_ROLE=admin` + `MAXY_SPECIALIST!=database-operator` so it never recurses into the recorder PTY or fires on public sessions. **Task 147** — the recorder is spawned via the same route Sidebar uses. ONE POST to `POST /api/admin/claude-sessions`, body carries `{specialist:'database-operator', model:'haiku', initialMessage:<json-envelope>, adminSessionId:<op>}` — no synthetic `senderId: 'turn-recorder'` marker. The Hono wrapper bypasses cookie auth on this exact method+path when the request originates from `127.0.0.1` (same trust boundary the claude-session-manager itself relies on), looks up the operator's senderId from the manager's `/<adminSessionId>/meta`, and forwards a Sidebar-shape spawn body. The `/recorder-spawn` sibling route is gone. The hook reads its UI port from `MAXY_UI_INTERNAL_PORT` (stamped on the manager systemd unit) — no fallback; absence emits `[turn-recorder] spawn-failed reason=missing-env env=MAXY_UI_INTERNAL_PORT` to stderr instead of silently 19199-ing. **Task 177** — `initialMessage` is a JSON-stringified envelope; the schema lives in [`platform/plugins/docs/references/admin-session.md`](../docs/references/admin-session.md) under "`initialMessage` JSON envelope (Task 177)". Top-level keys exactly: `turns`, `conversationId`, `accountId`, `occurredAt`. `turns` is the full conversation transcript, oldest first, newest last, with each entry `{ role: "user"|"assistant", text, ts, toolCalls? }`. No windowing, no truncation. Multi-record assistant messages collapse on `message.id`. `tool_use` and matching `tool_result` blocks attach as a single `toolCalls` entry on the owning assistant turn; the user record carrying only the `tool_result` does not create a separate user turn. No leading instruction prose. `toolCalls[].input` and `toolCalls[].output` are native JSON values, never re-stringified. (Replaces Task 175's `(operatorMessage, assistantReply)` pair, which asserted a temporal Q→A relationship the walker never enforced.) One observability line `[turn-recorder] envelope sessionId=<op> turnsCount=<n> userTurns=<n> assistantTurns=<n> toolCallTurns=<n>` precedes `spawn-request`. The envelope rides on the `/spawn` body as a trailing positional argv to `claude`, so the database-operator session's JSONL first `role=user` line is the JSON object verbatim. No separate `POST /:id/input` call, no bracketed-paste, no keystroke injection. The recorder-auto-archive subscriber stops the recorder PTY as soon as its JSONL contains an assistant message with `stop_reason === "end_turn"`. **Task 129** — every emit goes through `POST /api/admin/log-ingest` so the lines land in `server.log` keyed by the operator session id. The chain is `trigger` → `spawn-request` → `spawn-success` → `input-delivered` → `tool-call` × N → `tool-result` × N → `write-complete` → `auto-archive`; each gated-off path emits one `trigger-skipped reason=<role-not-admin|is-recorder|empty-stdin|missing-transcript|conversation-empty>` line. Failure modes — `spawn-failed`, `tool-surface-missing`, `input-failed`, `write-empty`, `auto-archive reason=stale-recorder` — each emit one named line; absence is itself a defect.
+- `hooks/turn-completed-graph-write.sh` — **Dormant since Task 214** — the Stop-hook registration is no longer written to account settings.json; admin delegates graph writes to `database-operator` via the Task tool. The script, envelope walker, loopback `/api/admin/claude-sessions` 127.0.0.1 bypass, `[turn-recorder]` emitters, recorder-auto-archive subscriber, and `initialMessage` envelope spec are preserved as reusable infrastructure for any future autonomous post-turn flow. Historical contract (still describes the dormant path): Stop hook fired once per completed admin-agent turn. Gates on `MAXY_SESSION_ROLE=admin` + `MAXY_SPECIALIST!=database-operator` so it never recurses into the recorder PTY or fires on public sessions. **Task 147** — the recorder is spawned via the same route Sidebar uses. ONE POST to `POST /api/admin/claude-sessions`, body carries `{specialist:'database-operator', model:'haiku', initialMessage:<json-envelope>, adminSessionId:<op>}` — no synthetic `senderId: 'turn-recorder'` marker. The Hono wrapper bypasses cookie auth on this exact method+path when the request originates from `127.0.0.1` (same trust boundary the claude-session-manager itself relies on), looks up the operator's senderId from the manager's `/<adminSessionId>/meta`, and forwards a Sidebar-shape spawn body. The `/recorder-spawn` sibling route is gone. The hook reads its UI port from `MAXY_UI_INTERNAL_PORT` (stamped on the manager systemd unit) — no fallback; absence emits `[turn-recorder] spawn-failed reason=missing-env env=MAXY_UI_INTERNAL_PORT` to stderr instead of silently 19199-ing. **Task 177** — `initialMessage` is a JSON-stringified envelope; the schema lives in [`platform/plugins/docs/references/admin-session.md`](../docs/references/admin-session.md) under "`initialMessage` JSON envelope (Task 177)". Top-level keys exactly: `turns`, `conversationId`, `accountId`, `occurredAt`. `turns` is the full conversation transcript, oldest first, newest last, with each entry `{ role: "user"|"assistant", text, ts, toolCalls? }`. No windowing, no truncation. Multi-record assistant messages collapse on `message.id`. `tool_use` and matching `tool_result` blocks attach as a single `toolCalls` entry on the owning assistant turn; the user record carrying only the `tool_result` does not create a separate user turn. No leading instruction prose. `toolCalls[].input` and `toolCalls[].output` are native JSON values, never re-stringified. (Replaces Task 175's `(operatorMessage, assistantReply)` pair, which asserted a temporal Q→A relationship the walker never enforced.) One observability line `[turn-recorder] envelope sessionId=<op> turnsCount=<n> userTurns=<n> assistantTurns=<n> toolCallTurns=<n>` precedes `spawn-request`. The envelope rides on the `/spawn` body as a trailing positional argv to `claude`, so the database-operator session's JSONL first `role=user` line is the JSON object verbatim. No separate `POST /:id/input` call, no bracketed-paste, no keystroke injection. The recorder-auto-archive subscriber stops the recorder PTY as soon as its JSONL contains an assistant message with `stop_reason === "end_turn"`. **Task 129** — every emit goes through `POST /api/admin/log-ingest` so the lines land in `server.log` keyed by the operator session id. The chain is `trigger` → `spawn-request` → `spawn-success` → `input-delivered` → `tool-call` × N → `tool-result` × N → `write-complete` → `auto-archive`; each gated-off path emits one `trigger-skipped reason=<role-not-admin|is-recorder|empty-stdin|missing-transcript|conversation-empty>` line. Failure modes — `spawn-failed`, `tool-surface-missing`, `input-failed`, `write-empty`, `auto-archive reason=stale-recorder` — each emit one named line; absence is itself a defect.
 
 ## Session identifiers (Task 135)
 

package/payload/platform/plugins/admin/hooks/__tests__/pre-tool-use-memory-write-revoke.test.sh

@@ -1,9 +1,15 @@
 #!/usr/bin/env bash
-# Task 213 regression test for the memory-write / memory-update revoke
-# block in pre-tool-use.sh. The block sits at the top of the admin branch
-# and ensures any admin tool_use targeting the two writers exits 2 with
-# stderr explaining the recorder ownership, and emits one structured
-# `admin-tool-revoke` line through `/api/admin/log-ingest`.
+# Task 213 (rev. Task 222) regression test for the memory-write /
+# memory-update gate in pre-tool-use.sh. The block sits at the top of the
+# admin branch and:
+#  * Blocks an admin direct call (parent JSONL transcript_path) with
+#    exit 2, stderr explaining the delegation contract, and one structured
+#    `admin-tool-revoke` line carrying caller=admin source=hook result=rejected.
+#  * Allows a Task subagent call (transcript_path matches subagent path
+#    pattern) with exit 0 and a structured `admin-tool-revoke` line
+#    carrying caller=subagent:<type> source=hook-passthrough result=allowed.
+#  * Fail-closed blocks any payload with missing/malformed
+#    transcript_path, emitting caller=unknown source=hook result=rejected.
 
 set -u
 
@@ -58,17 +64,21 @@ PY
 run_with_tool() {
   local tool="$1"
   local sid="$2"
+  local transcript_path="${3:-}"
   local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
   local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
   python3 -c '
 import json, sys
-print(json.dumps({
+payload = {
   "hook_event_name": "PreToolUse",
   "session_id": sys.argv[1],
   "tool_name": sys.argv[2],
   "tool_input": {"name":"Smalleys","accountId":"acct-x","scope":"shared"},
-}, separators=(",", ":")))
-' "$sid" "$tool" | \
+}
+if sys.argv[3]:
+  payload["transcript_path"] = sys.argv[3]
+print(json.dumps(payload, separators=(",", ":")))
+' "$sid" "$tool" "$transcript_path" | \
     MAXY_UI_INTERNAL_PORT="$LISTENER_PORT" \
     bash "$HOOK" admin >"$stdout_file" 2>"$stderr_file"
   HOOK_RC=$?
@@ -76,33 +86,141 @@ print(json.dumps({
   sleep 0.1  # let listener flush
 }
 
+# Helper: stage a synthetic parent transcript + subagent transcript pair
+# under a temp dir. The parent transcript carries one Task tool_use whose
+# input.subagent_type = "$1"; the subagent transcript is empty (the hook
+# does not depend on its contents — only on its path).
+stage_subagent_transcripts() {
+  local subagent_type="$1"
+  local tmp_root; tmp_root=$(mktemp -d); TMPFILES+=("$tmp_root")
+  local sess_id; sess_id="abc-session-uuid"
+  local agent_id; agent_id="a1234567890abcdef"
+  local parent_jsonl="${tmp_root}/${sess_id}.jsonl"
+  local subagent_dir="${tmp_root}/${sess_id}/subagents"
+  mkdir -p "$subagent_dir"
+  local subagent_jsonl="${subagent_dir}/agent-${agent_id}.jsonl"
+  # Parent: minimal assistant row with a Task tool_use carrying subagent_type
+  python3 -c '
+import json, sys
+row = {
+  "type": "assistant",
+  "uuid": "u-1",
+  "parentUuid": None,
+  "sessionId": "abc-session-uuid",
+  "message": {
+    "role": "assistant",
+    "content": [
+      {"type": "tool_use", "id": "toolu_T1", "name": "Task",
+       "input": {"subagent_type": sys.argv[1], "description": "write Beacons"}}
+    ]
+  }
+}
+print(json.dumps(row, separators=(",", ":")))
+' "$subagent_type" > "$parent_jsonl"
+  # Subagent: empty file is enough — the hook only checks the path pattern
+  : > "$subagent_jsonl"
+  echo "$subagent_jsonl"
+}
+
 start_listener
 
-# --- memory-write rejected ---------------------------------------------
+# A parent-transcript path is the default for admin-direct cases. The
+# hook treats any non-subagent path as admin direct, so a synthetic file
+# in a temp dir suffices — we don't need to populate it.
+ADMIN_TRANSCRIPT=$(mktemp); TMPFILES+=("$ADMIN_TRANSCRIPT")
+: > "$ADMIN_TRANSCRIPT"
+
+# --- admin-direct memory-write rejected, emits caller=admin -----------
 : > "$REQ_LOG"
-run_with_tool "mcp__plugin_memory_memory__memory-write" "sess-abc"
-[[ "$HOOK_RC" -eq 2 ]] || fail "memory-write expected exit 2, got $HOOK_RC"
-echo "$HOOK_STDERR" | grep -qF "admin agent does not write to the graph" \
-  || fail "memory-write stderr missing rationale, got: $HOOK_STDERR"
-if grep -qE '/api/admin/log-ingest	.*"tag":\s*"admin-tool-revoke".*sessionId=sess-abc.*tool=mcp__plugin_memory_memory__memory-write.*source=permission-hook' "$REQ_LOG"; then
-  pass "memory-write rejection emits admin-tool-revoke with sessionId, tool, source"
+run_with_tool "mcp__plugin_memory_memory__memory-write" "sess-abc" "$ADMIN_TRANSCRIPT"
+[[ "$HOOK_RC" -eq 2 ]] || fail "admin-direct memory-write expected exit 2, got $HOOK_RC"
+echo "$HOOK_STDERR" | grep -qF "admin agent does not write to the graph directly" \
+  || fail "admin-direct memory-write stderr missing rationale, got: $HOOK_STDERR"
+if grep -qE '/api/admin/log-ingest	.*"tag":\s*"admin-tool-revoke".*sessionId=sess-abc.*tool=mcp__plugin_memory_memory__memory-write.*caller=admin.*source=hook.*result=rejected' "$REQ_LOG"; then
+  pass "admin-direct memory-write blocks with caller=admin source=hook result=rejected"
 else
-  fail "memory-write rejection did not emit admin-tool-revoke; log: $(cat "$REQ_LOG")"
+  fail "admin-direct memory-write did not emit expected log line; log: $(cat "$REQ_LOG")"
 fi
 
-# --- memory-update rejected --------------------------------------------
+# --- admin-direct memory-update rejected, emits caller=admin ----------
 : > "$REQ_LOG"
-run_with_tool "mcp__plugin_memory_memory__memory-update" "sess-xyz"
-[[ "$HOOK_RC" -eq 2 ]] || fail "memory-update expected exit 2, got $HOOK_RC"
-if grep -qE '/api/admin/log-ingest	.*"tag":\s*"admin-tool-revoke".*sessionId=sess-xyz.*tool=mcp__plugin_memory_memory__memory-update.*source=permission-hook' "$REQ_LOG"; then
-  pass "memory-update rejection emits admin-tool-revoke with sessionId, tool, source"
+run_with_tool "mcp__plugin_memory_memory__memory-update" "sess-xyz" "$ADMIN_TRANSCRIPT"
+[[ "$HOOK_RC" -eq 2 ]] || fail "admin-direct memory-update expected exit 2, got $HOOK_RC"
+if grep -qE '/api/admin/log-ingest	.*"tag":\s*"admin-tool-revoke".*sessionId=sess-xyz.*tool=mcp__plugin_memory_memory__memory-update.*caller=admin.*source=hook.*result=rejected' "$REQ_LOG"; then
+  pass "admin-direct memory-update blocks with caller=admin source=hook result=rejected"
 else
-  fail "memory-update rejection did not emit admin-tool-revoke; log: $(cat "$REQ_LOG")"
+  fail "admin-direct memory-update did not emit expected log line; log: $(cat "$REQ_LOG")"
 fi
 
+# --- Task-subagent memory-write ALLOWED, emits caller=subagent:<type> -
+# The path-pattern match (*/subagents/agent-*.jsonl) is the deterministic
+# discriminator; the parent transcript carries the subagent_type for
+# enrichment.
+: > "$REQ_LOG"
+SUB_TRANSCRIPT=$(stage_subagent_transcripts "database-operator")
+run_with_tool "mcp__plugin_memory_memory__memory-write" "sess-sub-1" "$SUB_TRANSCRIPT"
+[[ "$HOOK_RC" -eq 0 ]] || fail "subagent memory-write expected exit 0, got $HOOK_RC stderr: $HOOK_STDERR"
+if grep -qE '/api/admin/log-ingest	.*"tag":\s*"admin-tool-revoke".*sessionId=sess-sub-1.*tool=mcp__plugin_memory_memory__memory-write.*caller=subagent:database-operator.*source=hook-passthrough.*result=allowed' "$REQ_LOG"; then
+  pass "subagent memory-write allowed with caller=subagent:database-operator source=hook-passthrough result=allowed"
+else
+  fail "subagent memory-write did not emit expected allow log line; log: $(cat "$REQ_LOG")"
+fi
+
+# --- Task-subagent memory-update ALLOWED ------------------------------
+: > "$REQ_LOG"
+SUB_TRANSCRIPT=$(stage_subagent_transcripts "database-operator")
+run_with_tool "mcp__plugin_memory_memory__memory-update" "sess-sub-2" "$SUB_TRANSCRIPT"
+[[ "$HOOK_RC" -eq 0 ]] || fail "subagent memory-update expected exit 0, got $HOOK_RC stderr: $HOOK_STDERR"
+if grep -qE '/api/admin/log-ingest	.*"tag":\s*"admin-tool-revoke".*sessionId=sess-sub-2.*tool=mcp__plugin_memory_memory__memory-update.*caller=subagent:database-operator.*source=hook-passthrough.*result=allowed' "$REQ_LOG"; then
+  pass "subagent memory-update allowed with caller=subagent:database-operator source=hook-passthrough result=allowed"
+else
+  fail "subagent memory-update did not emit expected allow log line; log: $(cat "$REQ_LOG")"
+fi
+
+# --- Subagent path with unreadable parent transcript falls back to bare
+# `caller=subagent` (no name) but still ALLOWS the call. The hook never
+# blocks a legitimate subagent caller because the parent enrichment fails.
+: > "$REQ_LOG"
+ORPHAN_TMP=$(mktemp -d); TMPFILES+=("$ORPHAN_TMP")
+ORPHAN_DIR="${ORPHAN_TMP}/orphan-sess/subagents"
+mkdir -p "$ORPHAN_DIR"
+ORPHAN_SUB="${ORPHAN_DIR}/agent-aorphanid.jsonl"
+: > "$ORPHAN_SUB"
+run_with_tool "mcp__plugin_memory_memory__memory-write" "sess-orphan" "$ORPHAN_SUB"
+[[ "$HOOK_RC" -eq 0 ]] || fail "subagent w/ missing parent expected exit 0, got $HOOK_RC"
+if grep -qE '/api/admin/log-ingest	.*caller=subagent[^:].*source=hook-passthrough.*result=allowed' "$REQ_LOG"; then
+  pass "subagent caller without resolvable subagent_type falls back to bare 'subagent' label and still allows"
+else
+  fail "subagent w/ missing parent did not fall back to bare caller=subagent; log: $(cat "$REQ_LOG")"
+fi
+
+# --- Missing transcript_path → fail-closed block, caller=unknown ------
+: > "$REQ_LOG"
+run_with_tool "mcp__plugin_memory_memory__memory-write" "sess-no-tp" ""
+[[ "$HOOK_RC" -eq 2 ]] || fail "missing transcript_path expected exit 2 (fail-closed), got $HOOK_RC"
+if grep -qE '/api/admin/log-ingest	.*"tag":\s*"admin-tool-revoke".*sessionId=sess-no-tp.*caller=unknown.*source=hook.*result=rejected' "$REQ_LOG"; then
+  pass "missing transcript_path fail-closes with caller=unknown source=hook result=rejected"
+else
+  fail "missing transcript_path did not fail-closed with expected log; log: $(cat "$REQ_LOG")"
+fi
+
+# --- Malformed stdin payload → fail-closed block ----------------------
+: > "$REQ_LOG"
+stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
+stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
+echo "not-valid-json{{{" | \
+  MAXY_UI_INTERNAL_PORT="$LISTENER_PORT" \
+  bash "$HOOK" admin >"$stdout_file" 2>"$stderr_file"
+HOOK_RC=$?
+# A non-JSON payload also defeats the upstream TOOL_NAME extraction (grep
+# pattern matches nothing), so this confirms the hook reaches its fall-
+# through path safely without parse-induced crash.
+[[ "$HOOK_RC" -eq 0 ]] || [[ "$HOOK_RC" -eq 2 ]] || fail "malformed payload produced unexpected exit $HOOK_RC"
+pass "malformed payload handled without crash (exit $HOOK_RC)"
+
 # --- memory-search (allowed read tool) NOT rejected --------------------
 : > "$REQ_LOG"
-run_with_tool "mcp__plugin_memory_memory__memory-search" "sess-read"
+run_with_tool "mcp__plugin_memory_memory__memory-search" "sess-read" "$ADMIN_TRANSCRIPT"
 [[ "$HOOK_RC" -eq 0 ]] || fail "memory-search expected exit 0, got $HOOK_RC stderr: $HOOK_STDERR"
 if grep -qE '"tag":\s*"admin-tool-revoke"' "$REQ_LOG"; then
   fail "memory-search must NOT emit admin-tool-revoke; log: $(cat "$REQ_LOG")"
@@ -115,7 +233,7 @@ fi
 # old namespace was never the surface admin saw, so matching it would
 # be a regression.
 : > "$REQ_LOG"
-run_with_tool "mcp__memory__memory-write" "sess-old-ns"
+run_with_tool "mcp__memory__memory-write" "sess-old-ns" "$ADMIN_TRANSCRIPT"
 [[ "$HOOK_RC" -eq 0 ]] || fail "pre-209 namespace expected exit 0, got $HOOK_RC"
 if grep -qE '"tag":\s*"admin-tool-revoke"' "$REQ_LOG"; then
   fail "pre-209 namespace must NOT emit admin-tool-revoke"