primcli 1.31.0 → 1.33.0

package/README.md

@@ -31,7 +31,8 @@ This package wraps the [@primitivedotdev/sdk](https://www.npmjs.com/package/@pri
 ### Receive webhook events without a public endpoint
 
 With an existing Primitive account and inbox, sign in or set `PRIMITIVE_API_KEY`.
-Run `primitive listen` to print existing webhook events as JSONL. Status goes to
+Run `primitive listen` to print existing webhook events as JSONL.
+`--json` is accepted explicitly; status remains JSON and stdout events remain JSONL. Status goes to
 stderr. No public URL or separate destination setup is required.
 
 For an agent, use a short hook that saves each event into its durable inbox:
@@ -130,6 +131,7 @@ primitive functions deploy --name my-fn --file ./dist/handler.js
 
 primitive send --to alice@example.com --body "Hello!" --wait
 primitive emails latest --limit 5
+primitive inbox next
 ```
 
 Run `primitive --help` for the full command list. Per-command help (`primitive functions deploy --help`) carries enough detail that an agent can compose any operation without leaving the terminal.
@@ -171,6 +173,77 @@ Use `primitive logout --force` to remove local CLI credentials, pending email-co
 
 Use `primitive signup <email>` for new account creation, then `primitive signup confirm <email> <code>` with the emailed verification code. Non-interactive signup is available with `--accept-terms` (pass `--signup-code <code>` too if you have one).
 
+## Reply state and the agent loop
+
+Every inbound email carries reply state: `awaiting` is `you` when the latest
+message in its thread is inbound (it waits on your reply) and `them` when you
+replied last; `reply_count` and `last_replied_at` describe replies to that one
+email. A reply counts once it is sent or committed to go (queued and scheduled
+count; gate-denied, agent-failed and canceled sends do not).
+
+`primitive emails latest` shows it as the AWAITING and REPLIES columns, and
+`--json` carries the fields. Filter on it with `--awaiting you|them` on
+`emails latest`, `emails list`, `emails search`, `emails wait`, `emails watch`
+and `search`, or with `awaiting:you` in a search query.
+
+`primitive inbox next` returns the oldest email awaiting your reply, its
+conversation (roles `user` and `assistant`; the API caps long threads and sets
+`truncated` when older messages are omitted), an `automated` verdict with
+reasons, and the exact `primitive reply --id <id>` command that answers it. The
+loop is:
+
+```bash
+primitive inbox next --json > next.json   # exit 5: nothing awaits you
+primitive reply --id "$(jq -r .email.id next.json)" --body "..."
+primitive inbox next --json               # the next one
+```
+
+| Exit | Meaning |
+|---|---|
+| 0 | An email awaits your reply; it is printed. |
+| 1 | Error, including `reply_state_unsupported` or `automated_filter_unsupported` from an older server. |
+| 2 | Invalid flags or arguments. |
+| 5 | Nothing awaits your reply (with `--wait`: still nothing at `--timeout`). |
+
+- Automated mail is skipped unless you pass `--include-automated`: null envelope
+  sender (bounces), mailer-daemon and postmaster, mail sent from the very address
+  it was delivered to, delivery, feedback and disposition reports, and mail that
+  declares itself automated (Auto-Submitted, Precedence bulk/list/junk,
+  List-Unsubscribe, List-Id, X-Auto-Response-Suppress, X-Failed-Recipients).
+  This is the same set Primitive's own automatic responders decline to answer.
+  The API decides this
+  when the mail arrives (`automated`, `automated_reasons` on every email) and
+  `inbox next` filters on it server-side (`awaiting=you&automated=false`), so a
+  call costs the same however much unanswered automated mail has piled up. On
+  an empty result, `automated_awaiting` says how much automated mail also
+  awaits. `automation_headers_known: false` means the email had no automation
+  headers on record (none declared, or received before they were captured), so
+  `automated: false` rests on the sender checks alone. Filter on the verdict
+  yourself with `--automated true|false` on `emails list`, `emails search`,
+  `emails wait` and `emails watch`, or `automated:false` in a search query.
+- The `awaiting` filter covers delivered mail only: mail the server rejected
+  (for example over the storage limit) was never delivered and is never
+  returned as awaiting you. A server whose filter still returns rejected mail
+  fails with `awaiting_rejected_unsupported`.
+- `--wait [--timeout N]` blocks until something awaits you (default 300 seconds,
+  0 waits forever). It reads the inbox's newest position before checking reply
+  state, then long-polls from that position and re-checks on every arrival and
+  at least every 30 seconds, so mail that lands between the check and the wait is
+  not missed. Mail that arrives while you compose a reply is still `awaiting=you`
+  on the next call, because the state lives on the server, not in a cursor.
+- The email carries `from_known_address` and `auth` (SPF, DMARC) so an agent can
+  weigh instructions in it; the transcript prints them and strips terminal
+  control sequences from sender-supplied text.
+- It is not a work queue. Nothing is claimed or locked, so two agents calling
+  `inbox next` on the same inbox get the same email until one replies. Run one
+  agent per inbox.
+- Against a server without the `automated` filter, `inbox next` fails with
+  `automated_filter_unsupported` rather than deciding automated mail itself and
+  re-reading all of it on every call; `--include-automated` still works there.
+- Against a server that does not report reply state, `inbox next` and every
+  `--awaiting` filter fail with `reply_state_unsupported` instead of treating
+  mail as unanswered.
+
 ## Command style
 
 Use task-oriented commands for normal workflows:
@@ -232,6 +305,14 @@ scheduled sends before deleting them. A 409 means the record is not currently
 eligible; a 500 or 503 may mean some files were removed already, so retry the same
 DELETE. Repeating a completed deletion succeeds.
 
+`primitive agent disconnect --profile <name>` stops that profile's tracked
+session receiver, revokes its connected credential at the saved API origin,
+then clears only that local credential after Primitive confirms revocation.
+Mail, notes, setup evidence and notification receipts remain. A network error,
+401, or unconfirmed receiver stop leaves the credential in place and requires
+checking the agent in the app before retrying. Foreground or external runtime
+hooks are not managed by this command.
+
 After disconnecting an agent, an owner or admin logged in with OAuth can run
 `primitive agent-connections remove-agent-connection --address agent@example.com`.
 This removes the revoked connection record while preserving mail, notes and the
@@ -400,20 +481,52 @@ Codex session of authenticated mail from explicitly approved senders:
 ```bash
 primitive listen --notify-session <session-uuid> --sender person@example.com
 primitive listen --notify-session <session-uuid> --sender first@example.com,second@example.com
-primitive listen --status --notify-session <session-uuid>
+primitive listen --background --notify-session <session-uuid> --contacts --contact-requests
+primitive listen --status --notify-session <session-uuid> --json
+primitive listen --status --notify-session <session-uuid> --email-id <received-id>
 primitive listen --status --notify-session <session-uuid> --limit 100 --cursor <nextCursor>
+primitive listen --stop --notify-session <session-uuid>
 ```
 
-This first notification path uses the native local-session Unix socket in
-Codex 0.156.1. Live runtime behavior was verified on macOS; Linux uses the same
+Notifications arrive as external `primitive.mail_received` tool-output events,
+never synthetic user messages. An idle session can wake to evaluate the notice;
+a busy session receives it in its active turn. The notice does not grant user
+authority or permission to execute requests from email.
+
+This notification path uses `turn/start` with empty `input` and `toolOutput` over
+the native local-session Unix socket in Codex. It requires runtime support for
+external tool-output turns and has no user-message fallback. Live runtime behavior was verified on macOS; Linux uses the same
 Unix transport but has not been verified against a live runtime. The session must already be open in a terminal with
-native daemon support enabled. If its socket is unavailable, this is an
-unsupported runtime setup: the CLI reports the gap and exits before creating a
-subscription. It does not launch a daemon, start/resume a conversation, install a
+native daemon support enabled, with compatible client and server versions.
+The foreground command exits if its socket is unavailable; a background receiver
+reports `reconnecting` and waits for a temporarily unavailable native socket.
+Neither creates a subscription before native preflight succeeds. The CLI does
+not launch a coding daemon, start/resume a conversation, install a
 connector, or change model, approval, or sandbox settings. Windows and other
 harnesses are not supported by this path. `CODEX_HOME` selects the native runtime
 home when it differs from `~/.codex`.
 
+`--background` starts one detached CLI process for this connection and exact
+session. It survives exit of the process that started it. Repeating the command
+reuses a live background receiver with the same CLI version and receiving options.
+Stop it before changing those options, upgrading the receiver, or replacing a
+foreground receiver. `--status` reports its phase and process health separately
+from historical receipts; a stale heartbeat is not healthy. `--stop` requests a
+stop from only that instance and preserves mail, subscriptions and receipts.
+Foreground listeners started by this version also report health, but still share
+their calling process's lifetime. Receivers from older versions are untracked.
+Failed receivers include a fixed `failureCode`; private error contents are never
+stored. Preserve unknown notification receipts and inspect the exact session
+before retrying.
+
+Background receivers reconnect after a known transport interruption. A previously
+verified session may temporarily be unloaded while its terminal reconnects; the
+receiver waits for that same session without loading it. Each attempt
+revalidates the original connection, exact loaded session, private socket and
+working directory. Authorization, identity, protocol and unknown-dispatch errors
+stop receiving instead of being retried. Reconnection never starts a missing
+session or grants tool authority. A healthy receiver is not proof of a model reply.
+
 Notification mode registers an `email.received`-only subscription and refuses
 mixed existing filters before leasing events. Native notification mode requires
 WebSocket and the shared saved subscription; `--transport poll` and a custom
@@ -438,9 +551,10 @@ locally using current email details; an ingress acknowledgement does not mean
 a native notification was accepted.
 
 Local private receipts are scoped to the API environment, connected credential,
-and exact session. Accepted means queued, not read or answered. A lost queue
-response or interrupted submission is held as unknown across restarts because
-the runtime does not deduplicate client message IDs. Inspect these receipts with
+and exact session. Accepted means the runtime accepted an external event, not
+that mail was read or answered. A lost response or interrupted submission is
+held as unknown across restarts because the runtime offers no idempotency key
+for these events. Inspect these receipts with
 `--status`; it does not connect to a runtime or receive mail. Status returns up
 to 100 receipts by default (maximum `--limit 1000`) and a `nextCursor` for the
 next page. Individual private receipt files and an event index preserve evidence
@@ -450,9 +564,9 @@ receipt state to force a retry. Definite failures before dispatch can be retried
 by restarting the listener.
 
 The CLI verifies the private socket and loaded session before each dispatch.
-The native queue API cannot atomically fence a terminal closing between that
-check and acceptance, so a concurrent close can leave input queued for that
-same session. The CLI never retargets a different session.
+The native turn API cannot atomically fence a terminal closing between that
+check and acceptance, so a concurrent close can leave an external event
+accepted for that same session. The CLI never retargets a different session.
 
 Connected chat, exact-parent `emails wait`, and native notification listeners
 share one receiver for the same local installation, API environment, and connected
@@ -461,8 +575,43 @@ the selected session. Another foreground participant can resume receiving when
 the owner exits. Generic stdout, exec, forwarding, and `emails watch` remain
 separate consumers.
 
-Automatic runtime configuration, contact-policy synchronization, and notification
-history backfill are not provided. Reply waits use targeted recovery for their
+With `--contacts`, the listener reads the connected agent's current owner policy
+and exact preferences before admission and again before dispatch. Add
+`--contact-requests` for owner-enabled structured first-contact requests.
+Contact and agent-contact commands return JSON by default and accept explicit `--json`.
+Use `primitive contacts request <address> --reason <purpose> --wait --json` to initiate and
+`primitive contacts accept --id <received-request-id> --json` to accept under the owner's
+instructions. Request acceptance is separate from a substantive task reply. See
+[contact requests and policy](../docs/contact-requests.md) for approval patterns,
+policy CLI commands, explicit `--notify` consent, and recovery.
+
+### Agent address notes
+
+Connected profiles default to their own address. They can read another address's
+organization notes with `--address`, but can write or delete only their own.
+Owner logins must pass `--address`.
+
+```sh
+primitive agent notes list
+primitive agent notes get AGENT_INFO
+primitive agent notes list --address peer@example.com --prefix AGENT_
+primitive agent notes set AGENT_WORKING "Researching the requested topic"
+primitive agent notes set AGENT_INFO --value-file agent-info.json --json-value --if-absent
+primitive agent notes delete AGENT_WORKING
+```
+
+`set` stores its argument as text unless `--json-value` is given. Use
+`--value-file` instead of a command argument for private or multiline content.
+New notes are private to the organization. An update preserves the note's
+current visibility unless `--public` or `--private` is explicit; `--public`
+publishes the updated value immediately. By default, `set` reads the current
+version once and writes conditionally, or creates with `if_absent` when missing.
+Use `--if-version <version>` or `--if-absent` to provide the condition directly.
+`delete` likewise reads the current version once unless `--if-version` is
+provided. Conflicts are never retried automatically.
+
+Automatic runtime configuration and notification history backfill are not
+provided. Reply waits use targeted recovery for their
 exact sent parent. Existing server queue retention and delivery-gap reporting
 still apply; keep a foreground listener running for ongoing notifications.
 
@@ -479,3 +628,67 @@ Address-scoped events contain parsed message content in `email.parsed`.
 `email.content.raw` and `email.content.download` are null. Signed download links,
 account routing metadata, and other SMTP envelope recipients are not exposed.
 Attachments can be fetched through the authenticated email attachment API.
+
+### Connect a coding session
+
+On a trusted machine where the owner or admin has already run `primitive signin`,
+an exact coding session can create its own address in that signed-in organization:
+
+```sh
+primitive agent enroll --session <session-uuid> --name Research --contact-requests --json
+```
+
+For Claude Code, add `--receiver external` and invoke the Primitive skill in
+that session so its Stop hook receives mail. The CLI selects a verified managed
+domain, fixes the address before creation, then privately claims and verifies
+the invitation. An uncertain creation or claim is held for inspection; the
+agent can continue with a fresh app invitation for that same address. This
+local pilot uses the saved
+owner OAuth login, which is accessible to other local processes under the same
+OS user. Do not use it on an untrusted runtime.
+
+`--contact-requests` uses that owner login to enable first-contact intake for
+the exact new address after verification. It preserves existing agent policy
+rules, uses a conditional write, and reads the policy back before reporting
+`contactRequestPolicy: "enabled"`. An explicit disable or concurrent conflict
+pauses enrollment without overwriting the policy; rerun this exact session
+after reviewing it.
+
+With a supported native session, one command handles the private claim, email
+verification and receiving. Pipe the invitation from the Primitive app to stdin:
+
+```sh
+primitive agent connect --profile work --session <session-uuid> --contact-requests --json < private-invitation.txt
+```
+
+Omit `--contact-requests` when owner policy disables request intake. Resume the
+same setup without the invitation using its returned `resumeCommand`; keep the
+same session, profile and intake choice. Select the saved profile for later
+commands with `PRIMITIVE_AGENT_PROFILE=work`.
+
+Verification submission and delivery are separate from receiver health. A queued
+verification reply is accepted for delivery. Do not claim again or resend because
+setup was interrupted. The CLI preserves its private recovery state.
+
+For Claude Code, use the same setup command with `--receiver external`. This
+verifies the email challenge and enables owner notifications, but does not start
+a receiver. The installed Primitive skill registers a Claude Stop hook that runs:
+
+```sh
+primitive listen --once --wake --hook-session --events email.received --timeout 604800
+```
+
+The hook selects the `session-<uuid>` profile, receives on WebSocket, and exits
+2 with only the received email ID so Claude can wake. It exits 0 after an idle
+timeout or in an unpaired session. Keep the interactive Claude session open;
+receipt content remains external input. Other runtimes need a tested event
+adapter before automatic idle receiving can be claimed.
+
+A connected `chat` command waits for one reply. Use `chat <peer> <task> --async`
+for delegated work: it returns the send result immediately and keeps this exact
+session subscribed to validated Read, ACK, Working, Typing and later reply
+events. The receiver delivers activity as external status, not new task text.
+The ordinary final reply still needs to be read and evaluated. A clarification
+or blocker does not end that conversation. Sender authentication,
+exact-session ownership and explicit silence still apply. Separate topics
+remain separate conversations.

package/dist/{cli-config-BvflSzQe.js → cli-config-Cv2-NAOd.js}

@@ -691,16 +691,15 @@ function listenProcessIdentity(pid) {
 					PATH: "/usr/bin:/bin:/usr/sbin:/sbin"
 				}
 			};
-			const boot = execFileSync("/usr/sbin/sysctl", ["-n", "kern.boottime"], options);
-			const bootMatch = /\{\s*sec\s*=\s*(\d+),\s*usec\s*=\s*(\d+)\s*\}/.exec(boot);
+			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 (!bootMatch || !/^[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:${bootMatch[1]}:${bootMatch[2]}:${started}`;
+			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;
@@ -727,13 +726,20 @@ function listenProcessIdentity(pid) {
 	} 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}|win32:\d{1,20})$/.test(saved.identity) ? saved.identity : 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;
 	}
@@ -790,8 +796,7 @@ function acquireListenLock(directory, scope) {
 			let stale = pid !== null && !processAlive(pid);
 			if (!stale && pid !== null) {
 				const saved = ownerIdentity(join(path, entries[0] ?? ""));
-				const current = saved === null ? null : listenProcessIdentity(pid);
-				stale = saved !== null && current !== null && saved !== current;
+				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] ?? "");
@@ -1777,4 +1782,4 @@ function redactCliEnvironment(environment) {
 	};
 }
 //#endregion
-export { syncMailDirectory as $, saveActiveChatState as A, requireDefaultLoginProfile as B, resolveCliAuth as C, deleteChatState as D, chatStatePath as E, agentProfilesDirectory as F, mailId as G, SharedMailStateError as H, connectedAgentIdentity as I, mailString as J, mailLockBusy as K, connectedApiBaseUrl as L, AgentConnectionSetupError as M, agentProfileDirectory as N, loadActiveChatState as O, agentProfileName as P, removeMailFile as Q, loadConnectedAgentProfile as R, normalizeApiBaseUrl as S, saveSignupCredentials as T, invalidSharedMail as U, saveConnectedAgentProfile as V, mailAddress as W, privateMailDirectory as X, mailTime as Y, readMailJson as Z, deleteCliCredentials as _, normalizeCliEnvironmentName as a, listenProcessIdentity as at, hasStoredCliLogin as b, resolveConfigEnvironment as c, PrimitiveApiClient as ct, validateCliHeaderName as d, withMailLock as et, validateCliHeaderValue as f, credentialsPath as g, credentialsLockPath as h, loadCliConfig as i, listenIdentity as it, AGENT_PROFILE_ENV as j, loadChatConversationByLocalId as k, saveCliConfig as l, createClient as lt, cliAccessTokenExpiresAt as m, deleteCliConfig as n, ListenStateError as nt, redactCliEnvironment as o, normalizeListenOrigin as ot, acquireCliCredentialsLock as p, mailObject as q, emptyCliConfig as r, acquireListenLock as rt, removeCliEnvironment as s, resolveListenSubscription as st, DEFAULT_ENVIRONMENT as t, writeMailJson as tt, upsertCliEnvironment as u, createConfig as ut, deleteCliCredentialsLock as v, saveCliCredentials as w, loadCliCredentials as x, detectPrimitiveKeyEnvMisname as y, parseConnectedAgentProfile as z };
+export { syncMailDirectory as $, saveActiveChatState as A, requireDefaultLoginProfile as B, resolveCliAuth as C, deleteChatState as D, chatStatePath as E, agentProfilesDirectory as F, mailId as G, SharedMailStateError as H, connectedAgentIdentity as I, mailString as J, mailLockBusy as K, connectedApiBaseUrl as L, AgentConnectionSetupError as M, agentProfileDirectory as N, loadActiveChatState as O, agentProfileName as P, removeMailFile as Q, loadConnectedAgentProfile as R, normalizeApiBaseUrl as S, saveSignupCredentials as T, invalidSharedMail as U, saveConnectedAgentProfile as V, mailAddress as W, privateMailDirectory as X, mailTime as Y, readMailJson as Z, deleteCliCredentials as _, normalizeCliEnvironmentName as a, listenIdentity as at, hasStoredCliLogin as b, resolveConfigEnvironment as c, resolveListenSubscription as ct, validateCliHeaderName as d, createConfig as dt, withMailLock as et, validateCliHeaderValue as f, credentialsPath as g, credentialsLockPath as h, loadCliConfig as i, compareListenProcessIdentity as it, AGENT_PROFILE_ENV as j, loadChatConversationByLocalId as k, saveCliConfig as l, PrimitiveApiClient as lt, cliAccessTokenExpiresAt as m, deleteCliConfig as n, ListenStateError as nt, redactCliEnvironment as o, listenProcessIdentity as ot, acquireCliCredentialsLock as p, mailObject as q, emptyCliConfig as r, acquireListenLock as rt, removeCliEnvironment as s, normalizeListenOrigin as st, DEFAULT_ENVIRONMENT as t, writeMailJson as tt, upsertCliEnvironment as u, createClient as ut, deleteCliCredentialsLock as v, saveCliCredentials as w, loadCliCredentials as x, detectPrimitiveKeyEnvMisname as y, parseConnectedAgentProfile as z };