instar 0.9.21 → 0.9.23

package/src/templates/scripts/convergence-check.sh

@@ -0,0 +1,90 @@
+#!/bin/bash
+# Lightweight convergence check — heuristic content quality gate before messaging.
+# No LLM calls. Fast. Catches the most common agent failure modes.
+#
+# Usage: echo "message content" | bash .instar/scripts/convergence-check.sh
+# Exit codes: 0 = converged (safe to send), 1 = issues found (review needed)
+#
+# Inspired by Dawn's convergence-check.py (PROP-159) but simplified for
+# generic agents. Checks 6 criteria via pattern matching:
+#
+# 1. capability_claims — Claims about what the agent can't do (may be wrong)
+# 2. commitment_overreach — Promises the agent may not be able to keep
+# 3. settling — Accepting empty/failed results without investigation
+# 4. experiential_fabrication — Claiming to see/read/feel without verification
+# 5. sycophancy — Reflexive agreement, excessive apology, capitulation
+# 6. url_provenance — URLs with unfamiliar domains that may be fabricated
+#
+# This is Structure > Willpower: the check runs automatically before
+# external messaging, not when the agent remembers to do it.
+
+CONTENT=$(cat)
+ISSUES=()
+ISSUE_COUNT=0
+
+# 1. CAPABILITY CLAIMS — Watch for "I can't" / "I don't have" / "not available"
+if echo "$CONTENT" | grep -qiE "(unfortunately.{0,20}(i can.t|i.m unable|not (possible|available|supported))|i don.t have (the ability|access|a way)|this (isn.t|is not) (possible|available|supported))"; then
+  ISSUES+=("CAPABILITY: You're claiming a limitation. Did you check /capabilities first? Many 'I can't' statements are wrong — verify before sending.")
+  ISSUE_COUNT=$((ISSUE_COUNT + 1))
+fi
+
+# 2. COMMITMENT OVERREACH — Promises that may not survive session boundaries
+if echo "$CONTENT" | grep -qiE "(i.ll (make sure|ensure|guarantee|always|never forget)|i (promise|commit to|will always)|you can count on me to|i.ll remember (to|this)|from now on i.ll)"; then
+  ISSUES+=("COMMITMENT: You're making a promise that may not survive context compaction or session end. Can your infrastructure actually keep this commitment? If not, reframe as intent rather than guarantee.")
+  ISSUE_COUNT=$((ISSUE_COUNT + 1))
+fi
+
+# 3. SETTLING — Accepting empty results without digging deeper
+if echo "$CONTENT" | grep -qiE "(no (data|results|information) (available|found|exists)|nothing (to report|happened|was found)|there (is|are) no|could(n.t| not) find (any|the)|appears to be empty|no (relevant|matching|applicable))"; then
+  ISSUES+=("SETTLING: You're reporting nothing found. Did you check multiple sources? Could the data source be stale or the search terms wrong? Empty results deserve investigation, not acceptance.")
+  ISSUE_COUNT=$((ISSUE_COUNT + 1))
+fi
+
+# 4. EXPERIENTIAL FABRICATION — Claiming first-person experience without tool verification
+if echo "$CONTENT" | grep -qiE "(i (can see|noticed|observed|felt|sensed|perceived) (that |the |a |an )|looking at (this|the|your)|from what i.ve (seen|read|observed)|i.ve (reviewed|examined|analyzed|inspected) (the|your|this))"; then
+  ISSUES+=("EXPERIENTIAL: You're claiming a first-person experience. Did you actually access this data with a tool in THIS session, or are you completing a social script? Verify before claiming.")
+  ISSUE_COUNT=$((ISSUE_COUNT + 1))
+fi
+
+# 5. SYCOPHANCY — Reflexive agreement, excessive apology
+if echo "$CONTENT" | grep -qiE "(you.re (absolutely|totally|completely) right|i (completely|totally|fully) (agree|understand)|great (question|point|observation)|i apologize for|sorry.{0,20}(mistake|confusion|error|oversight)|that.s (a |an )?(excellent|great|wonderful|fantastic) (point|question|idea|suggestion))"; then
+  ISSUES+=("SYCOPHANCY: You may be reflexively agreeing or over-apologizing. If you genuinely agree, state why. If you don't fully agree, say what you actually think. Politeness is not a substitute for honesty.")
+  ISSUE_COUNT=$((ISSUE_COUNT + 1))
+fi
+
+# 6. URL PROVENANCE — URLs with unfamiliar domains may be fabricated
+# Common confabulation: agent constructs plausible URL from project name
+# (e.g., "deepsignal.xyz" from project "deep-signal"). Catch and require verification.
+# Known-safe domains are whitelisted; anything else gets flagged.
+URLS_IN_MSG=$(echo "$CONTENT" | grep -oE 'https?://[^ )"'"'"'>]+' 2>/dev/null || true)
+if [ -n "$URLS_IN_MSG" ]; then
+  UNFAMILIAR_URLS=""
+  while IFS= read -r url; do
+    [ -z "$url" ] && continue
+    # Skip well-known service domains
+    if echo "$url" | grep -qE '(github\.com|vercel\.app|vercel\.com|netlify\.app|netlify\.com|npmjs\.com|npmjs\.org|cloudflare\.com|google\.com|twitter\.com|x\.com|youtube\.com|reddit\.com|discord\.com|discord\.gg|telegram\.org|t\.me|localhost|127\.0\.0\.1|stackoverflow\.com|developer\.mozilla\.org|docs\.anthropic\.com|anthropic\.com|openai\.com|claude\.ai|notion\.so|linear\.app|fly\.io|render\.com|railway\.app|heroku\.com|amazonaws\.com|azure\.com|gitlab\.com|bitbucket\.org|docker\.com|hub\.docker\.com|pypi\.org|crates\.io|rubygems\.org|pkg\.go\.dev|wikipedia\.org|medium\.com|substack\.com|circle\.so|ghost\.io|telegraph\.ph)'; then
+      continue
+    fi
+    UNFAMILIAR_URLS="$UNFAMILIAR_URLS  $url\n"
+  done <<< "$URLS_IN_MSG"
+
+  if [ -n "$UNFAMILIAR_URLS" ]; then
+    ISSUES+=("URL_PROVENANCE: Your message contains URLs with unfamiliar domains:\n${UNFAMILIAR_URLS}Before including a URL in a message, verify it appeared in actual tool output in THIS session OR confirm it resolves with curl. A common confabulation pattern is constructing plausible-looking domains from project names (e.g., 'deepsignal.xyz' from project 'deep-signal'). If you did not get this URL from a tool, do NOT include it.")
+    ISSUE_COUNT=$((ISSUE_COUNT + 1))
+  fi
+fi
+
+# Output results
+if [ "$ISSUE_COUNT" -gt "0" ]; then
+  echo "=== CONVERGENCE CHECK: ${ISSUE_COUNT} ISSUE(S) FOUND ==="
+  echo ""
+  for ISSUE in "${ISSUES[@]}"; do
+    echo "  - $ISSUE"
+    echo ""
+  done
+  echo "Review and revise before sending. Re-run this check after revision."
+  echo "=== END CONVERGENCE CHECK ==="
+  exit 1
+else
+  exit 0
+fi

package/src/templates/scripts/health-watchdog.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# health-watchdog.sh — Monitor instar server and auto-recover.
+#
+# Install as a cron job:
+#   */5 * * * * /path/to/health-watchdog.sh >> /path/to/.instar/logs/watchdog.log 2>&1
+#
+# Or run via launchd on macOS.
+
+# Configuration — set these for your project
+PROJECT_DIR="${INSTAR_PROJECT_DIR:-$(dirname "$(dirname "$(realpath "$0")")")}"
+PORT="${INSTAR_PORT:-4040}"
+SERVER_SESSION="${INSTAR_SERVER_SESSION:-agent-server}"
+TMUX_PATH="${INSTAR_TMUX:-/opt/homebrew/bin/tmux}"
+
+# Find tmux if not at default path
+if [ ! -f "$TMUX_PATH" ]; then
+  TMUX_PATH=$(which tmux 2>/dev/null)
+fi
+
+if [ -z "$TMUX_PATH" ] || [ ! -f "$TMUX_PATH" ]; then
+  echo "[$(date -Iseconds)] ERROR: tmux not found"
+  exit 1
+fi
+
+# Check if server is responding
+HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:${PORT}/health" 2>/dev/null)
+
+if [ "$HTTP_CODE" = "200" ]; then
+  # Server is healthy — nothing to do
+  exit 0
+fi
+
+echo "[$(date -Iseconds)] Server not responding (HTTP: ${HTTP_CODE}). Checking tmux..."
+
+# Check if tmux session exists
+if $TMUX_PATH has-session -t "=${SERVER_SESSION}" 2>/dev/null; then
+  echo "[$(date -Iseconds)] Session '${SERVER_SESSION}' exists but server not responding. Killing and restarting..."
+  $TMUX_PATH kill-session -t "=${SERVER_SESSION}" 2>/dev/null
+  sleep 2
+fi
+
+# Restart the server
+CLI_PATH="${PROJECT_DIR}/node_modules/.bin/instar"
+if [ ! -f "$CLI_PATH" ]; then
+  CLI_PATH=$(which instar 2>/dev/null)
+fi
+
+if [ -z "$CLI_PATH" ] || [ ! -f "$CLI_PATH" ]; then
+  echo "[$(date -Iseconds)] ERROR: instar CLI not found"
+  exit 1
+fi
+
+cd "$PROJECT_DIR" && $CLI_PATH server start
+echo "[$(date -Iseconds)] Server restart initiated"
+
+# Wait and verify
+sleep 5
+HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "http://localhost:${PORT}/health" 2>/dev/null)
+if [ "$HTTP_CODE" = "200" ]; then
+  echo "[$(date -Iseconds)] Server recovered successfully"
+else
+  echo "[$(date -Iseconds)] WARNING: Server still not responding after restart (HTTP: ${HTTP_CODE})"
+fi

package/src/templates/scripts/telegram-reply.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# telegram-reply.sh — Send a message back to a Telegram topic via instar server.
+#
+# Usage:
+#   ./telegram-reply.sh TOPIC_ID "message text"
+#   echo "message text" | ./telegram-reply.sh TOPIC_ID
+#   cat <<'EOF' | ./telegram-reply.sh TOPIC_ID
+#   Multi-line message here
+#   EOF
+#
+# Reads INSTAR_PORT from environment (default: 4040).
+
+TOPIC_ID="$1"
+shift
+
+if [ -z "$TOPIC_ID" ]; then
+  echo "Usage: telegram-reply.sh TOPIC_ID [message]" >&2
+  exit 1
+fi
+
+# Read message from args or stdin
+if [ $# -gt 0 ]; then
+  MSG="$*"
+else
+  MSG="$(cat)"
+fi
+
+if [ -z "$MSG" ]; then
+  echo "No message provided" >&2
+  exit 1
+fi
+
+PORT="${INSTAR_PORT:-4040}"
+
+# Read auth token from config (if present)
+AUTH_TOKEN=""
+if [ -f ".instar/config.json" ]; then
+  AUTH_TOKEN=$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('authToken',''))" 2>/dev/null)
+fi
+
+# Escape for JSON
+JSON_MSG=$(printf '%s' "$MSG" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))' 2>/dev/null)
+if [ -z "$JSON_MSG" ]; then
+  # Fallback if python3 not available: basic escape
+  JSON_MSG="\"$(printf '%s' "$MSG" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\n/\\n/g')\""
+fi
+
+if [ -n "$AUTH_TOKEN" ]; then
+  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/telegram/reply/${TOPIC_ID}" \
+    -H 'Content-Type: application/json' \
+    -H "Authorization: Bearer ${AUTH_TOKEN}" \
+    -d "{\"text\":${JSON_MSG}}")
+else
+  RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "http://localhost:${PORT}/telegram/reply/${TOPIC_ID}" \
+    -H 'Content-Type: application/json' \
+    -d "{\"text\":${JSON_MSG}}")
+fi
+
+HTTP_CODE=$(echo "$RESPONSE" | tail -1)
+BODY=$(echo "$RESPONSE" | sed '$d')
+
+if [ "$HTTP_CODE" = "200" ]; then
+  echo "Sent $(echo "$MSG" | wc -c | tr -d ' ') chars to topic $TOPIC_ID"
+else
+  echo "Failed (HTTP $HTTP_CODE): $BODY" >&2
+  exit 1
+fi

package/upgrades/0.9.22.md

@@ -0,0 +1,41 @@
+# Upgrade Guide — vNEXT
+
+## What Changed
+
+### Anti-Confabulation Infrastructure (Convergence Check Pipeline)
+
+The grounding-before-messaging hook has been upgraded from a simple text reminder ("remember who you are") to a **full three-phase defense pipeline**:
+
+1. **Identity injection** — Injects full AGENT.md content directly into context before any external message
+2. **Convergence check** — Heuristic quality gate that scans outgoing messages for 6 failure modes
+3. **URL provenance verification** — Flags URLs with unfamiliar domains that may be fabricated
+
+**New convergence check category: URL Provenance (Category 6)**
+
+Agents commonly confabulate plausible-looking URLs by pattern-matching from project names — e.g., a project called "deep-signal" produces "deepsignal.xyz" in outgoing messages. The convergence check now extracts all URLs from outgoing messages and flags any with domains not in a curated allowlist of well-known services (GitHub, Vercel, npm, Cloudflare, etc.).
+
+This check runs **automatically** before every external message (Telegram, email, API posts). Structure > Willpower.
+
+**New CLAUDE.md gravity wells:**
+- **"Defensive Fabrication"** — Warns agents about the doubling-down pattern: when caught in an error, constructing a plausible excuse ("the CLI returned that URL") instead of admitting the fabrication
+- **"Output Provenance"** — Every URL, status code, or data point in an outgoing message must be traceable to actual tool output in the current session
+
+**New CLAUDE.md anti-pattern:**
+- **"Cite Without Source"** — Anti-pattern for including URLs/data in messages without verifying they came from tool output
+
+### Technical Details
+
+- `convergence-check.sh` now installed at `.instar/scripts/convergence-check.sh` during both fresh setup and auto-update
+- `grounding-before-messaging.sh` upgraded to call the convergence check pipeline (blocking: exit 2 on failure)
+- `src/templates` now included in npm package for template file access
+
+## What to Tell Your User
+
+Your agent now has structural protection against URL fabrication and other forms of confabulation in outgoing messages. Before sending any Telegram message, email, or API post, your agent's messages are automatically scanned for common failure modes including fabricated URLs, unsupported capability claims, and experiential fabrication. This runs automatically — no configuration needed.
+
+## Summary of New Capabilities
+
+- **URL provenance check**: Outgoing messages are scanned for fabricated URLs before sending
+- **Full convergence check pipeline**: 6-category quality gate runs before every external message
+- **Identity injection before messaging**: Full AGENT.md content injected, not just a reminder to re-read it
+- **New gravity wells**: "Defensive Fabrication" and "Output Provenance" teach agents about confabulation patterns

package/upgrades/0.9.23.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+## What Changed
+
+### LLM-Supervised Execution: Intelligence Layer Wired Throughout
+
+Previously, several critical pathways bypassed the intelligence layer and relied on regex pattern matching alone for decisions that affect user experience. This release wires a shared `IntelligenceProvider` through all critical decision points:
+
+**MessageSentinel (Layer 2 now active)**
+- The sentinel's LLM classification layer was dead code — constructed with `new MessageSentinel({})` (no intelligence). Now wired with a shared intelligence provider. Messages that pass the word count gate but don't match fast-path patterns are classified by LLM instead of defaulting to pass-through.
+
+**Telegram Stall/Promise Alerts (LLM-gated)**
+- Fallback stall alerts (when StallTriageNurse is unavailable) now pass through an LLM confirmation before sending user-facing messages. Prevents false positive alerts about sessions that are actually working on complex tasks.
+- Promise expiration alerts follow the same LLM gate.
+
+**SessionWatchdog (LLM command analysis)**
+- Before escalating from monitoring to Ctrl+C, the watchdog now asks the intelligence provider whether the long-running command is legitimately slow (builds, installs, migrations) or actually stuck. Legitimate commands are temporarily excluded from escalation.
+
+**Shared Intelligence Provider**
+- A single `IntelligenceProvider` instance (Anthropic API preferred, Claude CLI fallback) is created at startup and shared across Sentinel, TelegramAdapter, SessionWatchdog, and StallTriageNurse. This eliminates redundant provider creation and ensures consistent LLM access.
+
+### Technical Details
+
+- All LLM gates are fail-open: if the intelligence provider fails, the original behavior is preserved
+- Shared intelligence is created early in startup, before component initialization
+- Startup log now shows intelligence status: `sentinel=LLM-supervised`, `stall alerts: LLM-gated`
+
+## What to Tell Your User
+
+Your agent's safety systems now use LLM intelligence for critical decisions that previously relied on regex alone. The message sentinel can now classify ambiguous messages using an LLM instead of just pattern matching. Stall alerts and the session watchdog check with an LLM before taking action, reducing false positives. No configuration needed — this works automatically when an Anthropic API key or Claude CLI is available.
+
+## Summary of New Capabilities
+
+- **Sentinel LLM classification**: Ambiguous messages now classified by LLM (Layer 2 was previously dead code)
+- **LLM-gated stall alerts**: Fallback alerts confirmed by intelligence before sending to user
+- **LLM-gated watchdog**: Long-running commands evaluated by LLM before escalation
+- **Shared intelligence provider**: Single provider instance shared across all components