@piagent/platform 1.3.0 → 1.4.0

package/scripts/piagent-dashboard.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { requestGatewayControl } from "../packages/piagent-webui/gateway/control-socket.ts";
+import { installedPiHostRoot } from "../packages/piagent-webui/gateway/pi-host.ts";
+import { gatewayProfileState, profileRef, readGatewayDescriptor, readOrCreateCatalogKey,
+  removeGatewayDescriptor } from "../packages/piagent-webui/gateway/profile-state.ts";
+import { startPiagentGateway } from "../packages/piagent-webui/gateway/gateway-service.ts";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+const expectedPiVersion = packageJson.peerDependencies["@earendil-works/pi-coding-agent"];
+const args = process.argv.slice(2);
+const command = ["--help", "-h"].includes(args[0]) ? args.shift()
+  : args[0] && !args[0].startsWith("-") ? args.shift() : "open";
+const noOpen = args.includes("--no-open");
+const json = args.includes("--json");
+const repair = args.includes("--repair");
+const agentDirIndex = args.indexOf("--agent-dir");
+const agentDir = agentDirIndex >= 0 ? args[agentDirIndex + 1] : undefined;
+
+function output(value) {
+  process.stdout.write(`${json ? JSON.stringify(value) : value}\n`);
+}
+
+function openBrowser(url) {
+  if (noOpen) return;
+  const opener = process.platform === "darwin" ? ["open", [url]]
+    : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
+      : ["xdg-open", [url]];
+  const result = spawnSync(opener[0], opener[1], { stdio: "ignore" });
+  if (result.status !== 0) process.stderr.write(`Dashboard is ready at ${url}\n`);
+}
+
+function processAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return !(error && typeof error === "object" && "code" in error && error.code === "ESRCH"); }
+}
+
+function ownerOnlyDirectory(target) {
+  try {
+    const stat = fs.lstatSync(target);
+    return stat.isDirectory() && !stat.isSymbolicLink() && (stat.mode & 0o077) === 0
+      && (typeof process.getuid !== "function" || stat.uid === process.getuid());
+  } catch { return false; }
+}
+
+function removeOwnedRegularFile(target) {
+  try {
+    const stat = fs.lstatSync(target);
+    if (!stat.isFile() || stat.isSymbolicLink()
+      || typeof process.getuid === "function" && stat.uid !== process.getuid()) return false;
+    fs.unlinkSync(target); return true;
+  } catch { return false; }
+}
+
+function removeOwnedSocket(target) {
+  if (process.platform === "win32") return false;
+  try {
+    const stat = fs.lstatSync(target);
+    if (!stat.isSocket() || stat.isSymbolicLink()
+      || typeof process.getuid === "function" && stat.uid !== process.getuid()) return false;
+    fs.unlinkSync(target); return true;
+  } catch { return false; }
+}
+
+async function control(action, timeoutMs = 1_500) {
+  const state = gatewayProfileState(agentDir);
+  return await requestGatewayControl(state.controlSocket, { action }, timeoutMs);
+}
+
+async function currentLaunchUrl() {
+  try {
+    const response = await control("issue-launch-url");
+    if (response.ok && response.value && typeof response.value === "object"
+      && typeof response.value.launchUrl === "string") return response.value.launchUrl;
+  } catch {
+    // Gateway is not ready yet.
+  }
+  return null;
+}
+
+async function ensureStarted() {
+  const existing = await currentLaunchUrl();
+  if (existing) return existing;
+  const effectiveAgentDir = path.resolve(agentDir ?? process.env.PI_CODING_AGENT_DIR ?? path.join(os.homedir(), ".pi", "agent"));
+  const child = spawn(process.execPath, [
+    "--disable-warning=ExperimentalWarning",
+    "--import", path.join(packageRoot, "scripts", "register-typescript-loader.mjs"),
+    fileURLToPath(import.meta.url),
+    "serve",
+    ...(agentDir ? ["--agent-dir", agentDir] : [])
+  ], { cwd: process.cwd(), env: { ...process.env,
+    PIAGENT_PINNED_TS_TRANSFORM_ROOT: path.join(effectiveAgentDir, "npm", "node_modules", "pi-mcp-adapter") },
+    detached: true, stdio: "ignore" });
+  child.unref();
+  const deadline = Date.now() + 12_000;
+  while (Date.now() < deadline) {
+    const url = await currentLaunchUrl();
+    if (url) return url;
+    await new Promise((resolve) => setTimeout(resolve, 80));
+  }
+  throw new Error("gateway-start-timeout");
+}
+
+async function serve() {
+  const gateway = await startPiagentGateway({ packageRoot, expectedPiVersion, agentDir });
+  const shutdown = () => { void gateway.close(); };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+  await gateway.wait();
+}
+
+async function main() {
+  if (command === "serve") return await serve();
+  if (["help", "--help", "-h"].includes(command)) {
+    output("Usage: piagent dashboard [open|status|stop|restart|doctor] [--no-open] [--json] [--repair]");
+    return;
+  }
+  if (command === "open" || command === "start") {
+    const launchUrl = await ensureStarted();
+    output(json ? { state: "running", launchUrl } : launchUrl);
+    openBrowser(launchUrl);
+    return;
+  }
+  if (command === "status") {
+    try {
+      const response = await control("health");
+      if (!response.ok) throw new Error(response.error);
+      output(json ? { state: "running", gateway: response.value } : "Piagent Gateway is running.");
+    } catch {
+      const descriptor = readGatewayDescriptor(gatewayProfileState(agentDir));
+      output(json ? { state: "stopped", staleDescriptor: Boolean(descriptor) } : "Piagent Gateway is stopped.");
+      process.exitCode = 1;
+    }
+    return;
+  }
+  if (command === "stop") {
+    try {
+      const response = await control("stop");
+      if (!response.ok) throw new Error(response.error);
+      output(json ? { state: "stopping" } : "Piagent Gateway is stopping.");
+    } catch {
+      output(json ? { state: "stopped" } : "Piagent Gateway is already stopped.");
+    }
+    return;
+  }
+  if (command === "restart") {
+    try { await control("stop"); } catch { /* already stopped */ }
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    const launchUrl = await ensureStarted();
+    output(json ? { state: "running", launchUrl } : launchUrl);
+    openBrowser(launchUrl);
+    return;
+  }
+  if (command === "doctor") {
+    const state = gatewayProfileState(agentDir);
+    const key = readOrCreateCatalogKey(state), descriptor = readGatewayDescriptor(state);
+    let actual = null;
+    try {
+      const hostRoot = installedPiHostRoot();
+      actual = JSON.parse(fs.readFileSync(path.join(hostRoot, "package.json"), "utf8")).version;
+    } catch { /* reported as a failed check below */ }
+    let health = null;
+    try {
+      const response = await control("health", 1_000);
+      health = response.ok ? "ready" : "unavailable";
+    } catch { health = "unavailable"; }
+    const staleDescriptor = Boolean(descriptor && !processAlive(descriptor.pid));
+    const invalidDescriptor = fs.existsSync(state.descriptorFile) && !descriptor;
+    const repairs = [];
+    if (repair && staleDescriptor && descriptor) {
+      removeGatewayDescriptor(state, descriptor.gatewayInstanceRef); repairs.push("stale-descriptor-removed");
+    } else if (repair && invalidDescriptor && removeOwnedRegularFile(state.descriptorFile)) repairs.push("invalid-descriptor-removed");
+    if (repair && health !== "ready" && removeOwnedSocket(state.controlSocket)) repairs.push("stale-control-socket-removed");
+    const checks = {
+      piHostVersion: actual === expectedPiVersion,
+      clientBuild: fs.existsSync(path.join(packageRoot, "packages", "piagent-webui", "dist", "client", "index.html")),
+      profileStateOwnerOnly: ownerOnlyDirectory(state.root),
+      descriptor: !invalidDescriptor && !staleDescriptor,
+      gatewayHealth: descriptor ? health === "ready" : true
+    };
+    const result = {
+      ok: Object.values(checks).every(Boolean),
+      expectedPiVersion,
+      actualPiVersion: actual,
+      profileRef: profileRef(state, key),
+      gateway: descriptor ? health === "ready" ? "ready" : staleDescriptor ? "stale" : "unavailable" : "not-registered",
+      checks,
+      repaired: repairs
+    };
+    output(json ? result : result.ok ? "Piagent Gateway doctor passed." : repair && repairs.length
+      ? "Piagent Gateway doctor repaired stale local state; run doctor again."
+      : "Piagent Gateway doctor found a version, build, ownership, or lifecycle mismatch.");
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  throw new Error(`unknown-dashboard-command:${command}`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`Piagent dashboard failed: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/scripts/piagent-webui-launcher.mjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+
+function help() {
+  return [
+    "Usage: piagent-webui [--session <opaque-session-ref>] [--no-open]",
+    "",
+    "Opens a WebUI already owned by the current Pi process.",
+    "Start it first with /piagent-webui inside the Pi terminal.",
+    "This command never creates a second Pi runtime."
+  ].join("\n");
+}
+
+function parse(argv) {
+  let session = null, open = true;
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--help" || value === "-h") return { help: true, session, open };
+    if (value === "--no-open") { open = false; continue; }
+    if (value === "--session" && typeof argv[index + 1] === "string" && REF.test(argv[index + 1])) { session = argv[index += 1]; continue; }
+    throw new Error(`Unknown or invalid option: ${value}`);
+  }
+  return { help: false, session, open };
+}
+
+function launcherDirectory(start) {
+  let current = path.resolve(start);
+  while (true) {
+    const candidate = path.join(current, ".pi", "piagent-state", "webui-launcher");
+    try { if (fs.lstatSync(candidate).isDirectory()) return candidate; } catch { /* keep walking */ }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function readDescriptor(file) {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 8_192 || process.platform !== "win32" && (stat.mode & 0o077) !== 0) {
+    throw new Error("WebUI launcher descriptor is unsafe");
+  }
+  const value = JSON.parse(fs.readFileSync(file, "utf8"));
+  const temporary = fs.realpathSync(os.tmpdir());
+  const socket = path.resolve(String(value.controlSocket ?? ""));
+  const canonicalSocket = fs.realpathSync(socket);
+  if (value.schemaVersion !== 1 || !REF.test(String(value.sessionRef ?? "")) || !REF.test(String(value.projectRef ?? ""))
+    || typeof value.controlToken !== "string" || !/^[A-Za-z0-9_-]{43}$/.test(value.controlToken)
+    || path.relative(temporary, canonicalSocket).startsWith("..") || path.isAbsolute(path.relative(temporary, canonicalSocket))) {
+    throw new Error("WebUI launcher descriptor is invalid");
+  }
+  return { ...value, controlSocket: socket };
+}
+
+function requestLaunch(descriptor) {
+  return new Promise((resolve, reject) => {
+    const socket = net.createConnection(descriptor.controlSocket);
+    let bytes = Buffer.alloc(0), settled = false;
+    const fail = (error) => { if (!settled) { settled = true; socket.destroy(); reject(error); } };
+    socket.setTimeout(2_000, () => fail(new Error("WebUI sidecar did not respond")));
+    socket.once("error", () => fail(new Error("WebUI sidecar is not running; use /piagent-webui in Pi")));
+    socket.once("connect", () => socket.write(`${JSON.stringify({ action: "launch", token: descriptor.controlToken })}\n`));
+    socket.on("data", (chunk) => {
+      if (settled) return;
+      bytes = Buffer.concat([bytes, chunk]);
+      if (bytes.length > 8_192) { fail(new Error("WebUI sidecar response exceeded its limit")); return; }
+      const newline = bytes.indexOf(10);
+      if (newline < 0) return;
+      try {
+        const response = JSON.parse(bytes.subarray(0, newline).toString("utf8"));
+        if (!response.ok || typeof response.launchUrl !== "string" || !/^http:\/\/127\.0\.0\.1:\d+\/#bootstrap=/.test(response.launchUrl)) {
+          fail(new Error("WebUI sidecar rejected the launch request")); return;
+        }
+        settled = true; socket.end(); resolve(response.launchUrl);
+      } catch { fail(new Error("WebUI sidecar returned an invalid response")); }
+    });
+  });
+}
+
+function openUrl(url) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "linux" ? "xdg-open" : null;
+  if (!command) return false;
+  const child = spawn(command, [url], { detached: true, stdio: "ignore" });
+  child.unref(); return true;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  let options;
+  try { options = parse(argv); }
+  catch (error) { process.stderr.write(`${error.message}\n${help()}\n`); return 2; }
+  if (options.help) { process.stdout.write(`${help()}\n`); return 0; }
+  const directory = launcherDirectory(process.cwd());
+  if (!directory) { process.stderr.write("No running Piagent WebUI was found. Run /piagent-webui inside the Pi terminal first.\n"); return 1; }
+  let descriptors;
+  try {
+    descriptors = fs.readdirSync(directory).filter((name) => /^[a-f0-9]{64}\.json$/.test(name))
+      .map((name) => readDescriptor(path.join(directory, name)))
+      .filter((value) => !options.session || value.sessionRef === options.session);
+  } catch (error) { process.stderr.write(`${error instanceof Error ? error.message : "WebUI launcher state is unavailable"}\n`); return 1; }
+  if (descriptors.length !== 1) {
+    process.stderr.write(descriptors.length === 0
+      ? "No matching running WebUI session was found.\n"
+      : "More than one WebUI session is running; pass --session <opaque-session-ref>.\n");
+    return 1;
+  }
+  try {
+    const url = await requestLaunch(descriptors[0]);
+    if (!options.open || !openUrl(url)) process.stdout.write(`${url}\n`);
+    else process.stdout.write(`Opened Piagent WebUI for ${descriptors[0].sessionRef}.\n`);
+    return 0;
+  } catch (error) { process.stderr.write(`${error instanceof Error ? error.message : "WebUI could not be opened"}\n`); return 1; }
+}
+
+if (process.argv[1] && fs.realpathSync(path.resolve(process.argv[1])) === fs.realpathSync(new URL(import.meta.url))) process.exit(await main());
+
+export { help, main, parse, readDescriptor, requestLaunch };

package/scripts/typescript-loader.mjs

@@ -1,12 +1,37 @@
 import fs from "node:fs/promises";
 import { stripTypeScriptTypes } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Repository TypeScript must remain erasable: the integrity lock hashes the
+// source bytes and `strip` fails closed if a future change needs codegen.
+// pi-mcp-adapter@2.15.0 is the sole exception because its published OAuth
+// implementation contains parameter properties. Keep that transform isolated
+// to the exact installed adapter root and Node release reviewed below. A Node
+// or adapter upgrade must deliberately update these pins before OAuth loads.
+export const PINNED_EXTERNAL_TRANSFORM = Object.freeze({
+  nodeVersion: "24.11.1",
+  packageName: "pi-mcp-adapter",
+  packageVersion: "2.15.0"
+});
+
+async function pinnedTransformRoot(url) {
+  const configured = process.env.PIAGENT_PINNED_TS_TRANSFORM_ROOT;
+  if (!configured || process.versions.node !== PINNED_EXTERNAL_TRANSFORM.nodeVersion) return false;
+  const root = await fs.realpath(configured), target = await fs.realpath(fileURLToPath(url));
+  const relative = path.relative(root, target);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) return false;
+  const metadata = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8"));
+  return metadata.name === PINNED_EXTERNAL_TRANSFORM.packageName && metadata.version === PINNED_EXTERNAL_TRANSFORM.packageVersion;
+}
 
 export async function load(url, context, nextLoad) {
   if (!url.endsWith(".ts")) return nextLoad(url, context);
   const source = await fs.readFile(new URL(url), "utf8");
+  const mode = await pinnedTransformRoot(url) ? "transform" : "strip";
   return {
     format: "module",
     shortCircuit: true,
-    source: stripTypeScriptTypes(source, { mode: "strip", sourceUrl: url })
+    source: stripTypeScriptTypes(source, { mode, sourceUrl: url })
   };
 }