shraga 0.1.34 → 0.1.35

package/defaults/skills/self-aware.md

@@ -81,6 +81,26 @@ bun install && bun run build && sudo systemctl restart "$APP_NAME"
 ```
 List checkpoints with `git -C "$APP_DIR" log --oneline`; reset to any of them.
 
+## Upgrading yourself (npm deployments)
+
+When the deployment consumes `shraga` as an npm dependency, you can move your own pinned version.
+**Only when the user asks** — there is no timer on this.
+
+```bash
+curl -s $ORIGIN/api/self-upgrade                                  # current, latest, blockers
+curl -s -XPOST $ORIGIN/api/self-upgrade -d '{"version":"latest"}'  # or a specific "0.1.35"
+```
+
+- **Owner only.** Both routes 403 for anyone else.
+- **Check `blockers` first and relay them.** A source checkout (upgrade with git instead) and a
+  local dev symlink at `node_modules/shraga` are both refused on purpose — do not work around either.
+- **202 means started, not succeeded.** The upgrade restarts the server, so the POST cannot report
+  the outcome. A detached supervisor installs, restarts, waits for `/api/version` to report the new
+  version, soaks it, and **reverts to the previous version automatically** if it doesn't hold.
+- **The result reaches you after the restart**, as a `self-upgrade.finished` event carrying
+  `status` (`ok` / `reverted` / `failed` / `revert-failed`) and a `log` path. Tell the owner what
+  happened — especially `revert-failed`, which means the box needs a human.
+
 ## Key paths (in source)
 
 - `src/server/` — Express + WebSocket server, Claude agent SDK integration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.34",
+  "version": "0.1.35",
   "description": "The teammate you delegate coding to — a self-hostable, multi-user AI coding agent web UI (Claude Code, with a pluggable engine seam).",
   "type": "module",
   "main": "./src/index.ts",

package/src/server/boot.ts

@@ -54,6 +54,7 @@ import { addUnread, markRead as markUnread, getUnreads } from './unread.ts';
 import { loadShragaConfig, getPublicOrigin } from './shraga-config.ts';
 import { startSidecars, stopSidecars } from './mcp-sidecar.ts';
 import { syncVendorRepos } from './vendor-sync.ts';
+import { SelfUpgrade } from './self-upgrade/index.ts';
 import { initEngines, getAvailableEngines, getEngine } from './engine/index.ts';
 import { statsSampler } from './stats.ts';
 import { getAll as getAllContacts } from './contacts.ts';
@@ -116,6 +117,7 @@ for (const e of __reg.engines ?? []) registerEngine(e);
 for (const s of __reg.eventSubs ?? []) subscribeEvent(s.source, s.handler);
 await initEngines();
 if (!PASSIVE) syncVendorRepos().catch(err => console.warn('[vendor-sync] error:', (err as Error).message));
+const selfUpgrade = new SelfUpgrade();
 seedDefaults();
 const purged = purgeExpiredSkills();
 if (purged.length) console.log(`[skills] Purged ${purged.length} expired skill(s): ${purged.join(', ')}`);
@@ -182,6 +184,41 @@ app.get('/api/version', (_req, res) => {
   } catch { res.json({ version: 'unknown' }); }
 });
 
+// ── Self-upgrade (owner only) ────────────────────────────────────────────────
+// Upgrading replaces the code serving this request and restarts the process, so it is strictly an
+// owner action, and the response can only ever be "started" — the OUTCOME arrives after the restart,
+// via the self-upgrade.finished event (see deliverPendingReport) and GET /api/self-upgrade.
+
+app.get('/api/self-upgrade', requireAuth, async (req, res) => {
+  if (!(req as any).user?.isOwner) return void res.status(403).json({ error: 'Only the owner can manage upgrades' });
+  const current = selfUpgrade.currentVersion();
+  let latest: string | null = null;
+  let latestError: string | undefined;
+  try { latest = await selfUpgrade.latestVersion(); }
+  catch (err) { latestError = (err as Error).message; }
+  res.json({
+    current,
+    latest,
+    latestError,
+    upToDate: !!latest && latest === current,
+    blockers: selfUpgrade.blockers(),
+    inFlight: selfUpgrade.inFlight(),
+    lastReport: selfUpgrade.lastReport(),
+  });
+});
+
+app.post('/api/self-upgrade', requireAuth, async (req, res) => {
+  if (!(req as any).user?.isOwner) return void res.status(403).json({ error: 'Only the owner can manage upgrades' });
+  try {
+    const plan = await selfUpgrade.start({ version: req.body?.version });
+    // 409, not 500: a refusal is a well-formed answer about the deployment's state, and the caller
+    // (often the agent, relaying to a human) needs the reason, not a stack trace.
+    res.status(plan.started ? 202 : 409).json(plan);
+  } catch (err) {
+    res.status(500).json({ error: (err as Error).message });
+  }
+});
+
 // Cached host stats — returns the in-memory ring buffer (does NOT sample on request).
 app.get('/api/stats', requireAuth, (_req, res) => {
   res.json({ samples: statsSampler.getStats() });
@@ -2034,6 +2071,11 @@ await new Promise<void>((resolve) => {
     console.log(`[server] Running on http://0.0.0.0:${PORT}`);
     resolve();
     if (PASSIVE) return; // no sidecars, recovery, or MCP warmers in passive mode
+    // Deliver here, not earlier in boot: an upgrade's outcome is only knowable once we are the
+    // process that came back, and the event has to land after the dispatcher is subscribed or the
+    // owner never hears how it went.
+    try { selfUpgrade.deliverPendingReport(); }
+    catch (err) { console.warn('[self-upgrade] could not deliver report:', (err as Error).message); }
     startSidecars().catch(err => console.error('[sidecar] startup error:', err));
     recoverInterruptedSessions().catch(err => console.error('[recovery] failed:', err));
     // The disk MCP catalog is warmed off the turn path by whichever engine consumes it — the CE default

package/src/server/self-upgrade/index.ts

@@ -0,0 +1,203 @@
+// Self-upgrade — re-pin Shraga's own package version in the deployment, restart, verify, and revert
+// automatically if the new version doesn't come back healthy.
+//
+// SHAPE: this module only PREFLIGHTS and HANDS OFF. The upgrade itself runs in a detached
+// supervisor.sh, because the restart kills this process — code that dies mid-operation cannot verify
+// or roll back its own work. Everything risky lives in the script; everything that decides whether
+// the attempt is even allowed lives here, where it can be tested and can answer the caller.
+//
+// USER-REQUESTED ONLY by design. There is no timer in this module: `POST /api/self-upgrade` is the
+// entry point. Deployments that want it scheduled can point a schedule at that route, which keeps
+// the "should I upgrade tonight?" policy out of the mechanism.
+import { existsSync, lstatSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { APP_ROOT, PACKAGE_ROOT, dataPath } from '../paths.ts';
+import { emitEvent } from '../events/bus.ts';
+
+const TAG = '[self-upgrade]';
+const PKG = 'shraga';
+
+export class SelfUpgrade {
+  public constructor(public options?: Partial<SelfUpgradeOptions>) {
+    this.options = { ...new SelfUpgradeOptions(), ...options };
+  }
+
+  private get o(): SelfUpgradeOptions { return this.options as SelfUpgradeOptions; }
+
+  /** Version of `pkg` this deployment currently has pinned in its app-root package.json. */
+  public currentVersion(): string | null {
+    try {
+      const pkg = JSON.parse(readFileSync(path.join(this.o.appRoot, 'package.json'), 'utf8'));
+      const dep = pkg.dependencies?.[this.o.pkg] ?? pkg.devDependencies?.[this.o.pkg];
+      return typeof dep === 'string' ? dep.replace(/^[\^~]/, '') : null;
+    } catch { return null; }
+  }
+
+  /** Latest version on the registry. Plain HTTP against the registry — no npm CLI, no auth needed
+   *  for a public package, and it works the same on a box with no npm installed. */
+  public async latestVersion(): Promise<string> {
+    const res = await fetch(`${this.o.registry}/${this.o.pkg}/latest`, { signal: AbortSignal.timeout(15_000) });
+    if (!res.ok) throw new Error(`registry lookup failed: ${res.status} ${res.statusText}`);
+    const body = await res.json() as { version?: string };
+    if (!body.version) throw new Error('registry returned no version');
+    return body.version;
+  }
+
+  public async versionExists(version: string): Promise<boolean> {
+    const res = await fetch(`${this.o.registry}/${this.o.pkg}/${version}`, { signal: AbortSignal.timeout(15_000) });
+    return res.ok;
+  }
+
+  /** Everything that must be true before we are willing to touch the deployment. Returns the reasons
+   *  it is NOT safe; empty array = go. Each check exists because of a way this can go wrong:
+   *   - not an npm consumer  → there is no dep pin to move (source checkout); upgrading means `git pull`.
+   *   - linked dependency    → node_modules/<pkg> is a dev symlink to a working checkout. Installing
+   *                            would silently replace live local source with a registry build.
+   *   - no restart command   → we could install a new version and never run it, leaving the pin and
+   *                            the running process disagreeing with no way to reconcile.
+   *   - upgrade in flight    → two supervisors racing on package.json is how you get a tree that
+   *                            matches neither version. */
+  public blockers(): string[] {
+    const reasons: string[] = [];
+    const pkgPath = path.join(this.o.appRoot, 'package.json');
+
+    if (!existsSync(pkgPath)) {
+      reasons.push(`no package.json at ${this.o.appRoot} — nothing to re-pin`);
+    } else if (!this.currentVersion()) {
+      reasons.push(`${this.o.pkg} is not a declared dependency of ${pkgPath} — this looks like a source checkout, upgrade it with git`);
+    }
+
+    const linkPath = path.join(this.o.appRoot, 'node_modules', this.o.pkg);
+    try {
+      if (lstatSync(linkPath).isSymbolicLink()) {
+        reasons.push(`node_modules/${this.o.pkg} is a symlink (local dev link) — installing would replace live local source with a registry build`);
+      }
+    } catch { /* absent is fine: install will create it */ }
+
+    if (!this.o.restartCmd) {
+      reasons.push('no restart command configured (RESTART_CMD / SHRAGA_RESTART_CMD) — an installed version could never be started');
+    }
+
+    const active = this.inFlight();
+    if (active) reasons.push(`an upgrade to ${active.target} is already in flight (started ${active.startedAt})`);
+
+    return reasons;
+  }
+
+  /** The in-flight marker, or null. Stale markers (older than maxRunMs) are ignored rather than
+   *  blocking forever — a supervisor killed by a reboot must not wedge the feature permanently. */
+  public inFlight(): { target: string; startedAt: string } | null {
+    try {
+      const lock = JSON.parse(readFileSync(this.o.lockFile, 'utf8')) as { target: string; startedAt: string; at: number };
+      if (Date.now() - lock.at > this.o.maxRunMs) return null;
+      return { target: lock.target, startedAt: lock.startedAt };
+    } catch { return null; }
+  }
+
+  /**
+   * Start an upgrade. Resolves as soon as the supervisor is detached — the result arrives later, in
+   * the report file, because this process is about to be restarted by that supervisor.
+   */
+  public async start(opts: { version?: string } = {}): Promise<UpgradePlan> {
+    const from = this.currentVersion();
+    const target = !opts.version || opts.version === 'latest' ? await this.latestVersion() : opts.version.replace(/^v/, '');
+
+    const blockers = this.blockers();
+    if (blockers.length) return { started: false, from, target, reason: blockers.join('; ') };
+    if (from === target) return { started: false, from, target, reason: `already on ${target}` };
+    if (!await this.versionExists(target)) return { started: false, from, target, reason: `${this.o.pkg}@${target} does not exist on the registry` };
+
+    mkdirSync(path.dirname(this.o.reportFile), { recursive: true });
+    writeFileSync(this.o.lockFile, JSON.stringify({ target, startedAt: new Date().toISOString(), at: Date.now() }));
+
+    // detached + ignored stdio: the supervisor must outlive us, and it will — we are its first
+    // casualty. It logs to a file of its own (see supervisor.sh).
+    const child = spawn('bash', [this.o.supervisorScript], {
+      cwd: this.o.appRoot,
+      detached: true,
+      stdio: 'ignore',
+      env: {
+        ...process.env,
+        APP_ROOT: this.o.appRoot,
+        PKG: this.o.pkg,
+        TARGET: target,
+        FROM: from ?? '',
+        RESTART_CMD: this.o.restartCmd,
+        HEALTH_URL: this.o.healthUrl,
+        REPORT: this.o.reportFile,
+        BUN: this.o.bun,
+        BOOT_TIMEOUT: String(this.o.bootTimeoutSec),
+        SOAK: String(this.o.soakSec),
+      },
+    });
+    child.unref();
+
+    console.log(`${TAG} handed off ${this.o.pkg} ${from} -> ${target} to supervisor pid ${child.pid}`);
+    return { started: true, from, target, reason: `upgrading to ${target}; the result will be reported when the server comes back` };
+  }
+
+  /** Read the report left by the last supervisor run, if any. */
+  public lastReport(): UpgradeReport | null {
+    try { return JSON.parse(readFileSync(this.o.reportFile, 'utf8')) as UpgradeReport; }
+    catch { return null; }
+  }
+
+  /**
+   * Call once at boot. A finished upgrade is only observable AFTER the restart, so this is where the
+   * outcome finally reaches a human: the report is turned into an event, and the deployment's own
+   * notifier trigger (the same path scheduled-job failures use) DMs the owner. Consuming the report
+   * — deleting it — is what makes the delivery exactly-once across restarts.
+   */
+  public deliverPendingReport(): UpgradeReport | null {
+    const report = this.lastReport();
+    if (!report) return null;
+    try { unlinkSync(this.o.reportFile); } catch { /* report already gone; emit anyway */ }
+    try { unlinkSync(this.o.lockFile); } catch { /* no lock to clear */ }
+
+    console.log(`${TAG} ${report.status}: ${report.detail}`);
+    emitEvent('self-upgrade.finished', report);
+    return report;
+  }
+}
+
+export class SelfUpgradeOptions {
+  /** The DEPLOYMENT root (holds package.json + node_modules) — never PACKAGE_ROOT, which for an npm
+   *  consumer is node_modules/shraga and has no dep pin to move. */
+  public appRoot: string = APP_ROOT;
+  public pkg: string = PKG;
+  public registry: string = process.env.SHRAGA_UPGRADE_REGISTRY?.trim() || 'https://registry.npmjs.org';
+  public restartCmd: string = (process.env.SHRAGA_RESTART_CMD || process.env.RESTART_CMD || '').trim();
+  public healthUrl: string = `http://127.0.0.1:${process.env.PORT || 3032}/api/version`;
+  public bun: string = process.env.SHRAGA_BUN?.trim() || process.execPath || 'bun';
+  /** Shipped inside src/, so it reaches npm consumers (package.json `files` includes src/). */
+  public supervisorScript: string = path.join(PACKAGE_ROOT, 'src', 'server', 'self-upgrade', 'supervisor.sh');
+  public reportFile: string = dataPath('.self-upgrade', 'report.json');
+  public lockFile: string = dataPath('.self-upgrade', 'in-flight.json');
+  public bootTimeoutSec: number = 180;
+  public soakSec: number = 60;
+  /** After this, an in-flight marker is treated as abandoned (supervisor killed by a reboot). */
+  public maxRunMs: number = 30 * 60 * 1000;
+}
+
+export interface UpgradePlan {
+  started: boolean;
+  from: string | null;
+  target: string;
+  reason: string;
+}
+
+export interface UpgradeReport {
+  status: 'ok' | 'reverted' | 'failed' | 'revert-failed';
+  detail: string;
+  from: string;
+  target: string;
+  installed: string;
+  package: string;
+  log: string;
+  finishedAt: string;
+}
+
+declare module '../events/types.ts' {
+  interface ShragaEventMap { 'self-upgrade.finished': UpgradeReport }
+}

package/src/server/self-upgrade/supervisor.sh

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# Upgrade supervisor — runs DETACHED, outside the server it is upgrading.
+#
+# WHY A SCRIPT AND NOT SERVER CODE: an upgrade restarts the server, so the process that starts the
+# upgrade cannot observe whether it worked. Anything that must survive the restart — the verify, and
+# above all the REVERT — has to live outside it. This is the same shape as power-guard.sh and
+# health-watchdog.sh, and it is the whole reason a self-upgrade can be trusted: the rollback path
+# does not depend on the code being rolled back.
+#
+# Contract (all via env, no positional args):
+#   APP_ROOT      consumer root holding package.json + the lockfile        (required)
+#   PKG           dependency name to re-pin, normally "shraga"             (required)
+#   TARGET        version to install, e.g. 0.1.35                          (required)
+#   FROM          version currently pinned, restored on failure            (required)
+#   RESTART_CMD   how to restart the service                               (required)
+#   HEALTH_URL    must report TARGET after the restart                     (required)
+#   REPORT        JSON report path; the server reads it on next boot       (required)
+#   BUN           bun binary                                  (default: bun on PATH)
+#   BOOT_TIMEOUT  seconds to wait for the version to flip     (default: 180)
+#   SOAK          seconds it must KEEP answering after that   (default: 60)
+#
+# Exit code is advisory only — nobody is listening. The REPORT file is the real output.
+set -uo pipefail
+
+: "${APP_ROOT:?}" "${PKG:?}" "${TARGET:?}" "${FROM:?}" "${RESTART_CMD:?}" "${HEALTH_URL:?}" "${REPORT:?}"
+BUN="${BUN:-bun}"
+BOOT_TIMEOUT="${BOOT_TIMEOUT:-180}"
+SOAK="${SOAK:-60}"
+
+cd "$APP_ROOT" || exit 1
+BACKUP="$(mktemp -d)"
+LOG="${REPORT%.json}.log"
+exec >>"$LOG" 2>&1
+
+ts() { date '+%F %T'; }
+say() { echo "[upgrade] $(ts) $*"; }
+
+# The report is the only channel back to the server, so write it defensively: a partial or
+# unparseable file must not look like a success.
+write_report() { # status detail installed
+  local tmp="$REPORT.tmp"
+  cat > "$tmp" <<JSON
+{
+  "status": "$1",
+  "detail": $(printf '%s' "$2" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))'),
+  "from": "$FROM",
+  "target": "$TARGET",
+  "installed": "$3",
+  "package": "$PKG",
+  "log": "$LOG",
+  "finishedAt": "$(date -u '+%FT%TZ')"
+}
+JSON
+  mv "$tmp" "$REPORT"
+}
+
+# Snapshot EVERYTHING the install can rewrite. Restoring package.json without its lockfile would
+# resolve a different tree than the one that was known-good.
+snapshot() {
+  cp package.json "$BACKUP/" 2>/dev/null || return 1
+  for f in bun.lock bun.lockb package-lock.json; do [ -f "$f" ] && cp "$f" "$BACKUP/"; done
+  return 0
+}
+restore() {
+  cp "$BACKUP/package.json" package.json || return 1
+  for f in bun.lock bun.lockb package-lock.json; do [ -f "$BACKUP/$f" ] && cp "$BACKUP/$f" "$f"; done
+  return 0
+}
+
+pin() { # version — rewrite only this dep's pin, leaving the rest of package.json byte-identical
+  PKG="$PKG" V="$1" python3 - <<'PY'
+import json, os, re
+pkg, ver = os.environ['PKG'], os.environ['V']
+src = open('package.json').read()
+pat = re.compile(r'("%s"\s*:\s*")[^"]*(")' % re.escape(pkg))
+if not pat.search(src):
+    raise SystemExit(f'{pkg} not found in package.json')
+open('package.json', 'w').write(pat.sub(lambda m: m.group(1) + ver + m.group(2), src, count=1))
+PY
+}
+
+# Healthy = the endpoint answers AND reports the version we expect. "It responds" is not enough:
+# a server that came back on the OLD version is a failed upgrade, not a healthy one.
+reports_version() { # version
+  local body
+  body="$(curl -sf -m 10 "$HEALTH_URL" 2>/dev/null)" || return 1
+  printf '%s' "$body" | grep -q "\"$1\"" || return 1
+  return 0
+}
+
+wait_for_version() { # version timeout
+  local deadline=$(( SECONDS + $2 ))
+  while [ "$SECONDS" -lt "$deadline" ]; do
+    reports_version "$1" && return 0
+    sleep 5
+  done
+  return 1
+}
+
+# A server that boots, flips the version, then dies 20s later has NOT upgraded successfully — that is
+# exactly the crash-loop an unattended upgrade must catch. Keep probing for the whole soak window.
+soak() { # version seconds
+  local deadline=$(( SECONDS + $2 ))
+  while [ "$SECONDS" -lt "$deadline" ]; do
+    reports_version "$1" || return 1
+    sleep 5
+  done
+  return 0
+}
+
+install_and_restart() { # version label
+  say "installing $PKG@$1 ($2)"
+  if ! pin "$1"; then say "pin failed"; return 1; fi
+  if ! "$BUN" install; then say "bun install failed"; return 1; fi
+  say "restarting via: $RESTART_CMD"
+  eval "$RESTART_CMD" || say "restart command returned non-zero (continuing — some managers do)"
+  return 0
+}
+
+# ── Upgrade ───────────────────────────────────────────────────────────────────
+say "=== $PKG $FROM -> $TARGET ==="
+if ! snapshot; then
+  write_report failed "could not snapshot package.json in $APP_ROOT — refused to touch anything" "$FROM"
+  exit 1
+fi
+
+if ! install_and_restart "$TARGET" upgrade; then
+  restore && "$BUN" install >/dev/null 2>&1
+  write_report failed "install of $PKG@$TARGET failed; package.json restored, service untouched" "$FROM"
+  exit 1
+fi
+
+if wait_for_version "$TARGET" "$BOOT_TIMEOUT" && soak "$TARGET" "$SOAK"; then
+  say "verified $TARGET (booted + soaked ${SOAK}s)"
+  write_report ok "upgraded to $TARGET and verified for ${SOAK}s" "$TARGET"
+  exit 0
+fi
+
+# ── Revert ────────────────────────────────────────────────────────────────────
+say "verification FAILED — reverting to $FROM"
+if ! restore; then
+  write_report revert-failed "upgrade to $TARGET failed AND the backup could not be restored — MANUAL FIX NEEDED. Backup: $BACKUP" unknown
+  exit 1
+fi
+if ! install_and_restart "$FROM" revert; then
+  write_report revert-failed "upgrade to $TARGET failed and reinstalling $FROM ALSO failed — MANUAL FIX NEEDED. Backup: $BACKUP" unknown
+  exit 1
+fi
+
+if wait_for_version "$FROM" "$BOOT_TIMEOUT"; then
+  say "reverted to $FROM"
+  write_report reverted "upgrade to $TARGET failed verification; reverted to $FROM and confirmed healthy" "$FROM"
+  rm -rf "$BACKUP"
+  exit 0
+fi
+
+write_report revert-failed "upgrade to $TARGET failed and the revert to $FROM did not come back healthy — MANUAL FIX NEEDED. Backup: $BACKUP" unknown
+exit 1