@reserendipity/dsh-superagent 0.0.0-stage → 0.1.0

package/lib/instance-status-Cqaju-dw.js

@@ -0,0 +1,87 @@
+import { a as literal, c as object, i as boolean, l as record, n as _enum, s as number, u as string } from "./schemas-MhNERx8d.js";
+import { chmodSync, renameSync, utimesSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+const INSTANCE_STATUS_FILE = "instance-status.json";
+const INSTANCE_STATUS_INTERVAL_MS = 1e4;
+/** Older than this mtime means the instance stopped publishing, whatever its pid claims. */
+const INSTANCE_STATUS_STALE_MS = 3e4;
+const HealthEntrySchema = object({
+	state: _enum([
+		"starting",
+		"ready",
+		"paused",
+		"error"
+	]),
+	detail: string(),
+	at: string().optional(),
+	code: string().optional(),
+	values: record(string(), string()).optional()
+});
+const SetupProblemSchema = object({
+	place: string(),
+	code: string(),
+	detail: string()
+});
+const InstanceStatusSchema = object({
+	schema: literal(1),
+	/** The instance record's name when the shell exports SUPERAGENT_INSTANCE; the viewer falls back to the record name. */
+	name: string().nullable(),
+	pid: number().int().positive(),
+	startedAt: string(),
+	/** When the content last changed; the mtime is the heartbeat, not this field. */
+	writtenAt: string(),
+	state: _enum([
+		"starting",
+		"running",
+		"stopping"
+	]),
+	health: record(string(), HealthEntrySchema),
+	load: object({
+		running: number().int().nonnegative(),
+		queued: number().int().nonnegative(),
+		maxWorkers: number().int().positive()
+	}),
+	paused: boolean(),
+	setup: object({
+		configured: boolean(),
+		problem: SetupProblemSchema.nullable()
+	}),
+	watchdog: object({
+		everyMinutes: number(),
+		stallMinutes: number(),
+		lastTickAt: string().nullable()
+	}),
+	tickets: object({
+		open: number().int().nonnegative(),
+		stalled: number().int().nonnegative()
+	}),
+	configPath: string().nullable()
+});
+const instanceStatusPath = (stateDir) => join(stateDir, INSTANCE_STATUS_FILE);
+/**
+* Validates, then replaces the status file atomically: a temporary file in the same directory is renamed over the
+* target, so a reader never parses a half-written document. Mode 0600 is requested on the write (Windows keeps its own
+* ACLs; the call is there for the Unix builds of the plugin).
+*/
+function writeInstanceStatus(stateDir, status) {
+	const parsed = InstanceStatusSchema.parse(status);
+	const target = instanceStatusPath(stateDir);
+	const temporary = target + ".tmp-" + process.pid;
+	writeFileSync(temporary, JSON.stringify(parsed, null, 2) + "\n", {
+		encoding: "utf8",
+		mode: 384
+	});
+	renameSync(temporary, target);
+	try {
+		chmodSync(target, 384);
+	} catch {}
+}
+/** Heartbeat without a rewrite: refresh the mtime of an already published file. */
+function touchInstanceStatus(stateDir) {
+	const now = /* @__PURE__ */ new Date();
+	try {
+		utimesSync(instanceStatusPath(stateDir), now, now);
+	} catch {}
+}
+//#endregion
+export { touchInstanceStatus as a, InstanceStatusSchema as i, INSTANCE_STATUS_INTERVAL_MS as n, writeInstanceStatus as o, INSTANCE_STATUS_STALE_MS as r, INSTANCE_STATUS_FILE as t };

package/lib/instances-view.d.ts

@@ -0,0 +1,164 @@
+import { S as $strip, _ as output, a as ZodLiteral, c as ZodObject, d as ZodRecord, f as ZodString, i as ZodEnum, l as ZodOptional, n as ZodBoolean, o as ZodNullable, s as ZodNumber } from "./schemas-lx-F2nnt.js";
+//#region src/app/instance-status.d.ts
+/**
+ * The per-instance status file: the only write side of the cross-instance view.
+ *
+ * A separate process cannot read another instance's health from the database without opening it, and opening it takes
+ * the very lock the instance holds. So each instance publishes a small, versioned snapshot of what it already knows
+ * (health, load, pause, Watchdog schedule, ticket counts), and the viewer only reads it. `schema` is the contract: a
+ * reader that does not know a newer number reports that instance as incompatible instead of guessing.
+ *
+ * The file is rewritten only when its content changes; between rewrites the instance touches its mtime, which is what
+ * the viewer uses as the heartbeat. Rewriting every interval would churn the disk for no new information.
+ */
+declare const INSTANCE_STATUS_SCHEMA = 1;
+declare const InstanceStatusSchema: ZodObject<{
+  schema: ZodLiteral<1>;
+  name: ZodNullable<ZodString>;
+  pid: ZodNumber;
+  startedAt: ZodString;
+  writtenAt: ZodString;
+  state: ZodEnum<{
+    starting: "starting";
+    running: "running";
+    stopping: "stopping";
+  }>;
+  health: ZodRecord<ZodString, ZodObject<{
+    state: ZodEnum<{
+      error: "error";
+      starting: "starting";
+      ready: "ready";
+      paused: "paused";
+    }>;
+    detail: ZodString;
+    at: ZodOptional<ZodString>;
+    code: ZodOptional<ZodString>;
+    values: ZodOptional<ZodRecord<ZodString, ZodString>>;
+  }, $strip>>;
+  load: ZodObject<{
+    running: ZodNumber;
+    queued: ZodNumber;
+    maxWorkers: ZodNumber;
+  }, $strip>;
+  paused: ZodBoolean;
+  setup: ZodObject<{
+    configured: ZodBoolean;
+    problem: ZodNullable<ZodObject<{
+      place: ZodString;
+      code: ZodString;
+      detail: ZodString;
+    }, $strip>>;
+  }, $strip>;
+  watchdog: ZodObject<{
+    everyMinutes: ZodNumber;
+    stallMinutes: ZodNumber;
+    lastTickAt: ZodNullable<ZodString>;
+  }, $strip>;
+  tickets: ZodObject<{
+    open: ZodNumber;
+    stalled: ZodNumber;
+  }, $strip>;
+  configPath: ZodNullable<ZodString>;
+}, $strip>;
+type InstanceStatus = output<typeof InstanceStatusSchema>;
+//#endregion
+//#region src/app/instances-view.d.ts
+/**
+ * The read side of the cross-instance view: one report per record in the instance registry `config/instances.json`, built only
+ * from files another process already wrote. This module never writes, never opens the instance database, never takes
+ * the state lock and never starts or stops anything — the `ViewIo` seam exists so a test can prove that.
+ *
+ * What each report is derived from:
+ *  - `<stateDir>/instance-status.json` (written by the instance itself, versioned by `schema`);
+ *  - `<stateDir>.lock` (proper-lockfile's directory: presence and mtime, never acquired);
+ *  - the instance's own pid, checked with signal 0;
+ *  - as a fallback for instances older than the status file, a read-only `GET state` on the record's port.
+ *
+ * Liveness is the status file's mtime, not `writtenAt`: the instance touches the mtime every interval and rewrites the
+ * content only when it changed.
+ */
+type InstanceState = 'running' | 'unresponsive' | 'dead' | 'stale-lock' | 'incompatible' | 'unknown';
+interface InstanceRecord {
+  name: string;
+  label?: string;
+  profile?: string;
+  stateDir?: string;
+  port?: number;
+}
+interface InstanceReport {
+  name: string;
+  label: string | null;
+  stateDir: string | null;
+  state: InstanceState;
+  reason: string | null;
+  source: 'status' | 'http' | 'none';
+  pid: number | null;
+  pidAlive: boolean | null;
+  heartbeatAgeSeconds: number | null;
+  lockPresent: boolean;
+  lockAgeSeconds: number | null;
+  statusSchema: number | null;
+  writtenAt: string | null;
+  startedAt: string | null;
+  health: InstanceStatus['health'] | null;
+  load: InstanceStatus['load'] | null;
+  paused: boolean | null;
+  setup: InstanceStatus['setup'] | null;
+  watchdog: InstanceStatus['watchdog'] | null;
+  tickets: InstanceStatus['tickets'] | null;
+  configPath: string | null;
+}
+interface InstancesView {
+  schema: typeof INSTANCE_STATUS_SCHEMA;
+  collectedAt: string;
+  instances: InstanceReport[];
+  /** Why the record list itself could not be read; the instance reports are then empty. */
+  problem: string | null;
+}
+/** The filesystem seam: only reads. */
+interface ViewIo {
+  existsSync: (path: string) => boolean;
+  readFileSync: (path: string, encoding: 'utf8') => string;
+  statSync: (path: string) => {
+    mtimeMs: number;
+  };
+}
+/** An `GET state` answer, mapped into the same report fields. */
+interface ProbeReply {
+  health?: Record<string, {
+    state: string;
+    detail: string;
+  }>;
+  load?: {
+    running: number;
+    queued: number;
+    maxWorkers: number;
+  };
+  paused?: boolean;
+  setup?: {
+    configured: boolean;
+    problem: {
+      place: string;
+      code: string;
+      detail: string;
+    } | null;
+  };
+}
+interface CollectOptions {
+  /** Directory that holds `config/instances.json` (the install root the caller names). */
+  installRoot?: string;
+  /** Tests inject records directly; production reads them from `installRoot`. */
+  records?: readonly InstanceRecord[];
+  now?: number;
+  io?: ViewIo;
+  /** Tests inject liveness; production asks the OS. */
+  pidAlive?: (pid: number) => boolean;
+  /** Tests inject a stub; production probes over HTTP only when no status file exists. */
+  probe?: (port: number) => Promise<ProbeReply | null>;
+}
+/** Builds the report list; the only exported behaviour, used by the CLI and by tests. */
+declare function collectInstances(options?: CollectOptions): Promise<InstancesView>;
+/** The human table the `--instances-status` flag prints; the JSON form is the data layer items 8 and 12 consume. */
+declare function formatInstances(view: InstancesView): string;
+//#endregion
+export { CollectOptions, InstanceRecord, InstanceReport, InstanceState, InstancesView, ProbeReply, ViewIo, collectInstances, formatInstances };

package/lib/instances-view.js

@@ -0,0 +1,258 @@
+import { i as InstanceStatusSchema, r as INSTANCE_STATUS_STALE_MS, t as INSTANCE_STATUS_FILE } from "./instance-status-Cqaju-dw.js";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/app/instances-view.ts
+const nodeIo = {
+	existsSync: (path) => existsSync(path),
+	readFileSync: (path, encoding) => readFileSync(path, encoding),
+	statSync: (path) => statSync(path)
+};
+const defaultPidAlive = (pid) => {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code === "EPERM";
+	}
+};
+const readOnlyGet = async (port) => {
+	try {
+		const response = await fetch(`http://127.0.0.1:${port}/orchestrator/api/state`, {
+			headers: { "x-orchestrator-request": "1" },
+			signal: AbortSignal.timeout(1500)
+		});
+		return response.ok ? await response.json() : null;
+	} catch {
+		return null;
+	}
+};
+const seconds = (milliseconds) => Math.max(0, Math.round(milliseconds / 1e3));
+/** Reads `config/instances.json` in the shape the desktop shell wrote (the shell was removed on 2026-11-07; the file is still accepted). */
+function readRecords(installRoot, io) {
+	const file = join(installRoot, "config", "instances.json");
+	if (!io.existsSync(file)) return {
+		records: [],
+		problem: `no instance records at ${file}`
+	};
+	try {
+		const parsed = JSON.parse(io.readFileSync(file, "utf8").replace(/^\uFEFF/, ""));
+		const list = Array.isArray(parsed) ? parsed : parsed?.instances;
+		if (!Array.isArray(list)) return {
+			records: [],
+			problem: `${file} holds no instance list`
+		};
+		return {
+			records: list.filter((entry) => typeof entry === "object" && entry !== null && typeof entry.name === "string"),
+			problem: null
+		};
+	} catch (error) {
+		return {
+			records: [],
+			problem: `${file} could not be read: ${error instanceof Error ? error.message : String(error)}`
+		};
+	}
+}
+function lockOf(stateDir, io, now) {
+	const path = stateDir + ".lock";
+	if (!io.existsSync(path)) return {
+		present: false,
+		ageSeconds: null
+	};
+	try {
+		return {
+			present: true,
+			ageSeconds: seconds(now - io.statSync(path).mtimeMs)
+		};
+	} catch {
+		return {
+			present: true,
+			ageSeconds: null
+		};
+	}
+}
+function heartbeatOf(stateDir, io, now) {
+	try {
+		return seconds(now - io.statSync(join(stateDir, INSTANCE_STATUS_FILE)).mtimeMs);
+	} catch {
+		return null;
+	}
+}
+/** Parses one instance's status file, naming the exact way it failed instead of collapsing to "unknown". */
+function statusOf(file, io) {
+	if (!io.existsSync(file)) return { missing: true };
+	let parsed;
+	try {
+		parsed = JSON.parse(io.readFileSync(file, "utf8").replace(/^\uFEFF/, ""));
+	} catch (error) {
+		return {
+			failure: "unknown",
+			reason: `${INSTANCE_STATUS_FILE} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+			schema: null
+		};
+	}
+	const version = typeof parsed === "object" && parsed !== null && typeof parsed.schema === "number" ? parsed.schema : null;
+	const checked = InstanceStatusSchema.safeParse(parsed);
+	if (!checked.success) return version !== null && version !== 1 ? {
+		failure: "incompatible",
+		reason: `${INSTANCE_STATUS_FILE} declares schema ${version}; this viewer reads 1`,
+		schema: version
+	} : {
+		failure: "unknown",
+		reason: `${INSTANCE_STATUS_FILE} does not match schema 1: ${checked.error.issues[0]?.message ?? "invalid"}`,
+		schema: version
+	};
+	return {
+		status: checked.data,
+		schema: checked.data.schema
+	};
+}
+function base(record, stateDir) {
+	return {
+		name: record.name,
+		label: record.label ?? null,
+		stateDir,
+		state: "unknown",
+		reason: null,
+		source: "none",
+		pid: null,
+		pidAlive: null,
+		heartbeatAgeSeconds: null,
+		lockPresent: false,
+		lockAgeSeconds: null,
+		statusSchema: null,
+		writtenAt: null,
+		startedAt: null,
+		health: null,
+		load: null,
+		paused: null,
+		setup: null,
+		watchdog: null,
+		tickets: null,
+		configPath: null
+	};
+}
+/** One record's report. Every failure is named on that record only; the other instances are unaffected. */
+async function reportOf(record, options) {
+	const { now, io, pidAlive, probe } = options;
+	if (!record.stateDir) return {
+		...base(record, null),
+		reason: "the record names no stateDir, so there is nothing to observe"
+	};
+	const stateDir = record.stateDir;
+	const report = base(record, stateDir);
+	const lock = lockOf(stateDir, io, now);
+	report.lockPresent = lock.present;
+	report.lockAgeSeconds = lock.ageSeconds;
+	const read = statusOf(join(stateDir, INSTANCE_STATUS_FILE), io);
+	if ("failure" in read) return {
+		...report,
+		state: read.failure,
+		source: "status",
+		statusSchema: read.schema,
+		reason: read.reason
+	};
+	if ("missing" in read) {
+		if ((record.port ?? 0) > 0) {
+			const reply = await probe(record.port);
+			if (reply) return {
+				...report,
+				state: "running",
+				source: "http",
+				health: reply.health,
+				load: reply.load ?? null,
+				paused: reply.paused ?? null,
+				setup: reply.setup ?? null,
+				reason: "no status file; probed the read-only state route"
+			};
+		}
+		if (!lock.present) return {
+			...report,
+			state: "dead",
+			reason: "no status file and no state lock (the instance is stopped)"
+		};
+		const old = (lock.ageSeconds ?? 0) > INSTANCE_STATUS_STALE_MS / 1e3;
+		return {
+			...report,
+			state: old ? "stale-lock" : "unknown",
+			source: "none",
+			reason: old ? `no status file; the state lock has not moved for ${lock.ageSeconds ?? "?"}s (a crash left it behind)` : "no status file; the state lock is held and fresh (the instance predates the status file or is still starting)"
+		};
+	}
+	const status = read.status;
+	const heartbeat = heartbeatOf(stateDir, io, now);
+	const alive = pidAlive(status.pid);
+	const state = !alive ? "dead" : heartbeat !== null && heartbeat > 30 ? "unresponsive" : "running";
+	return {
+		...report,
+		state,
+		source: "status",
+		pid: status.pid,
+		pidAlive: alive,
+		heartbeatAgeSeconds: heartbeat,
+		statusSchema: read.schema,
+		writtenAt: status.writtenAt,
+		startedAt: status.startedAt,
+		health: status.health,
+		load: status.load,
+		paused: status.paused,
+		setup: status.setup,
+		watchdog: status.watchdog,
+		tickets: status.tickets,
+		configPath: status.configPath,
+		reason: !alive ? `pid ${status.pid} is not running${lock.present ? `; the state lock is still present (${lock.ageSeconds ?? "?"}s old)` : ""}; last change ${status.writtenAt}` : state === "unresponsive" ? `the heartbeat has not moved for ${heartbeat ?? "?"}s` : null
+	};
+}
+/** Builds the report list; the only exported behaviour, used by the CLI and by tests. */
+async function collectInstances(options = {}) {
+	const now = options.now ?? Date.now();
+	const io = options.io ?? nodeIo;
+	const pidAlive = options.pidAlive ?? defaultPidAlive;
+	const probe = options.probe ?? readOnlyGet;
+	const collectedAt = new Date(now).toISOString();
+	let records = options.records ? [...options.records] : [];
+	let problem = null;
+	if (!options.records) {
+		if (!options.installRoot) problem = "no install root was given and no records were injected";
+		else ({records, problem} = readRecords(options.installRoot, io));
+	}
+	return {
+		schema: 1,
+		collectedAt,
+		instances: await Promise.all(records.map((record) => reportOf(record, {
+			now,
+			io,
+			pidAlive,
+			probe
+		}))),
+		problem
+	};
+}
+const column = (text, width) => text.length >= width ? text : text + " ".repeat(width - text.length);
+/** The human table the `--instances-status` flag prints; the JSON form is the data layer items 8 and 12 consume. */
+function formatInstances(view) {
+	if (view.problem) return `problem: ${view.problem}`;
+	return [`${column("NAME", 14)}${column("STATE", 13)}${column("HEARTBEAT", 11)}${column("PID", 8)}${column("LOAD", 10)}${column("HEALTH", 28)} REASON`, ...view.instances.map((instance) => {
+		const health = instance.health ? Object.values(instance.health).every((entry) => entry.state === "ready") ? "all ready" : Object.entries(instance.health).filter(([, entry]) => entry.state !== "ready").map(([part, entry]) => `${part}:${entry.state}`).join(" ") : "—";
+		const load = instance.load ? `${instance.load.running}/${instance.load.maxWorkers} +${instance.load.queued}q` : "—";
+		const heartbeat = instance.heartbeatAgeSeconds === null ? "—" : `${instance.heartbeatAgeSeconds}s`;
+		return `${column(instance.name, 14)}${column(instance.state, 13)}${column(heartbeat, 11)}${column(instance.pid === null ? "—" : String(instance.pid), 8)}${column(load, 10)}${column(health, 28)} ${instance.reason ?? "—"}`;
+	})].join("\n");
+}
+async function main() {
+	const argv = process.argv.slice(2);
+	const asJson = argv.includes("--json");
+	const rootIndex = argv.indexOf("--install-root");
+	const installRoot = rootIndex >= 0 ? argv[rootIndex + 1] : process.env.SUPERAGENT_INSTALL_ROOT;
+	if (!installRoot) {
+		process.stderr.write("usage: instances-view.js --instances-status [--json] --install-root <dir>\n");
+		process.exitCode = 2;
+		return;
+	}
+	const view = await collectInstances({ installRoot });
+	process.stdout.write((asJson ? JSON.stringify(view, null, 2) : formatInstances(view)) + "\n");
+}
+/** Runs only when node executes this built file, never when a test imports the module. */
+if (process.argv[1] && basename(process.argv[1]) === "instances-view.js" && fileURLToPath(import.meta.url) === process.argv[1]) main();
+//#endregion
+export { collectInstances, formatInstances };