instar 0.1.0

package/src/server/routes.ts

@@ -0,0 +1,278 @@
+/**
+ * HTTP API routes — health, status, sessions, jobs, events.
+ *
+ * Extracted/simplified from Dawn's 2267-line routes.ts.
+ * All the observability you need, none of the complexity you don't.
+ */
+
+import { Router } from 'express';
+import { execSync as execSyncFn } from 'node:child_process';
+import type { SessionManager } from '../core/SessionManager.js';
+import type { StateManager } from '../core/StateManager.js';
+import type { JobScheduler } from '../scheduler/JobScheduler.js';
+import type { AgentKitConfig } from '../core/types.js';
+import type { TelegramAdapter } from '../messaging/TelegramAdapter.js';
+import type { RelationshipManager } from '../core/RelationshipManager.js';
+
+interface RouteContext {
+  config: AgentKitConfig;
+  sessionManager: SessionManager;
+  state: StateManager;
+  scheduler: JobScheduler | null;
+  telegram: TelegramAdapter | null;
+  relationships: RelationshipManager | null;
+  startTime: Date;
+}
+
+export function createRoutes(ctx: RouteContext): Router {
+  const router = Router();
+
+  // ── Health ──────────────────────────────────────────────────────
+
+  router.get('/health', (_req, res) => {
+    const uptimeMs = Date.now() - ctx.startTime.getTime();
+    res.json({
+      status: 'ok',
+      uptime: uptimeMs,
+      uptimeHuman: formatUptime(uptimeMs),
+      version: '0.1.0',
+      project: ctx.config.projectName,
+    });
+  });
+
+  // ── Status ──────────────────────────────────────────────────────
+
+  router.get('/status', (_req, res) => {
+    const sessions = ctx.sessionManager.listRunningSessions();
+    const schedulerStatus = ctx.scheduler?.getStatus() ?? null;
+
+    res.json({
+      sessions: {
+        running: sessions.length,
+        max: ctx.config.sessions.maxSessions,
+        list: sessions.map(s => ({ id: s.id, name: s.name, jobSlug: s.jobSlug })),
+      },
+      scheduler: schedulerStatus,
+    });
+  });
+
+  // ── Sessions ────────────────────────────────────────────────────
+
+  router.get('/sessions', (req, res) => {
+    const status = req.query.status as string | undefined;
+    const sessions = status
+      ? ctx.state.listSessions({ status: status as any })
+      : ctx.state.listSessions();
+
+    res.json(sessions);
+  });
+
+  router.get('/sessions/:name/output', (req, res) => {
+    const lines = parseInt(req.query.lines as string) || 100;
+    const output = ctx.sessionManager.captureOutput(req.params.name, lines);
+
+    if (output === null) {
+      res.status(404).json({ error: `Session "${req.params.name}" not found or not running` });
+      return;
+    }
+
+    res.json({ session: req.params.name, output });
+  });
+
+  router.post('/sessions/:name/input', (req, res) => {
+    const { text } = req.body;
+    if (!text || typeof text !== 'string') {
+      res.status(400).json({ error: 'Request body must include "text" field' });
+      return;
+    }
+
+    const success = ctx.sessionManager.sendInput(req.params.name, text);
+    if (!success) {
+      res.status(404).json({ error: `Session "${req.params.name}" not found or not running` });
+      return;
+    }
+
+    res.json({ ok: true });
+  });
+
+  router.post('/sessions/spawn', (req, res) => {
+    const { name, prompt, model, jobSlug } = req.body;
+
+    if (!name || !prompt) {
+      res.status(400).json({ error: '"name" and "prompt" are required' });
+      return;
+    }
+
+    try {
+      const session = ctx.sessionManager.spawnSession({ name, prompt, model, jobSlug });
+      // spawnSession is async but we want to handle errors,
+      // so we use .then/.catch
+      session.then(s => res.status(201).json(s)).catch(err => {
+        res.status(500).json({ error: err.message });
+      });
+    } catch (err: any) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  router.delete('/sessions/:id', (req, res) => {
+    try {
+      const killed = ctx.sessionManager.killSession(req.params.id);
+      if (!killed) {
+        res.status(404).json({ error: `Session "${req.params.id}" not found` });
+        return;
+      }
+      res.json({ ok: true, killed: req.params.id });
+    } catch (err: any) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  // ── Jobs ────────────────────────────────────────────────────────
+
+  router.get('/jobs', (_req, res) => {
+    if (!ctx.scheduler) {
+      res.json({ jobs: [], scheduler: null });
+      return;
+    }
+
+    const jobs = ctx.scheduler.getJobs().map(job => {
+      const jobState = ctx.state.getJobState(job.slug);
+      return { ...job, state: jobState };
+    });
+
+    res.json({ jobs, queue: ctx.scheduler.getQueue() });
+  });
+
+  router.post('/jobs/:slug/trigger', (req, res) => {
+    if (!ctx.scheduler) {
+      res.status(503).json({ error: 'Scheduler not running' });
+      return;
+    }
+
+    const reason = (req.body?.reason as string) || 'manual';
+
+    try {
+      const result = ctx.scheduler.triggerJob(req.params.slug, reason);
+      res.json({ slug: req.params.slug, result });
+    } catch (err: any) {
+      res.status(404).json({ error: err.message });
+    }
+  });
+
+  // ── Telegram ────────────────────────────────────────────────────
+
+  router.post('/telegram/reply/:topicId', async (req, res) => {
+    if (!ctx.telegram) {
+      res.status(503).json({ error: 'Telegram not configured' });
+      return;
+    }
+
+    const topicId = parseInt(req.params.topicId);
+    const { text } = req.body;
+    if (!text || typeof text !== 'string') {
+      res.status(400).json({ error: '"text" field required' });
+      return;
+    }
+
+    try {
+      await ctx.telegram.sendToTopic(topicId, text);
+      res.json({ ok: true, topicId });
+    } catch (err: any) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  // ── tmux Sessions (raw) ─────────────────────────────────────────
+
+  router.get('/sessions/tmux', (_req, res) => {
+    try {
+      const tmuxPath = ctx.config.sessions.tmuxPath;
+      const output = execSyncFn(`${tmuxPath} list-sessions -F '#{session_name}' 2>/dev/null || true`, {
+        encoding: 'utf-8',
+      }).trim();
+
+      const sessions = output
+        ? output.split('\n').filter(Boolean).map((name: string) => ({ name }))
+        : [];
+
+      res.json({ sessions });
+    } catch {
+      res.json({ sessions: [] });
+    }
+  });
+
+  // ── Relationships ─────────────────────────────────────────────────
+
+  router.get('/relationships', (_req, res) => {
+    if (!ctx.relationships) {
+      res.json({ relationships: [] });
+      return;
+    }
+    const sortBy = (_req.query.sort as 'significance' | 'recent' | 'name') || 'significance';
+    res.json({ relationships: ctx.relationships.getAll(sortBy) });
+  });
+
+  // Stale must be before :id to avoid "stale" matching as a param
+  router.get('/relationships/stale', (req, res) => {
+    if (!ctx.relationships) {
+      res.json({ stale: [] });
+      return;
+    }
+    const days = parseInt(req.query.days as string) || 14;
+    res.json({ stale: ctx.relationships.getStaleRelationships(days) });
+  });
+
+  router.get('/relationships/:id', (req, res) => {
+    if (!ctx.relationships) {
+      res.status(503).json({ error: 'Relationships not configured' });
+      return;
+    }
+    const record = ctx.relationships.get(req.params.id);
+    if (!record) {
+      res.status(404).json({ error: 'Relationship not found' });
+      return;
+    }
+    res.json(record);
+  });
+
+  router.get('/relationships/:id/context', (req, res) => {
+    if (!ctx.relationships) {
+      res.status(503).json({ error: 'Relationships not configured' });
+      return;
+    }
+    const context = ctx.relationships.getContextForPerson(req.params.id);
+    if (!context) {
+      res.status(404).json({ error: 'Relationship not found' });
+      return;
+    }
+    res.json({ context });
+  });
+
+  // ── Events ──────────────────────────────────────────────────────
+
+  router.get('/events', (req, res) => {
+    const limit = parseInt(req.query.limit as string) || 50;
+    const type = req.query.type as string | undefined;
+    const sinceHours = parseInt(req.query.since as string) || 24;
+
+    const since = new Date(Date.now() - sinceHours * 60 * 60 * 1000);
+    const events = ctx.state.queryEvents({ since, type, limit });
+
+    res.json(events);
+  });
+
+  return router;
+}
+
+function formatUptime(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) return `${days}d ${hours % 24}h`;
+  if (hours > 0) return `${hours}h ${minutes % 60}m`;
+  if (minutes > 0) return `${minutes}m ${seconds % 60}s`;
+  return `${seconds}s`;
+}

package/src/templates/default-jobs.json

@@ -0,0 +1,47 @@
+[
+  {
+    "slug": "health-check",
+    "name": "Health Check",
+    "description": "Monitor server health, session status, and system resources. Alert if anything needs attention.",
+    "schedule": "*/5 * * * *",
+    "priority": "critical",
+    "expectedDurationMinutes": 1,
+    "model": "haiku",
+    "enabled": true,
+    "execute": {
+      "type": "prompt",
+      "value": "Run a quick health check: verify the instar server is responding (curl http://localhost:PORT/health), check disk space (df -h), and report any issues to the Agent Attention topic via telegram-reply.sh. Only send a message if something needs attention — silence means healthy."
+    },
+    "tags": ["coherence", "default"]
+  },
+  {
+    "slug": "reflection-trigger",
+    "name": "Reflection Trigger",
+    "description": "Review recent work and update MEMORY.md if any learnings exist. Ensures growth is captured, not lost.",
+    "schedule": "0 */4 * * *",
+    "priority": "medium",
+    "expectedDurationMinutes": 5,
+    "model": "sonnet",
+    "enabled": true,
+    "execute": {
+      "type": "prompt",
+      "value": "Review what has happened in the last 4 hours by reading recent activity logs and session reports. If there are any learnings, patterns, or insights worth remembering, update .instar/MEMORY.md. If nothing significant happened, do nothing. This is about capturing growth — not generating busy work."
+    },
+    "tags": ["coherence", "default"]
+  },
+  {
+    "slug": "relationship-maintenance",
+    "name": "Relationship Maintenance",
+    "description": "Review tracked relationships. Surface observations about stale contacts or notable patterns.",
+    "schedule": "0 9 * * *",
+    "priority": "low",
+    "expectedDurationMinutes": 3,
+    "model": "sonnet",
+    "enabled": true,
+    "execute": {
+      "type": "prompt",
+      "value": "Review all relationship files in .instar/relationships/. Note anyone you haven't heard from in over 2 weeks who has significance >= 3. If there are observations worth surfacing (stale important relationships, patterns across conversations, things people mentioned that might need follow-up), send a brief summary to the Agent Attention topic. If everything looks fine, do nothing."
+    },
+    "tags": ["coherence", "default"]
+  }
+]

package/src/templates/hooks/compaction-recovery.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Compaction recovery — re-injects identity when Claude's context compresses.
+# Without this, the agent loses its identity every 30-60 minutes.
+#
+# This is the single most impactful hook for agent continuity.
+# When context compresses, Claude effectively starts over. This hook
+# ensures the agent knows who it is after every compaction event.
+#
+# Installed by instar during setup. Runs as a Claude Code PostToolUse hook.
+
+INSTAR_DIR="${CLAUDE_PROJECT_DIR:-.}/.instar"
+
+# Check if we're in a post-compaction state by looking for compaction markers
+# Claude Code emits specific patterns when context is compressed
+# This hook provides the recovery seed
+
+if [ -f "$INSTAR_DIR/AGENT.md" ]; then
+  AGENT_NAME=$(head -5 "$INSTAR_DIR/AGENT.md" | grep -i "name\|I am\|My name" | head -1)
+  if [ -n "$AGENT_NAME" ]; then
+    echo "Identity reminder: $AGENT_NAME"
+    echo "Read .instar/AGENT.md and .instar/MEMORY.md to restore full context."
+  fi
+fi

package/src/templates/hooks/dangerous-command-guard.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Dangerous command guard — blocks destructive operations.
+# Part of instar's "Security Through Identity" model.
+#
+# Installed by instar during setup. Runs as a Claude Code PreToolUse hook on Bash.
+
+# The command being executed is passed via TOOL_INPUT
+INPUT="$1"
+
+# Patterns that should be blocked without explicit user confirmation
+DANGEROUS_PATTERNS=(
+  "rm -rf /"
+  "rm -rf ~"
+  "rm -rf \."
+  "git push --force"
+  "git push -f"
+  "git reset --hard"
+  "git clean -fd"
+  "DROP TABLE"
+  "DROP DATABASE"
+  "TRUNCATE"
+  "DELETE FROM"
+  "> /dev/sda"
+  "mkfs\."
+  "dd if="
+  ":(){:|:&};:"
+)
+
+for pattern in "${DANGEROUS_PATTERNS[@]}"; do
+  if echo "$INPUT" | grep -qi "$pattern"; then
+    echo "BLOCKED: Potentially destructive command detected: $pattern"
+    echo "If you genuinely need to run this command, ask the user for explicit confirmation first."
+    exit 2
+  fi
+done

package/src/templates/hooks/grounding-before-messaging.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Grounding before messaging — ensures the agent re-reads its identity
+# before sending any external message. Part of "Security Through Identity."
+#
+# This is both behavioral integrity AND security:
+# - An agent that knows who it is can detect "this doesn't sound like me"
+# - Identity grounding acts as an immune system against prompt injection
+#
+# Installed by instar during setup. Runs as a Claude Code PreToolUse hook on Bash.
+
+INPUT="$1"
+
+# Detect messaging commands (telegram-reply, email sends, etc.)
+if echo "$INPUT" | grep -qE "(telegram-reply|send-email|send-message|POST.*/telegram/reply)"; then
+  INSTAR_DIR="${CLAUDE_PROJECT_DIR:-.}/.instar"
+
+  if [ -f "$INSTAR_DIR/AGENT.md" ]; then
+    echo "Before sending this message, remember who you are."
+    echo "Re-read .instar/AGENT.md if you haven't recently."
+    echo "Security Through Identity: An agent that knows itself is harder to compromise."
+  fi
+fi

package/src/templates/hooks/session-start.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+# Session start hook — injects identity context when a new Claude session begins.
+# This is how the agent maintains continuity: every session starts with self-knowledge.
+#
+# Installed by instar during setup. Runs as a Claude Code PreToolUse hook.
+
+INSTAR_DIR="${CLAUDE_PROJECT_DIR:-.}/.instar"
+
+# Build identity context
+CONTEXT=""
+
+# Core identity
+if [ -f "$INSTAR_DIR/AGENT.md" ]; then
+  CONTEXT="${CONTEXT}Your identity file is at .instar/AGENT.md — read it if you need to remember who you are.\n"
+fi
+
+# User context
+if [ -f "$INSTAR_DIR/USER.md" ]; then
+  CONTEXT="${CONTEXT}Your user context is at .instar/USER.md — read it to know who you're working with.\n"
+fi
+
+# Memory
+if [ -f "$INSTAR_DIR/MEMORY.md" ]; then
+  CONTEXT="${CONTEXT}Your persistent memory is at .instar/MEMORY.md — check it for past learnings.\n"
+fi
+
+# Relationships
+if [ -d "$INSTAR_DIR/relationships" ]; then
+  REL_COUNT=$(ls -1 "$INSTAR_DIR/relationships"/*.json 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$REL_COUNT" -gt "0" ]; then
+    CONTEXT="${CONTEXT}You have ${REL_COUNT} tracked relationships in .instar/relationships/.\n"
+  fi
+fi
+
+if [ -n "$CONTEXT" ]; then
+  echo "$CONTEXT"
+fi

package/src/templates/hooks/settings-template.json

@@ -0,0 +1,45 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .instar/hooks/dangerous-command-guard.sh \"$TOOL_INPUT\"",
+            "blocking": true
+          },
+          {
+            "type": "command",
+            "command": "bash .instar/hooks/grounding-before-messaging.sh \"$TOOL_INPUT\"",
+            "blocking": false
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .instar/hooks/session-start.sh",
+            "blocking": false
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "compaction",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .instar/hooks/compaction-recovery.sh",
+            "blocking": false
+          }
+        ]
+      }
+    ]
+  }
+}

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,54 @@
+#!/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}"
+
+# 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
+
+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}}")
+
+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