primcli 1.74.1 → 3.0.0-preview.1

package/dist/{notify-session-DJAb9SGm.js → notify-session-BN0JTPZ3.js}

@@ -1,29 +1,19 @@
-import { Et as downloadEmailAttachmentPart, J as parseWebhookEvent, K as isEmailReceivedEvent, c as classifySignalContent, q as isTrustedSender } from "./repeats-BL7ZC-_6-B_ESsWTH.js";
-import { _ as acquireListenLock, g as ListenStateError, y as listenIdentity } from "./shared-mail-files-CZfm7E2k.js";
-import { B as wakeInteractionSentence, T as wakeReadCommand, w as skillFirstLine } from "./api-command-fKP3NYa7.js";
+import { Et as downloadEmailAttachmentPart, J as parseWebhookEvent, K as isEmailReceivedEvent, c as classifySignalContent, q as isTrustedSender } from "./repeats-Dj_o6c-X-Bf9G0xds.js";
+import { E as wakeReadCommand, T as skillFirstLine, V as wakeInteractionSentence } from "./api-command-ctHBqTL5.js";
+import { _ as acquireListenLock, g as ListenStateError, y as listenIdentity } from "./shared-mail-files-BAQSGxxz.js";
 import { closeSync, copyFileSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, opendirSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { createHash, randomUUID, scryptSync } from "node:crypto";
 import { dirname, isAbsolute, join, normalize, resolve } from "node:path";
+import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { lstat, realpath } from "node:fs/promises";
 import { isDeepStrictEqual } from "node:util";
 import WebSocket from "ws";
-//#region src/oclif/connect-skill.ts
+import { request } from "node:http";
+import { request as request$1 } from "node:https";
+import { performance } from "node:perf_hooks";
+// src/oclif/connect-skill.ts
 const CONNECT_SKILL_NAME = "primitive-connect";
-const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-/**
-* The runtime whose tool environment names this exact session. A session ID
-* that matches neither runtime's variable has no detectable runtime.
-*/
-function detectAgentRuntime(session, env = process.env) {
-	const wanted = session.toLowerCase();
-	const claude = env.CLAUDE_CODE_SESSION_ID?.trim().toLowerCase();
-	const codex = (env.CODEX_THREAD_ID?.trim() || env.CODEX_SESSION_ID?.trim())?.toLowerCase();
-	if (!UUID.test(wanted)) return null;
-	if (claude === wanted && codex !== wanted) return "claude";
-	if (codex === wanted && claude !== wanted) return "codex";
-	return null;
-}
 function connectSkillTarget(options) {
 	const env = options.env ?? process.env;
 	const cwd = resolve(options.cwd ?? process.cwd());
@@ -288,8 +278,7 @@ function installConnectSkill(options) {
 		};
 	}
 }
-//#endregion
-//#region src/oclif/notify-session-errors.ts
+// src/oclif/notify-session-errors.ts
 var NativeSessionError = class extends ListenStateError {
 	submitted;
 	constructor(message, submitted = false) {
@@ -315,8 +304,7 @@ var NotificationOutcomeUnknownError = class extends NativeSessionError {
 		super(message, true);
 	}
 };
-//#endregion
-//#region src/oclif/notify-session-native.ts
+// src/oclif/notify-session-native.ts
 /** Codex explicitly refused this input before adding it to the turn queue. */
 var NativeTurnNotSubmittedError = class extends NativeSessionError {
 	constructor() {
@@ -580,8 +568,332 @@ async function connectNativeSession(options) {
 		}
 	};
 }
-//#endregion
-//#region src/oclif/notify-session-content.ts
+// src/oclif/listen-handlers.ts
+const HANDLER_TIMEOUT_MS = 3e4;
+const MAX_RESPONSE_BYTES = 1048576;
+const FORWARDED_HEADERS = /* @__PURE__ */ new Set([
+	"content-type",
+	"user-agent",
+	"primitive-signature",
+	"mymx-signature",
+	"x-webhook-event",
+	"x-webhook-id",
+	"x-primitive-webhook-delivery-id",
+	"x-primitive-email-id",
+	"x-primitive-endpoint-id"
+]);
+function normalizeForwardTarget(target) {
+	if (/^\d+$/.test(target)) return `http://localhost:${target}`;
+	if (/^(localhost|127\.0\.0\.1|\[::1\])(?::|\/|$)/.test(target)) return `http://${target}`;
+	return target;
+}
+function validateListenHandlerOptions(options) {
+	if (options.exec !== void 0 && process.platform === "win32") throw new Error("--exec requires a POSIX shell and process groups. On Windows, use --forward-to with a local HTTP handler.");
+	if (options.exec !== void 0 && options.forwardTo !== void 0) throw new Error("Choose either --exec or --forward-to.");
+	if (options.exec !== void 0 && (!options.exec.trim() || options.exec.includes("\0"))) throw new Error("--exec requires a nonempty shell command.");
+	if (options.forwardTo !== void 0) {
+		let url;
+		try {
+			url = new URL(normalizeForwardTarget(options.forwardTo));
+		} catch {
+			throw new Error("--forward-to requires an HTTP or HTTPS URL.");
+		}
+		if (!["http:", "https:"].includes(url.protocol) || !url.hostname || url.username || url.password || url.hash) throw new Error("--forward-to requires HTTP or HTTPS without userinfo or a fragment.");
+	}
+}
+/** User hooks retain their configuration, but not the CLI's API credentials. */
+function hookEnvironment(delivery) {
+	const env = { ...process.env };
+	for (const name of Object.keys(env)) if (/^PRIMITIVE_(?:(?:API_|OAUTH_|AUTH_)?(?:KEY|TOKEN|ACCESS_TOKEN|REFRESH_TOKEN)|API_HEADERS|LEASE_TOKEN)$/i.test(name)) delete env[name];
+	return {
+		...env,
+		PRIMITIVE_EVENT_ID: delivery.event_id,
+		PRIMITIVE_DELIVERY_ID: delivery.delivery_id,
+		PRIMITIVE_EVENT_TYPE: delivery.event_type
+	};
+}
+async function writeChunk(output, chunk, signal) {
+	signal.throwIfAborted();
+	let onError = () => {};
+	let onAbort = () => {};
+	let onDrain = () => {};
+	let onClose = () => {};
+	try {
+		await new Promise((resolve, reject) => {
+			let callbackDone = false;
+			let returned = false;
+			let accepted = false;
+			let drained = false;
+			const finish = () => {
+				if (returned && callbackDone && (accepted || drained)) resolve();
+			};
+			onError = reject;
+			onAbort = () => reject(signal.reason);
+			onClose = () => reject(/* @__PURE__ */ new Error("Output closed before accepting the event."));
+			onDrain = () => {
+				drained = true;
+				finish();
+			};
+			output.on("error", onError);
+			output.on("close", onClose);
+			output.on("drain", onDrain);
+			signal.addEventListener("abort", onAbort, { once: true });
+			accepted = output.write(chunk, (error) => {
+				if (error) reject(error);
+				else {
+					callbackDone = true;
+					finish();
+				}
+			});
+			returned = true;
+			finish();
+		});
+	} finally {
+		output.off("error", onError);
+		output.off("close", onClose);
+		output.off("drain", onDrain);
+		signal.removeEventListener("abort", onAbort);
+	}
+}
+function stopProcessGroup(child) {
+	if (!child.pid) return;
+	try {
+		process.kill(-child.pid, "SIGKILL");
+	} catch {}
+}
+var ChildCleanupError = class extends Error {};
+async function reapChild(child, closed) {
+	stopProcessGroup(child);
+	child.stdin?.destroy();
+	child.stdout?.destroy();
+	child.stderr?.destroy();
+	let timer;
+	try {
+		await Promise.race([closed, new Promise((_resolve, reject) => {
+			timer = setTimeout(() => reject(new ChildCleanupError("The hook did not close after termination. Its delivery remains uncompleted.")), 1e3);
+		})]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+async function execute(command, delivery, stderr, signal) {
+	signal.throwIfAborted();
+	const child = spawn(command, {
+		shell: true,
+		detached: true,
+		env: hookEnvironment(delivery),
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		windowsHide: true
+	});
+	const closed = new Promise((resolve) => child.once("close", () => resolve()));
+	const stop = () => stopProcessGroup(child);
+	signal.addEventListener("abort", stop, { once: true });
+	const consume = async (stream) => {
+		for await (const chunk of stream) await writeChunk(stderr, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk), signal);
+	};
+	child.once("exit", stop);
+	try {
+		const exited = new Promise((resolve, reject) => {
+			child.once("error", reject);
+			child.once("close", (code) => resolve(code));
+		});
+		const stdin = writeChunk(child.stdin, Buffer.from(delivery.body, "utf8"), signal).then(() => child.stdin.end());
+		const [code] = await Promise.all([
+			exited,
+			stdin,
+			consume(child.stdout),
+			consume(child.stderr)
+		]);
+		signal.throwIfAborted();
+		return code;
+	} finally {
+		try {
+			await reapChild(child, closed);
+		} finally {
+			signal.removeEventListener("abort", stop);
+		}
+	}
+}
+function structuredErrorCode(body) {
+	try {
+		const value = JSON.parse(body);
+		if (typeof value !== "object" || value === null) return void 0;
+		const object = value;
+		const nested = typeof object.error === "object" && object.error !== null ? object.error.code : void 0;
+		const code = typeof nested === "string" ? nested : object.code;
+		return typeof code === "string" && /^[a-z][a-z0-9_]{0,63}$/.test(code) ? code : void 0;
+	} catch {
+		return;
+	}
+}
+var ForwardFailure = class extends Error {
+	statusCode;
+	transportError;
+	constructor(statusCode, transportError) {
+		super("Webhook transport did not complete.");
+		this.statusCode = statusCode;
+		this.transportError = transportError;
+	}
+};
+async function forward(target, delivery, signal) {
+	signal.throwIfAborted();
+	const url = new URL(normalizeForwardTarget(target));
+	const body = Buffer.from(delivery.body, "utf8");
+	const headers = {};
+	for (const [name, value] of Object.entries(delivery.headers)) if (FORWARDED_HEADERS.has(name.toLowerCase())) headers[name.toLowerCase()] = value;
+	headers["content-length"] = String(body.length);
+	return new Promise((resolve, reject) => {
+		let observedStatus = null;
+		let settled = false;
+		const fail = (kind = observedStatus === null ? "network" : "io") => {
+			if (settled) return;
+			settled = true;
+			reject(new ForwardFailure(observedStatus, kind));
+		};
+		const request$2 = (url.protocol === "https:" ? request$1 : request)(url, {
+			method: "POST",
+			headers,
+			signal,
+			rejectUnauthorized: true
+		}, (response) => {
+			observedStatus = response.statusCode ?? null;
+			const chunks = [];
+			let size = 0;
+			response.on("error", () => fail());
+			response.on("aborted", () => fail());
+			response.on("data", (chunk) => {
+				size += chunk.length;
+				if (size > MAX_RESPONSE_BYTES) {
+					fail("response_too_large");
+					request$2.destroy();
+				} else chunks.push(chunk);
+			});
+			response.on("end", () => {
+				if (settled) return;
+				if (!response.complete || size > MAX_RESPONSE_BYTES) {
+					fail(size > MAX_RESPONSE_BYTES ? "response_too_large" : "io");
+					return;
+				}
+				settled = true;
+				const status = response.statusCode ?? 0;
+				const succeeded = status >= 200 && status < 300;
+				resolve({
+					status,
+					confirmed: succeeded && (response.headers["x-primitive-confirmed"] === "true" || response.headers["x-mymx-confirmed"] === "true"),
+					errorCode: succeeded ? void 0 : status >= 300 && status < 400 ? "handler_redirect" : structuredErrorCode(Buffer.concat(chunks).toString("utf8")) ?? (status >= 400 && status < 500 ? "handler_4xx" : status >= 500 ? "handler_5xx" : "unknown_error")
+				});
+			});
+		});
+		request$2.on("error", () => fail());
+		request$2.end(body);
+	});
+}
+function jsonLine(body) {
+	try {
+		return JSON.stringify(JSON.parse(body));
+	} catch {
+		throw new Error("Webhook body is not valid JSON.");
+	}
+}
+/**
+* The API withholds an event's body from a credential that cannot read the
+* mail it carries. Such an event is never handed on as if it were the event:
+* listening stops with an explanation and the delivery stays uncompleted.
+*/
+function readableDelivery(delivery) {
+	if (delivery.body === null) throw new ListenStateError("The API withheld this event's content from the listening credential; the delivery remains uncompleted. Listen with a credential that can read this mail.");
+	return {
+		...delivery,
+		body: delivery.body
+	};
+}
+function createListenHandler(options = {}) {
+	validateListenHandlerOptions(options);
+	return async (received, signal) => {
+		signal.throwIfAborted();
+		const delivery = readableDelivery(received);
+		const start = performance.now();
+		const work = new AbortController();
+		let timedOut = false;
+		const cancel = () => work.abort(signal.reason);
+		signal.addEventListener("abort", cancel, { once: true });
+		const timer = setTimeout(() => {
+			timedOut = true;
+			work.abort(/* @__PURE__ */ new Error("Event handler timed out."));
+		}, HANDLER_TIMEOUT_MS);
+		const duration = () => Math.min(HANDLER_TIMEOUT_MS, Math.max(0, Math.round(performance.now() - start)));
+		try {
+			if (options.exec !== void 0) {
+				const code = await execute(options.exec, delivery, options.stderr ?? process.stderr, work.signal);
+				signal.throwIfAborted();
+				return {
+					succeeded: code === 0,
+					outcome: {
+						mode: "exec",
+						exit_code: code,
+						duration_ms: duration()
+					}
+				};
+			}
+			if (options.forwardTo !== void 0) {
+				const response = await forward(options.forwardTo, delivery, work.signal);
+				signal.throwIfAborted();
+				return {
+					succeeded: response.status >= 200 && response.status < 300,
+					outcome: {
+						mode: "http",
+						status_code: response.status,
+						confirmed: response.confirmed,
+						duration_ms: duration(),
+						...response.errorCode ? { error_code: response.errorCode } : {}
+					}
+				};
+			}
+			await writeChunk(options.stdout ?? process.stdout, Buffer.from(`${jsonLine(delivery.body)}\n`, "utf8"), work.signal);
+			signal.throwIfAborted();
+			return {
+				succeeded: true,
+				outcome: {
+					mode: "stdout",
+					write_succeeded: true,
+					duration_ms: duration()
+				}
+			};
+		} catch (error) {
+			signal.throwIfAborted();
+			if (error instanceof ChildCleanupError) throw error;
+			if (options.exec !== void 0) return {
+				succeeded: false,
+				outcome: {
+					mode: "exec",
+					exit_code: null,
+					transport_error: timedOut ? "timeout" : "io",
+					duration_ms: duration()
+				}
+			};
+			if (options.forwardTo !== void 0) return {
+				succeeded: false,
+				outcome: {
+					mode: "http",
+					status_code: error instanceof ForwardFailure ? error.statusCode : null,
+					confirmed: false,
+					transport_error: timedOut ? "timeout" : error instanceof ForwardFailure ? error.transportError : "network",
+					duration_ms: duration()
+				}
+			};
+			throw error;
+		} finally {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", cancel);
+			work.abort();
+		}
+	};
+}
+// src/oclif/notify-session-content.ts
 var NotificationRetryError = class extends ListenStateError {};
 function notificationPartReader(client) {
 	return async (emailId, partIndex, signal) => {
@@ -683,8 +995,7 @@ async function classifyNotificationContent(email, readPart, signal) {
 	if (classification.classification === "unavailable") throw new NotificationRetryError("Interaction classification is unavailable; retrying through the delivery queue.");
 	return classification;
 }
-//#endregion
-//#region src/oclif/notify-session-state.ts
+// src/oclif/notify-session-state.ts
 const invalid = () => new ListenStateError("Notification receipts are unavailable or inconsistent. Preserve this state to avoid duplicate notifications.");
 function uuid(value) {
 	if (typeof value !== "string" || !SESSION_UUID.test(value)) throw invalid();
@@ -934,8 +1245,7 @@ function notificationReceiptPage(configDir, scope, threadId, options = {}) {
 		nextCursor: hasMore ? ids.at(-1) ?? null : null
 	};
 }
-//#endregion
-//#region src/oclif/notify-session.ts
+// src/oclif/notify-session.ts
 function notificationScope(origin, apiKey) {
 	if (!apiKey?.startsWith("pconn_")) throw new ListenStateError("--notify-session requires a connected-agent credential scoped to its own address.");
 	return listenIdentity(origin, `connection:${scryptSync(apiKey, "primitive-listener-identity-v1", 32).toString("hex")}`);
@@ -970,9 +1280,10 @@ async function openSessionNotifications(options) {
 			}
 		});
 		if (delivery.event_type !== "email.received") throw new ListenStateError("Notification mode received an unrelated event. It remains uncompleted; use an email.received-only subscription.");
+		const { body } = readableDelivery(delivery);
 		let event;
 		try {
-			event = parseWebhookEvent(JSON.parse(delivery.body), delivery.event_type);
+			event = parseWebhookEvent(JSON.parse(body), delivery.event_type);
 		} catch {
 			throw new ListenStateError("Invalid email event; the delivery remains uncompleted.");
 		}
@@ -1133,5 +1444,4 @@ async function openSessionNotifications(options) {
 }
 var ContactNoticeSuppressed = class extends Error {};
 var ContactNoticeDeferred = class extends Error {};
-//#endregion
-export { detectAgentRuntime as _, NotificationRetryError as a, installedVersion as b, readConversationStatusContent as c, defaultSessionSocket as d, NativeSessionDisconnectedError as f, connectSkillTarget as g, NotificationOutcomeUnknownError as h, notificationReceiptPage as i, SESSION_UUID as l, NativeSessionNotLoadedError as m, notificationSenders as n, isRoutineNotificationContent as o, NativeSessionError as p, openSessionNotifications as r, notificationPartReader as s, notificationScope as t, connectNativeSession as u, installConnectSkill as v, readBundledConnectSkill as x, installedConnectSkillFile as y };
+export { readBundledConnectSkill as S, NotificationOutcomeUnknownError as _, NotificationRetryError as a, installedConnectSkillFile as b, readConversationStatusContent as c, SESSION_UUID as d, connectNativeSession as f, NativeSessionNotLoadedError as g, NativeSessionError as h, notificationReceiptPage as i, createListenHandler as l, NativeSessionDisconnectedError as m, notificationSenders as n, isRoutineNotificationContent as o, defaultSessionSocket as p, openSessionNotifications as r, notificationPartReader as s, notificationScope as t, readableDelivery as u, connectSkillTarget as v, installedVersion as x, installConnectSkill as y };

package/dist/oclif/auto-signal-worker.js

@@ -1,11 +1,11 @@
-import { Ut as getSentEmail } from "../repeats-BL7ZC-_6-B_ESsWTH.js";
-import { _ as acquireListenLock } from "../shared-mail-files-CZfm7E2k.js";
-import { b as readThreadContext, kt as createAuthenticatedCliApiClient } from "../api-command-fKP3NYa7.js";
-import { t as sendSignal } from "../signal-command-Cte4mAL3.js";
+import { Gt as getSentEmail } from "../repeats-Dj_o6c-X-Bf9G0xds.js";
+import { Mt as createAuthenticatedCliApiClient, x as readThreadContext } from "../api-command-ctHBqTL5.js";
 import { AUTO_SIGNAL_KIND_ENV, AUTO_WORKING_RENEW_MS, autoSignalsDisabled, clearWorkingSending, markWorkingSending, readAutoClaim, readWorkingLease, recordRenewer, stopWorkingLease, writeWorkingLease } from "./auto-signals.js";
+import { _ as acquireListenLock } from "../shared-mail-files-BAQSGxxz.js";
+import { t as sendSignal } from "../signal-command-CRUMUCNa.js";
 import { join } from "node:path";
 import { homedir } from "node:os";
-//#region src/oclif/auto-signal-worker.ts
+// src/oclif/auto-signal-worker.ts
 function configDirectory(env) {
 	if (env.PRIMITIVE_CONFIG_DIR) return env.PRIMITIVE_CONFIG_DIR;
 	return join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "primitive");
@@ -164,5 +164,4 @@ async function runAutoSignalWorker(env = process.env, deps = {}) {
 		}
 	} catch {}
 }
-//#endregion
 export { runAutoSignalWorker };

package/dist/oclif/auto-signals.js

@@ -1,11 +1,11 @@
-import { d as readMailJson, h as writeMailJson, i as mailId, l as privateMailDirectory, r as mailAddress } from "../shared-mail-files-CZfm7E2k.js";
-import { n as isPlainChatReply, o as scopedChatSenderTrust } from "../scoped-chat-DAiOb622.js";
+import { n as isPlainChatReply, o as scopedChatSenderTrust } from "../scoped-chat-DZ42V3jq.js";
+import { d as readMailJson, h as writeMailJson, i as mailId, l as privateMailDirectory, r as mailAddress } from "../shared-mail-files-BAQSGxxz.js";
 import { existsSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-//#region src/oclif/auto-signals.ts
+// src/oclif/auto-signals.ts
 /**
 * Automatic communication signals. When mail from the verified owner or a
 * verified same-organization member is surfaced to an agent session, the CLI
@@ -63,7 +63,7 @@ function autoSignalEligible(detail, identity, admission) {
 		if (!detail.message_id) return false;
 		const parsed = detail.parsed;
 		const to = parsed?.to_addresses;
-		if (!Array.isArray(to) || to.length !== 1 || lower(to[0]?.address) !== agent || (parsed.cc?.length ?? 0) > 0 || (parsed.bcc?.length ?? 0) > 0) return false;
+		if (!Array.isArray(to) || to.length !== 1 || lower(to[0]?.address) !== agent || (parsed?.cc?.length ?? 0) > 0 || (parsed?.bcc?.length ?? 0) > 0) return false;
 		return isPlainChatReply(detail);
 	} catch {
 		return false;
@@ -612,5 +612,4 @@ function resumeAutoWorking(configDir, options = {}) {
 		return 0;
 	}
 }
-//#endregion
 export { AUTO_SIGNALS_OPT_OUT_ENV, AUTO_SIGNAL_EMAIL_ENV, AUTO_SIGNAL_KIND_ENV, AUTO_SIGNAL_WORKER_ENV, AUTO_WORKING_CAP_MS, AUTO_WORKING_EXPIRES_SECONDS, AUTO_WORKING_RENEW_MS, activeWorkingLeases, autoSignalEligible, autoSignalEntrypoint, autoSignalsDisabled, claimAutoRead, clearWorkingSending, dispatchAutoRead, dispatchAutoWorking, haltAutoWorking, isSentSignal, markWorkingSending, readAutoClaim, readWorkingLease, recordRenewer, recordSentSignal, releaseStopHold, renewerAlive, restoreAutoWorking, restoreWorkingLease, resumeAutoWorking, spawnAutoSignalWorker, startWorkingLease, stopWorkingLease, writeWorkingLease };

package/dist/oclif/global-org-flag.js

@@ -0,0 +1,76 @@
+// src/oclif/global-org-flag.ts
+/**
+* The global `--org <org>` flag. bin/run.js takes it out of argv before oclif
+* parses the command, so every command accepts it, and passes it on as
+* PRIMITIVE_CLI_ORG. Only a saved `primitive login` made as yourself can switch
+* organizations; every other credential refuses a different organization.
+*
+* No oclif import here: this runs before oclif loads.
+*/
+/** Selects the organization for one command. */
+const ORG_SELECTION_ENV = "PRIMITIVE_CLI_ORG";
+/** Split `--org <value>` and `--org=<value>` out of argv, before any `--`. */
+function extractGlobalOrgFlag(argv) {
+	const separator = argv.indexOf("--");
+	const head = separator === -1 ? [...argv] : argv.slice(0, separator);
+	const tail = separator === -1 ? [] : argv.slice(separator);
+	const command = head[0] ?? "";
+	if (command === "memories" || command.startsWith("memories:")) return {
+		ok: true,
+		argv: [...argv],
+		org: null
+	};
+	const kept = [];
+	let org = null;
+	for (let index = 0; index < head.length; index += 1) {
+		const arg = head[index];
+		if (arg === "--org") {
+			const value = head[index + 1];
+			if (value === void 0 || value.startsWith("-") || !value.trim()) return {
+				ok: false,
+				message: "--org needs an organization id or name, for example `--org acme`."
+			};
+			org = value.trim();
+			index += 1;
+			continue;
+		}
+		if (arg.startsWith("--org=")) {
+			const value = arg.slice(6).trim();
+			if (!value) return {
+				ok: false,
+				message: "--org needs an organization id or name, for example `--org=acme`."
+			};
+			org = value;
+			continue;
+		}
+		kept.push(arg);
+	}
+	return {
+		ok: true,
+		argv: [...kept, ...tail],
+		org
+	};
+}
+/**
+* Apply the flag to this process: strip it from `process.argv` and set
+* PRIMITIVE_CLI_ORG. Returns an error message for a malformed flag.
+*/
+function applyGlobalOrgFlag(processArgv = process.argv, env = process.env) {
+	const parsed = extractGlobalOrgFlag(processArgv.slice(2));
+	if (!parsed.ok) return parsed.message;
+	if (parsed.org !== null) {
+		processArgv.splice(2, processArgv.length - 2, ...parsed.argv);
+		env[ORG_SELECTION_ENV] = parsed.org;
+	}
+	return null;
+}
+/**
+* `env` without an organization selection, for a child that acts as a
+* connected agent profile: the profile acts in its own organization.
+*/
+function withoutOrgSelection(env) {
+	const next = { ...env };
+	delete next[ORG_SELECTION_ENV];
+	return next;
+}
+export { ORG_SELECTION_ENV, applyGlobalOrgFlag, extractGlobalOrgFlag, withoutOrgSelection };