@rubytech/create-realagent-code 0.1.253 → 0.1.255

package/payload/platform/plugins/admin/hooks/insight.sh

@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — on-demand `/insight`. When the operator types the
+# literal token `/insight` as a standalone message (or a standalone line), the
+# admin agent runs a four-pass review (technical learnings, operator-
+# relationship updates, graph-completeness sweep, typed-edge auto-extraction)
+# over the session so far and calls the deterministic
+# `session-retrospective-mark-complete` MCP sentinel — then the session
+# CONTINUES. Nothing is blocked, terminated, reset, or cleared. Task 634
+# replaced the Task 282 session-end Stop gate with this trigger; the four
+# passes and the sentinel call are byte-for-byte the same process — only the
+# trigger and timing changed.
+#
+# Trigger detection. The token is read from the `prompt` field of the
+# UserPromptSubmit stdin envelope, case-insensitively, matching the whole
+# message (after .strip()) OR a standalone line within it — never embedded in
+# prose. This is the same whole-message / standalone-line discipline the
+# session-end gate applied to its end-intent tokens; it keeps "give me some
+# /insight into the numbers" from false-triggering.
+#
+# Injection. On a match the four-pass instruction is printed to STDOUT.
+# UserPromptSubmit stdout is appended to the turn as additional context, so the
+# agent receives the instruction alongside the operator's `/insight` message.
+# Structured logs go through POST /api/admin/log-ingest (never stdout), so the
+# injected context stays clean. There is no exit-2 path and no stderr
+# instruction — UserPromptSubmit cannot and must not block the turn.
+#
+# Standing reconciliation (no-event failure detector). The run-and-continue
+# model removes the Stop gate that previously forced completion, so the
+# dominant failure mode is "triggered but never completed" — the agent injects
+# the instruction, returns prose, and never calls the sentinel. Because this
+# hook fires on every prompt, it scans the transcript (`transcript_path`) each
+# invocation for the latest real-user turn whose text matches `/insight`; when
+# no `session-retrospective-mark-complete` tool_use appears after that turn it
+# emits `[insight] prior-incomplete sessionId=<id> triggered-turn=<idx>`. This
+# surfaces an unfinished pass on the next prompt without waiting for session
+# end and without reproducing the failure.
+# [[feedback_no_stdout_parsing_for_control_flow]] — the trigger is a literal
+# token match, never prose parsing.
+#
+# Gating (common guards live in `lib/admin-graph-pass-common.sh`):
+#   - role-not-admin / is-specialist / empty-stdin / missing-transcript:
+#     handled by the shared helper, emit `trigger-skipped` and exit 0.
+#   - no-insight-token: the prompt carries no standalone `/insight` token,
+#     emit `trigger-skipped` and exit 0.
+#
+# Input: Claude Code's UserPromptSubmit stdin shape
+#   { "session_id": "<id>", "transcript_path": "<jsonl path>",
+#     "prompt": "<operator message>", "hook_event_name": "UserPromptSubmit" }
+
+set -uo pipefail
+
+AGP_LOG_TAG="insight"
+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
+
+# Extract the operator's raw prompt from the envelope. Empty when absent.
+PROMPT=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    p = d.get("prompt", "") or ""
+    sys.stdout.write(p if isinstance(p, str) else "")
+except Exception:
+    pass
+' 2>/dev/null)
+
+# Single Python pass reports two facts on one line:
+#   1. Whether PROMPT carries a standalone `/insight` token → token or empty.
+#   2. Reconciliation: the index of the latest real-user transcript turn whose
+#      text matches `/insight` that has NO subsequent
+#      `session-retrospective-mark-complete` tool_use → index or empty.
+# Output: <trigger-token-or-empty>\t<prior-incomplete-idx-or-empty>
+INSPECTION=$(PROMPT="$PROMPT" TRANSCRIPT_PATH="$TRANSCRIPT_PATH" python3 - <<'PY'
+import os, json
+
+SENTINEL_TOOL = "mcp__admin__session-retrospective-mark-complete"
+TOKEN = "/insight"
+
+def text_has_standalone_token(text):
+    # Case-insensitive: token is the whole message (after strip) OR a
+    # standalone line within it. Never matches the token embedded in prose.
+    if not text:
+        return False
+    haystacks = {text.strip().lower()}
+    for line in text.splitlines():
+        s = line.strip().lower()
+        if s:
+            haystacks.add(s)
+    return TOKEN in haystacks
+
+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 isinstance(b, dict) and b.get("type") == "text":
+                t = b.get("text")
+                if isinstance(t, str):
+                    out.append(t)
+        return "".join(out)
+    return ""
+
+def is_assistant(rec):
+    return (isinstance(rec, dict) and rec.get("type") == "assistant"
+            and isinstance(rec.get("message"), dict)
+            and rec["message"].get("role") == "assistant")
+
+def assistant_tool_use_names(rec):
+    if not is_assistant(rec):
+        return []
+    content = rec["message"].get("content")
+    if not isinstance(content, list):
+        return []
+    return [b.get("name") for b in content
+            if isinstance(b, dict) and b.get("type") == "tool_use"
+            and isinstance(b.get("name"), str)]
+
+# Trigger — read from the prompt field, not the transcript.
+trigger = TOKEN if text_has_standalone_token(os.environ.get("PROMPT", "")) else ""
+
+# Reconciliation — scan the transcript for the latest real-user `/insight`
+# turn and check whether a sentinel tool_use follows it.
+records = []
+try:
+    with open(os.environ["TRANSCRIPT_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:
+    records = []
+
+latest_insight_idx = -1
+for i in range(len(records) - 1, -1, -1):
+    if is_real_user(records[i]) and text_has_standalone_token(extract_user_text(records[i])):
+        latest_insight_idx = i
+        break
+
+prior_incomplete = ""
+if latest_insight_idx != -1:
+    after = records[latest_insight_idx + 1:]
+    # "Triggered but never completed" means the agent RESPONDED to the
+    # `/insight` turn (≥1 assistant record after it) yet never called the
+    # sentinel. Requiring an assistant record excludes the just-submitted
+    # `/insight` turn — which has no response yet — so a genuine trigger
+    # never self-reports as incomplete, regardless of whether Claude Code
+    # has already written the current prompt to the transcript.
+    assistant_after = any(is_assistant(r) for r in after)
+    sentinel_after = any(SENTINEL_TOOL in assistant_tool_use_names(r) for r in after)
+    if assistant_after and not sentinel_after:
+        prior_incomplete = str(latest_insight_idx)
+
+print(f"{trigger}\t{prior_incomplete}")
+PY
+)
+TRIGGER_TOKEN="${INSPECTION%%	*}"
+PRIOR_INCOMPLETE_IDX="${INSPECTION#*	}"
+
+# Standing reconciliation emit — independent of the current trigger.
+if [ -n "$PRIOR_INCOMPLETE_IDX" ]; then
+  agp_emit_log "prior-incomplete sessionId=${SESSION_ID} triggered-turn=${PRIOR_INCOMPLETE_IDX}"
+fi
+
+if [ -z "$TRIGGER_TOKEN" ]; then
+  agp_emit_log "trigger-skipped sessionId=${SESSION_ID} reason=no-insight-token"
+  exit 0
+fi
+
+agp_emit_log "trigger sessionId=${SESSION_ID} token=${TRIGGER_TOKEN}"
+
+cat <<'INSTRUCTION'
+The operator requested an insight pass — run the four passes now over the session so far, then keep going in this same session. Do NOT call `session-reset`, do NOT clear the context, do NOT end the session: the conversation continues afterward and the operator (or a parallel session) keeps working against the same live state. 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.
+
+Pass 4 — Typed-edge auto-extraction. Delegate to `database-operator` via the Task tool with a prompt naming the typed-edge pass and the session-start timestamp. The specialist calls `memory-typed-edge-pass` with that timestamp and returns the counters. Capture `nodesProcessed` and the accepted count from its reply.
+
+Then call `session-retrospective-mark-complete` with all five counts (learningsCount, preferencesCount, graphWriteCount, typedEdgesCount, nodesProcessed) and reply with one short paragraph in your house voice summarising what you wrote — then carry on with the operator's work.
+INSTRUCTION
+
+exit 0

package/payload/platform/plugins/admin/hooks/lib/admin-graph-pass-common.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # Shared plumbing for the admin-side hook that orchestrates admin-walked
-# graph writes: `session-end-retrospective.sh` (Stop on operator end-intent).
-# Originally introduced (Task 439) as shared plumbing across two hooks; the
+# graph writes: `insight.sh` (UserPromptSubmit on the operator's `/insight`
+# token). Originally introduced (Task 439) as shared plumbing across two hooks; the
 # per-turn sibling was removed in Task 447 because session-end Pass 3 already
 # performs the graph-completeness sweep. The library is retained — its
 # stdin parse, role / specialist / transcript guards, log-ingest envelope,
@@ -10,7 +10,7 @@
 #
 # Caller contract:
 #   1. Set `AGP_LOG_TAG` to the hook's identifying tag before sourcing.
-#      `session-retrospective` is the current value; the helper itself
+#      `insight` is the current value; the helper itself
 #      does not log under its own tag.
 #   2. Source this file.
 #   3. Call `agp_setup_logging`, `agp_read_stdin`, `agp_parse_stdin`,
@@ -122,7 +122,7 @@ agp_guard_role_specialist() {
 }
 
 # Usage: agp_guard_transcript [require-stdin]
-# Pass `require-stdin` (session-end-retrospective) to emit `empty-stdin` on a
+# Pass `require-stdin` (insight.sh) to emit `empty-stdin` on a
 # blank `INPUT`. Without the flag, parse failure on a non-empty INPUT
 # collapses to `missing-transcript` cleanly.
 agp_guard_transcript() {
@@ -138,7 +138,7 @@ agp_guard_transcript() {
 
 # Walks $TRANSCRIPT_PATH and reports, in one line on stdout:
 #   <real-user-present:yes|no>\t<matched-tool-name-or-empty>
-# A "real user" record matches `session-end-retrospective.sh`'s `is_real_user`
+# A "real user" record matches `insight.sh`'s `is_real_user`
 # — `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, never turn starts.

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 { embed } from "../../../../lib/embed-client/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";
@@ -913,6 +914,17 @@ eagerTool(server, "admin-add", "Add a new admin user to this account. Creates a
             const firstSpace = trimmedName.search(/\s/);
             const givenName = firstSpace === -1 ? trimmedName : trimmedName.slice(0, firstSpace).trim();
             const familyName = firstSpace === -1 ? null : (trimmedName.slice(firstSpace + 1).trim() || null);
+            // Task 636 — :Person is vector-indexed; embed the admin-personal Person
+            // at write time so it is findable by semantic memory-search, not only
+            // after a reindex. A failed embed sets null (audit catches it) and the
+            // write proceeds — embedding must never block PIN setup.
+            let personEmbedding = null;
+            try {
+                personEmbedding = await embed(`[Person] ${[givenName, familyName].filter(Boolean).join(" ")} role: admin-personal`);
+            }
+            catch (err) {
+                process.stderr.write(`[graph-write] warn reason=embed-failed labels=Person agent=admin-add detail=${err instanceof Error ? err.message : String(err)}\n`);
+            }
             // stamp `accountId` on every AdminUser at MERGE time, both
             // ON CREATE and ON MATCH (the latter via COALESCE so a pre-existing
             // value isn't overwritten if it differs — which would itself be a
@@ -949,12 +961,13 @@ eagerTool(server, "admin-add", "Add a new admin user to this account. Creates a
                familyName: $familyName,
                role: 'admin-personal',
                scope: 'admin',
+               embedding: $personEmbedding,
                createdAt: $createdAt
              })
              MERGE (au)-[:OWNS]->(newPerson)
              RETURN false AS reused
            }
-           RETURN reused`, { userId, name: trimmedName, createdAt, accountId: ACCOUNT_ID, givenName, familyName });
+           RETURN reused`, { userId, name: trimmedName, createdAt, accountId: ACCOUNT_ID, givenName, familyName, personEmbedding });
             if (result.records.length > 0) {
                 personReused = result.records[0].get("reused");
             }
@@ -3089,27 +3102,28 @@ eagerTool(server, "action-edit", "Edit a pending action's input and then execute
     }
 });
 // ===================================================================
-// Session-end retrospective sentinel (Task 282)
+// Insight-pass completion sentinel (Task 282, retriggered on-demand by Task 634)
 // ===================================================================
 //
-// 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
+// Deterministic completion signal for the on-demand `/insight` pass
+// (`platform/plugins/admin/hooks/insight.sh`, a UserPromptSubmit hook). The
+// hook injects the four-pass instruction when the operator types `/insight`;
+// this tool_use is the agent's record that all four passes ran. Calling it
+// does not block, release, or end anything — the session continues. Its
+// absence after an `/insight` turn is what the hook's standing reconciliation
+// surfaces as `[insight] prior-incomplete`
 // ([[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, missing graph writes, and the typed-edge auto-extraction pass — and persisting each one (Task-tool delegations to database-operator for graph writes and the typed-edge pass, 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."),
+//   trigger → complete   (and, on failure, trigger with no following complete)
+// against one operator sessionId.
+server.tool("session-retrospective-mark-complete", "Marks an on-demand insight pass complete. Call this AFTER walking the session for technical learnings, operator-relationship updates, missing graph writes, and the typed-edge auto-extraction pass — and persisting each one (Task-tool delegations to database-operator for graph writes and the typed-edge pass, Write to SOUL.md for tonal updates). The counts you pass are the number of items you actually persisted in each pass. Calling it records that the insight pass ran; it does not block or end the session — keep working afterward.", {
+    learningsCount: z.number().int().nonnegative().describe("Technical-learning / correction nodes you delegated to database-operator in this insight pass."),
+    preferencesCount: z.number().int().nonnegative().describe("SOUL.md writes you made for tonal / working-style observations in this insight pass."),
     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."),
-    typedEdgesCount: z.number().int().nonnegative().describe("Typed edges accepted (MERGEd) by the typed-edge auto-extraction pass that database-operator ran in this retrospective. 0 is valid (no prose nodes touched or none yielded edges)."),
-    nodesProcessed: z.number().int().nonnegative().describe("Prose-bearing nodes the typed-edge pass enumerated and scanned in this retrospective. 0 is valid (no prose nodes since the session started)."),
+    typedEdgesCount: z.number().int().nonnegative().describe("Typed edges accepted (MERGEd) by the typed-edge auto-extraction pass that database-operator ran in this insight pass. 0 is valid (no prose nodes touched or none yielded edges)."),
+    nodesProcessed: z.number().int().nonnegative().describe("Prose-bearing nodes the typed-edge pass enumerated and scanned in this insight pass. 0 is valid (no prose nodes since the session started)."),
 }, async ({ learningsCount, preferencesCount, graphWriteCount, typedEdgesCount, nodesProcessed }) => {
     const sessionId = process.env.SESSION_ID || "unknown";
     const line = `complete sessionId=${sessionId} learningsCount=${learningsCount} preferencesCount=${preferencesCount} graphWriteCount=${graphWriteCount} typedEdgesCount=${typedEdgesCount} nodesProcessed=${nodesProcessed}`;
@@ -3120,7 +3134,7 @@ server.tool("session-retrospective-mark-complete", "Marks the end-of-session ret
         // 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)}`);
+        console.error(`[insight] log-ingest-skipped sessionId=${sessionId} reason=missing-env env=PLATFORM_PORT line=${JSON.stringify(line)}`);
     }
     else {
         try {
@@ -3128,7 +3142,7 @@ server.tool("session-retrospective-mark-complete", "Marks the end-of-session ret
             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 }),
+                body: JSON.stringify({ tag: "insight", level: "info", line }),
                 signal: AbortSignal.timeout(2000),
             });
         }
@@ -3137,13 +3151,13 @@ server.tool("session-retrospective-mark-complete", "Marks the end-of-session ret
             // 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)}`);
+            console.error(`[insight] 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} typedEdges=${typedEdgesCount} nodesProcessed=${nodesProcessed}). Session is now free to end.`,
+                text: `Insight pass marked complete (learnings=${learningsCount} preferences=${preferencesCount} graphWrites=${graphWriteCount} typedEdges=${typedEdgesCount} nodesProcessed=${nodesProcessed}). The session continues — carry on with the operator's work.`,
             }],
     };
 });