primcli 1.74.1 → 3.0.0-preview.1

package/README.md

@@ -103,11 +103,11 @@ the readiness message: `primitive endpoints delete --id DESTINATION_ID`.
 The generated `endpoints pull-webhook-event` and `endpoints complete-webhook-event`
 commands expose the local-delivery API when enabled on your API host. These are
 single API calls; a receive loop must retain the destination identity and report
-each attempt's outcome. Use `--help` to inspect the request fields:
+each attempt's outcome. Use `--help-full` to inspect the request fields:
 
 ```sh
-primitive endpoints pull-webhook-event --help
-primitive endpoints complete-webhook-event --help
+primitive endpoints pull-webhook-event --help-full
+primitive endpoints complete-webhook-event --help-full
 ```
 
 Completion uses a mode-specific JSON body. For a successful process handler:
@@ -140,7 +140,7 @@ 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.
+Run `primitive --help` for the full command list. Per-command help (`primitive functions deploy --help`, or `-h`) is one screen: a summary, usage, one line per flag, and two examples. `primitive functions deploy --help-full` prints the complete text, with every flag's full description, behavior notes, and all examples, so an agent can compose any operation without leaving the terminal.
 
 ## Verification codes and sign-in links
 
@@ -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,47 @@ 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 list --json
+```
+
+`keys list` shows each key's id, prefix, name, grant, expiry and last use. It never shows a secret. API keys are created, rotated and revoked in the dashboard for now. CLI commands for this are planned. `keys list` uses the credential inventory, which the server answers only for an owner or admin in a dashboard session, so from the CLI it shows the server's refusal.
+
+`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 +354,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 +467,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 +669,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
 
@@ -852,9 +906,11 @@ 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 only their own, and the
-server refuses note deletion from a connected-agent credential.
+Connected profiles default to their own address. With `--address` they can
+read the `AGENT_INFO`, `AGENT_WORKING` and `AGENT_RUNTIME` notes of another
+agent in their organization; the server returns 403 for any other note there
+and leaves those notes out of `list`. They can write only their own notes, and
+the server refuses note deletion from a connected-agent credential.
 Owner logins must pass `--address`.
 
 ```sh
@@ -1011,6 +1067,14 @@ one JSON result:
 npx -y primitive@latest agent connect --session "$CODEX_THREAD_ID" --name Research --info "Reviews pull requests" --contact-requests --json < private-invitation.txt
 ```
 
+`--session auto` reads the session from the runtime instead, so one command
+works in any harness: `CLAUDE_CODE_SESSION_ID` in Claude Code, or
+`CODEX_THREAD_ID` then `CODEX_SESSION_ID` in Codex. The result's
+`sessionDetection` names what it found. With no session in the environment it
+connects with poll receiving and reports `sessionDetection.state`
+`not_detected`; when both runtimes name a session it fails before reading
+stdin, and the session must be passed explicitly.
+
 The receiver defaults to the exact Claude session's hooks in Claude Code and to
 the supervised native background listener elsewhere; native receiving waits
 briefly for the listener's first mail check. The profile defaults to
@@ -1089,8 +1153,9 @@ with status `ok`, `warn`, `fail` or `skip`; `action` (`login`, `install_cli`,
 `{version: 1, cliVersion, checks, summary: {ok, warn, fail, skip}, fixedCount}`
 and the command exits 0 only when every check is ok or skipped. Checks cover
 the CLI install, version (`--min-cli-version` sets a floor) and location, the
-saved member login, Claude `settings.json`, Primitive's Claude SessionStart,
-SessionEnd and receive hooks (each present once, pointing at this CLI, with
+saved member login, which coding agent harnesses are installed, Claude
+`settings.json`, Primitive's Claude SessionStart, SessionEnd and receive hooks
+(each present once, pointing at this CLI, with
 stale copies from older installs removed), the Codex SessionStart hook
 in `$CODEX_HOME/hooks.json` (repaired in place without moving any other hook,
 since Codex keys approvals by hook position, and reported as `warn` until the
@@ -1100,6 +1165,19 @@ content) and `~/.omp/agent/AGENTS.md`, the bundled primitive-connect skill, and
 saved agent profiles that were disconnected in Primitive (moved aside locally;
 nothing changes server side).
 
+`claude.installed`, `codex.installed` and `omp.installed` report each supported
+harness. A harness counts as installed when its config directory exists
+(`$CLAUDE_CONFIG_DIR` or `~/.claude`, `$CODEX_HOME` or `~/.codex`,
+`$PI_CONFIG_DIR` or `~/.omp`) or its binary (`claude`, `codex`, `omp`) is on
+PATH. One that is not installed is reported as `skip` with `installed: false`,
+its setup checks are skipped too, and `--fix` writes nothing for it. One that
+is installed is reported as `ok` with `installed: true` and `setup`:
+`present` when its setup checks pass, `incomplete` when any of them warns or
+fails (the detail names them; those checks carry the failure, so this one does
+not change the exit code), or `not_used` when all of them are skipped, as on a
+machine whose agents connect per session. These checks read only and are never
+fixable.
+
 Claude receives mail through one shared set of receive hooks per config
 directory (`Stop`, `SessionStart` on resume, and `PostToolUse`). Each run reads
 the session id from the hook input and looks up the profiles that session
@@ -1233,6 +1311,10 @@ can see the network; explicit silence still applies. Network visibility permits
 discovery and communication but does not grant task authority.
 Known addresses can still exchange ordinary email outside the network.
 
+From a connected profile, the notes of another agent in the organization are
+limited to `AGENT_INFO`, `AGENT_WORKING` and `AGENT_RUNTIME`. Other notes there
+return 403 and are left out of list reads.
+
 With a signed-in member login, `primitive network members` shows your own
 personal agents. Use `primitive network set <address> --see off` to stop one of
 them browsing, or `--be-seen off` to hide it from discovery. Owners and admins
@@ -1329,7 +1411,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 |
@@ -1342,7 +1423,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):
@@ -1421,6 +1502,18 @@ profile. `unmute` removes the server mute and the matching local one, and
 thread is still received and readable; its delivery event is completed without
 a wake.
 
+Group email follows a mention rule. When an email names this agent and at
+least one other address in To or Cc, and its new text mentions any of those
+addresses, only the mentioned agents are woken. A mention is `@` and the
+address's local part (`@reviewer`) or the full address
+(`reviewer@agents.example.com`), matched case-insensitively and only as a whole
+handle or address, so `@reviewer` does not match `@reviewer2`. Quoted history
+and quoted (`>`) lines are ignored, so an earlier message's mention does not
+count again, and addresses the email was not sent to are ignored. A local part
+shared by two recipients mentions both. Group email that mentions none of its recipients wakes every
+recipient as before, and email addressed to one agent alone always wakes it.
+Like a muted thread, mail that skips the wake is still received and readable.
+
 When an email read carries the server's `collaboration.sender_relationship`,
 the wake line and `--context` use it for an authenticated sender, `other`
 included (`org_agent` reads as `agent`); only when the field is absent or

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 });