primcli 1.70.0 → 1.72.0

package/README.md

@@ -142,6 +142,49 @@ 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.
 
+## Verification codes and sign-in links
+
+Your address works for signing up and logging in to other services. After you
+enter it, wait for the email and take what you need from it:
+
+```bash
+# Sign up with your address, then:
+primitive wait --from github.com --code      # prints 482913
+primitive wait --from vercel.com --link      # prints the sign-in link
+primitive wait --subject "verify" --timeout 90s
+primitive wait --from stripe.com --code --json
+```
+
+`primitive wait` waits for the next email to the identity the CLI resolves (a
+connected agent profile's own address, or any inbound mail for a member login)
+and prints it: sender, subject, time, the start of its text and its ID, ready
+for `primitive reply --id <id>`. Only mail that arrives after the command starts
+matches; `--include-existing` also lets one of the newest 50 emails match, for
+a code that arrived before you started waiting.
+
+- `--from` takes an address or a bare domain; `github.com` matches any sender at
+  it or its subdomains. It narrows the wait; it does not authenticate the sender.
+- `--subject` matches text in the subject; `--thread <id>` and
+  `--reply-to <sent-email-id>` narrow to a conversation.
+- `--timeout` takes `90s`, `5m`, `1h` or plain seconds (default `5m`, `0` waits
+  forever).
+- `--code` prints only the one-time code, preferring numbers next to words like
+  code, verification or passcode and ignoring years, phone numbers, prices and
+  order numbers. A code split as `123 456` prints as `123456`.
+- `--link` prints only the most likely verify, confirm, sign-in, magic or reset
+  link, skipping unsubscribe, privacy, help and social links and removing an
+  obvious click-tracking wrapper.
+- `--json` prints one object: `id`, `thread_id`, `from`, `to`, `subject`,
+  `received_at`, `text` and, when asked, `code` and `link`.
+
+| Exit | Meaning |
+|---|---|
+| 0 | A matching email arrived and was printed. |
+| 1 | Error (API failure or authentication). |
+| 2 | Invalid flags or arguments. |
+| 5 | No matching email before `--timeout`. |
+| 6 | The email arrived without a code (`--code`) or link (`--link`); its ID is on stderr. |
+
 ## Waiting with connected credentials
 
 After sending, wait for the existing send's reply without sending again:
@@ -157,8 +200,9 @@ default, so fast replies are not missed; use `--since <timestamp>` to narrow the
 window. They require an authenticated peer and the exact outbound parent.
 Interaction attachments remain pending with inspection guidance. JSONL includes
 matching email details, or use `--table` for compact output and `--number N` for
-multiple replies. Timeout exits 1; repeat the same wait to recover without
-resending. Connected waits share one local address event receiver and recover
+multiple replies. `--json` prints the same JSONL and reports a timeout or error
+as one final JSON line with `error` and `exit_code`. Timeout exits 1; repeat
+the same wait to recover without resending. Connected waits share one local address event receiver and recover
 through exact-parent search, without scanning inbox history. Additional content
 filters on this command require organization credentials.
 
@@ -538,6 +582,31 @@ The sender sees the stop in the thread. `primitive emails get --id <email-id>
 --context` marks a repeating message with its cadence and, when the recipient may
 stop it, the exact stop command.
 
+## Custom headers and scheduled sends
+
+`send` and `reply` take `--header "Name: value"` (or `Name=value`), repeatable
+once per name. The CLI checks only the shape and refuses a duplicate name; the
+server decides which names are allowed and says why in a `validation_error`.
+
+```bash
+primitive send --to alice@example.com --body "Spring sale" --header "X-Campaign-Id: spring-sale" --header "Auto-Submitted=auto-generated"
+primitive reply --id <email-id> --body "Ticket updated." --header "X-Ticket-Id: 4821"
+```
+
+`send --scheduled-at <time>` records the send with status `scheduled` and sends it
+at that time. The time needs `Z` or a numeric UTC offset. It cannot be combined
+with `--wait`, `--attachment`, `--fyi` or `--if-latest-message-id`. The summary
+says the message is scheduled and how to cancel it, and the `--json` envelope
+adds a `cancel_scheduled_send` follow-up command.
+
+```bash
+primitive send --to alice@example.com --body "Reminder: standup" --scheduled-at 2026-10-09T17:00:00Z --idempotency-key standup-2026-10-09
+primitive sent cancel --idempotency-key standup-2026-10-09
+```
+
+Generated operation commands also expose the request headers the spec declares,
+for example `primitive sending send-email --idempotency-key <key>`.
+
 ## Recipient routing
 
 Bind a recipient address to a destination so inbound mail resolves to a single
@@ -1061,6 +1130,50 @@ stops running. Claude reports the same SessionEnd for a restart, a switch to
 another session and a real exit, so the hook waits five minutes first, and a
 start of the same session within that time cancels the end.
 
+#### Session agent identity in Claude Code
+
+Claude Code gives SessionStart hooks a file named by `CLAUDE_ENV_FILE` and
+runs it before every later Bash command in the session. Once the session's
+profile is saved and connected (on the first start, on resume, or for a
+session whose agent already exists), the SessionStart hook appends two lines
+to it:
+
+```sh
+export PRIMITIVE_AGENT_PROFILE=session-<session id>
+export PRIMITIVE_AGENT_ADDRESS=<the agent's email address>
+```
+
+So every `primitive` command in the session, and any tool that runs
+`primitive`, acts as the session's agent without a prefix, and `send` and
+`reply` send from the agent's address without `--from`. Registration that
+finishes after the hook returns still writes the lines, and later commands
+pick them up. Nothing is written for a session that already sets
+`PRIMITIVE_AGENT_PROFILE` (including to an empty value), when the file already
+assigns either variable, while setup is still pending, while another connected
+profile is bound to or receives for the session, or for a profile that is not
+saved, so a session is never pointed at a profile that does not exist.
+
+`PRIMITIVE_AGENT_ADDRESS` is for other tools in the session that need the
+agent's email address without running the CLI. It is set only together with
+`PRIMITIVE_AGENT_PROFILE` and always names that profile's address.
+`primitive whoami` prints the address alone on its first line, offline, and
+`primitive whoami --json` adds `address`, `profile` and `source`
+(`session_hook` for the session's own exported agent, `env` for any other
+`PRIMITIVE_AGENT_PROFILE`).
+
+Commands that manage the member login (`login`, `logout`, `signup`,
+`agent enroll`, and the other commands that refuse a selected profile) still
+refuse. To run any command as the member login from inside such a session,
+put an empty `PRIMITIVE_AGENT_PROFILE=` in front of it, or run it under
+`env -u PRIMITIVE_AGENT_PROFILE`:
+
+```sh
+PRIMITIVE_AGENT_PROFILE= primitive whoami
+```
+
+Codex hooks have no equivalent of `CLAUDE_ENV_FILE`, so Codex sessions still
+select their profile with `PRIMITIVE_AGENT_PROFILE` on each command.
+
 An agent that `session-register` created is disconnected only when its session
 has not started again for 30 days, by `machine doctor --fix` or the next
 `session-register` on the machine, and only while the session's profile still