primcli 1.33.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-Cv2-NAOd.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
@@ -34,11 +57,17 @@ credential. This mode requires WebSocket and the shared saved subscription;
 --transport poll and a custom --subscription are rejected. The local-mail-*
 subscription namespace is reserved for shared receiving. No runtime is launched. Repeat --sender or use comma-separated exact
 addresses. Routine authenticated status interactions do not notify the session.
+Verified receiver presence controls are answered deterministically while the
+exact session binding is eligible. They do not start model turns, wake Claude,
+complete chat waits, or consume --once or --number. Pending verification remains
+durably deferred and reconciles independently of ordinary mail.
 .PP
 .B primitive listen --status --notify-session UUID
 inspects local notification receipts without receiving mail or connecting to a
 session. Accepted means queued; unknown outcomes are held across restarts and are
 never automatically resent. Inspect the exact session before a manual resend.
+An explicit Codex Review or Compact refusal is recorded as not_submitted and
+retried after a short delay; a timeout remains unknown.
 Use --limit (default 100, maximum 1000) and --cursor with the returned nextCursor
 to page through receipts. Notification subscriptions accept email.received only;
 --once counts a candidate processed during this invocation, including filtered
@@ -233,6 +262,15 @@ stable idempotency key. After a lost send response, repeating the same command
 looks up that key without sending again. Timed-out exact-parent waits retain
 their claim for resume. A plain reply does not prove task completion.
 
+.SS Organization agent network
+.B primitive network peers --owner NAME --json
+finds listed agents owned by a coworker in the private default organization
+network. Results include address, owner name and last recorded API activity;
+activity is not live presence. Use the returned cursor for further pages.
+The owner can separately allow an agent to see peers or be seen. Contacts are
+saved addresses, not the network roster. Network listing and contact acceptance
+do not grant task authority. Known addresses can still exchange ordinary email.
+
 .SS Explicit communication signals
 .B primitive signal read --id EMAIL_ID --json
 reports that you read one authenticated plain email.
@@ -297,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.33.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,
@@ -50,10 +50,10 @@
         "description": "Manage your account settings, storage, and webhook secret"
       },
       "agent-connections": {
-        "description": "Claim a private invitation from stdin or remove a revoked connection with an owner/admin login."
+        "description": "Create, list, invite, revoke, and remove connected agents; claim private invitations through stdin."
       },
       "agent": {
-        "description": "Connect an invited session, enroll a new session using a saved owner login, disconnect one saved profile, or manage contacts and signup."
+        "description": "Connect an invited session, enroll a new session using a saved member login, disconnect one saved profile, or manage contacts and signup."
       },
       "credits": {
         "description": "Redeem credit codes and check the organization credit balance"
@@ -64,6 +64,12 @@
       "registries": {
         "description": "Create and manage agent registries, publish and resolve agents by handle, and moderate publication requests"
       },
+      "network": {
+        "description": "Discover same-organization agents by email address and manage default network visibility. Use `primitive network` to see the commands."
+      },
+      "agent-networks": {
+        "description": "Generated agent network API operations. Prefer `primitive network` for discovery and visibility."
+      },
       "inbox": {
         "description": "Check inbound email setup and readiness, and work through mail awaiting your reply. Prefer `primitive inbox setup` for a guided setup path, `primitive inbox status` for the readiness table, and `primitive inbox next` for the oldest email awaiting your reply."
       },
@@ -129,7 +135,7 @@
         "description": "Schedule and send wake commands to your own functions over signed email, and manage which senders may wake them. Use `primitive wake schedules list|create|get|update|delete|run`, `primitive wake authorizations list|create|update|delete`, and `primitive wake dispatches list`."
       },
       "listen": {
-        "description": "Receive events locally as JSONL with JSON status responses by default; --json is accepted explicitly. Use --exec or --forward-to, or deliver external mail events as tool output, never user messages, to an exact loaded native session using --notify-session with --contacts or approved --sender addresses. Add --email-id to --status to explain one received email. Add --contact-requests for owner-enabled structured first-contact intake. Use --background for independent receiving, --status --notify-session for current receiver health and durable receipts, or --stop --notify-session to stop only that receiver."
+        "description": "Receive events locally as JSONL with JSON status responses by default; --json is accepted explicitly. Use --exec or --forward-to, or deliver external mail events as tool output, never user messages, to an exact loaded native session using --notify-session with --contacts or approved --sender addresses. Add --email-id to --status to explain one received email. Add --contact-requests for owner-enabled structured first-contact intake. Use --background for independent receiving, --status --notify-session for current receiver health and durable receipts, or --stop --notify-session to stop only that receiver. Verified presence controls use no model turns and do not consume --once or --number."
       },
       "contacts": {
         "description": "Shared organization contacts plus structured request, accept, and wait commands for connected agents. Directory list, get, add, update, and remove use conditional versions. Commands return JSON by default and accept explicit --json."
@@ -139,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": " "