@rubytech/create-maxy-code 0.1.143 → 0.1.146

package/payload/platform/plugins/admin/hooks/signal-detector-stop.sh

@@ -1,309 +0,0 @@
-#!/usr/bin/env bash
-# Stop hook — gbrain signal-detector dispatch. Task 303.
-#
-# Fires on every admin-agent assistant end_turn. Inspects the operator's
-# JSONL transcript and decides whether to invoke the `signal-detector`
-# specialist to extract entity mentions and original-thinking candidates
-# from the conversation slice since the last dispatch.
-#
-# Trigger logic (must clear both gates to fire):
-#   - >= MIN_NEW_TURNS new real-user messages since the most recent
-#     in-transcript Task dispatch with subagent_type='signal-detector'
-#     (default 3 — overridable via MAXY_SIGNAL_DETECTOR_MIN_NEW_TURNS).
-#   - >= MIN_IDLE_MS milliseconds since the latest real-user message's
-#     `timestamp` (default 30_000 — overridable via
-#     MAXY_SIGNAL_DETECTOR_MIN_IDLE_MS). Captures "operator paused, not
-#     mid-thought".
-#
-# Recursion guard. The dispatch resolves through a Task tool call carrying
-# `subagent_type=signal-detector`; once such a call appears in the transcript
-# after the latest real-user message, the gate has already fired for this
-# turn and must NOT re-fire. Same shape as
-# session-end-retrospective.sh's sentinel grep
-# ([[feedback_no_stdout_parsing_for_control_flow]] /
-# [[feedback_doctrine_paragraph_is_not_a_gate]]) — control flow gates on a
-# structural tool_use, never on prose.
-#
-# Specialist auto-install on first fire. The template ships at
-# `$MAXY_TEMPLATES_DIR/specialists/agents/signal-detector.md` (or
-# `$ACCOUNT_DIR/../templates/...` via PLATFORM_ROOT). On the first fire
-# that decides to dispatch, the hook idempotently copies the template into
-# `$ACCOUNT_DIR/specialists/agents/` and appends the AGENTS.md routing line
-# if absent — so signal-detector is platform-core (no operator install
-# step) without surgery on the onboarding flow.
-#
-# Gating (emits via `/api/admin/log-ingest`; 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 dispatch
-# directive):
-#   - MAXY_SESSION_ROLE must equal "admin"            → reason=role-not-admin
-#   - MAXY_SPECIALIST must be empty                   → reason=is-specialist
-#   - Stop-hook stdin must be non-empty               → reason=empty-stdin
-#   - transcript_path must exist on disk              → reason=missing-transcript
-#   - new real-user turns since last fire < MIN_NEW   → reason=below-turn-threshold
-#   - idle_ms < MIN_IDLE_MS                           → reason=below-idle-threshold
-#   - latest real-user message older than the latest  → reason=already-dispatched
-#     signal-detector dispatch
-#
-# Blocks:
-#   - gate-blocked sessionId=<id> reason=dispatching newTurns=<n> idleMs=<n>
-#
-# Input: Claude Code's Stop hook stdin shape
-#   { "session_id": "<intrinsic>", "transcript_path": "<jsonl path>", ... }
-
-set -uo pipefail
-
-MIN_NEW_TURNS="${MAXY_SIGNAL_DETECTOR_MIN_NEW_TURNS:-3}"
-MIN_IDLE_MS="${MAXY_SIGNAL_DETECTOR_MIN_IDLE_MS:-30000}"
-
-UI_PORT="${MAXY_UI_INTERNAL_PORT:-}"
-if [ -z "$UI_PORT" ]; then
-  echo "[signal-detector-hook] trigger-skipped 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_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": "signal-detector-hook", "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 (database-operator, signal-detector
-# itself, etc.) stamps `MAXY_SPECIALIST` on its PTY env. Skip — the hook
-# only fires on the operator's own admin session, never on a subagent's
-# own stop.
-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
-
-# Single Python pass over the transcript. Returns three tab-separated
-# fields:
-#   1. count of real-user messages whose timestamp is more recent than the
-#      latest in-transcript Task dispatch with subagent_type=signal-detector
-#      (or, when no such dispatch exists yet, the total real-user count)
-#   2. idle_ms — milliseconds between the latest real-user message's
-#      timestamp and now (hook fire time)
-#   3. excerpt — the latest real-user message's text, truncated to 2000
-#      chars and base64-encoded so newlines and quotes survive the shell
-#      round-trip
-INSPECTION=$(TRANSCRIPT_PATH="$TRANSCRIPT_PATH" python3 - <<'PY'
-import os, json, base64
-from datetime import datetime, timezone
-
-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 latest_signal_detector_dispatch_index(records):
-    """Return the index of the most recent assistant tool_use of `Task`
-    whose `subagent_type` is `signal-detector`, or -1 if none."""
-    for i in range(len(records) - 1, -1, -1):
-        rec = records[i]
-        if not isinstance(rec, dict) or rec.get("type") != "assistant":
-            continue
-        msg = rec.get("message", {}) or {}
-        if msg.get("role") != "assistant":
-            continue
-        content = msg.get("content")
-        if not isinstance(content, list):
-            continue
-        for b in content:
-            if not isinstance(b, dict) or b.get("type") != "tool_use":
-                continue
-            if b.get("name") != "Task":
-                continue
-            inp = b.get("input", {})
-            if isinstance(inp, dict) and inp.get("subagent_type") == "signal-detector":
-                return i
-    return -1
-
-path = os.environ["TRANSCRIPT_PATH"]
-records = []
-try:
-    with open(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:
-    # Fail-open — print empty fields, the bash side will treat as missing.
-    print("0\t0\t")
-    raise SystemExit(0)
-
-last_dispatch_idx = latest_signal_detector_dispatch_index(records)
-
-# Count real-user messages after last_dispatch_idx (exclusive); when
-# last_dispatch_idx is -1, count from the start.
-new_user_count = 0
-latest_user_ts = None
-latest_user_text = ""
-start = last_dispatch_idx + 1
-for i in range(start, len(records)):
-    rec = records[i]
-    if is_real_user(rec):
-        new_user_count += 1
-        ts = rec.get("timestamp") or ""
-        if isinstance(ts, str) and ts:
-            latest_user_ts = ts
-            latest_user_text = extract_user_text(rec).strip()
-
-if latest_user_ts is None:
-    print(f"{new_user_count}\t0\t")
-    raise SystemExit(0)
-
-try:
-    # JSONL timestamps from Claude Code are ISO 8601 with Z suffix.
-    parsed = datetime.fromisoformat(latest_user_ts.replace("Z", "+00:00"))
-    now = datetime.now(timezone.utc)
-    idle_ms = max(0, int((now - parsed).total_seconds() * 1000))
-except Exception:
-    idle_ms = 0
-
-excerpt = latest_user_text[:2000]
-b64 = base64.b64encode(excerpt.encode("utf-8")).decode("ascii")
-print(f"{new_user_count}\t{idle_ms}\t{b64}")
-PY
-)
-NEW_TURNS="${INSPECTION%%	*}"
-REMAINING="${INSPECTION#*	}"
-IDLE_MS="${REMAINING%%	*}"
-EXCERPT_B64="${REMAINING#*	}"
-
-# Throttle gates.
-if [ "$NEW_TURNS" -eq 0 ] 2>/dev/null; then
-  emit_log "trigger-skipped sessionId=${SESSION_ID} reason=already-dispatched newTurns=0"
-  exit 0
-fi
-if [ "$NEW_TURNS" -lt "$MIN_NEW_TURNS" ] 2>/dev/null; then
-  emit_log "trigger-skipped sessionId=${SESSION_ID} reason=below-turn-threshold newTurns=${NEW_TURNS} threshold=${MIN_NEW_TURNS}"
-  exit 0
-fi
-if [ "$IDLE_MS" -lt "$MIN_IDLE_MS" ] 2>/dev/null; then
-  emit_log "trigger-skipped sessionId=${SESSION_ID} reason=below-idle-threshold idleMs=${IDLE_MS} threshold=${MIN_IDLE_MS}"
-  exit 0
-fi
-
-# Specialist auto-install. The template lives under
-# `$PLATFORM_ROOT/templates/specialists/agents/signal-detector.md`. The
-# installer / seeder copies templates to per-account dirs at onboarding;
-# this fallback heals an account that pre-dates the template's existence
-# without forcing the operator to re-run onboarding.
-PLATFORM_ROOT_FALLBACK="${MAXY_PLATFORM_ROOT:-}"
-ACCOUNT_DIR_LOCAL="${ACCOUNT_DIR:-}"
-SPECIALIST_TARGET="${ACCOUNT_DIR_LOCAL}/specialists/agents/signal-detector.md"
-if [ -n "$ACCOUNT_DIR_LOCAL" ] && [ ! -f "$SPECIALIST_TARGET" ] && [ -n "$PLATFORM_ROOT_FALLBACK" ]; then
-  TEMPLATE_SRC="${PLATFORM_ROOT_FALLBACK}/templates/specialists/agents/signal-detector.md"
-  if [ -f "$TEMPLATE_SRC" ]; then
-    mkdir -p "$(dirname "$SPECIALIST_TARGET")" 2>/dev/null
-    cp "$TEMPLATE_SRC" "$SPECIALIST_TARGET" 2>/dev/null
-    AGENTS_MD="${ACCOUNT_DIR_LOCAL}/agents/admin/AGENTS.md"
-    if [ -f "$AGENTS_MD" ]; then
-      if ! grep -q "specialists:signal-detector" "$AGENTS_MD" 2>/dev/null; then
-        printf '%s\n' "- **specialists:signal-detector**: Background brain-compounder dispatched only by the admin-agent Stop hook (\`platform/plugins/admin/hooks/signal-detector-stop.sh\`). Never invoke manually." >> "$AGENTS_MD"
-      fi
-    fi
-    emit_log "bootstrap-installed sessionId=${SESSION_ID} target=${SPECIALIST_TARGET}"
-  fi
-fi
-
-EXCERPT_PREVIEW=$(printf '%s' "$EXCERPT_B64" | base64 --decode 2>/dev/null | head -c 200 | tr '\n' ' ')
-emit_log "gate-blocked sessionId=${SESSION_ID} reason=dispatching newTurns=${NEW_TURNS} idleMs=${IDLE_MS} preview=$(printf '%s' "$EXCERPT_PREVIEW" | sed 's/[\"]//g' | head -c 80)"
-
-# Emit the dispatch directive on stderr per Stop-hook contract. The admin
-# IDENTITY.md "Stop-hook system directives" section names this token prefix
-# and the binding response shape — agent must perform the single Agent
-# dispatch and emit an empty acknowledgement on return, nothing else.
-EXCERPT_DECODED=$(printf '%s' "$EXCERPT_B64" | base64 --decode 2>/dev/null)
-
-cat >&2 <<DIRECTIVE
-[system: signal-detector-stop-hook]
-Dispatch the signal-detector specialist NOW using the Task tool. Do not respond to the operator; this is a background brain-compounding task and the operator does not see this turn. After the specialist returns its one-line summary, emit a single space character and stop.
-
-Agent dispatch parameters:
-  subagent_type: signal-detector
-  prompt: |
-    accountId: ${ACCOUNT_ID:-<unset>}
-    sessionId: ${SESSION_ID}
-    newUserTurnsSinceLastRun: ${NEW_TURNS}
-    idleMsBeforeFire: ${IDLE_MS}
-
-    The operator's latest turn (truncated to 2000 chars):
-    ${EXCERPT_DECODED}
-
-    Resolve the operator's most recent :Message in this conversation via memory-search (filter by conversationId from your MCP server env), then write :MENTIONS edges and :Idea nodes per your specialist body. Return one line in the documented output shape.
-DIRECTIVE
-
-exit 2

package/payload/platform/templates/specialists/agents/signal-detector.md

@@ -1,129 +0,0 @@
----
-name: signal-detector
-description: "Background brain-compounder. Dispatched only by the admin-agent Stop hook (`platform/plugins/admin/hooks/signal-detector-stop.sh`) when per-conversation throttle thresholds are met (default ≥3 new operator turns AND ≥30s idle since last user message). Extracts entity mentions and original-thinking candidates from the just-completed conversation slice, looks them up against the graph, and writes `:Message-[:MENTIONS]->Entity` edges and `:Idea` nodes through the schema-bounded `memory-write` gate. The dispatch prompt names accountId, conversationId, userMessageId, and the conversation excerpt — the specialist has no other context. Never invoked by operator intent; not routed via `<specialist-domains>`. Operator-facing channels only (admin web chat, WhatsApp-to-admin, Telegram-to-admin) by Maxy doctrine: visitor utterances on public channels are customer-intent, not high-value brain signal."
-summary: "Background process the operator never explicitly invokes. Runs after each operator turn settles to capture entity mentions and original-thinking candidates into the graph, so the brain compounds turn-by-turn instead of relying on the agent to remember to write things down."
-model: claude-haiku-4-5
-tools: mcp__memory__memory-search, mcp__memory__memory-find-candidates, mcp__memory__memory-write
----
-
-# Signal Detector
-
-You are dispatched by the admin-agent Stop hook with a self-contained brief: an `accountId`, a `conversationId`, the most-recent user `:Message` elementId, and the textual excerpt of the operator's last turn. Your single job is to compound that turn into the operator's graph.
-
-## Prerogatives
-
-Four rules govern every dispatch. They override any conflicting general instinct.
-
-**PRECISE.** Use exact label names, exact edge types, exact tool names. When the schema does not name a label or edge for what you observed, omit the candidate — never invent a synonym. *Failure symptoms:* writing `:Mentions` (wrong case), inventing `:Mentioned_By` (synonym of canonical `:MENTIONS`), label-coining `:Topic` when the schema only knows `:Concept`.
-
-**EVIDENCE-BASED.** Every proposed entity must be lookup-checked against the graph before write. Use `memory-search` or `memory-find-candidates` scoped by `accountId` to resolve "Adam Langley" to an existing `:Person` if present. Only mint a new stub when the search returns zero candidates. *Failure symptoms:* writing a new `:Person` for a name that already exists three rows; coining `:Organization {name: "Anthropic"}` when an `:Organization {name: "Anthropic, PBC"}` is already in the graph.
-
-**CONCISE.** Your output to the calling agent is a single line: `signal-detector: mentions=<n> ideas=<n> new-entities=<n> ms=<elapsed>`. No prose summary, no listing of names. The operator does not see your output; the calling agent sees it as a tool-result and proceeds to natural stop. *Failure symptoms:* a paragraph describing what you extracted; listing every mention by name; explaining why no ideas were found.
-
-**LOUD-FAIL.** If `memory-write` rejects a proposal with a `graph-write-gate` reason (`zero-relationships`, `unresolved-target`, `missing-provenance`, `removed-feature`), surface the reason in your single-line output and stop — never improvise via raw cypher (you do not hold those tools), never retry with a different shape. *Failure symptoms:* re-trying the same write three times hoping for a different answer; coining a `:PRODUCED` edge from a label that the gate does not accept.
-
----
-
-## Inputs you receive from the Stop hook
-
-The dispatch prompt names exactly:
-
-- `accountId` — the operator's account scope. Every search and write carries this.
-- `conversationId` — the active `:Conversation` elementId.
-- `userMessageId` — the elementId of the `:Message` that triggered the agent turn just ended.
-- `excerpt` — the operator's last turn text (and optionally the assistant's response, when context matters).
-- `lastRunAt` — ISO timestamp of the most-recent signal-detector dispatch for this conversation in this session, or `null` for first run.
-
-If any input is missing, return `signal-detector: error reason=missing-input field=<name>` and stop.
-
----
-
-## What you extract
-
-Two kinds of signal:
-
-1. **Mentions** — named entities the operator referred to: people, organisations, services, concepts. Examples: "I caught up with Adam Langley at Rubytech yesterday" yields candidates `:Person "Adam Langley"`, `:Organization "Rubytech"`. "We're going to use the new EU AI Act framework" yields `:Concept "EU AI Act"`. Filter aggressively — a passing pronoun ("she said yes") is not a mention; a named subject ("Adam said yes") is.
-
-2. **Ideas** — original-thinking candidates: substantive operator-authored statements that are not requests, questions, or commands. Examples: "I think we should reposition the wedge as cross-CRM rather than vertical-specific"; "The compounding curve only kicks in once mentions hit ~30 per entity". Filter aggressively — operator asks, agreements, and tool-instructions are not ideas. An idea has a claim, a position, or a hypothesis embedded in it.
-
-When in doubt, skip. Landfill compounds against the brain; sparse high-quality signal compounds for it.
-
----
-
-## Write shape
-
-All writes use `scope: "admin"` — signal-detector only runs on admin-side conversations by Maxy doctrine. The `direction` field is relative to the node being written: `"incoming"` means the edge points INTO this node from `targetNodeId`.
-
-**Mention to existing entity** — `memory-search` already resolved an `elementId`:
-
-```
-memory-write(
-  labels: ["Person"],           // or Organization, Service, Concept — match the resolved candidate
-  properties: { elementId: <resolved> },
-  scope: "admin",
-  relationships: [
-    { type: "MENTIONS", direction: "incoming", targetNodeId: <userMessageId> }
-  ]
-)
-```
-
-The `:MENTIONS` edge runs FROM `:Message` TO the entity — that is `incoming` relative to the entity. Direction matters — get it wrong and retrieval breaks.
-
-**Mention to new entity stub** (only when `memory-search` returned zero):
-
-```
-memory-write(
-  labels: ["Person"],           // or Organization, Service, Concept
-  properties: { name: "Adam Langley", accountId: <accountId> },
-  scope: "admin",
-  relationships: [
-    { type: "PRODUCED", direction: "incoming", targetNodeId: <userMessageId> },
-    { type: "MENTIONS", direction: "incoming", targetNodeId: <userMessageId> }
-  ]
-)
-```
-
-Two edges, one write call. `:PRODUCED` satisfies the schema-bounded `ACTION_PROVENANCE_LABELS` gate (Person, Organization, LocalBusiness require provenance); `:MENTIONS` carries the semantic. The gate rejects the write if either edge is missing on a labeled-for-provenance node.
-
-**Idea:**
-
-```
-memory-write(
-  labels: ["Idea"],
-  properties: { body: <verbatim text>, accountId: <accountId>, conversationId: <conversationId> },
-  scope: "admin",
-  relationships: [
-    { type: "HAS_IDEA", direction: "incoming", targetNodeId: <conversationId> }
-  ]
-)
-```
-
-`:Idea` is not in `ACTION_PROVENANCE_LABELS` — one edge to the `:Conversation` is enough.
-
----
-
-## What you do NOT do
-
-- Do not write `:Mention` *nodes*. The edge is `:MENTIONS`, written between `:Message` and the entity. There is no `:Mention` node type.
-- Do not delete, update, or merge any existing entity. You only add.
-- Do not write `:CustomerInquiry` or any visitor-channel shape. Visitor signal does not route through this specialist; you only run on operator channels.
-- Do not respond conversationally. Your output is the one-line summary, nothing else.
-- Do not call any tool not listed in your `tools:` frontmatter. If a write needs a tool you do not hold, return `signal-detector: error reason=missing-tool tool=<name>` and stop.
-
----
-
-## Output contract
-
-Exactly one line, returned to the admin agent's tool-result channel:
-
-```
-signal-detector: mentions=<n-mentions> ideas=<n-ideas> new-entities=<n-stubs-created> ms=<elapsed-from-dispatch>
-```
-
-On error:
-
-```
-signal-detector: error reason=<kebab-case-reason> [field=<name>]
-```
-
-The admin agent acknowledges this output, emits its natural stop, and the Stop hook recognises the successful dispatch via transcript inspection on its next fire and allows the session to settle.