primcli 1.34.0 → 1.35.0

package/dist/oclif/listen-supervisor.js

@@ -0,0 +1,2 @@
+import { i as runBackgroundListenSupervisor } from "../listen-background-D6UhIbkO.js";
+export { runBackgroundListenSupervisor };

package/dist/oclif/proxy-auto-detect.js

@@ -1,3 +1,4 @@
+import { n as jsonOutputRequested } from "../json-output-KAIuP9rG.js";
 import { spawnSync } from "node:child_process";
 //#region src/oclif/proxy-auto-detect.ts
 const PROXY_ENV_VARS = [
@@ -44,7 +45,7 @@ function restartWithProxyEnvIfNeeded(options = {}) {
 		process.exit(code);
 		throw new Error("process.exit returned unexpectedly");
 	});
-	if (!hintPrinted) {
+	if (!hintPrinted && !jsonOutputRequested(argv.slice(2))) {
 		hintPrinted = true;
 		const names = detectedVars.join("/");
 		stderr.write(`primitive: proxy detected via ${names}, restarting with NODE_USE_ENV_PROXY=1\n`);

package/dist/oclif/root-signup-hint.js

@@ -1,4 +1,4 @@
-import { S as normalizeApiBaseUrl, c as resolveConfigEnvironment, i as loadCliConfig } from "../cli-config-x39ZVsXJ.js";
+import { S as normalizeApiBaseUrl, c as resolveConfigEnvironment, i as loadCliConfig } from "../cli-config-DmhlcS3s.js";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";

package/dist/shared-mail-files-Cbwnf79a.js

@@ -0,0 +1,351 @@
+import { chmodSync, closeSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { dirname, join, win32 } from "node:path";
+import { setTimeout } from "node:timers/promises";
+import { execFileSync } from "node:child_process";
+//#region src/oclif/listen-state.ts
+var ListenStateError = class extends Error {};
+function normalizeListenOrigin(value) {
+	const url = new URL(value);
+	if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw new ListenStateError("The API base URL must be an HTTP(S) URL without credentials, query, or fragment.");
+	return `${url.origin}${url.pathname.replace(/\/+$/, "")}`;
+}
+function listenIdentity(origin, accountId) {
+	return createHash("sha256").update(JSON.stringify([normalizeListenOrigin(origin), accountId])).digest("hex");
+}
+function privateDirectory(path) {
+	mkdirSync(path, {
+		recursive: true,
+		mode: 448
+	});
+	if (!lstatSync(path).isDirectory() || lstatSync(path).isSymbolicLink()) throw new ListenStateError("Listener state must be a private directory.");
+	chmodSync(path, 448);
+}
+function processAlive(pid) {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return error.code !== "ESRCH";
+	}
+}
+function listenProcessIdentity(pid) {
+	if (!Number.isSafeInteger(pid) || pid < 1) return null;
+	try {
+		if (process.platform === "linux") {
+			const boot = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+			const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+			const end = stat.lastIndexOf(")");
+			const started = stat.slice(end + 1).trim().split(/\s+/)[19];
+			if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(boot) || !stat.startsWith(`${pid} (`) || end < 0 || !started || !/^\d+$/.test(started)) return null;
+			return `linux:${boot}:${started}`;
+		}
+		if (process.platform === "darwin") {
+			const options = {
+				encoding: "utf8",
+				timeout: 1e3,
+				maxBuffer: 4096,
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				],
+				env: {
+					LC_ALL: "C",
+					TZ: "UTC",
+					PATH: "/usr/bin:/bin:/usr/sbin:/sbin"
+				}
+			};
+			const bootId = execFileSync("/usr/sbin/sysctl", ["-n", "kern.bootsessionuuid"], options).trim().toLowerCase();
+			const started = execFileSync("/bin/ps", [
+				"-p",
+				String(pid),
+				"-o",
+				"lstart="
+			], options).trim().replace(/\s+/g, " ");
+			if (!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(bootId) || !/^[A-Z][a-z]{2} [A-Z][a-z]{2} \d{1,2} \d{2}:\d{2}:\d{2} \d{4}$/.test(started)) return null;
+			return `darwin-boot:${bootId}:${started}`;
+		}
+		if (process.platform === "win32") {
+			const root = process.env.SystemRoot;
+			if (!root || !win32.isAbsolute(root)) return null;
+			const started = execFileSync(win32.join(root, "System32", "WindowsPowerShell", "v1.0", "powershell.exe"), [
+				"-NoLogo",
+				"-NoProfile",
+				"-NonInteractive",
+				"-Command",
+				`$ErrorActionPreference='Stop'; (Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks.ToString([System.Globalization.CultureInfo]::InvariantCulture)`
+			], {
+				encoding: "utf8",
+				timeout: 2e3,
+				maxBuffer: 4096,
+				windowsHide: true,
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				]
+			}).trim();
+			return /^\d{1,20}$/.test(started) ? `win32:${started}` : null;
+		}
+	} catch {}
+	return null;
+}
+/** Legacy macOS timestamps cannot prove that a live PID changed owners. */
+function compareListenProcessIdentity(saved, current) {
+	if (saved === null || current === null) return null;
+	if (saved === current) return true;
+	if (saved.startsWith("darwin:") || current.startsWith("darwin:")) return null;
+	return false;
+}
+function ownerIdentity(path) {
+	try {
+		const stat = lstatSync(path);
+		if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024) return null;
+		const saved = JSON.parse(readFileSync(path, "utf8"));
+		if (!saved || typeof saved !== "object" || !("version" in saved) || saved.version !== 1 || !("identity" in saved) || typeof saved.identity !== "string") return null;
+		return /^(?:linux:[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}:\d+|darwin:\d+:\d+:[A-Z][a-z]{2} [A-Z][a-z]{2} \d{1,2} \d{2}:\d{2}:\d{2} \d{4}|darwin-boot:[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}:[A-Z][a-z]{2} [A-Z][a-z]{2} \d{1,2} \d{2}:\d{2}:\d{2} \d{4}|win32:\d{1,20})$/.test(saved.identity) ? saved.identity : null;
+	} catch {
+		return null;
+	}
+}
+function removeOwner(path, owner) {
+	try {
+		unlinkSync(join(path, owner));
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	try {
+		rmdirSync(path);
+	} catch (error) {
+		if (![
+			"ENOENT",
+			"ENOTEMPTY",
+			"EEXIST"
+		].includes(error.code ?? "")) throw error;
+	}
+}
+function acquireListenLock(directory, scope) {
+	privateDirectory(directory);
+	const path = join(directory, `${createHash("sha256").update(scope).digest("hex")}.lock`);
+	const owner = `${process.pid}-${randomUUID()}`;
+	const candidate = mkdtempSync(join(directory, ".claim-"));
+	chmodSync(candidate, 448);
+	writeFileSync(join(candidate, owner), JSON.stringify({
+		version: 1,
+		identity: listenProcessIdentity(process.pid)
+	}), {
+		mode: 384,
+		flag: "wx"
+	});
+	let installed = false;
+	try {
+		for (let attempt = 0; attempt < 8; attempt++) {
+			try {
+				renameSync(candidate, path);
+				installed = true;
+				break;
+			} catch (error) {
+				if (!["EEXIST", "ENOTEMPTY"].includes(error.code ?? "")) throw error;
+			}
+			let entries;
+			try {
+				entries = readdirSync(path);
+			} catch (error) {
+				if (error.code === "ENOENT") continue;
+				throw error;
+			}
+			if (entries.length === 0) continue;
+			const match = entries.length === 1 ? /^(\d+)-[a-f0-9-]{36}$/.exec(entries[0] ?? "") : null;
+			const pid = match ? Number(match[1]) : null;
+			let stale = pid !== null && !processAlive(pid);
+			if (!stale && pid !== null) {
+				const saved = ownerIdentity(join(path, entries[0] ?? ""));
+				stale = compareListenProcessIdentity(saved, saved === null ? null : listenProcessIdentity(pid)) === false;
+			}
+			if (!stale) throw new ListenStateError("Another listener is using this subscription, or its owner cannot be verified. Stop the original listener before reconnecting. To use a separate subscription instead, run: primitive listen --subscription local-" + randomUUID());
+			removeOwner(path, entries[0] ?? "");
+		}
+		if (!installed) throw new ListenStateError("Subscription lock changed concurrently. Retry the command.");
+	} finally {
+		if (!installed) removeOwner(candidate, owner);
+	}
+	let released = false;
+	return () => {
+		if (!released) {
+			released = true;
+			removeOwner(path, owner);
+		}
+	};
+}
+function resolveListenSubscription(configDir, identity, explicit) {
+	const directory = join(configDir, "listen", identity);
+	privateDirectory(directory);
+	let name = explicit;
+	if (name === void 0) {
+		const unlock = acquireListenLock(directory, "default-name");
+		try {
+			const file = join(directory, "default.json");
+			try {
+				if (!lstatSync(file).isFile() || lstatSync(file).isSymbolicLink()) throw new ListenStateError("Invalid listener identity file.");
+				const saved = JSON.parse(readFileSync(file, "utf8"));
+				if (typeof saved.name !== "string" || !/^local-[a-f0-9-]{36}$/.test(saved.name)) throw new ListenStateError("Invalid listener identity file.");
+				name = saved.name;
+			} catch (error) {
+				if (error.code !== "ENOENT") throw error;
+				name = `local-${randomUUID()}`;
+				const temporary = join(directory, `.state-${randomUUID()}`);
+				const fd = openSync(temporary, "wx", 384);
+				try {
+					writeFileSync(fd, `${JSON.stringify({ name })}\n`);
+					fsyncSync(fd);
+				} finally {
+					closeSync(fd);
+				}
+				renameSync(temporary, file);
+			}
+			if (process.platform !== "win32") for (const path of [
+				directory,
+				join(configDir, "listen"),
+				configDir
+			]) {
+				const directoryFd = openSync(path, "r");
+				try {
+					fsyncSync(directoryFd);
+				} finally {
+					closeSync(directoryFd);
+				}
+			}
+		} finally {
+			unlock();
+		}
+	}
+	if (!name || name.length > 64 || !/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/.test(name)) throw new ListenStateError("Use a subscription name of 1–64 letters, digits, underscores, or hyphens.");
+	return {
+		name,
+		release: acquireListenLock(directory, `subscription:${name}`)
+	};
+}
+//#endregion
+//#region src/oclif/shared-mail-files.ts
+var SharedMailStateError = class extends ListenStateError {};
+const invalidSharedMail = () => new SharedMailStateError("Shared mail state is invalid or inconsistent. Preserve it before retrying to avoid duplicate delivery.");
+function privateMailPermissions(info, platform = process.platform) {
+	return platform === "win32" || info.uid === process.getuid?.() && (info.mode & 63) === 0;
+}
+function privateMailDirectory(path, create = false) {
+	if (create) {
+		const created = mkdirSync(path, {
+			recursive: true,
+			mode: 448
+		});
+		if (created !== void 0) {
+			let current = path;
+			for (;;) {
+				syncMailDirectory(current);
+				syncMailDirectory(dirname(current));
+				if (current === created) break;
+				current = dirname(current);
+			}
+		}
+	}
+	const stat = lstatSync(path);
+	if (!stat.isDirectory() || !privateMailPermissions(stat)) throw invalidSharedMail();
+}
+function syncMailDirectory(path, platform = process.platform) {
+	if (platform === "win32") return;
+	const fd = openSync(path, "r");
+	try {
+		fsyncSync(fd);
+	} finally {
+		closeSync(fd);
+	}
+}
+function readMailJson(path, maxBytes = 16384) {
+	try {
+		const info = lstatSync(path);
+		if (!info.isFile() || !privateMailPermissions(info) || info.size > maxBytes) throw invalidSharedMail();
+		const value = JSON.parse(readFileSync(path, "utf8"));
+		if (value === null) throw invalidSharedMail();
+		return value;
+	} catch (error) {
+		if (error.code === "ENOENT") return null;
+		throw invalidSharedMail();
+	}
+}
+function writeMailJson(path, value) {
+	privateMailDirectory(dirname(path), true);
+	const temporary = join(dirname(path), `.write-${randomUUID()}`);
+	try {
+		const fd = openSync(temporary, "wx", 384);
+		try {
+			writeFileSync(fd, `${JSON.stringify(value)}\n`);
+			fsyncSync(fd);
+		} finally {
+			closeSync(fd);
+		}
+		renameSync(temporary, path);
+		syncMailDirectory(dirname(path));
+	} finally {
+		try {
+			unlinkSync(temporary);
+		} catch {}
+	}
+}
+function removeMailFile(path) {
+	try {
+		unlinkSync(path);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	syncMailDirectory(dirname(path));
+}
+function mailLockBusy(error) {
+	return error instanceof ListenStateError && /^(Another listener|Subscription lock changed)/.test(error.message);
+}
+async function withMailLock(directory, action, signal) {
+	const deadline = performance.now() + 5e3;
+	for (;;) {
+		signal?.throwIfAborted();
+		let release;
+		try {
+			release = acquireListenLock(directory, "shared-mail-state");
+		} catch (error) {
+			if (!mailLockBusy(error) || performance.now() >= deadline) throw error;
+			await setTimeout(25, void 0, { signal });
+			continue;
+		}
+		try {
+			signal?.throwIfAborted();
+			return action();
+		} finally {
+			release();
+		}
+	}
+}
+function mailObject(value, keys) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw invalidSharedMail();
+	const result = value;
+	if (Object.keys(result).length !== keys.length || keys.some((key) => !Object.hasOwn(result, key))) throw invalidSharedMail();
+	return result;
+}
+function mailId(value) {
+	if (typeof value !== "string" || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(value)) throw invalidSharedMail();
+	return value.toLowerCase();
+}
+function mailString(value, max = 256) {
+	if (typeof value !== "string" || !value || value.length > max || Array.from(value).some((character) => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127)) throw invalidSharedMail();
+	return value;
+}
+function mailAddress(value) {
+	const address = mailString(value, 254).toLowerCase();
+	if (!/^[^\s<>@]+@[^\s<>@]+\.[^\s<>@]+$/.test(address)) throw invalidSharedMail();
+	return address;
+}
+function mailTime(value) {
+	const time = mailString(value, 40);
+	if (!Number.isFinite(Date.parse(time))) throw invalidSharedMail();
+	return new Date(time).toISOString();
+}
+//#endregion
+export { resolveListenSubscription as S, acquireListenLock as _, mailLockBusy as a, listenProcessIdentity as b, mailTime as c, readMailJson as d, removeMailFile as f, ListenStateError as g, writeMailJson as h, mailId as i, privateMailDirectory as l, withMailLock as m, invalidSharedMail as n, mailObject as o, syncMailDirectory as p, mailAddress as r, mailString as s, SharedMailStateError as t, privateMailPermissions as u, compareListenProcessIdentity as v, normalizeListenOrigin as x, listenIdentity as y };

package/man/primitive.1

@@ -20,6 +20,29 @@ Most commands print human-readable output by default. Commands that expose JSON
 .B --json
 flag or use generated operation output that can be piped into tools such as
 .BR jq (1).
+.PP
+With
+.BR --json ,
+stdout is exactly one JSON document, on success and on failure, and stderr
+stays empty, so output merged with 2>&1 still parses. Notices the command
+would print on stderr go in the document's
+.B warnings
+array; a failure adds
+.B error
+and
+.BR exit_code .
+Generated API commands keep their usual stdout shape with
+.BR --json :
+the data payload only. They do not print the
+.B next cursor:
+line then; add
+.B --envelope
+to get the full response envelope, with the pagination cursor in
+.B meta.cursor
+and empty-result hints in
+.BR summary .
+.B primitive listen
+streams JSONL and is not covered by this rule.
 .SH LOCAL WEBHOOK EVENTS
 .PP
 .B primitive listen
@@ -312,6 +335,19 @@ chat sent the message but no reply arrived before the timeout. Wait; do not rese
 .B 4
 .BR uncertain :
 transport error, conflict, server error, or a send record with status unknown. The message may have gone out; check sent history before retrying.
+.PP
+Every
+.B --json
+envelope from these commands carries
+.B sent_email_id
+(null until a send record is known) and
+.BR idempotency_key ,
+including on an uncertain outcome. Reconcile with
+.BR "primitive sent get --idempotency-key KEY" ;
+not_found means no record is visible yet, not that nothing was created, so
+retry only with the same
+.BR --idempotency-key ,
+never a new one.
 .SH ENVIRONMENT
 .TP
 .B PRIMITIVE_API_KEY

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primcli",
-  "version": "1.34.0",
+  "version": "1.35.0",
   "description": "Official Primitive CLI: deploy Primitive Functions, send and inspect mail, manage endpoints, all from the terminal. Wraps the @primitivedotdev/sdk runtime client with one-shot commands.",
   "type": "module",
   "sideEffects": false,
@@ -145,6 +145,9 @@
       },
       "agent:notes": {
         "description": "Read and maintain organization address notes. Connected profiles default to their own address and can write only their own notes. Use agent notes list|get|set|delete; new notes are private, and updates preserve visibility unless explicitly changed. Commands return JSON by default."
+      },
+      "agent:working": {
+        "description": "Short, expiring work claims stored in the AGENT_WORKING address note. Set a claim when work starts, clear it when work ends, and check a peer's claim with get --address before editing a shared file. Claims are advisory, not locks."
       }
     },
     "topicSeparator": " "