@agentplate/cli 1.0.0

package/src/serve/system.ts

@@ -0,0 +1,90 @@
+/**
+ * Host system metrics for the System Monitor screen + bottom status bar.
+ *
+ * Reads real CPU / memory / disk / uptime of the machine running `agentplate
+ * serve` via Node's `os` module and a `df` probe (best-effort; degrades to nulls
+ * if a probe fails). CPU load is approximated from the 1-minute load average
+ * over the core count — cheap and dependency-free.
+ */
+
+import { cpus, freemem, hostname, loadavg, totalmem, uptime } from "node:os";
+
+export interface SystemMetrics {
+	cpu: {
+		cores: number;
+		/** 0..100 utilization estimate from 1-min load average / cores. */
+		percent: number;
+		loadAvg: [number, number, number];
+	};
+	memory: {
+		usedBytes: number;
+		totalBytes: number;
+		percent: number;
+	};
+	disk: {
+		usedBytes: number | null;
+		totalBytes: number | null;
+		percent: number | null;
+	};
+	uptimeSeconds: number;
+	hostname: string;
+	platform: string;
+}
+
+/** Probe disk usage of the root filesystem via `df -k /` (best-effort). */
+async function diskUsage(): Promise<SystemMetrics["disk"]> {
+	// `df` is Unix-only; on Windows report unknown rather than erroring (the UI
+	// already renders "—" for null disk metrics).
+	if (process.platform === "win32") {
+		return { usedBytes: null, totalBytes: null, percent: null };
+	}
+	try {
+		const proc = Bun.spawn(["df", "-k", "/"], { stdout: "pipe", stderr: "pipe" });
+		const out = await new Response(proc.stdout).text();
+		await proc.exited;
+		// Second line: Filesystem 1K-blocks Used Available Capacity ... Mounted
+		const line = out.trim().split("\n")[1] ?? "";
+		const cols = line.split(/\s+/);
+		const totalKb = Number(cols[1]);
+		const usedKb = Number(cols[2]);
+		if (!Number.isFinite(totalKb) || !Number.isFinite(usedKb) || totalKb <= 0) {
+			return { usedBytes: null, totalBytes: null, percent: null };
+		}
+		const totalBytes = totalKb * 1024;
+		const usedBytes = usedKb * 1024;
+		return { usedBytes, totalBytes, percent: Math.round((usedBytes / totalBytes) * 100) };
+	} catch {
+		return { usedBytes: null, totalBytes: null, percent: null };
+	}
+}
+
+/** Collect a full system-metrics snapshot. */
+export async function collectSystemMetrics(): Promise<SystemMetrics> {
+	const cores = cpus().length || 1;
+	const la = loadavg();
+	const load1 = la[0] ?? 0;
+	const cpuPercent = Math.min(100, Math.round((load1 / cores) * 100));
+
+	const total = totalmem();
+	const free = freemem();
+	const usedMem = total - free;
+
+	const disk = await diskUsage();
+
+	return {
+		cpu: {
+			cores,
+			percent: cpuPercent,
+			loadAvg: [la[0] ?? 0, la[1] ?? 0, la[2] ?? 0],
+		},
+		memory: {
+			usedBytes: usedMem,
+			totalBytes: total,
+			percent: total > 0 ? Math.round((usedMem / total) * 100) : 0,
+		},
+		disk,
+		uptimeSeconds: Math.round(uptime()),
+		hostname: hostname(),
+		platform: process.platform,
+	};
+}

package/src/serve/weather.ts

@@ -0,0 +1,140 @@
+/**
+ * Weather widget data via Open-Meteo (free, no API key).
+ *
+ * Geocodes a location name → lat/lon, then fetches current conditions + a 3-day
+ * forecast. Best-effort: on any network/parse failure returns `available:false`
+ * so the UI can hide or stub the widget. Results are cached briefly to avoid
+ * hammering the API from the 5s snapshot loop (the widget is polled, not pushed).
+ */
+
+const DEFAULT_LOCATION = process.env.AGENTPLATE_WEATHER_LOCATION || "Madrid";
+
+export interface WeatherDay {
+	date: string;
+	tempMax: number;
+	tempMin: number;
+	code: number;
+}
+
+export interface Weather {
+	available: boolean;
+	location: string;
+	tempC: number | null;
+	feelsLikeC: number | null;
+	humidity: number | null;
+	windKmh: number | null;
+	code: number | null;
+	description: string;
+	forecast: WeatherDay[];
+}
+
+const WMO: Record<number, string> = {
+	0: "Clear sky",
+	1: "Mainly clear",
+	2: "Partly cloudy",
+	3: "Overcast",
+	45: "Fog",
+	48: "Rime fog",
+	51: "Light drizzle",
+	61: "Light rain",
+	63: "Rain",
+	65: "Heavy rain",
+	71: "Light snow",
+	73: "Snow",
+	80: "Rain showers",
+	95: "Thunderstorm",
+};
+
+function describe(code: number | null): string {
+	return code != null ? (WMO[code] ?? "—") : "—";
+}
+
+interface CacheEntry {
+	at: number;
+	value: Weather;
+}
+const cache = new Map<string, CacheEntry>();
+const TTL_MS = 10 * 60 * 1000; // 10 minutes
+
+const empty = (location: string): Weather => ({
+	available: false,
+	location,
+	tempC: null,
+	feelsLikeC: null,
+	humidity: null,
+	windKmh: null,
+	code: null,
+	description: "—",
+	forecast: [],
+});
+
+/** Fetch current weather + forecast for a location (cached ~10 min). */
+export async function fetchWeather(loc?: string | null): Promise<Weather> {
+	const location = loc?.trim() || DEFAULT_LOCATION;
+	const cached = cache.get(location);
+	if (cached && Date.now() - cached.at < TTL_MS) return cached.value;
+
+	try {
+		// 1. Geocode.
+		const geoRes = await fetch(
+			`https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(location)}&count=1`,
+		);
+		const geo = (await geoRes.json()) as {
+			results?: Array<{ latitude: number; longitude: number; name: string }>;
+		};
+		const place = geo.results?.[0];
+		if (!place) {
+			const v = empty(location);
+			cache.set(location, { at: Date.now(), value: v });
+			return v;
+		}
+
+		// 2. Current + daily forecast.
+		const wxRes = await fetch(
+			`https://api.open-meteo.com/v1/forecast?latitude=${place.latitude}&longitude=${place.longitude}` +
+				`&current=temperature_2m,apparent_temperature,relative_humidity_2m,weather_code,wind_speed_10m` +
+				`&daily=weather_code,temperature_2m_max,temperature_2m_min&forecast_days=3&timezone=auto`,
+		);
+		const wx = (await wxRes.json()) as {
+			current?: {
+				temperature_2m: number;
+				apparent_temperature: number;
+				relative_humidity_2m: number;
+				weather_code: number;
+				wind_speed_10m: number;
+			};
+			daily?: {
+				time: string[];
+				weather_code: number[];
+				temperature_2m_max: number[];
+				temperature_2m_min: number[];
+			};
+		};
+		const cur = wx.current;
+		const daily = wx.daily;
+		const forecast: WeatherDay[] = daily
+			? daily.time.map((date, i) => ({
+					date,
+					tempMax: Math.round(daily.temperature_2m_max[i] ?? 0),
+					tempMin: Math.round(daily.temperature_2m_min[i] ?? 0),
+					code: daily.weather_code[i] ?? 0,
+				}))
+			: [];
+
+		const value: Weather = {
+			available: Boolean(cur),
+			location: place.name,
+			tempC: cur ? Math.round(cur.temperature_2m) : null,
+			feelsLikeC: cur ? Math.round(cur.apparent_temperature) : null,
+			humidity: cur ? Math.round(cur.relative_humidity_2m) : null,
+			windKmh: cur ? Math.round(cur.wind_speed_10m) : null,
+			code: cur ? cur.weather_code : null,
+			description: describe(cur?.weather_code ?? null),
+			forecast,
+		};
+		cache.set(location, { at: Date.now(), value });
+		return value;
+	} catch {
+		return empty(location);
+	}
+}

package/src/sessions/reaper.test.ts

@@ -0,0 +1,162 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { sessionsDbPath } from "../paths.ts";
+import type { AgentSession } from "../types.ts";
+import { reapIdleSessions, selectIdleSessions } from "./reaper.ts";
+import { createSessionStore } from "./store.ts";
+
+const NOW = Date.parse("2026-06-01T12:00:00.000Z");
+const IDLE_MS = 10 * 60_000;
+
+/** ISO timestamp `n` minutes before NOW. */
+function minsAgo(n: number): string {
+	return new Date(NOW - n * 60_000).toISOString();
+}
+
+function mk(overrides: Partial<AgentSession>): AgentSession {
+	return {
+		id: `s-${overrides.agentName ?? "a"}`,
+		agentName: "a",
+		capability: "builder",
+		taskId: "t",
+		runId: "r1",
+		// Not under .agentplate/worktrees, so the removable-worktree guard skips git.
+		worktreePath: "/tmp/not-managed/a",
+		branchName: "agentplate/a",
+		state: "idle",
+		parentAgent: null,
+		depth: 1,
+		pid: null,
+		runtimeSessionId: null,
+		startedAt: minsAgo(60),
+		lastActivity: minsAgo(60),
+		...overrides,
+	};
+}
+
+describe("selectIdleSessions", () => {
+	test("reaps an active session idle past the window", () => {
+		const out = selectIdleSessions([mk({ agentName: "old", lastActivity: minsAgo(11) })], {
+			idleMs: IDLE_MS,
+			now: NOW,
+		});
+		expect(out.map((s) => s.agentName)).toEqual(["old"]);
+	});
+
+	test("keeps a session active within the window", () => {
+		const out = selectIdleSessions([mk({ agentName: "fresh", lastActivity: minsAgo(5) })], {
+			idleMs: IDLE_MS,
+			now: NOW,
+		});
+		expect(out).toEqual([]);
+	});
+
+	test("reaps exactly at the boundary", () => {
+		const out = selectIdleSessions([mk({ agentName: "edge", lastActivity: minsAgo(10) })], {
+			idleMs: IDLE_MS,
+			now: NOW,
+		});
+		expect(out.map((s) => s.agentName)).toEqual(["edge"]);
+	});
+
+	test("reaps stalled working/booting sessions too (no activity = idle)", () => {
+		const sessions = [
+			mk({ agentName: "hung", state: "working", lastActivity: minsAgo(20) }),
+			mk({ agentName: "boot", state: "booting", lastActivity: minsAgo(20) }),
+		];
+		expect(
+			selectIdleSessions(sessions, { idleMs: IDLE_MS, now: NOW })
+				.map((s) => s.agentName)
+				.sort(),
+		).toEqual(["boot", "hung"]);
+	});
+
+	test("skips terminal states", () => {
+		const sessions = [
+			mk({ agentName: "done", state: "completed", lastActivity: minsAgo(60) }),
+			mk({ agentName: "failed", state: "failed", lastActivity: minsAgo(60) }),
+			mk({ agentName: "stopped", state: "stopped", lastActivity: minsAgo(60) }),
+		];
+		expect(selectIdleSessions(sessions, { idleMs: IDLE_MS, now: NOW })).toEqual([]);
+	});
+
+	test("excludes the coordinator by default", () => {
+		const coord = mk({
+			agentName: "coordinator",
+			capability: "coordinator",
+			state: "working",
+			lastActivity: minsAgo(60),
+		});
+		expect(selectIdleSessions([coord], { idleMs: IDLE_MS, now: NOW })).toEqual([]);
+	});
+
+	test("honors a custom exclude list", () => {
+		const lead = mk({ agentName: "l", capability: "lead", lastActivity: minsAgo(60) });
+		expect(
+			selectIdleSessions([lead], { idleMs: IDLE_MS, now: NOW, excludeCapabilities: ["lead"] }),
+		).toEqual([]);
+	});
+
+	test("skips sessions with an unparseable lastActivity", () => {
+		const bad = mk({ agentName: "bad", lastActivity: "not-a-date" });
+		expect(selectIdleSessions([bad], { idleMs: IDLE_MS, now: NOW })).toEqual([]);
+	});
+});
+
+describe("reapIdleSessions", () => {
+	let root: string;
+	beforeEach(() => {
+		root = mkdtempSync(join(tmpdir(), "ap-reap-"));
+	});
+	afterEach(() => {
+		rmSync(root, { recursive: true, force: true });
+	});
+
+	test("marks idle sessions stopped, leaves fresh ones, and reports what it reaped", async () => {
+		const store = createSessionStore(sessionsDbPath(root));
+		try {
+			const run = store.createRun("r");
+			store.upsertSession(
+				mk({ id: "s-old", agentName: "old", runId: run.id, lastActivity: minsAgo(30) }),
+			);
+			store.upsertSession(
+				mk({ id: "s-fresh", agentName: "fresh", runId: run.id, lastActivity: minsAgo(2) }),
+			);
+
+			const reaped = await reapIdleSessions(store, root, { idleMs: IDLE_MS, now: NOW });
+
+			expect(reaped.map((r) => r.agentName)).toEqual(["old"]);
+			expect(reaped[0]?.idleMs).toBe(30 * 60_000);
+			// `old` is now stopped; `fresh` keeps running.
+			expect(store.getSessionByAgent("old")?.state).toBe("stopped");
+			expect(store.getSessionByAgent("fresh")?.state).toBe("idle");
+		} finally {
+			store.close();
+		}
+	});
+
+	test("never touches the coordinator even when long-idle", async () => {
+		const store = createSessionStore(sessionsDbPath(root));
+		try {
+			const run = store.createRun("r");
+			store.upsertSession(
+				mk({
+					id: "s-coord",
+					agentName: "coordinator",
+					capability: "coordinator",
+					state: "working",
+					worktreePath: root, // coordinator runs at the project root
+					runId: run.id,
+					lastActivity: minsAgo(120),
+				}),
+			);
+			const reaped = await reapIdleSessions(store, root, { idleMs: IDLE_MS, now: NOW });
+			expect(reaped).toEqual([]);
+			expect(store.getSessionByAgent("coordinator")?.state).toBe("working");
+		} finally {
+			store.close();
+		}
+	});
+});

package/src/sessions/reaper.ts

@@ -0,0 +1,149 @@
+/**
+ * Idle-session reaper — terminate agents that have gone quiet.
+ *
+ * Agentplate workers run spawn-per-turn: between turns a worker sits `idle` with
+ * no live process, waiting for mail that may never come. A stalled turn can also
+ * leave a session stuck `working`. Either way, an agent with no activity for the
+ * configured idle window is dead weight — it counts toward the concurrency cap and
+ * clutters the UI. This module reaps them: mark the session `stopped`, kill any
+ * live pid, and (by default) remove its worktree + branch.
+ *
+ * "Activity" is the session's `last_activity`, which `sling` bumps on every
+ * streamed runtime event, so an agent actively working a long turn keeps itself
+ * fresh and is never reaped — only genuinely idle/stalled agents are. The
+ * coordinator is excluded by default (it's a long-lived interactive session whose
+ * worktree IS the project root, and it does not stream per-turn events).
+ */
+
+import { worktreesDir } from "../paths.ts";
+import type { AgentSession, SessionState } from "../types.ts";
+import { deleteBranch, removeWorktree, worktreeExists } from "../worktree/manager.ts";
+import type { SessionStore } from "./store.ts";
+
+/** States that can be reaped — the pre-terminal (still-counted) ones. */
+const REAPABLE_STATES: readonly SessionState[] = ["booting", "working", "idle"];
+
+/** Capabilities never reaped (the coordinator runs at the project root). */
+const DEFAULT_EXCLUDE: readonly string[] = ["coordinator"];
+
+export interface SelectIdleOptions {
+	/** Idle window in milliseconds: reap sessions with no activity for this long. */
+	idleMs: number;
+	/** Reference "now" in epoch ms (injectable for tests). */
+	now: number;
+	/** Capabilities to skip (defaults to `["coordinator"]`). */
+	excludeCapabilities?: readonly string[];
+}
+
+/**
+ * Pure selector: which sessions are idle past the window. Kept side-effect-free so
+ * the reap policy is trivially unit-testable without a store or git.
+ */
+export function selectIdleSessions(
+	sessions: readonly AgentSession[],
+	opts: SelectIdleOptions,
+): AgentSession[] {
+	const exclude = new Set(opts.excludeCapabilities ?? DEFAULT_EXCLUDE);
+	return sessions.filter((s) => {
+		if (!REAPABLE_STATES.includes(s.state)) return false;
+		if (exclude.has(s.capability)) return false;
+		const last = Date.parse(s.lastActivity);
+		if (Number.isNaN(last)) return false;
+		return opts.now - last >= opts.idleMs;
+	});
+}
+
+/** One reaped agent, returned for logging / reporting. */
+export interface ReapedAgent {
+	id: string;
+	agentName: string;
+	capability: string;
+	/** How long it had been idle, in ms. */
+	idleMs: number;
+	/** Whether its worktree was removed (false if kept, missing, or removal failed). */
+	worktreeRemoved: boolean;
+}
+
+export interface ReapOptions {
+	/** Idle window in milliseconds. */
+	idleMs: number;
+	/** Reference "now" in epoch ms (defaults to `Date.now()`). */
+	now?: number;
+	/** Remove the reaped agent's worktree + branch (default true). */
+	removeWorktrees?: boolean;
+	/** Capabilities to skip (defaults to `["coordinator"]`). */
+	excludeCapabilities?: readonly string[];
+}
+
+/**
+ * Reap idle sessions: kill any live pid, optionally remove the worktree + branch,
+ * and mark the session `stopped`. Every side effect is best-effort and isolated
+ * per session — a failure to kill a process or remove a worktree still marks the
+ * session stopped and never aborts the sweep. Returns the agents that were reaped.
+ */
+export async function reapIdleSessions(
+	store: SessionStore,
+	root: string,
+	opts: ReapOptions,
+): Promise<ReapedAgent[]> {
+	const now = opts.now ?? Date.now();
+	const removeWorktrees = opts.removeWorktrees !== false;
+	const stale = selectIdleSessions(store.listSessions(), {
+		idleMs: opts.idleMs,
+		now,
+		excludeCapabilities: opts.excludeCapabilities,
+	});
+
+	const reaped: ReapedAgent[] = [];
+	for (const s of stale) {
+		// 1. Kill any live process (spawn-per-turn workers usually have no pid).
+		if (s.pid != null) {
+			try {
+				process.kill(s.pid, "SIGTERM");
+			} catch {
+				// Already gone / not ours — nothing to do.
+			}
+		}
+
+		// 2. Remove the worktree + branch (guarded against the project root).
+		let worktreeRemoved = false;
+		if (removeWorktrees && isRemovableWorktree(root, s.worktreePath)) {
+			try {
+				if (await worktreeExists(root, s.worktreePath)) {
+					await removeWorktree(root, s.worktreePath, { force: true });
+				}
+				worktreeRemoved = true;
+				// Branch delete is separate and best-effort (no-op if already gone).
+				try {
+					await deleteBranch(root, s.branchName);
+				} catch {
+					// Branch may be merged away or shared — leave it.
+				}
+			} catch {
+				worktreeRemoved = false;
+			}
+		}
+
+		// 3. Mark the session terminated so it stops counting and shows as stopped.
+		store.updateSessionState(s.id, "stopped");
+
+		reaped.push({
+			id: s.id,
+			agentName: s.agentName,
+			capability: s.capability,
+			idleMs: now - Date.parse(s.lastActivity),
+			worktreeRemoved,
+		});
+	}
+	return reaped;
+}
+
+/**
+ * Only worktrees under `.agentplate/worktrees/` are removable. This refuses to
+ * touch the project root (the coordinator's `worktreePath`) or any path outside
+ * the managed worktrees dir — a hard safety net beyond the capability exclusion.
+ */
+function isRemovableWorktree(root: string, worktreePath: string): boolean {
+	if (!worktreePath || worktreePath === root) return false;
+	return worktreePath.startsWith(worktreesDir(root));
+}