@rubytech/create-maxy-code 0.1.158 → 0.1.161

package/payload/platform/plugins/admin/hooks/per-turn-graph-pass-gate.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Stop hook — per-turn gate. Task 440.
+#
+# Mirrors `session-end-retrospective.sh`'s structural primitive (exit 2 +
+# stderr instruction + sentinel-grep release) but fires on every admin turn
+# end rather than only on operator end-intent. Closes the gap left when
+# Task 425 moved the per-turn graph pass off Stop onto UserPromptSubmit:
+# the UserPromptSubmit `additionalContext` directive carries the prior-writes
+# skip-list and the instruction, but admin can silently drop the directive
+# because UserPromptSubmit's only blocking shape erases the prompt without
+# feeding stderr to Claude. The structural fix is here — Stop's exit-2
+# stderr-to-Claude contract gives the gate a release path admin can act on.
+#
+# Release conditions, evaluated against the operator's JSONL since the
+# latest real-user message (string content OR a content list with at least
+# one non-`tool_result` block):
+#   A. admin dispatched the writes — a `Task` `tool_use` whose
+#      `input.subagent_type` is `database-operator` appeared.
+#   B. admin declined the writes — a `tool_use` whose `name` is exactly
+#      `mcp__admin__pre-turn-graph-pass-skip` appeared. The sentinel takes a
+#      `reason` string (free-form, e.g. `no-new-entities`,
+#      `turn-is-acknowledgement`); the tool records the call for audit but
+#      takes no graph action.
+#
+# Either release path emits `gate-released sessionId=<id> via=<dispatch|skip-sentinel>`
+# and exits 0. Both Stop-hook tags emit independently and compose: the
+# session-end retrospective gates only on `/end` intent and uses its own
+# sentinel; this hook gates every turn and uses the two release patterns
+# above.
+#
+# Recursion guard — the shared `agp_guard_role_specialist` skips when
+# `MAXY_SPECIALIST` is set, so the database-operator subagent's own turn
+# end never re-triggers this gate.
+#
+# Loop-safety — once release path A or B fires, the matching tool_use sits
+# in the JSONL and every subsequent Stop on the same operator-prompt window
+# sees it and exits 0 with `gate-released`. The Task 412 loop case is
+# avoided because the release decision is JSONL-based, never a re-fire of
+# the directive.
+#
+# Input: Claude Code's Stop hook stdin shape
+#   { "session_id": "<intrinsic>", "transcript_path": "<jsonl path>", ... }
+
+set -uo pipefail
+
+AGP_LOG_TAG="per-turn-graph-pass-gate"
+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
+# shellcheck source=lib/admin-graph-pass-common.sh
+source "$AGP_LIB"
+
+agp_setup_logging
+agp_read_stdin
+agp_parse_stdin
+agp_guard_role_specialist
+agp_guard_transcript require-stdin
+
+# Release alternation: the MCP-prefixed skip-sentinel name, or a Task
+# tool_use with `input.subagent_type=database-operator` (matched as the
+# synthetic name `Task:database-operator` by the helper).
+RELEASE_PATTERN='mcp__admin__pre-turn-graph-pass-skip|Task:database-operator'
+
+INSPECTION=$(agp_scan_post_user_toolnames "$RELEASE_PATTERN")
+USER_PRESENT="${INSPECTION%%	*}"
+MATCHED_NAME="${INSPECTION#*	}"
+
+if [ "$USER_PRESENT" != "yes" ]; then
+  # No real-user message in the transcript yet — e.g. the SessionStart
+  # bootstrap turn, an empty transcript, or a session that only contains
+  # tool_result-shaped user records. Nothing to gate against.
+  agp_emit_log "trigger-skipped sessionId=${SESSION_ID} reason=no-real-user"
+  exit 0
+fi
+
+if [ -n "$MATCHED_NAME" ]; then
+  case "$MATCHED_NAME" in
+    Task:database-operator)
+      VIA="dispatch"
+      ;;
+    mcp__admin__pre-turn-graph-pass-skip)
+      VIA="skip-sentinel"
+      ;;
+    *)
+      VIA="unknown"
+      ;;
+  esac
+  agp_emit_log "gate-released sessionId=${SESSION_ID} via=${VIA}"
+  exit 0
+fi
+
+agp_emit_log "gate-blocked sessionId=${SESSION_ID} reason=sentinel-absent"
+
+cat >&2 <<'INSTRUCTION'
+Before this turn closes, do the per-turn graph pass. Scan the operator's latest message for any new graph-worthy content not already covered by the prior-writes block in this turn's pre-turn-graph-pass directive — mentions of named entities, ideas or learnings the operator stated, contacts named for the first time, tasks the operator committed to, decisions, anything the schema admits.
+
+For each candidate write, dispatch one Task to the `database-operator` specialist with a brief that names the label, the relevant properties, and (when attaching to an existing node) the elementId from the prior-writes list. Skip writes the prior-writes list already covers.
+
+If the turn supports no new writes, call the `pre-turn-graph-pass-skip` MCP tool with a short `reason` (e.g. `no-new-entities`, `turn-is-acknowledgement`) so the gate releases. Calling that tool is the deterministic signal that you considered the turn and chose not to write.
+
+Either path releases this gate and lets the turn close. Do not surface this dispatch in your reply to the operator.
+INSTRUCTION
+
+exit 2

package/payload/platform/plugins/admin/hooks/pre-turn-graph-pass.sh

@@ -64,7 +64,14 @@ fi
 agp_guard_role_specialist
 agp_guard_transcript
 
-CONVERSATION_ID="${CONVERSATION_NODE_ID:-}"
+# Task 429 — the env var carries the graph `:Conversation.sessionId`.
+# Claude Code's own stdin `session_id` field (parsed into `SESSION_ID`
+# by `agp_parse_stdin`) is a distinct identifier (JSONL filename); one
+# graph sessionId can map to many Claude session ids. Shadow the lib's
+# `SESSION_ID` into `CLAUDE_SESSION_ID` so the rest of this hook can
+# refer to the graph identifier as `SESSION_ID` without collision.
+CLAUDE_SESSION_ID="$SESSION_ID"
+SESSION_ID="${SESSION_NODE_ID:-}"
 
 # Fetch the actual content of every node already written under this
 # conversation, account-scoped. The route runs loopback-only — the hook
@@ -74,9 +81,9 @@ CONVERSATION_ID="${CONVERSATION_NODE_ID:-}"
 # elementId admin already resolved when attaching to an existing node).
 PRIOR_WRITES="(none)"
 PRIOR_WRITES_COUNT=0
-if [ -n "$CONVERSATION_ID" ]; then
+if [ -n "$SESSION_ID" ]; then
   CONTEXT_JSON=$(curl -sS --max-time 5 -G \
-    --data-urlencode "conversationId=${CONVERSATION_ID}" \
+    --data-urlencode "sessionId=${SESSION_ID}" \
     --data-urlencode "accountId=${ACCOUNT_ID:-}" \
     "$CONTEXT_URL" 2>/dev/null || echo '')
   if [ -n "$CONTEXT_JSON" ]; then
@@ -120,8 +127,8 @@ fi
 # Compose the directive body before logging so contextBytes reflects
 # the actual payload size handed to admin (skip-list + directive prose).
 DIRECTIVE_BODY=$(ACCOUNT_ID_OUT="${ACCOUNT_ID:-<unset>}" \
-  SESSION_ID_OUT="${SESSION_ID}" \
-  CONVERSATION_ID_OUT="${CONVERSATION_ID:-<unset>}" \
+  CLAUDE_SESSION_ID_OUT="${CLAUDE_SESSION_ID}" \
+  SESSION_ID_OUT="${SESSION_ID:-<unset>}" \
   PRIOR_WRITES_OUT="${PRIOR_WRITES}" \
   python3 - <<'PY'
 import os
@@ -135,8 +142,8 @@ body = (
     "If the turn supports no new writes, dispatch nothing. "
     "Do not surface these dispatches in your reply to the operator. After the dispatches return, continue with your normal response to the operator's prompt.\n\n"
     f"accountId: {os.environ['ACCOUNT_ID_OUT']}\n"
-    f"sessionId: {os.environ['SESSION_ID_OUT']}\n"
-    f"conversationId: {os.environ['CONVERSATION_ID_OUT']}\n\n"
+    f"claudeSessionId: {os.environ['CLAUDE_SESSION_ID_OUT']}\n"
+    f"sessionId: {os.environ['SESSION_ID_OUT']}\n\n"
     "<prior-writes>\n"
     f"{os.environ['PRIOR_WRITES_OUT']}\n"
     "</prior-writes>\n"
@@ -146,7 +153,7 @@ PY
 )
 CONTEXT_BYTES=${#DIRECTIVE_BODY}
 
-agp_emit_log "dispatch sessionId=${SESSION_ID} conversationId=${CONVERSATION_ID:-<unset>} directive-shape=admin-walks priorWritesCount=${PRIOR_WRITES_COUNT} contextBytes=${CONTEXT_BYTES} ms=0"
+agp_emit_log "dispatch claudeSessionId=${CLAUDE_SESSION_ID} sessionId=${SESSION_ID:-<unset>} directive-shape=admin-walks priorWritesCount=${PRIOR_WRITES_COUNT} contextBytes=${CONTEXT_BYTES} ms=0"
 
 # Emit the documented UserPromptSubmit JSON envelope on stdout. Python
 # handles JSON encoding so embedded newlines, quotes, and backslashes

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)
 // ===================================================================
 //