primcli 1.75.0 → 3.0.0-preview.2

package/README.md

@@ -150,9 +150,9 @@ 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 --from accounts.example.com --link  # prints the sign-in link
 primitive wait --subject "verify" --timeout 90s
-primitive wait --from stripe.com --code --json
+primitive wait --from billing.example.com --code --json
 ```
 
 `primitive wait` waits for the next email to the identity the CLI resolves (a
@@ -224,8 +224,55 @@ Use `primitive signin <email> --accept-terms`, then `primitive signin confirm <e
 
 Use `primitive logout --force` to remove local CLI credentials, pending email-code auth state, and stale credential locks without contacting Primitive. This is the recovery command when an interrupted auth command leaves the CLI saying another credential operation is already in progress.
 
+Use `primitive org leave` to leave the organization you are signed in to. It asks for confirmation first; pass `--yes` to skip the prompt in scripts. Leaving is final. Only a person signed in with `primitive login` can leave; API keys are refused. The only owner of an organization cannot leave it until someone else is made an owner. If the server asks you to confirm in the dashboard, the command prints the confirmation page and, in a terminal, asks for the token it shows; in a script, pass the token with `--step-up-token`. Refusals from the server are printed as returned, and the command exits 1.
+
 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`.
 
+### Switching organizations
+
+Where the server supports it, browser login (`primitive login` with no email) logs you in as yourself rather than into one organization. The organization you choose in the browser becomes the current one, and you can switch without logging in again:
+
+```bash
+primitive orgs                 # your organizations, your role, and whether the CLI may be used there
+primitive org use acme         # switch by name or id
+primitive emails list --org beta   # act in another organization for one command
+```
+
+`--org` works on every command (set `PRIMITIVE_CLI_ORG` for the same effect; `primitive memories` keeps its own `--org` flag for organization-scoped memories). Each organization decides who may use the CLI there; when it refuses, `primitive orgs` and `primitive org use` show the reason (`not_a_member`, `cli_access_disabled_by_org`, `role_insufficient` or `cli_access_revoked`). The CLI keeps a short-lived access token per organization and gets a new one when it expires or is rejected. `primitive logout` signs you out of every organization.
+
+Against a server without organization switching, and for logins saved by earlier CLI versions, the login stays bound to one organization and works as before. `--org` naming a different organization is refused for such a login, for an API key and for a connected agent profile.
+
+`primitive login --permission <permission>` asks for a narrowed login. A server that does not offer narrowed CLI logins refuses it, and the CLI stops rather than logging in with a wider grant.
+
+### Grants and keys
+
+`primitive whoami` shows your organization, role and grant when the server reports them. `primitive whoami --check mail:send` asks whether the current credential may use a permission, prints the decision, and exits 1 when it may not; nothing is enforced by asking. A request refused because the credential's grant lacks a permission fails with `grant_forbidden`, and the CLI names the permission.
+
+```bash
+primitive keys list
+primitive keys get <id> --json
+primitive keys create --name orders --permission mail:read --rule <rule-id>
+primitive keys update <id> --add mail:send,mail:reply
+primitive keys rotate <id>
+primitive keys revoke <id>
+```
+
+`keys list` shows each key's id, prefix, name, permissions, the mail it reaches, expiry and last use, and `keys get` shows one key in full. Neither shows a secret. You see your own keys, and every key if your role may read them all.
+
+`keys create` needs you to say what the key can do: a `--preset`, or `--permission` with the mail it reaches (`--address`, `--domain`, `--rule`, each repeatable, or `--all-mailboxes`). There is no default, and a super admin key needs `--preset super_admin`. A key never holds more than you do, and your organization's credential policy applies. `keys update` adds or removes permissions (`--add`, `--remove`) or replaces the key's email rules (`--rule`); the key keeps its id and secret. A request already held open with that key, such as a long poll or a wait, ends once when its permissions change.
+
+Creating, rotating and changing a key need your approval in the browser. The command prints the approval link, opens it where it can, and waits for the one-time token the page shows. In a script, approve first and pass the token with `--step-up-token`. The new secret is printed once, alone on stdout (or in the JSON with `--json`), and the CLI never saves it, so store it right away. `keys revoke` asks for confirmation; pass `--yes` in scripts.
+
+`primitive roles list`, `primitive roles groups`, `primitive roles mailbox-access` and `primitive roles access-mode` read roles, groups, mailbox access and the access mode. Where the server has not enabled them, they print `feature_disabled`. The built-in roles are `owner`, `admin`, `operator` and `member`. `operator` has every permission `admin` has except managing members, changing roles, sending invitations and billing. By default, owners, admins and operators may use the CLI. An organization can open it to every member by setting `cli_access` to `all_members` in its credential policy.
+
+### Trying the preview
+
+Install the 3.0.0 preview with `npm install -g primitive@preview`. `npm install -g primitive` stays on the latest stable version.
+
+### Downgrading after signing in as yourself
+
+A login as yourself is saved with `auth_method: "user_grant"`, which CLI 1.75.0 and earlier cannot read: every command there fails with `Stored Primitive CLI credentials are malformed`. Run `primitive logout` with this CLI before installing an older one. If you have already downgraded, `primitive logout` removes the local file but does not revoke the login on the server, so sign in again afterwards.
+
 ## Reply state and the agent loop
 
 Every inbound email carries reply state: `awaiting` is `you` when the latest
@@ -315,6 +362,7 @@ primitive emails get --id <inbound-email-id> --compact
 primitive sent list
 primitive sent delete --id <sent-email-id>
 primitive domains list
+primitive billing
 primitive functions templates
 primitive functions init my-fn --template email-reply
 primitive functions logs --id <function-id>
@@ -427,8 +475,8 @@ signal or interaction, so two agents cannot keep acknowledging each other.
 acknowledgement for a message identified by its Message-Id.
 
 A plain `primitive reply` to an email the server classifies as an interaction
-the reply does not complete (a payment or contact request, or a kind this CLI
-cannot answer), or to informational mail or a status signal, is still sent.
+the reply does not complete (a contact request, or a kind this CLI cannot
+answer), or to informational mail or a status signal, is still sent.
 Without `--json` one `Warning:` line on stderr names the command that answers
 it; with `--json` the envelope carries `interaction_warning` (`code`,
 `email_id`, `kind`, `category`, `message`, `expected`), null otherwise.
@@ -629,65 +677,79 @@ primitive routes remove <route-id>
 Recipient routing is gated by an organization entitlement; routes are inert
 until it is enabled.
 
-## x402 payments
-
-The `primitive payments` command group drives non-custodial x402 USDC payments. One agent registers a payout address and requests a payment; the paying agent signs locally with its own wallet key and settles. The key never leaves your machine. Networks are `base` and `base-sepolia`. Amounts take a human USDC value (`--amount-usdc 0.01`) or token base units (`--amount 10000`, since USDC has 6 decimals). Your org is resolved automatically from your API key, so payout registration takes no org flag.
-
-```bash
-# Payee, one time: register the default address your org is paid at. Signs an
-# ownership message locally with your wallet key. Org is auto-resolved.
-primitive payments register-payout-address --network base-sepolia --label treasury
-
-# Payee: request a payment with a human USDC amount. Prints the challenge JSON
-# to stdout; a one-line summary goes to stderr.
-primitive payments charge --network base-sepolia --amount-usdc 0.01
-# Capture the challenge JSON to hand to the payer.
-primitive payments charge --network base-sepolia --amount-usdc 0.01 > challenge.json
-
-# Payer: sign and settle the challenge locally. Reads the challenge inline,
-# from a file, or piped on stdin.
-primitive payments pay --challenge-file challenge.json
-cat challenge.json | primitive payments pay
-
-# Email-native flow: the payee issues a challenge over an email thread.
-# Note: create-email-challenge takes --amount in token base units only; unlike
-# `charge` it has no --amount-usdc. USDC has 6 decimals, so multiply by
-# 1,000,000: 0.01 USDC is --amount 10000.
-primitive payments create-email-challenge --from payee@your-domain.example \
-  --to payer@their-domain.example --amount 10000 --network base-sepolia
-# Payer (recommended): pay the email challenge in one step. Signs the challenge
-# locally with your wallet key AND sends the signed interaction.json, so you
-# skip the manual sign-then-send dance. --in-reply-to is the inbound challenge
-# email you received; it is fetched to address the payment to the payee, with
-# From defaulting to the payer it was sent to. The send is not threaded under
-# the challenge (the payment associates by interaction_id). The message carries
-# a short default note alongside the attachment; pass --body to customize it.
-primitive payments pay-email --challenge-file challenge.json \
-  --in-reply-to <inbound-challenge-email-id> --wait
-
-# Advanced: sign only, without sending. Emits the portable interaction.json
-# artifact you can attach yourself (e.g. with `primitive send --attachment`).
-primitive payments pay-email-step --challenge-file challenge.json > interaction.json
-
-# Inspect a challenge by id, or list your registered payout addresses.
-primitive payments get-challenge --id <challenge-id>
-primitive payments list-payout-addresses
-
-# Read and update the org spend policy (kill-switch, per-payment and daily caps,
-# payee allowlist). The update merges: omitted fields keep their value.
-primitive payments get-spend-policy
-primitive payments update-spend-policy --max-per-payment 5000000
-```
-
-`charge` is the friendly verb that matches the SDK `charge` and accepts `--amount-usdc`; `create-challenge` is the lower-level command that takes base-unit `--amount`. Either creates a challenge. All four signing commands accept `--json`. `register-payout-address` and `pay` print a human-readable summary by default and raw JSON with `--json`; `pay-email` and `pay-email-step` print JSON by default (the send result and the `interaction.json` bytes, respectively), and `--json` switches them to a fuller envelope object.
-
-The signing commands (`register-payout-address`, `pay`, `pay-email`, and `pay-email-step`) need your wallet key. `pay-email` is the recommended payer path for the email-native flow: it signs and sends in one step. `pay-email-step` signs only and emits the `interaction.json` artifact for advanced use where you want to deliver it yourself. Set the key in `PRIMITIVE_X402_PRIVATE_KEY` (a `0x`-prefixed hex private key) so it never lands in shell history or the process list:
-
-```bash
-export PRIMITIVE_X402_PRIVATE_KEY=0x...
+## Supported receiver API
+
+A receiver in a coding harness that the CLI does not support must decide
+which received emails may wake its session. `primitive/receiver` exposes the
+CLI's own contact admission policy for that decision. It is the only
+supported library import from this package.
+
+```ts
+import { createWakePolicy, WakePolicyError } from "primitive/receiver";
+
+const policy = createWakePolicy({
+  recipient: "agent@example.com",
+  contactRequests: false,
+  readContactPolicy: (signal) => readPolicy(signal),
+  readContactPage: (cursor, signal) => readContacts(cursor, signal),
+  readNetworkAdmission: (emailId, sender, signal) =>
+    checkNetworkAdmission(emailId, sender, signal),
+});
+
+const decision = await policy.admit({ emailId, sender, receivedAt }, signal);
+if (decision.kind !== "denied") {
+  const confirm = await policy.recheck(decision, signal);
+  confirm(); // immediately before the wake
+  wake(decision.kind === "request" ? "contact request" : "mail");
+}
 ```
 
-A `--private-key` flag is available as an escape hatch for scripted use, but the environment variable is preferred. The non-signing commands (`charge`, `get-challenge`, `list-payout-addresses`, `get-spend-policy`, `update-spend-policy`) need only your Primitive API key. Run `primitive payments <command> --help` for the full flag list of any command.
+The three readers call the API as the connected address. Each returns the
+`data` of one operation:
+
+| Reader | API operation | CLI command |
+| --- | --- | --- |
+| `readContactPolicy` | `getAgentContactPolicy` | `primitive contacts get-agent-contact-policy` |
+| `readContactPage` | `listAgentContacts`, 100 rows per page, with the next `cursor` or `null` | `primitive agent contacts list` |
+| `readNetworkAdmission` | `checkDefaultNetworkContactAdmission` | `primitive agent-networks check-default-network-contact-admission` |
+
+`admit` returns one of three decisions for an email:
+
+- `allowed`: the email may wake the session.
+- `request`: a first-contact request from an unknown sender. It is returned
+  only when `contactRequests` is true and the owner allows contact requests.
+  Show it as a request, never as a task. Allow at most one per sender.
+- `denied`: the email must not wake the session.
+
+An admission carries the email ID, sender and received time, normalized to
+lower case and ISO 8601. Pass the sender only after you check that it is
+authenticated.
+
+Permission can change between admission and wake. Call `recheck` with the
+admission that `admit` returned, then call the function it returns
+synchronously right before the wake. That function throws when the
+permission was refreshed since, or when the policy read behind it is older
+than 30 seconds. Admissions are bound to the policy that issued them, so
+`recheck` rejects any other object with a `TypeError`.
+
+Failures are `WakePolicyError` values. Branch on `code`:
+
+| `code` | `retryable` | Meaning |
+| --- | --- | --- |
+| `policy_read_failed` | true | A policy read failed temporarily. The policy paces repeated reads itself. |
+| `network_admission_pending` | true | The server has not settled network admission for this email. Retry in a few seconds. |
+| `permission_changed` | true | Permission changed or expired before the wake. Admit the email again. |
+| `policy_unavailable` | false | The policy is invalid or access was lost. Retrying will not help until access is restored. |
+
+A reader reports a temporary failure, such as a rate limit, a 5xx response
+or a dropped connection, by throwing `new WakePolicyError("policy_read_failed")`.
+Any other error from a reader makes the policy unavailable. An aborted signal
+rejects with the signal's reason.
+
+The package also resolves `primitive/bin/*`, `primitive/dist/*` and
+`primitive/man/*` so existing deep imports keep working. Those paths are not
+supported. File names under `dist/` other than `dist/receiver.js` change
+between releases, and the paths may stop resolving in a later major version.
 
 ## Migrating from `@primitivedotdev/sdk` CLI
 
@@ -1357,7 +1419,6 @@ untrusted content names the command:
 
 | Server classification | `how to answer` |
 |---|---|
-| `x402.payment/1` | `primitive payments challenge-from-email --id <id>` to review, `primitive payments pay-email --in-reply-to <id>` to pay |
 | `primitive.contact/1` | `primitive contacts accept --id <id>` |
 | `repeat.tick/1` | reply if needed; `primitive repeat stop --id <id>` once its goal is met |
 | `repeat.stop/1`, status signals, `fyi` | no reply needed |
@@ -1370,7 +1431,7 @@ When the server classifies the email as an interaction, its `interaction.json`
 part is left out of the attachment list. `primitive inbox next` carries the
 same `interaction` and `next_actions` in its JSON envelope, prints the same
 line above the conversation, and ends with matching instructions: the answering
-command first for payment and contact requests (a reply only as optional), "No
+command first for contact requests (a reply only as optional), "No
 reply needed." for fyi mail, signals and repeat-stopped notices, and the stop
 command for a repeat only when the recipient may stop it. `inbox next` skips
 mail that needs no reply (fyi mail, status signals, repeat-stopped notices):

package/bin/claude-pending-mail.mjs

@@ -200,7 +200,7 @@ export const WAKE_SENTENCES = {
 export function wakeSentence(label) {
   if (label === "fyi" || label === "repeat.stop/1")
     return WAKE_SENTENCES.no_reply;
-  if (label === "x402.payment/1" || label === "primitive.contact/1")
+  if (label === "primitive.contact/1")
     return WAKE_SENTENCES.answer_with_command;
   if (label === "repeat.tick/1") return WAKE_SENTENCES.repeat;
   return WAKE_SENTENCES.unsupported;

package/bin/run.js

@@ -72,5 +72,19 @@ const { writeRootAuthContextIfNeeded } = await import(
 );
 await writeRootAuthContextIfNeeded();
 
+// `--org <org>` works on every command: take it out of argv before oclif
+// parses the command, and pass it on as PRIMITIVE_CLI_ORG. Applied last, so
+// the detached receiver and signal workers started above never inherit it.
+{
+  const { applyGlobalOrgFlag } = await import(
+    "../dist/oclif/global-org-flag.js"
+  );
+  const orgFlagError = applyGlobalOrgFlag();
+  if (orgFlagError) {
+    process.stderr.write(`${orgFlagError}\n`);
+    process.exit(2);
+  }
+}
+
 const { execute } = await import("@oclif/core");
 await execute({ dir: import.meta.url });