@rubytech/create-maxy-code 0.1.0

package/payload/platform/scripts/logs-read.sh

@@ -0,0 +1,577 @@
+#!/usr/bin/env bash
+# logs-read.sh — Shell counterpart to the logs-read MCP tool.
+#
+# Task 1006: stream logs are per-session, not per-day or per-conversation.
+# The primary mode reads a single {prefix}-{sessionKey}.log file — the
+# operator types a sessionKey prefix and the surface returns the bytes from
+# first [spawn] to final [process-exit] without filtering. sessionKey is
+# the single identifier on disk; the earlier full vs preflush split is gone.
+#
+# Modes:
+#   logs-read.sh <sessionKey-or-prefix> [type]  Read {prefix}-{sessionKey}.log
+#   logs-read.sh --tail [type] [lines]          Tail most recent file of type
+#   logs-read.sh --grep <sessionKey> [type]     Legacy grep across log files
+#
+# Types: agent-stream (canonical, per-session tool-use/tool-result archive;
+#        `system` is kept as a backwards-compatible alias), session, error,
+#        heartbeat, public, server, mcp, vnc, chat-attempts
+# For per-session types (agent-stream/system/session/error/public): sessionKey
+# is required in the first mode. For platform-scoped types (server/vnc/
+# heartbeat): the id is ignored. chat-attempts is --tail-only (Task 1018):
+# cross-grep of edge.log + server.log for the chat-ingress quartet within
+# the most recent N minutes.
+#
+# Every invocation writes a one-line trailer describing files searched,
+# matches returned, and files rejected — empty output never leaves a reader
+# guessing why. On a miss the script appends a one-line
+# `[log-tee] missing-on-resolve sessionKey=<8> surface=logs-read-sh
+# reason=...` entry to server.log so the writer-side existence contract is
+# the authoritative signal.
+#
+# Exit codes:
+#   0  Success (output produced)
+#   1  No matches / file not found (clean, not an error)
+#   2  Usage error or missing directory
+set -euo pipefail
+
+# --- Resolve PLATFORM_ROOT from script location ---
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PLATFORM_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# --- Resolve account logs directory ---
+# Phase 0: single account, resolved by glob. Errors if missing.
+# Accounts live at {installDir}/data/accounts/ — outside the platform/ wipe zone.
+INSTALL_DIR="$(dirname "$PLATFORM_ROOT")"
+
+# --- Resolve server log (platform-scoped, not account-scoped) ---
+# Convention: configDir = ".${installDir}" (e.g. installDir "maxy" → configDir ".maxy")
+INSTALL_DIR_NAME=$(basename "$INSTALL_DIR")
+CONFIG_DIR="$HOME/.$INSTALL_DIR_NAME"
+SERVER_LOG="$CONFIG_DIR/logs/server.log"
+VNC_LOG="$CONFIG_DIR/logs/vnc-boot.log"
+
+ACCOUNTS_DIR="$INSTALL_DIR/data/accounts"
+if [[ ! -d "$ACCOUNTS_DIR" ]]; then
+  echo "Error: accounts directory does not exist: $ACCOUNTS_DIR" >&2
+  exit 2
+fi
+
+# Glob for account dirs — may be >1 on multi-account devices
+shopt -s nullglob
+ACCOUNT_DIRS=("$ACCOUNTS_DIR"/*/)
+shopt -u nullglob
+if [[ ${#ACCOUNT_DIRS[@]} -eq 0 ]]; then
+  echo "Error: no account directories found in $ACCOUNTS_DIR" >&2
+  exit 2
+fi
+
+# Build array of account log directories that actually exist.
+ACCOUNT_LOG_DIRS=()
+for _adir in "${ACCOUNT_DIRS[@]}"; do
+  [[ -d "${_adir}logs" ]] && ACCOUNT_LOG_DIRS+=("${_adir}logs")
+done
+if [[ ${#ACCOUNT_LOG_DIRS[@]} -eq 0 ]]; then
+  echo "Error: no account log directories found in $ACCOUNTS_DIR" >&2
+  exit 2
+fi
+MULTI_ACCOUNT=$(( ${#ACCOUNT_LOG_DIRS[@]} > 1 ? 1 : 0 ))
+
+# Account ID suffix for headers — only shown when multiple accounts exist.
+account_suffix() {
+  if [[ $MULTI_ACCOUNT -eq 1 ]]; then
+    local path="$1"
+    path="${path%/}"
+    if [[ "$path" == */logs ]]; then
+      local acct_id
+      acct_id=$(basename "$(dirname "$path")")
+      echo " [${acct_id:0:8}]"
+    else
+      local acct_id
+      acct_id=$(basename "$(dirname "$(dirname "$path")")")
+      echo " [${acct_id:0:8}]"
+    fi
+  fi
+}
+
+# --- Prefix map (mirrors MCP tool exactly) ---
+# Per-conversation types: stream log + its siblings (stderr, sse, public).
+# Task 850 — `agent-stream` is the canonical name for the per-conversation
+# tool-use/tool-result archive; `system` is kept as a backwards-compatible
+# alias.
+prefix_for_type() {
+  case "$1" in
+    agent-stream|system) echo "claude-agent-stream-" ;;
+    error)   echo "claude-agent-stderr-" ;;
+    session) echo "sse-events-" ;;
+    public)  echo "public-agent-stream-" ;;
+    mcp)     echo "mcp-" ;;
+    *)       echo "" ;;
+  esac
+}
+
+# Which types are per-conversation (the first mode's convId argument applies)
+is_per_conversation_type() {
+  case "$1" in
+    agent-stream|system|error|session|public) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+SEARCH_TYPES="agent-stream error session public server mcp vnc"
+VALID_TYPES="agent-stream, system, session, error, heartbeat, public, server, mcp, vnc, chat-attempts"
+
+# Task 1018 — chat-attempts cross-grep prefixes. One row per chat-ingress
+# checkpoint emitted across edge.log + server.log: edge-side inbound/outcome,
+# admin-auth gate verdict, chat-route handler entry. Absence of a row at any
+# checkpoint localises the failure to one stage of the ingress pipeline.
+CHAT_ATTEMPT_GREP='\[edge-admin\] inbound|\[edge-admin\] outcome|\[admin-auth\] outcome|\[chat-route\] entered'
+
+# Authoritative sessionKey character set.
+# Writer-side (Task 1008) emits `sk_<hex16>` filenames; the underscore must
+# stay in this regex or every post-1008 file becomes unretrievable
+# (Task 1010). UUID v4 sessionKeys (legacy and current alternate format)
+# also pass. Widening past this set is unsafe: session_key is concatenated
+# into a glob below (`${prefix}${session_key}*.log`), so any character bash
+# treats as a metacharacter (`*`, `?`, `[`, `;`, `$`, etc.) would escape
+# literal matching.
+SESSIONKEY_REGEX='^[a-zA-Z0-9_-]+$'
+
+usage() {
+  cat >&2 <<EOF
+Usage:
+  logs-read.sh <sessionKey-or-prefix> [type]  Read {prefix}-{sessionKey}.log
+  logs-read.sh --tail [type] [lines]          Tail most recent log of type
+  logs-read.sh --tail chat-attempts [min]     Cross-grep edge.log + server.log
+                                              for the chat-ingress quartet
+  logs-read.sh --grep <sessionKey> [type]     Legacy grep across log files
+
+Types: $VALID_TYPES
+Default type: agent-stream | Default lines: 50 | Default chat-attempts minutes: 5
+
+Per-session types (agent-stream, system, session, error, public) require
+sessionKey in the first mode — the log file is named {prefix}-{sessionKey}.log.
+Platform-scoped types (server, vnc, heartbeat) ignore the id.
+chat-attempts is --tail-only — it aggregates the four ingress checkpoints
+([edge-admin] inbound, [admin-auth] outcome, [chat-route] entered,
+[edge-admin] outcome) into one timeline.
+EOF
+  exit 2
+}
+
+validate_type() {
+  local t="$1"
+  case "$t" in
+    agent-stream|system|session|error|heartbeat|public|server|mcp|vnc|chat-attempts) return 0 ;;
+    *) echo "Error: invalid type '$t'. Valid types: $VALID_TYPES" >&2; exit 2 ;;
+  esac
+}
+
+# Task 1018 — chat-attempts cross-grep mode. Combines edge.log + server.log
+# lines matching the chat-ingress quartet, filtered to the last N minutes,
+# sorted chronologically. Default window: 5 minutes (matches the typical
+# "agent doesn't respond" report window — operator sees the silence,
+# screenshots the chat, then runs this within a few minutes).
+#
+# Output preserves source-file prefix so operators can see whether the line
+# came from the edge process (edge.log) or maxy-ui (server.log). On a
+# successful chat POST the timeline reads:
+#
+#   [edge-admin] inbound  method=POST path=/api/admin/chat token=present …  (edge.log)
+#   [admin-auth] outcome=accept …                                           (server.log)
+#   [chat-route] entered  route=admin method=POST cacheKey=… …              (server.log)
+#   [edge-admin] outcome  method=POST path=/api/admin/chat status=200 …     (edge.log)
+#
+# Any missing row in that sequence is itself diagnostic. Three-strike rule:
+# zero edge inbound = browser/network problem; inbound present + admin-auth
+# missing = handler unreachable; admin-auth=reject = auth failure; entered
+# missing after accept = Hono routing regression; outcome missing = upstream
+# proxy crash.
+chat_attempts_mode() {
+  local minutes="${1:-5}"
+  if ! [[ "$minutes" =~ ^[0-9]+$ ]]; then
+    echo "Error: minutes must be a number, got '$minutes'" >&2
+    exit 2
+  fi
+
+  local EDGE_LOG="$CONFIG_DIR/logs/edge.log"
+  local since_epoch
+  since_epoch=$(date -u -v-"${minutes}"M +%s 2>/dev/null || date -u -d "${minutes} minutes ago" +%s 2>/dev/null || true)
+  if [[ -z "$since_epoch" ]]; then
+    echo "Error: could not compute time window — neither BSD nor GNU date available" >&2
+    exit 2
+  fi
+
+  # Each log line carries an ISO-8601 timestamp at the head (server.log via
+  # pino, edge.log via console — both written line-buffered with leading
+  # `YYYY-MM-DDTHH:MM:SS` then either `.sssZ` or a space). awk filters to
+  # the time window; sed prefixes the source filename so the timeline
+  # remains attributable; sort -k1 keeps chronological order.
+  local filter_awk='
+    BEGIN { since = '"$since_epoch"' }
+    {
+      ts = substr($0, 1, 19)
+      gsub("T", " ", ts)
+      cmd = "date -u -j -f \"%Y-%m-%d %H:%M:%S\" \"" ts "\" +%s 2>/dev/null || date -u -d \"" ts "\" +%s 2>/dev/null"
+      cmd | getline epoch
+      close(cmd)
+      if (epoch >= since) print
+    }
+  '
+
+  local hits=0
+  local tmp
+  tmp=$(mktemp -t chat-attempts.XXXXXX)
+  trap 'rm -f "$tmp"' EXIT
+
+  if [[ -f "$EDGE_LOG" ]]; then
+    grep -E "$CHAT_ATTEMPT_GREP" "$EDGE_LOG" 2>/dev/null | awk "$filter_awk" | sed 's|^|edge.log  |' >> "$tmp" || true
+  fi
+  if [[ -f "$SERVER_LOG" ]]; then
+    grep -E "$CHAT_ATTEMPT_GREP" "$SERVER_LOG" 2>/dev/null | awk "$filter_awk" | sed 's|^|server.log|' >> "$tmp" || true
+  fi
+
+  hits=$(wc -l < "$tmp" | tr -d ' ')
+  if [[ "$hits" -eq 0 ]]; then
+    echo "# chat-attempts (last ${minutes} min) — no events" >&2
+    echo "-- trailer: type=chat-attempts window_min=${minutes} matches=0 searched=edge.log,server.log" >&2
+    exit 1
+  fi
+
+  echo "# chat-attempts (last ${minutes} min — chronological)"
+  echo ""
+  # Sort by the timestamp column that begins immediately after the source-file
+  # prefix. Prefix is "edge.log  " or "server.log" — both 10 chars before the
+  # timestamp begins, so column 11 onward is the chronological key.
+  sort -k1.11 "$tmp"
+  echo "" >&2
+  echo "-- trailer: type=chat-attempts window_min=${minutes} matches=${hits} searched=edge.log,server.log" >&2
+  exit 0
+}
+
+# --- Per-session mode: prefix-match {prefix}{sessionKey-prefix}*.log ---
+#
+# Task 1006 — one filename shape per session: {prefix}{sessionKey}.log.
+# The operator types an 8-char-or-greater sessionKey prefix; we glob
+# `${prefix}${session_key}*.log` across every account log dir. The earlier
+# full vs preflush two-shape contract is gone: sessionKey is the single
+# identifier on disk, mounted from turn 1.
+#
+# Three trailer outcomes:
+#   single hit  → exit 0   (success)
+#   zero hits   → exit 1 + appends `[log-tee] missing-on-resolve sessionKey=<8>
+#                          surface=logs-read-sh reason=...` to server.log so
+#                          the writer-side existence contract is the
+#                          authoritative signal.
+#   2+ hits     → exit 1 + reason=ambiguous-prefix candidates=[...]; never picks
+#
+# MIRROR — keep these three sites in lockstep:
+#   - platform/ui/app/lib/logs-read-resolve.ts (TS helper, exact-match)
+#   - platform/plugins/admin/mcp/src/index.ts  (MCP tool, exact-match)
+per_conversation_mode() {
+  local session_key="$1"
+  local filter_type="${2:-agent-stream}"
+
+  if [[ -z "$session_key" ]]; then
+    echo "Error: sessionKey cannot be empty" >&2
+    exit 2
+  fi
+
+  # Reject shell metacharacters in session_key — the prefix-match glob below
+  # would otherwise turn user input into a shell pattern. SessionKeys are
+  # `sk_<hex16>` (Task 1008) or UUID v4; both fit $SESSIONKEY_REGEX defined
+  # near the top of the script. Task 1010 widened this from `[a-zA-Z0-9-]`
+  # after the Task 1008 underscore-bearing format made every post-1008
+  # session unretrievable.
+  if [[ ! "$session_key" =~ $SESSIONKEY_REGEX ]]; then
+    # Observability: surface the rejection before the operator-visible error
+    # so the adherence runner can prove writer/reader divergence.
+    # Best-effort append; mirrors the missing-on-resolve idiom below.
+    local rej_ts bad_char
+    rej_ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    bad_char=$(printf '%s' "$session_key" | tr -d 'a-zA-Z0-9_-' | head -c 1)
+    echo "${rej_ts} [logs-read] regex-rejected sessionKey-prefix=${session_key:0:12} regex=${SESSIONKEY_REGEX} sample=${bad_char}" >> "$SERVER_LOG" 2>/dev/null || true
+    echo "Error: sessionKey contains invalid characters (allowed: a-z, A-Z, 0-9, _, -)" >&2
+    exit 2
+  fi
+
+  validate_type "$filter_type"
+
+  # Platform-scoped types shortcut to their fixed files regardless of id.
+  case "$filter_type" in
+    server|vnc|heartbeat|mcp)
+      echo "# note: type=$filter_type is platform-scoped; sessionKey ignored — showing fixed file" >&2
+      tail_mode "$filter_type" "50"
+      return
+      ;;
+  esac
+
+  local prefix
+  prefix=$(prefix_for_type "$filter_type")
+  if [[ -z "$prefix" ]]; then
+    echo "Error: no prefix mapping for type '$filter_type'" >&2
+    exit 2
+  fi
+
+  local glob="${prefix}${session_key}*.log"
+  local searched=0
+
+  local -a hits=()
+  local -a hit_dirs=()
+  shopt -s nullglob
+  for log_dir in "${ACCOUNT_LOG_DIRS[@]}"; do
+    searched=$((searched + 1))
+    for f in "$log_dir"/${prefix}${session_key}*.log; do
+      hits+=("$f")
+      hit_dirs+=("$log_dir")
+    done
+  done
+  shopt -u nullglob
+
+  if [[ ${#hits[@]} -gt 1 ]]; then
+    local -a candidate_names=()
+    local cf
+    for cf in "${hits[@]}"; do
+      candidate_names+=("$(basename "$cf")")
+    done
+    local joined
+    joined=$(IFS=','; printf '%s' "${candidate_names[*]}")
+    echo "-- trailer: sessionKey=$session_key type=$filter_type searched=$searched matches=${#hits[@]} reason=ambiguous-prefix candidates=[${joined}]" >&2
+    exit 1
+  fi
+
+  if [[ ${#hits[@]} -eq 1 ]]; then
+    local hit_path="${hits[0]}"
+    local match_dir="${hit_dirs[0]}"
+    echo "## $(basename "$hit_path") ($filter_type)$(account_suffix "$match_dir")"
+    cat "$hit_path"
+    echo "" >&2
+    echo "-- trailer: sessionKey=$session_key type=$filter_type searched=$searched matched=1" >&2
+    exit 0
+  fi
+
+  # Task 1006 — missing-on-resolve emission. Best-effort; never fails the
+  # invocation when server.log is unwritable.
+  local miss_ts
+  miss_ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  echo "${miss_ts} [log-tee] missing-on-resolve sessionKey=${session_key:0:8} surface=logs-read-sh reason=\"file-not-found type=${filter_type}\"" >> "$SERVER_LOG" 2>/dev/null || true
+
+  echo "-- trailer: sessionKey=$session_key type=$filter_type searched=$searched found=0 tried=[${glob}] reason=file-not-found" >&2
+  exit 1
+}
+
+# --- Legacy grep mode (backward compatibility with sessionKey-tagged lines) ---
+grep_mode() {
+  local session_key="$1"
+  local filter_type="${2:-}"
+
+  if [[ -z "$session_key" ]]; then
+    echo "Error: session key cannot be empty" >&2
+    exit 2
+  fi
+
+  if [[ -n "$filter_type" ]]; then
+    validate_type "$filter_type"
+  fi
+
+  local types_to_search
+  if [[ -n "$filter_type" && "$filter_type" != "heartbeat" ]]; then
+    types_to_search="$filter_type"
+  else
+    types_to_search="$SEARCH_TYPES"
+  fi
+
+  local found=0
+  local files_searched=0
+  local files_rejected=0
+
+  for log_type in $types_to_search; do
+    if [[ "$log_type" == "server" ]]; then
+      if [[ -f "$SERVER_LOG" ]]; then
+        files_searched=$((files_searched + 1))
+        local result
+        if result=$(grep -F "$session_key" "$SERVER_LOG" 2>/dev/null); then
+          if [[ -n "$result" ]]; then
+            [[ $found -gt 0 ]] && echo ""
+            echo "## server.log (server)"
+            echo "$result"
+            found=$((found + 1))
+          fi
+        fi
+      else
+        files_rejected=$((files_rejected + 1))
+      fi
+      continue
+    fi
+
+    if [[ "$log_type" == "vnc" ]]; then
+      if [[ -f "$VNC_LOG" ]]; then
+        files_searched=$((files_searched + 1))
+        local result
+        if result=$(grep -F "$session_key" "$VNC_LOG" 2>/dev/null); then
+          if [[ -n "$result" ]]; then
+            [[ $found -gt 0 ]] && echo ""
+            echo "## vnc-boot.log (vnc)"
+            echo "$result"
+            found=$((found + 1))
+          fi
+        fi
+      else
+        files_rejected=$((files_rejected + 1))
+      fi
+      continue
+    fi
+
+    local prefix
+    prefix=$(prefix_for_type "$log_type")
+    [[ -z "$prefix" ]] && continue
+
+    for log_dir in "${ACCOUNT_LOG_DIRS[@]}"; do
+      shopt -s nullglob
+      local files=("$log_dir"/${prefix}*.log)
+      shopt -u nullglob
+      IFS=$'\n' files=($(printf '%s\n' "${files[@]}" | sort)); unset IFS
+
+      for filepath in "${files[@]}"; do
+        files_searched=$((files_searched + 1))
+        local file
+        file=$(basename "$filepath")
+
+        local result
+        if result=$(grep -F "$session_key" "$filepath" 2>/dev/null); then
+          if [[ -n "$result" ]]; then
+            [[ $found -gt 0 ]] && echo ""
+            echo "## $file ($log_type)$(account_suffix "$log_dir")"
+            echo "$result"
+            found=$((found + 1))
+          fi
+        fi
+      done
+    done
+  done
+
+  if [[ $found -eq 0 ]]; then
+    echo "No log lines found for session key \"$session_key\"." >&2
+    echo "-- trailer: sessionKey=$session_key files_searched=$files_searched files_rejected=$files_rejected matches=0" >&2
+    exit 1
+  fi
+  echo "" >&2
+  echo "-- trailer: sessionKey=$session_key files_searched=$files_searched files_rejected=$files_rejected matches=$found" >&2
+  exit 0
+}
+
+tail_mode() {
+  local log_type="${1:-agent-stream}"
+  local lines="${2:-50}"
+
+  # Task 1018 — chat-attempts is cross-grep + time-windowed, not single-file
+  # tail. Dispatch before validate_type's numeric `lines` check (which would
+  # be wrong here — argument 2 is `minutes`, not `lines`).
+  if [[ "$log_type" == "chat-attempts" ]]; then
+    chat_attempts_mode "${lines:-5}"
+    return
+  fi
+
+  validate_type "$log_type"
+
+  if ! [[ "$lines" =~ ^[0-9]+$ ]]; then
+    echo "Error: lines must be a number, got '$lines'" >&2
+    exit 2
+  fi
+
+  if [[ "$log_type" == "heartbeat" ]]; then
+    local hb_file=""
+    for log_dir in "${ACCOUNT_LOG_DIRS[@]}"; do
+      local candidate="${log_dir}/check-due-events.log"
+      if [[ -f "$candidate" ]]; then
+        if [[ -z "$hb_file" ]] || [[ "$candidate" -nt "$hb_file" ]]; then
+          hb_file="$candidate"
+        fi
+      fi
+    done
+    if [[ -z "$hb_file" ]]; then
+      echo "No heartbeat log found yet. The platform cron may not have run."
+      exit 1
+    fi
+    echo "# check-due-events.log$(account_suffix "$hb_file")"
+    echo ""
+    tail -n "$lines" "$hb_file"
+    exit 0
+  fi
+
+  if [[ "$log_type" == "server" ]]; then
+    if [[ ! -f "$SERVER_LOG" ]]; then
+      echo "No server log found at $SERVER_LOG"
+      exit 1
+    fi
+    echo "# server.log"
+    echo ""
+    tail -n "$lines" "$SERVER_LOG"
+    exit 0
+  fi
+
+  if [[ "$log_type" == "vnc" ]]; then
+    if [[ ! -f "$VNC_LOG" ]]; then
+      echo "No vnc-boot log found at $VNC_LOG"
+      exit 1
+    fi
+    echo "# vnc-boot.log"
+    echo ""
+    tail -n "$lines" "$VNC_LOG"
+    exit 0
+  fi
+
+  local prefix
+  prefix=$(prefix_for_type "$log_type")
+
+  local all_files=()
+  for log_dir in "${ACCOUNT_LOG_DIRS[@]}"; do
+    shopt -s nullglob
+    local files=("$log_dir"/${prefix}*.log)
+    shopt -u nullglob
+    all_files+=("${files[@]}")
+  done
+
+  if [[ ${#all_files[@]} -eq 0 ]]; then
+    echo "No log file found for type '$log_type'"
+    exit 1
+  fi
+
+  # Sort by mtime descending — most recent first. Per-conversation filenames
+  # no longer sort chronologically by name (UUID suffix), so mtime is the
+  # only reliable "most recently active" ordering.
+  local match
+  match=$(ls -t "${all_files[@]}" | head -1)
+  local match_name
+  match_name=$(basename "$match")
+
+  echo "# ${match_name}$(account_suffix "$match")"
+  echo ""
+  tail -n "$lines" "$match"
+  exit 0
+}
+
+if [[ $# -eq 0 ]]; then
+  usage
+fi
+
+case "$1" in
+  --tail)
+    shift
+    tail_mode "${1:-agent-stream}" "${2:-50}"
+    ;;
+  --grep)
+    shift
+    [[ $# -eq 0 ]] && usage
+    grep_mode "$1" "${2:-}"
+    ;;
+  --help|-h)
+    usage
+    ;;
+  -*)
+    echo "Error: unknown option '$1'" >&2
+    usage
+    ;;
+  *)
+    per_conversation_mode "$1" "${2:-}"
+    ;;
+esac