primcli 1.62.1 → 1.64.0

package/README.md

@@ -1036,7 +1036,13 @@ It gives the session an address once, named `<runtime>-<repository>`, using the
 saved member login, and only re-verifies on resume; a session whose agent was
 disconnected or removed never gets a second address. The SessionEnd hook runs
 `primitive agent session-end`, which disconnects only agents that
-`session-register` created. The end is recorded first, so a registration still
+`session-register` created, and only while the session's profile still holds
+that exact credential: an agent later connected into the same profile (for
+example with `primitive agent connect`) is left connected, and only the
+registered agent's own receive hooks are removed. Claude reports the same
+SessionEnd for a restart, a switch to another session and a real exit, so the
+hook waits five minutes before disconnecting, and a start of the same session
+within that time cancels the end. The end is recorded first, so a registration still
 running disconnects the agent it creates; when the local credential is gone it
 revokes by address with the member login, and an unconfirmed disconnect is
 reported as `disconnect_pending` and retried by `machine doctor --fix`. Both always exit 0 and finish slow work in the
@@ -1134,15 +1140,22 @@ and `body_text`, fenced and labelled untrusted. With `--json` it prints one
 object with `envelope`, `subject` and `body_text`.
 
 `primitive emails get --id <id> --compact` is the smallest read, for keeping
-an email cheap in a model's context. It prints one JSON object with `id`,
-`thread_id`, `received_at`, `from`, `to`, `subject`, `body_text` and
-`attachments` (filename, content type, size and part index). Quoted history
-below a reply is removed and counted in `quoted_chars_removed`, and an email
-with no text part has its HTML reduced to text (`body_source` is then `html`).
-The HTML body, authentication results, routing and webhook delivery state are
-left out. It makes one request and sends no signal. Use `--context` instead when
-a connected agent needs to know who the sender is to it and how to answer; the
-two flags cannot be combined.
+an email cheap in a model's context. It prints the server's readable read as
+one JSON object: `id`, `thread_id`, `received_at`, `from`, `to`, `subject`,
+`preheader`, `body_text`, `attachments` (filename, content type, size and part
+index) and the counts below. Hidden content, layout and quoted reply history
+are removed by the server (`quoted_chars_removed` counts the history), and
+every link in `body_text` is a `[n]` marker. `link_count` says how many links
+there are; `--links all` or `--links 1,2,3` adds their targets as `links`
+(`[{ "n": 1, "url": "..." }]`). A long body arrives in pages of `--max-chars`
+characters (500 to 100000, default 16000): when `body_next_offset` is not null,
+run the same command with `--offset <body_next_offset>` for the next page.
+`body_incomplete` is true when the stored body was itself cut short, so the
+text ends before the message did. The three flags need `--compact`. It makes
+one request and sends no signal. Against a server that does not offer the
+readable read yet, the CLI prints its own local compact view instead and says
+so on stderr. Use `--context` instead when a connected agent needs to know who
+the sender is to it and how to answer; the two flags cannot be combined.
 
 The envelope also carries `interaction` (the server's `interaction_hint`,
 `interaction_kind` and `fyi`, plus a `category` and whether a plain reply

package/dist/{api-command-Bj8WyqXK.js → api-command-C3XihKH7.js}

@@ -1,4 +1,4 @@
-import { b as __exportAll } from "./repeats-x4QM2yoG-De3MV3st.js";
+import { S as __exportAll, _ as WEBHOOK_EVENT_TYPES, g as SENT_EMAIL_EVENT_TYPES } from "./repeats-BL7ZC-_6-Dzangtkf.js";
 import { C as resolveCliAuth, F as agentProfilesDirectory, G as createClient, H as requireDefaultLoginProfile, K as createConfig, N as agentProfileDirectory, R as loadConnectedAgentProfile, S as normalizeApiBaseUrl, T as saveSignupCredentials, W as PrimitiveApiClient, _ as deleteCliCredentials, c as resolveConfigEnvironment, d as validateCliHeaderName, f as validateCliHeaderValue, i as loadCliConfig, j as AGENT_PROFILE_ENV, m as cliAccessTokenExpiresAt, p as acquireCliCredentialsLock, w as saveCliCredentials, x as loadCliCredentials, y as detectPrimitiveKeyEnvMisname } from "./cli-config-DMszFbGn.js";
 import { h as writeMailJson, m as withMailLock, p as syncMailDirectory, u as privateMailPermissions } from "./shared-mail-files-MwlVE90c.js";
 import { Command, Errors, Flags } from "@oclif/core";
@@ -316,7 +316,13 @@ const verifyAgentSignup = (options) => (options.client ?? client).post({
 * addresses that have already sent it authenticated mail) with tight send
 * limits. Use the returned `api_key` as a Bearer token on later calls. The
 * account can be upgraded to a full developer account by confirming an
-* email through the claim flow. This endpoint does not require an API key.
+* email through the claim flow. Upgrading raises the send cap and grants
+* the developer plan's default features (such as Functions); it does not
+* unlock sending to arbitrary recipients, because the recipient rules on
+* the account still apply. `GET /send-permissions` reports those rules
+* (its list of individual addresses can be partial), and
+* `POST /sendability` answers for one specific recipient. This endpoint
+* does not require an API key.
 *
 */
 const createAgentAccount = (options) => (options.client ?? client).post({
@@ -356,8 +362,13 @@ const startAgentClaim = (options) => (options.client ?? client).post({
 *
 * Confirms the verification code emailed by `/agent/claim/start` and
 * upgrades the account to the `developer` plan. The org id, API key, and
-* managed inbox all carry over; the send cap lifts. Authenticated by the
-* agent's own API key.
+* managed inbox all carry over; the send cap lifts and the developer
+* plan's default features (such as Functions) unlock. Upgrading does not
+* unlock sending to arbitrary recipients: the recipient rules on the
+* account still apply. `GET /send-permissions` reports those rules (its
+* list of individual addresses can be partial), and `POST /sendability`
+* answers for one specific recipient. Authenticated by the agent's own
+* API key.
 *
 */
 const verifyAgentClaim = (options) => (options.client ?? client).post({
@@ -1538,8 +1549,12 @@ const updateRoute = (options) => (options.client ?? client).patch({
 /**
 * List webhook deliveries
 *
-* Returns a paginated list of webhook delivery attempts. Each delivery
-* includes a nested `email` object with sender, recipient, and subject.
+* Returns a paginated list of webhook delivery attempts, newest first.
+* A delivery of an inbound email includes a nested `email` object with
+* sender, recipient, and subject. A delivery of an opt-in
+* `sent_email.*` event has `email_id` and `email` set to null and
+* `sent_email_id` set to the send it is about. Filter by `event_type`
+* and `sent_email_id` to find the deliveries of one send.
 *
 */
 const listDeliveries = (options) => (options?.client ?? client).get({
@@ -1553,11 +1568,15 @@ const listDeliveries = (options) => (options?.client ?? client).get({
 /**
 * Replay a webhook delivery
 *
-* Re-sends the stored webhook payload from a previous delivery attempt.
-* If the original endpoint is still active, it is targeted. If the
-* original endpoint was deleted, the oldest active endpoint is used.
-* Deactivated endpoints cannot be replayed to. Rate limited per-org,
-* sharing an org-wide budget with email replays.
+* Re-sends a previous delivery to its original endpoint. If that
+* endpoint was deleted or deactivated, the replay is rejected.
+* Supports inbound email deliveries and `sent_email.*` deliveries.
+* An inbound email delivery is replayed with its original stored
+* payload and event id. A `sent_email.*` delivery is replayed with the
+* same event id but a payload rebuilt from the send as it is now; it
+* is rejected if the send was deleted or the endpoint is no longer an
+* active http endpoint. Rate limited per-org, sharing an org-wide
+* budget with email replays.
 *
 */
 const replayDelivery = (options) => (options.client ?? client).post({
@@ -3690,6 +3709,79 @@ function ensureSearchReportsAutomated(apiClient) {
 	return probe;
 }
 //#endregion
+//#region src/oclif/endpoint-event-types.ts
+const EVENT_TYPES_FLAG_OPERATIONS = /* @__PURE__ */ new Set(["createEndpoint", "updateEndpoint"]);
+const EVENT_TYPES_FLAG_DESCRIPTION = "Event types this endpoint subscribes to, comma separated or repeated (sets rules.event_types). Omitting the subscription means every event type except the opt-in sent_email.* events, which an endpoint receives only when it lists them; sent_email.* expands to all four. Keep email.received in the list if the endpoint also handles inbound mail. On update, the endpoint's other rules are kept.";
+const SENT_EMAIL_WILDCARD = "sent_email.*";
+const KNOWN_EVENT_TYPES = new Set(WEBHOOK_EVENT_TYPES);
+var EventTypesFlagError = class extends Error {};
+/**
+* Turn the raw `--event-types` values into the list to store: split on
+* commas, trim, expand `sent_email.*`, and drop duplicates while keeping the
+* order the caller gave.
+*/
+function parseEventTypesFlag(values) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const value of values) for (const raw of value.split(",")) {
+		const name = raw.trim();
+		if (name === "") continue;
+		const names = name === SENT_EMAIL_WILDCARD ? [...SENT_EMAIL_EVENT_TYPES] : [name];
+		for (const entry of names) {
+			if (seen.has(entry)) continue;
+			seen.add(entry);
+			out.push(entry);
+		}
+	}
+	if (out.length === 0) throw new EventTypesFlagError("--event-types needs at least one event type. To receive every event type except the opt-in sent_email.* events, omit the subscription instead.");
+	if (out.length > 50) throw new EventTypesFlagError(`--event-types accepts at most 50 event types (got ${out.length}).`);
+	return out;
+}
+/** The names in `eventTypes` this CLI does not recognise. */
+function unknownEventTypes(eventTypes) {
+	return eventTypes.filter((name) => !KNOWN_EVENT_TYPES.has(name));
+}
+function unknownEventTypesWarning(unknown) {
+	return `Warning: ${unknown.join(", ")} ${unknown.length === 1 ? "is" : "are"} not an event type this CLI knows. Subscriptions match exact names, so a misspelled name receives nothing. Continuing; newer event types may not be known to this CLI yet.\n`;
+}
+function isPlainObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+* The rules an update starts from: the endpoint's current rules, read from
+* the endpoint list. Throws when the endpoint cannot be found, so an update
+* never replaces rules it could not read.
+*/
+async function currentEndpointRules(endpointId, listEndpoints) {
+	const response = await listEndpoints();
+	if (response.error) throw new EventTypesFlagError("Could not read the endpoint's current rules to keep them. Retry, or pass the full rules with --raw-body.");
+	const row = (response.data?.data ?? []).find((endpoint) => endpoint.id === endpointId);
+	if (!row) throw new EventTypesFlagError(`No endpoint ${endpointId} is visible to this credential, so its rules cannot be updated.`);
+	return isPlainObject(row.rules) ? row.rules : {};
+}
+/**
+* Put `eventTypes` in the request body's `rules.event_types`, on top of
+* `baseRules` (rules the caller passed in the body win over `baseRules`).
+*/
+function withEventTypes(body, eventTypes, baseRules = {}) {
+	if (body !== void 0 && !isPlainObject(body)) throw new EventTypesFlagError("--raw-body must be a JSON object when also passing --event-types.");
+	const current = body ?? {};
+	if (current.rules !== void 0 && !isPlainObject(current.rules)) throw new EventTypesFlagError("rules in --raw-body must be a JSON object when also passing --event-types.");
+	const explicitRules = current.rules ?? {};
+	return {
+		...current,
+		rules: {
+			...baseRules,
+			...explicitRules,
+			event_types: [...eventTypes]
+		}
+	};
+}
+/** True when the caller already passed `rules` in the request body. */
+function bodyHasRules(body) {
+	return isPlainObject(body) && body.rules !== void 0;
+}
+//#endregion
 //#region src/oclif/endpoints-test-redirect.ts
 async function detectFunctionEndpoint(endpointId, listEndpoints) {
 	let response;
@@ -5133,7 +5225,7 @@ function savedConnectedProfiles(configDir, exclude) {
 */
 async function otherProfiles(configDir, session, current) {
 	if (session) try {
-		const { connectedProfilesForSession } = await import("./machine-session-Bdr3jFm4.js").then((n) => n.s);
+		const { connectedProfilesForSession } = await import("./machine-session-B3JznlvO.js").then((n) => n.s);
 		return {
 			inSession: true,
 			profiles: connectedProfilesForSession(configDir, session, current)
@@ -5740,7 +5832,18 @@ function buildFlags(operation) {
 			flags[name] = bodyFieldFlag(field, aliasesForOperation?.[field.name]);
 			bodyFieldFlagToProperty.set(name, field.name);
 		}
+		const extraFlags = OPERATION_EXTRA_BODY_FLAGS[operation.sdkName] ?? {};
+		for (const [name, extra] of Object.entries(extraFlags)) {
+			if (RESERVED_FLAG_NAMES.has(name)) continue;
+			if (flags[name] !== void 0) continue;
+			flags[name] = Flags.boolean({ description: extra.description });
+			bodyFieldFlagToProperty.set(name, extra.property);
+		}
 	}
+	if (EVENT_TYPES_FLAG_OPERATIONS.has(operation.sdkName)) flags["event-types"] = Flags.string({
+		description: EVENT_TYPES_FLAG_DESCRIPTION,
+		multiple: true
+	});
 	if (operation.binaryResponse) flags.output = Flags.string({ description: "Write binary response bytes to a file" });
 	if (ATTACHMENT_WAIT_OPERATIONS.has(operation.sdkName)) flags.wait = Flags.boolean({
 		allowNo: true,
@@ -5761,6 +5864,18 @@ function collectBodyFieldFlags(parsedFlags, bodyFieldFlagToProperty) {
 	}
 	return result;
 }
+async function applyEventTypesFlag(params) {
+	try {
+		const eventTypes = parseEventTypesFlag(params.values);
+		const unknown = unknownEventTypes(eventTypes);
+		if (unknown.length > 0 && !params.quiet) process.stderr.write(unknownEventTypesWarning(unknown));
+		const baseRules = params.endpointId !== void 0 && !bodyHasRules(params.body) ? await currentEndpointRules(params.endpointId, params.listEndpoints) : {};
+		return withEventTypes(params.body, eventTypes, baseRules);
+	} catch (error) {
+		if (error instanceof EventTypesFlagError) throw new Errors.CLIError(error.message);
+		throw error;
+	}
+}
 function collectValues(parameters, flags) {
 	const values = {};
 	for (const parameter of parameters) {
@@ -5810,6 +5925,17 @@ const OPERATION_HINTS = {
 	verifyAgentSignup: "Tip: pass --verification-code <code> (or --code; both work). The response carries OAuth tokens but not your assigned inbox domain; run `primitive domains list` (or `primitive whoami`) after success to see the managed *.primitive.email address that routes to this account."
 };
 const OPERATION_FLAG_ALIASES = { verifyAgentSignup: { verification_code: ["code"] } };
+const OPERATION_EXTRA_BODY_FLAGS = { addDomain: { "mail-relay": {
+	property: "mail_relay",
+	description: "Keep your existing mailbox provider: the domain's MX points at a Primitive mail relay, which forwards mail to your mailboxes and stores a copy in Primitive. Requires mail relay to be enabled for your account. Google Workspace only for now."
+} } };
+const MAIL_RELAY_NOT_ENABLED_MESSAGE = "Mail relay is not enabled for this account, so the domain was not added. Retry without --mail-relay to point the domain's MX at Primitive directly, or ask Primitive to enable mail relay for your account.";
+const MAIL_RELAY_UNAVAILABLE_MESSAGE = "No mail relay is available on this API server right now, so the domain was not added. Retry later, or retry without --mail-relay to point the domain's MX at Primitive directly.";
+const OPERATION_ERROR_HINTS = { addDomain: (code, body) => {
+	if (code === "mail_relay_unavailable") return MAIL_RELAY_UNAVAILABLE_MESSAGE;
+	const mailRelay = body !== null && typeof body === "object" && body.mail_relay === true;
+	if (code === "feature_disabled" && mailRelay) return MAIL_RELAY_NOT_ENABLED_MESSAGE;
+} };
 const OPERATION_SUCCESS_HOOKS = { verifyAgentSignup: ({ envelope, configDir, apiBaseUrl, writeStderr }) => {
 	const data = envelope?.data;
 	if (!data?.access_token || !data?.refresh_token) return;
@@ -5865,6 +5991,16 @@ function createOperationCommand(operation) {
 						}
 					} else body = explicit;
 				}
+				if (EVENT_TYPES_FLAG_OPERATIONS.has(operation.sdkName) && Array.isArray(parsedFlags["event-types"])) body = await applyEventTypesFlag({
+					body,
+					values: parsedFlags["event-types"],
+					endpointId: operation.sdkName === "updateEndpoint" && typeof parsedFlags.id === "string" ? parsedFlags.id : void 0,
+					listEndpoints: () => listEndpoints({
+						client: apiClient.client,
+						responseStyle: "fields"
+					}),
+					quiet: parsedFlags.json === true
+				});
 				if (operation.bodyRequired && body === void 0) throw new Errors.CLIError(`Operation ${operation.operationId} requires a body. Pass each field as a --flag (see --help) or supply JSON via --raw-body / --body-file.`);
 				const operationFn = sdk_gen_exports[operation.sdkName];
 				const query = collectValues(operation.queryParams, parsedFlags);
@@ -5888,6 +6024,8 @@ function createOperationCommand(operation) {
 				if (result.error) {
 					const errorPayload = extractErrorPayload(result.error);
 					writeErrorWithHints(errorPayload);
+					const operationErrorHint = OPERATION_ERROR_HINTS[operation.sdkName]?.(extractErrorCode(errorPayload), body);
+					if (operationErrorHint) process.stderr.write(`${operationErrorHint}\n`);
 					if (replyStateSurface && isAwaitingRejectedError(errorPayload)) process.stderr.write(`${awaitingRejectedError(replyStateSurface).message}\n`);
 					if (automatedSurface && isAutomatedRejectedError(errorPayload)) process.stderr.write(`${automatedRejectedError(automatedSurface).message}\n`);
 					surfaceUnauthorizedHint({
@@ -5991,7 +6129,7 @@ function createOperationCommand(operation) {
 	return OperationCommand;
 }
 const EMPTY_RESULT_HINTS = {
-	listDeliveries: "(no results) No webhook deliveries logged yet. If you have an endpoint configured but expected to see test fires here: test deliveries from `primitive endpoints test` are NOT logged in this list, they're synchronous and visible only in the test-endpoint command's response. Real deliveries are logged when an inbound `email.received` event fans out to your endpoints. If you have no endpoints, run `primitive endpoints list` to check.",
+	listDeliveries: "(no results) No webhook deliveries logged yet. If you have an endpoint configured but expected to see test fires here: test deliveries from `primitive endpoints test` are NOT logged in this list, they're synchronous and visible only in the test-endpoint command's response. Real deliveries are logged when an event fans out to your endpoints: an inbound `email.received`, or a `sent_email.*` event for an endpoint that lists it in rules.event_types (they arrive within a few minutes of the result). If you have no endpoints, run `primitive endpoints list` to check.",
 	listEndpoints: "(no results) No webhook endpoints configured. Add one with `primitive endpoints create --url <your-url>`.",
 	listEmails: "(no results) No inbound emails received yet on this account. Send one to a verified domain to populate this list. For a compact view, prefer `primitive emails latest`.",
 	listDomains: "(no results) No domains on this account. Add one with `primitive domains add --domain <yourdomain.example>`.",