@rubytech/create-maxy-code 0.1.157 → 0.1.159

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

@@ -1,8 +1,9 @@
 #!/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.
+# a four-pass retrospective (technical learnings, operator-relationship
+# updates, graph-completeness sweep, typed-edge auto-extraction) and called
+# the deterministic `session-retrospective-mark-complete` MCP sentinel
+# tool. Task 282; converged onto the Task 439 shared helper.
 #
 # Trigger detection. End-intent is the operator's most recent real-user
 # message matching one of the literal token strings:
@@ -23,109 +24,49 @@
 # whose `name` is exactly `mcp__admin__session-retrospective-mark-complete`
 # — that is the prefixed form Claude Code writes for MCP tools in the
 # JSONL; the unprefixed name only appears in the operator-facing
-# instruction text below. 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.
+# instruction text below. 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
+# Gating (common guards live in `lib/admin-graph-pass-common.sh`; this
+# hook adds the end-intent gating layered on top):
+#   - role-not-admin / is-specialist / empty-stdin / missing-transcript:
+#     handled by the shared helper, emit `trigger-skipped` and exit 0.
+#   - no-intent-match: latest real-user message has no end-intent token,
+#     emit `trigger-skipped` and exit 0.
 #
 # 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)
+#     (exit 2; stderr carries the four-pass retrospective instruction —
+#     stderr is the Stop-hook contract for handing instructions back to
+#     the agent).
 #
 # 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
+AGP_LOG_TAG="session-retrospective"
+AGP_LIB="$(dirname "$0")/lib/admin-graph-pass-common.sh"
+if [ ! -f "$AGP_LIB" ]; then
+  echo "[${AGP_LOG_TAG}] trigger-skipped sessionId=unknown reason=missing-helper path=${AGP_LIB}" >&2
   exit 0
 fi
-UI_BASE="http://127.0.0.1:${UI_PORT}"
-LOG_INGEST_URL="${UI_BASE}/api/admin/log-ingest"
+# shellcheck source=lib/admin-graph-pass-common.sh
+source "$AGP_LIB"
 
-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
+agp_setup_logging
+agp_read_stdin
+agp_parse_stdin
+agp_guard_role_specialist
+agp_guard_transcript require-stdin
 
 # Single Python pass walks the transcript and reports two facts:
 #   1. The latest end-intent token in the most recent real-user message,
@@ -243,18 +184,18 @@ INTENT_TOKEN="${INSPECTION%%	*}"
 SENTINEL_PRESENT="${INSPECTION#*	}"
 
 if [ -z "$INTENT_TOKEN" ]; then
-  emit_log "trigger-skipped sessionId=${SESSION_ID} reason=no-intent-match"
+  agp_emit_log "trigger-skipped sessionId=${SESSION_ID} reason=no-intent-match"
   exit 0
 fi
 
-emit_log "trigger sessionId=${SESSION_ID} token=${INTENT_TOKEN}"
+agp_emit_log "trigger sessionId=${SESSION_ID} token=${INTENT_TOKEN}"
 
 if [ "$SENTINEL_PRESENT" = "yes" ]; then
-  emit_log "gate-released sessionId=${SESSION_ID}"
+  agp_emit_log "gate-released sessionId=${SESSION_ID}"
   exit 0
 fi
 
-emit_log "gate-blocked sessionId=${SESSION_ID} reason=sentinel-absent"
+agp_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 four-pass retrospective inside this same admin session — do not spawn a new session, do not background anything. Use the tools you already have.

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

@@ -17,7 +17,7 @@
 # body. No recorder-only carving on the manager side.
 #
 # Task 177 — `initialMessage` is a JSON object stringified to a string.
-# Top-level keys EXACTLY: turns, conversationId, accountId, occurredAt.
+# Top-level keys EXACTLY: turns, sessionId, accountId, occurredAt.
 # `turns` is the chronologically-ordered conversation window — every
 # user / assistant message in the operator's JSONL, oldest first, no
 # windowing or truncation. Each entry:
@@ -109,7 +109,7 @@ fi
 #         "toolCalls"?: [{ "tool": "...", "input": {...}, "output": ... }] },
 #       ...
 #     ],
-#     "conversationId": "<session_id>",
+#     "sessionId": "<session_id>",
 #     "accountId":      "<ACCOUNT_ID env>",
 #     "occurredAt":     "<hook fire time, ISO-8601 UTC, .000Z>"
 #   }
@@ -136,7 +136,7 @@ def concat_text(content):
                 out.append(t)
     return "".join(out)
 
-path, conversation_id, account_id, occurred_at = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4]
+path, session_id, account_id, occurred_at = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4]
 
 turns = []                  # ordered output: { role, text, ts, toolCalls? }
 msg_id_to_turn_index = {}   # collapse rule for assistant message.id
@@ -236,7 +236,7 @@ except Exception:
 
 envelope = {
     "turns":          turns,
-    "conversationId": conversation_id,
+    "sessionId": session_id,
     "accountId":      account_id,
     "occurredAt":     occurred_at,
 }

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

@@ -1325,20 +1325,20 @@ server.tool("agent-list", "List all public (non-admin) agents with their full co
         };
     }
 });
-eagerTool(server, "logs-read", "Read recent logs. Stream logs (type=agent-stream/error/session/public) are per-session — pass `sessionKey` (preferred) or the legacy `conversationId` alias to retrieve a single session's log from first [spawn] to final [process-exit]. type=agent-stream: per-session tool-use/tool-result archive (every `[tool-use]` and `[tool-result]` pair with full input + output JSON, plus raw Claude stream-json, agent events, and MCP server stderr via tee). USE THIS when investigating what an agent ACTUALLY did with its tools — server.log only carries `[persist] tool-call persisted` markers, not bodies. (`type=system` is a backwards-compatible alias for the same archive.) type=session: SSE events sent to client. type=error: Claude subprocess stderr (raw — NODE_DEBUG HTTP/NET/UNDICI traces land in agent-stream via the stream tee, not here). type=heartbeat: platform event dispatcher (check-due-events cron). type=public: public agent diagnostic log. type=server: platform server log. type=mcp: MCP server stderr (per-plugin raw). type=vnc: VNC browser viewer lifecycle.", {
+eagerTool(server, "logs-read", "Read recent logs. Stream logs (type=agent-stream/error/session/public) are per-session — pass `sessionKey` (preferred) or the legacy `sessionId` alias to retrieve a single session's log from first [spawn] to final [process-exit]. type=agent-stream: per-session tool-use/tool-result archive (every `[tool-use]` and `[tool-result]` pair with full input + output JSON, plus raw Claude stream-json, agent events, and MCP server stderr via tee). USE THIS when investigating what an agent ACTUALLY did with its tools — server.log only carries `[persist] tool-call persisted` markers, not bodies. (`type=system` is a backwards-compatible alias for the same archive.) type=session: SSE events sent to client. type=error: Claude subprocess stderr (raw — NODE_DEBUG HTTP/NET/UNDICI traces land in agent-stream via the stream tee, not here). type=heartbeat: platform event dispatcher (check-due-events cron). type=public: public agent diagnostic log. type=server: platform server log. type=mcp: MCP server stderr (per-plugin raw). type=vnc: VNC browser viewer lifecycle.", {
     type: z.enum(["agent-stream", "system", "session", "error", "heartbeat", "public", "server", "mcp", "vnc"]).optional(),
     lines: z.number().optional(),
     sessionKey: z.string().optional(),
-    conversationId: z.string().optional(),
-}, async ({ type, lines = 50, sessionKey, conversationId }) => {
+    sessionId: z.string().optional(),
+}, async ({ type, lines = 50, sessionKey, sessionId }) => {
     if (!ACCOUNT_ID)
         return refuseNoAccount("logs-read");
     try {
         const LOG_DIR = resolve(getAccountDir(), "logs");
         // sessionKey is the single identifier on disk.
-        // `conversationId` is retained as a legacy alias that maps to the
+        // `sessionId` is retained as a legacy alias that maps to the
         // sessionKey-named file will collapse the alias in the UI.
-        const idForResolve = sessionKey ?? conversationId;
+        const idForResolve = sessionKey ?? sessionId;
         if (idForResolve) {
             if (!existsSync(LOG_DIR)) {
                 return { content: [{ type: "text", text: `Log directory does not exist: ${LOG_DIR}` }] };
@@ -1868,7 +1868,7 @@ eagerTool(server, "session-reset", "Reset the current session. Compacts conversa
 });
 eagerTool(server, "session-resume", "Resume a previous session. Loads the selected session's message history into the chat timeline " +
     "and routes new messages to that conversation. Call after the user selects a session from the " +
-    "session-list results. Pass the conversationId from the selected session.", { conversationId: z.string().uuid().describe("The conversationId of the session to resume") }, async () => {
+    "session-list results. Pass the sessionId from the selected session.", { sessionId: z.string().uuid().describe("The sessionId of the session to resume") }, async () => {
     if (!ACCOUNT_ID)
         return refuseNoAccount("session-resume");
     return { content: [{ type: "text", text: "resumed" }] };
@@ -2727,12 +2727,12 @@ function cleanupPendingAction(actionId) {
 }
 async function persistApprovalToolCall(opts) {
     // Write doctrine: a ToolCall without its owning Conversation is
-    // noise — every admin tool call belongs to a chat. When conversationId is
+    // noise — every admin tool call belongs to a chat. When sessionId is
     // missing or its Conversation cannot be matched, we log and skip the
     // persist rather than create an orphan ToolCall node. The legacy
     // OPTIONAL-MATCH + FOREACH pattern created orphans silently.
-    if (!opts.conversationId) {
-        console.error(`[approval] ToolCall skipped (no conversationId): tool=${opts.toolName} state=${opts.approvalState}`);
+    if (!opts.sessionId) {
+        console.error(`[approval] ToolCall skipped (no sessionId): tool=${opts.toolName} state=${opts.approvalState}`);
         return;
     }
     if (!ACCOUNT_ID) {
@@ -2747,7 +2747,7 @@ async function persistApprovalToolCall(opts) {
         const optionalFields = [
             opts.originalInput != null ? ", originalInput: $originalInput" : "",
         ].join("");
-        const res = await session.run(`MATCH (c:Conversation {conversationId: $conversationId})
+        const res = await session.run(`MATCH (c:Conversation {sessionId: $sessionId})
        CREATE (c)-[:HAS_TOOL_CALL]->(tc:ToolCall {
          callId: $callId,
          toolName: $toolName,
@@ -2758,7 +2758,7 @@ async function persistApprovalToolCall(opts) {
          agentType: 'admin',
          accountId: $accountId,
          approvalState: $approvalState,
-         conversationId: $conversationId,
+         sessionId: $sessionId,
          createdBySource: 'admin-approval',
          startedAt: datetime($startedAt),
          completedAt: datetime($completedAt)
@@ -2772,13 +2772,13 @@ async function persistApprovalToolCall(opts) {
             isError: opts.isError,
             accountId: ACCOUNT_ID,
             approvalState: opts.approvalState,
-            conversationId: opts.conversationId,
+            sessionId: opts.sessionId,
             startedAt: new Date().toISOString(),
             completedAt: new Date().toISOString(),
             ...(opts.originalInput != null ? { originalInput: opts.originalInput.slice(0, 300) } : {}),
         });
         if (res.summary.counters.updates().nodesCreated === 0) {
-            console.error(`[approval] ToolCall skipped (conversation ${opts.conversationId} not found): tool=${opts.toolName}`);
+            console.error(`[approval] ToolCall skipped (conversation ${opts.sessionId} not found): tool=${opts.toolName}`);
             return;
         }
         console.error(`[approval] ToolCall persisted: ${opts.toolName} state=${opts.approvalState}`);
@@ -2883,8 +2883,8 @@ eagerTool(server, "action-approve", "Approve a pending action and execute it imm
     "executed via the target plugin's MCP server. The result is returned and an audit " +
     "record is written to Neo4j with approvalState: approved.", {
     actionId: z.string().describe("The action ID to approve (from action-pending)"),
-    conversationId: z.string().optional().describe("Current conversation ID for audit trail linking"),
-}, async ({ actionId, conversationId }) => {
+    sessionId: z.string().optional().describe("Current conversation ID for audit trail linking"),
+}, async ({ actionId, sessionId }) => {
     if (!ACCOUNT_ID)
         return refuseNoAccount("action-approve");
     const action = readPendingAction(actionId);
@@ -2925,7 +2925,7 @@ eagerTool(server, "action-approve", "Approve a pending action and execute it imm
             output: result.text,
             isError: result.isError,
             approvalState: "approved",
-            conversationId,
+            sessionId,
         });
         cleanupPendingAction(actionId);
         return {
@@ -2943,7 +2943,7 @@ eagerTool(server, "action-approve", "Approve a pending action and execute it imm
             output: errMsg,
             isError: true,
             approvalState: "approved",
-            conversationId,
+            sessionId,
         });
         return {
             content: [{ type: "text", text: `Action approved but execution failed: ${errMsg}` }],
@@ -2955,8 +2955,8 @@ eagerTool(server, "action-reject", "Reject a pending action. The action is not e
     "to Neo4j with approvalState: rejected.", {
     actionId: z.string().describe("The action ID to reject (from action-pending)"),
     reason: z.string().optional().describe("Optional reason for rejection"),
-    conversationId: z.string().optional().describe("Current conversation ID for audit trail linking"),
-}, async ({ actionId, reason, conversationId }) => {
+    sessionId: z.string().optional().describe("Current conversation ID for audit trail linking"),
+}, async ({ actionId, reason, sessionId }) => {
     if (!ACCOUNT_ID)
         return refuseNoAccount("action-reject");
     const action = readPendingAction(actionId);
@@ -2987,7 +2987,7 @@ eagerTool(server, "action-reject", "Reject a pending action. The action is not e
         output: `Rejected by admin.${reasonSuffix}`,
         isError: false,
         approvalState: "rejected",
-        conversationId,
+        sessionId,
     });
     cleanupPendingAction(actionId);
     return {
@@ -2999,8 +2999,8 @@ eagerTool(server, "action-edit", "Edit a pending action's input and then execute
     "action (e.g., change the email subject) before approving.", {
     actionId: z.string().describe("The action ID to edit (from action-pending)"),
     editedInput: z.string().describe("The modified tool input as a JSON string"),
-    conversationId: z.string().optional().describe("Current conversation ID for audit trail linking"),
-}, async ({ actionId, editedInput, conversationId }) => {
+    sessionId: z.string().optional().describe("Current conversation ID for audit trail linking"),
+}, async ({ actionId, editedInput, sessionId }) => {
     if (!ACCOUNT_ID)
         return refuseNoAccount("action-edit");
     const action = readPendingAction(actionId);
@@ -3051,7 +3051,7 @@ eagerTool(server, "action-edit", "Edit a pending action's input and then execute
             isError: result.isError,
             approvalState: "approved",
             originalInput: JSON.stringify(originalInput),
-            conversationId,
+            sessionId,
         });
         cleanupPendingAction(actionId);
         return {
@@ -3070,7 +3070,7 @@ eagerTool(server, "action-edit", "Edit a pending action's input and then execute
             isError: true,
             approvalState: "approved",
             originalInput: JSON.stringify(originalInput),
-            conversationId,
+            sessionId,
         });
         return {
             content: [{ type: "text", text: `Action edited and approved but execution failed: ${errMsg}` }],
@@ -3079,6 +3079,47 @@ eagerTool(server, "action-edit", "Edit a pending action's input and then execute
     }
 });
 // ===================================================================
+// Per-turn graph-pass skip sentinel (Task 440)
+// ===================================================================
+//
+// Deterministic decline signal for the per-turn graph-pass gate Stop hook
+// (`platform/plugins/admin/hooks/per-turn-graph-pass-gate.sh`). The hook
+// walks the operator's JSONL for any `tool_use` of THIS tool's exact name
+// since the latest real-user message and, when present, releases the Stop
+// gate with `via=skip-sentinel`. The other release path is a `Task` tool_use
+// with `input.subagent_type=database-operator` (admin dispatched writes).
+// Both paths remove the LLM from the per-turn discretion path entirely
+// ([[feedback_doctrine_paragraph_is_not_a_gate]]).
+server.tool("pre-turn-graph-pass-skip", "Marks the current operator turn as having no new graph writes to dispatch. Call this when the just-submitted operator turn is a pure acknowledgement, contains no new named entities / ideas / commitments / contacts / learnings, or is otherwise already fully covered by the prior-writes skip-list in the pre-turn graph-pass directive. The per-turn Stop gate releases on the presence of this tool_use in the transcript since the latest real-user message - calling it is the deterministic signal that you considered the turn and chose not to write. The other release path is a Task dispatch to the `database-operator` specialist; call THAT when there are writes to do, and call THIS when there are not. Do not call both.", {
+    reason: z.string().min(1).describe("Short tag explaining why the turn warrants no writes. Free-form, e.g. `no-new-entities`, `turn-is-acknowledgement`, `already-covered-by-prior-writes`, `operator-asked-for-existing-data`. Recorded for audit; not used for control flow."),
+}, async ({ reason }) => {
+    const sessionId = process.env.SESSION_ID || "unknown";
+    const line = `skip sessionId=${sessionId} reason=${reason}`;
+    if (!PLATFORM_PORT) {
+        console.error(`[per-turn-graph-pass-gate] 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: "per-turn-graph-pass-gate", level: "info", line }),
+                signal: AbortSignal.timeout(2000),
+            });
+        }
+        catch (err) {
+            console.error(`[per-turn-graph-pass-gate] log-ingest-failed sessionId=${sessionId} err=${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return {
+        content: [{
+                type: "text",
+                text: `Per-turn graph pass marked skipped (reason=${reason}). The gate will release this turn.`,
+            }],
+    };
+});
+// ===================================================================
 // Session-end retrospective sentinel (Task 282)
 // ===================================================================
 //